API reference · v1

One call. 95+ ways to read a handset.

Post an IMEI and the id of the lookup you want; a JSON object comes back. Loss and theft reports, activation-lock state, the network a handset was first sold on, SIM lock, warranty dates, model detail — all of it through the same route. Each call draws credits as it runs, so there is nothing to subscribe to and no monthly floor to clear.

Create account Sign in Straight to the reference

Two commands

# 1. what can be run, and what each one costs
curl https://phonedecoded.com/api/v1/checks/services

# 2. run one against a number
curl -X POST https://phonedecoded.com/api/v1/checks \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"imei":"356938035643809","service":6}'

Catalogue

95+

Priced

Per call

Payload

JSON

Access

API key

Base URL

https://phonedecoded.com/api/v1

Every path on this page hangs off that prefix. JSON goes both ways; there is no form encoding and no XML.

Authentication

One header, X-API-Key, on every POST /checks you send. There is no OAuth dance and no bearer token to refresh. Keys are minted and killed from the dashboard, which means you need an account before you write any code. Reading the catalogue (GET /checks/services) is open to anyone.

The two calls

GET /api/v1/checks/services Open, no key

Lists what is available and what each one draws. Read it at start-up rather than hard-coding ids: the catalogue moves as lookups are added and retired. The service value is what you quote on the call below.

Response 200

{
  "services": [
    { "service": 3, "name": "iCloud On/off", "category": "apple", "credits": 3, "instant": true },
    { "service": 6, "name": "WW Blacklist Status — Pro", "category": "blacklist", "credits": 3, "instant": true }
  ]
}

credits: What one successful call draws down (1 credit ≈ £1).
instant: True where the answer comes back inside the request. Everything else is fulfilment work that completes later, not a slow HTTP call.

POST /api/v1/checks X-API-Key

Takes one number and one service id and answers with what came back. Credits move only when there is a real answer to hand you: an empty result, or a source that could not be reached, costs nothing and can be retried.

Request body

{
  "imei": "356938035643809",   // required — 8 to 20 characters
  "service": 6                 // required — an id from the catalogue call
}

Response 200

{
  "service": 6,
  "service_name": "WW Blacklist Status — Pro",
  "imei": "356938035643809",
  "credits_used": 3,
  "credit_balance": 97,
  "result": {
    "Blacklist Status": "Clean"
  },
  "summary": {
    "blacklist_clean": true
  }
}

Do not expect a fixed shape from result — a warranty answer and a loss report have nothing in common, so the keys follow whatever the lookup returned. Where the same fact can be expressed the same way across services, it is repeated in summary as a plain boolean or value. Read summary first and fall back to the raw block.

What comes back

HTTP	What it means	Billed?
200	The lookup ran and the answer is in the body.	Yes — the service price
401	The `X-API-Key` header was absent, malformed or revoked.	No
402	Not enough credit to cover this one. The body names the shortfall as `required` against your `balance`.	No
404	No such `service` — re-read the catalogue.	No
422	The body did not validate, or this number produced nothing on this lookup.	No

Paying for calls

· Prices are fixed per service and published in the open catalogue at /checks/services (1 credit ≈ £1).
· A call that answers with nothing is never billed, so a retry costs you no more than the first attempt did.
· Credits are bought in blocks. Turn on auto top-up if you run batches — a 402 halfway through one is the expensive kind of failure.

Looking after the key

· An account holds one key, issued from the dashboard.
· Issuing a new one kills the old one on the spot, so deploy the replacement in the same breath.
· If a key ends up somewhere public, revoke it and read the request log — every call is recorded against the key that made it.

Create account