Authentication

The API uses an API key. Most endpoints expect the key in the access-key header. GET /order/browser is the one exception and takes the key as a query parameter; see Browser orders.

API key

Send your API key in the access-key header. The key is a UUID v4 issued to your account.

access-key: YOUR_API_KEY

Example:

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

List endpoints need page and size, so a bare GET /service returns a 400.

IP allow-list

For API-key requests to any REST endpoint, including GET /order/browser, the originating IP must be present in the account's IP allow-list. Add your server IPs in the dashboard to avoid YOUR_IP_IS_NOT_PERMITED errors.

Browser orders

GET /order/browser places an order from a URL and takes the API key in the key query parameter:

https://api.imeilookup.com/order/browser?key=YOUR_API_KEY&service=SERVICE_ID&imei=YOUR_IDENTIFIER

Use this endpoint only from a browser you control, for a quick manual check. Do not build integrations on it, and do not turn it into a shareable or one-click link: the URL carries your account API key, which can place charged orders.

Treat these URLs like passwords

• Exposure. A URL that contains your API key can end up in browser history, bookmarks, copied or pasted links, chat and ticket messages, and server and proxy logs. Anyone who sees the URL can use the key.
• Repeated requests. This is a GET request that places a paid order. Opening it again, refreshing the page, a link preview or link scanner, a browser prefetch or an automatic retry can each place another order, and each one is charged. Do not assume repeated requests are de-duplicated.
• No sharing. Never send these links to other people or paste them into documentation, tickets or source code.

If a URL containing your key was shared or logged, treat the key as exposed and contact support.

For integrations, call POST /order/single from your server with the access-key header. The key then stays out of URLs, history and logs, and your code can handle timeouts and polling safely; see Placing orders and polling.

The IP allow-list applies to GET /order/browser like every other REST endpoint: a browser-link order from an IP address that is not on your allow-list is blocked, even with a valid key. The allow-list does not make a key in a URL safe to share, though. Anyone on an allowed IP address, or anyone who obtains the key and can reach the API from one, can still place charged orders.

Authentication errors

Status	Code	Meaning
403	LOGIN_AGAIN	The access-key header is missing, empty or not a valid key format.
401	INVALID_TOKEN	The key format is valid but the key is not recognised.
401	YOUR_IP_IS_NOT_PERMITED	Request IP is not in the allow-list.
403	YOU_ARE_NOT_ALLOWED	You are not allowed to do this.
403	YOU_ARE_BLOCKED	The account is blocked.
403	PENDING_FOR_APPROVAL	The account has not been approved yet.

On GET /order/browser the key is in the URL. There, an unrecognised key returns 401 INVALID_API_KEY, and a missing or empty key returns 400 with key should not be empty.

A missing key and an unknown key return different codes and statuses, so treat every 401 and 403 from this table as an authentication problem rather than matching on a single code.

Before your first request

1. Get your account approved. A new account returns PENDING_FOR_APPROVAL until it is approved.
2. Get your API key from your dashboard.
3. Add your server's IP address to the IP allow-list in the dashboard. Requests from other addresses return YOUR_IP_IS_NOT_PERMITED. If you do not know your server's outbound IP, ask your hosting provider.
4. Make a first call such as GET /service?page=0&size=10. Then read Placing orders and polling and place your first order with Single order.

Retrying and asking for help

• Do not retry 400, 401, 403, 404 or 405 responses unchanged. Fix the request, the key, the IP allow-list or the account first.
• Never resubmit an order automatically after a timeout or a 5xx. See Placing orders and polling.

When you contact support, include the UTC time of the request, the endpoint, the HTTP status, the full response body, and the order ID or batch ID if you have one. Never send your API key.

Requests blocked before the API

Some requests are rejected by the edge network before they reach the API. These responses do not use the JSON error format above. For example, some HTTP clients have received a 403 with Cloudflare error 1010 while the same request sent with cURL reached the API. If you see this, contact support and include the time of the request.