Dealer API

API access is part of every dealer plan: Verified Dealer, Dealer Pro and Dealer Enterprise.

1. 1In your dealer dashboard, open API and make a key. On Dealer Enterprise, each key belongs to a branch.
2. 2Copy it straight away: we show it once.
3. 3Keep it on your server, never in an app or a web page. If it leaks, revoke it and make a new one.

Send it in the Authorization header of every request:

Authorization: Bearer sk_live_…

Send the IMEI, or a serial number as query, as JSON with your key in the Authorization header.

curl -X POST https://cdr-server.vercel.app/v1/checks \
  -H "Authorization: Bearer sk_live_…" \
  -H "Content-Type: application/json" \
  -d '{"imei": "354398601234891"}'

{
  "id": "6720c1a3e4b0a1f2c3d4e5f6",
  "reference": "SPV-8B21D4E911C0A7F3B2D1",
  "checkedAt": "2026-09-28T07:42:10.000Z",
  "query": "354398601234891",
  "imeiValidity": "valid",
  "device": { "manufacturer": "Apple", "model": "iPhone 13 Pro" },
  "outcome": "CLEAN",
  "result": "No adverse record",
  "riskLevel": "low",
  "findings": [
    { "tone": "ok", "headline": "No lost or stolen report against this device", "detail": "…" }
  ],
  "billing": {
    "included": false,
    "charged": 20,
    "currency": "KES",
    "creditBalance": 380,
    "includedLeft": 0
  },
  "disclaimer": "…"
}

curl https://cdr-server.vercel.app/v1/usage \
  -H "Authorization: Bearer sk_live_…"

{
  "planActive": true,
  "paidThrough": "2026-10-28T07:00:00.000Z",
  "month": { "start": "2026-09-28T07:00:00.000Z", "end": "2026-10-28T07:00:00.000Z" },
  "plan": "verified",
  "includedChecks": 25,
  "includedUsed": 25,
  "paidChecks": 41,
  "nextCheckPrice": 20,
  "creditBalance": 380,
  "currency": "KES"
}

A test key answers with zeros, and with paidThrough and month set to null.

To build against the API safely, make a test key under API in your dealer dashboard, on any plan. It starts sk_test_ and works like a live key, but every check answers with a sample result in the same shape: no device is looked up, no record is read, and nothing is charged or counted. /v1/usage answers with zeros.

The IMEI's last digit picks the answer, so you can try each one:

A sample's reference starts SPV-00000000, and its billing is all zeros. Revoke a test key like any other.

Each month of your plan includes 25 checks on Verified Dealer, or 150 on Dealer Pro, shared across the dashboard, bulk uploads and the API. After that, each API check comes out of your prepaid credit at the price for how many you've paid for this month:

On Dealer Enterprise, your contract sets the included checks and the price of each check after them. Top up credit by M-Pesa from your dashboard. A check that can't be run isn't charged.

• Up to 120 requests a minute per key, checks and usage together.
• Each answer to a working key says what's left in its RateLimit header; resetis the seconds until the minute starts over. A request turned away for its key doesn't count.
• Over the limit, you get 429 rate_limited with a Retry-After header: the seconds to wait before sending again.
• One device per request: an imei, or a serial number as query, 4 to 40 characters long. For a whole file of devices, use Bulk uploads in your dealer dashboard.

RateLimit-Policy: 120;w=60
RateLimit: limit=120, remaining=97, reset=41

Every error is JSON: a message you can show people, and a content code your system can act on (null where there's no code).

{
  "message": "You've used this month's 25 included checks, and your credit is too low for another (KES 20). Top up to keep checking.",
  "content": "insufficient_credit"
}

• 400

  No code

  The body has no imei (or query), or it's shorter than 4 or longer than 40 characters.

  invalid

  Insurer keys only: the number isn't a valid 15-digit IMEI. It isn't charged.

• 401

  unauthorized

  No key, a wrong key, or a revoked key.

• 402

  plan_inactive

  Your plan isn't paid up for this month.

  insufficient_credit

  The included checks are used and your credit is too low for the next one.

• 403

  key_paused

  The key is for a branch that isn't on your plan now. Use another key.

  api_closed

  Insurer keys only: API access is off for your insurer.

• 429

  rate_limited

  More than 120 requests in a minute on one key. Wait the seconds in Retry-After.

• 500

  No code

  Something went wrong on our side. A check that can't be run isn't charged, so try again.

Insurers use the same API. Your main contact makes keys under Device checks in your insurer portal, once Simuplace's team turns API access on. Each phone is billed at your price on your monthly invoice, not from credit.

Send IMEIs only: a number that isn't a valid IMEI comes back as 400 invalid and isn't charged. Each answer also carries the phone's record:

{
  …
  "record": {
    "registeredSince": "2026-07-01T09:12:00.000Z",
    "ownerChanges": 1,
    "earlierClaims": 0,
    "checkedByOthers": 2
  },
  "billing": { "charged": 20, "currency": "KES", "invoice": "2026-10" }
}

/v1/usage answers with this month so far. A key stops working with 403 api_closed while API access is off.

{
  "month": { "start": "2026-09-30T21:00:00.000Z", "end": "2026-10-31T21:00:00.000Z" },
  "checks": 1284,
  "amount": 25680,
  "price": 20,
  "currency": "KES",
  "invoiceOn": "2026-10-31T21:00:00.000Z"
}