Simuplace dealer API

1. Get a key

API access is part of the Verified Dealer and Dealer Pro plans. In your dealer dashboard, open API and make a key. We show it once: keep it on your server, never in an app or a web page. If it leaks, revoke it and make a new one.

2. Check a device

Send the IMEI (or a serial number as query) 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"}'

The answer:

{
  "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": "…"
}

outcome

What our records say. One of the values below.

result

The same, in words, as your dashboard shows it. An invalid IMEI reads “Invalid IMEI”.

riskLevel

low, medium or high, with the reasons in findings.

imeiValidity

valid, invalid (the number was never issued), or not_applicable for serial numbers.

billing

Whether it came out of your included checks, what it cost, and what's left.

3. See your usage

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"
}

Test keys

To build against the API safely, make a test key under API in your dealer dashboard. 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.

Billing

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:

Top up credit by M-Pesa from your dashboard. A check that can't be run isn't charged.

Errors

Errors come back as { "message": "…", "content": "code" } with these statuses:

For insurers

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" }
}

registeredSince

When its owner got it, or null if it isn't registered on Simuplace.

ownerChanges

How many times it changed hands on Simuplace.

earlierClaims

Claims on it under any policy: how many, never whose.

checkedByOthers

Checks by anyone but you and its owner in the last 30 days. Never who.

billing

What it cost, and the month whose invoice it's on.

/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"
}