Introduction

The IMEILookup API is a REST API for IMEI checks by IMEI, serial number (SN) or MEID. It lets you place lookups, track their results, and browse the catalog of available services.

The REST API uses JSON request bodies and application responses; GET endpoints accept query parameters. REST calls normally authenticate with the access-key header, while the browser-order endpoint uses the key query parameter.

The full OpenAPI description is available as openapi.json and openapi.yaml.

WebSocket and webhooks

WebSocket (WSS) and webhooks are available on request. Access is not turned on automatically. Sign in to your dashboard and use the request card there.

Request access

Base URL

Every endpoint in this documentation is relative to the production base URL:

https://api.imeilookup.com

There is no version prefix. For example, the bulk-order endpoint is reached at:

POST https://api.imeilookup.com/order

Authentication

Authentication uses an API key, described in detail on the Authentication page:

Method	Where	Typical use
API key	access-key header	Server-to-server calls (recommended)
API key (browser URL)	key query parameter	GET /order/browser only

Resources

Resource	Description
Orders	One lookup of an IMEI, serial number (SN) or MEID with a chosen service.
Batches	Groups of orders created by a single bulk request.
Services	The catalog of lookup products with pricing and limits.

Endpoint	What it does
Single order	POST /order/single: check one identifier
Bulk order	POST /order: check many in one batch
Browser order	GET /order/browser: order from a URL
Get a single order	GET /order/single: read one order
List orders	GET /order: list and filter your orders
List batches	GET /batch: list your batches
List services	GET /service: list available services

Identifiers

The imei property carries the identifier a service accepts: an IMEI, a serial number (SN) or a MEID. The property name does not change with the type. Which types a service accepts depends on the service, and GET /service does not yet say which; check the service title and description, and expect INVALID_IMEI_PROVIDED if you send a type the service does not take.

• Always send identifiers as strings, in JSON bodies and in query parameters. Do not convert them to numbers: that drops leading zeros and loses precision on long values.
• Send the value as printed on the device, without spaces, dashes or other separators. The API does not document any normalisation, so do not rely on it trimming or reformatting the value.
• Real identifiers only. Identifiers are validated, and a made-up number such as 123456789098765 is rejected. A TAC (the first 8 digits of an IMEI) on its own is not documented as accepted input; send the full identifier.
• Not yet published: the exact length, character set, checksum, whitespace and serial-number case rules for each service. They differ by service and have not been confirmed, so this site does not state them.

Batch names

batchName is a string. It is required on POST /order. On POST /order/single it is optional; if you send it, it cannot be an empty string (leave the field out instead). GET /order/browser has no batch name. The maximum length and the allowed characters have not been confirmed. An invalid name returns INVALID_BATCH_NAME on the bulk endpoint.

Validation errors

Code	Where	Meaning
TAC_FAILED	POST /order/single, GET /order/browser	The identifier failed TAC validation.
INVALID_IMEI_PROVIDED	POST /order/single, GET /order/browser	The identifier is not valid for the service.
INVALID_IMEI	POST /order	One or more identifiers in the list are not valid.

All three are 400 responses. None returns an order ID, so there is nothing to poll. For POST /order, rejected numbers are counted in rejected and are not charged. Whether a rejected single order is recorded or charged has not been confirmed; check your order list (GET /order) rather than assuming.

Results

The result object holds the lookup output. Its keys depend on the service, so do not treat any example as a universal schema. result is null while an order is still running.

A service's time value, for example Instant, is informational. It is not a guarantee: an order for a service listed as Instant stayed in Processing for minutes in testing. A service description is sometimes sample output, not prose.

Pagination

List endpoints (GET /order, GET /batch, GET /service) use zero-based page numbering. Send both page and size; neither has a default.

Endpoint	size limits	Response
GET /order	maximum 5000	Status counts and an orders array
GET /batch	minimum 5, maximum 5000	See the endpoint page
GET /service	required	total and a services array

The order list has no total field. Request the next page until a page comes back with fewer than size items. The failed, waiting, success and processing counters in that response count all orders that match your filters, across every page, not only the orders on the current page. They stay the same when page or size changes and change when you add or change filters such as from and to.

A service's limit is the number of identifiers allowed in one order for that service. It is separate from the size parameter used to page through lists.

Errors

Application errors include an HTTP status and a message. Depending on the error, message is a string or an array of strings:

{
  "message": "ERROR_CODE",
  "statusCode": 400
}

{
  "message": ["PAGE_NUMBER_REQUIRED", "PAGE_SIZE_REQUIRED"],
  "error": "Bad Request",
  "statusCode": 400
}

Handle both message shapes, and check the HTTP status first. Some responses also carry an error field. Unexpected server failures can return a plain "message": "Internal server error".

Requests that never reach the API, for example ones blocked at the edge network, can use a different response format. See Authentication.

The error codes page lists the shared codes and the codes for each endpoint. Endpoint pages list the responses they can return. Treat these lists as a guide and keep a generic fallback for codes you do not recognise.

Quick start

1. Get an API key from your dashboard and add your server's IP address to the account's IP allow-list.

2. List the services your account can use. Both page and size are required:

   curl "https://api.imeilookup.com/service?page=0&size=10" \
     -H "access-key: YOUR_API_KEY"

   Pick a service id from the response. Your account may not have access to every service.

3. Place an order with that service ID and an identifier the service accepts. Identifiers are validated, so placeholder values such as 123456789098765 are rejected:

   curl -X POST https://api.imeilookup.com/order/single \
     -H "access-key: YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"serviceId": SERVICE_ID, "imei": "YOUR_IDENTIFIER"}'

4. If the response has "status": "Processing", the lookup is still running. Fetch the order until it finishes:

   curl "https://api.imeilookup.com/order/single?id=ORDER_ID" \
     -H "access-key: YOUR_API_KEY"

Read Placing orders and polling before you automate steps 3 and 4. A timeout does not mean the order failed, and resending the request can create and charge a second order.

Using a DHRU panel? See the DHRU integration guide.