Device Risk API · Docs

Authentication

Every request must be HMAC-signed. After signing up for the Risk API tier, you receive a key pair (public ID + secret) from account → licenses.

Signing:

ts = unix_seconds()  // must be within 5 minutes of server time
canonical = method + "\n" + path + "\n" + ts + "\n" + sha256(body).hex()
mac = hmac_sha256(secret, canonical).hex()

Authorization: KakelRisk <public_id>:<mac>
X-Risk-Timestamp: <ts>

POST /v1/lookup

Look up a device against KAKEL's blacklist.

POST https://kakel.io/api/risk/v1/lookup
Content-Type: application/json
Authorization: KakelRisk pub_xxx:mac

{
  "imei": "355008280102090",
  "apple_serial": null,
  "ecid": null
}

Response:

{
  "queried": { "imei": "355008280102090" },
  "counts": {
    "ios_blocked": 1,
    "sim_unlock_blocked": 0,
    "companion_stolen_reports": 0,
    "gsma": 0
  },
  "highest_severity": "blocked",
  "records": [
    {
      "source": "ios_blocked",
      "severity": "blocked",
      "reason": "ACTIVATION_LOCK",
      "reported_at": "2026-05-18T03:21:11Z",
      "cleared_at": null
    }
  ]
}

POST /v1/lookup/batch

Up to 100 devices per batch. Charged per-device against your account.

POST /api/risk/v1/lookup/batch
{
  "devices": [
    { "imei": "355008280102090" },
    { "apple_serial": "CW5P97DC21" },
    { "imei": "358149541181957" }
  ]
}

Response is a parallel array of { queried, counts, ... } objects, one per input device.

Contribute back: POST /v1/report (write tier)

If you're on the write tier, you can contribute stolen / blocked reports back to KAKEL's dataset. Revenue share applies on subsequent matched lookups by other Risk API customers.

POST /api/risk/v1/report
{
  "imei": "355008280102090",
  "source": "external",
  "reason": "Reported stolen — customer evidence on file",
  "severity": "blocked",
  "evidence_url": "https://your-cdn/evidence/abc.pdf"
}

Rate limits + pricing

Per-call pricing: $0.10/lookup, or fixed monthly tiers for volume customers (~10k/mo: $499/mo, ~100k/mo: $2,999/mo). Burst limit 100 req/s per key. Sustained 30 req/s.

Rate-limit headers on every response:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1747724400

Exceeding burst returns 429 Too Many Requests with a Retry-After header.

Data sources

Records in the dataset originate from: