{ "openapi": "3.0.0", "paths": { "/order": { "get": { "operationId": "list-orders", "parameters": [ { "name": "page", "required": true, "in": "query", "description": "Zero-based page number. Required.", "schema": { "example": "0", "type": "number", "minimum": 0 } }, { "name": "size", "required": true, "in": "query", "description": "Items per page. Required. Maximum 5000 (larger values return `INVALID_PAGE_SIZE`).", "schema": { "example": "10", "type": "number", "maximum": 5000 } }, { "name": "orderStatus", "required": false, "in": "query", "description": "Filter orders by order status: `Waiting`, `Processing`, `Success` or `Failed`. Any other value, including `Pending` (a batch state, not an order status), returns `ORDER_STATUS_INVALID`. See [Placing orders and polling](/docs/guides/orders-and-polling#order-statuses).", "schema": { "type": "string", "enum": [ "Failed", "Waiting", "Success", "Processing" ] } }, { "name": "from", "required": false, "in": "query", "description": "Optional. Return orders from this date (ISO string). Can be used on its own, without `to`.", "schema": { "type": "string" } }, { "name": "to", "required": false, "in": "query", "description": "Optional. Return orders up to this date (ISO string). Can be used on its own, without `from`.", "schema": { "type": "string" } }, { "name": "serviceId", "required": false, "in": "query", "description": "Filter orders by service ID. A badly formatted value returns 400 `SERVICE_ID_INVALID`; a service ID that does not exist returns 404 `SERVICE_NOT_FOUND`.", "schema": { "type": "number" } }, { "name": "search", "required": false, "in": "query", "description": "Full IMEI or serial number. Filter orders by identifier. Must be sent as a list: repeat the parameter for several values (`search=A&search=B`) and use `search[]=A` for a single value. A bare `search=A` is rejected with `SEARCH_MUST_BE_LIST`.", "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": true }, { "name": "batchName", "required": false, "in": "query", "description": "Filter orders by batch name", "schema": { "type": "string" } }, { "name": "batchId", "required": false, "in": "query", "description": "Filter orders by batch ID", "schema": { "type": "number" } } ], "responses": { "200": { "description": "Returns a paginated list of orders", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderListResponseDto" }, "examples": { "orders": { "summary": "Page with one order", "value": { "failed": 0, "waiting": 0, "success": 1, "processing": 0, "orders": [ { "id": 32344241, "imei": "357619537445062", "status": "Success", "created": "2026-10-12T22:08:44.759Z", "updated": "2026-10-12T22:08:44.775Z", "orderCost": 0.01, "result": { "IMEI": "357619537445062", "Manufacturer": "Apple Inc", "Model Code": "A2403", "Model Name": "iPhone 12" }, "batch": { "id": 9740938, "title": "Direct order", "service": "Any Make & Model Check [TAC DB]", "user": { "username": "demouser", "role": "Main" } } } ] } }, "empty": { "summary": "No matching orders", "value": { "failed": 0, "waiting": 0, "success": 0, "processing": 0, "orders": [] } } } } } }, "400": { "description": "Bad Request — PAGE_NUMBER_INVALID, PAGE_SIZE_INVALID, INVALID_PAGE_SIZE, ORDER_STATUS_INVALID, INVALID_DATE_PROVIDED, SERVICE_ID_INVALID, SEARCH_MUST_BE_LIST, FILTER_VALUE_INVALID, INVALID_BATCH_NAME_FILTER, SUBUSERS_MUST_BE_LIST, SUBUSERS_ARE_INVALID, INVALID_SORT_VALUE, INVALID_ORDER_TYPE", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "401": { "description": "Unauthorized — INVALID_TOKEN, YOUR_IP_IS_NOT_PERMITED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "403": { "description": "Forbidden — LOGIN_AGAIN, YOU_ARE_NOT_ALLOWED, YOU_ARE_BLOCKED, PENDING_FOR_APPROVAL, CANNOT_VIEW_HISTORY", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "404": { "description": "Not Found — SERVICE_NOT_FOUND", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "500": { "description": "Internal Server Error — unexpected server failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } } }, "security": [ { "api-key": [] } ], "summary": "List orders", "tags": [ "Orders" ], "description": "Returns one page of orders and four status counters. There is no `total` field and no top-level `service` object; the service title is `batch.service` on each order.\n\nThe counters `success`, `failed`, `waiting` and `processing` 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 they change when you add or change filters such as `from` and `to`.\n\nTo find out whether more pages exist, request the next page until a page comes back with fewer than `size` orders (or no orders)." }, "post": { "operationId": "place-a-bulk-order", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlaceBulkOrdersDto" } } } }, "responses": { "201": { "description": "Bulk order placed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderBulkResponseDto" }, "example": { "batchId": 9740940, "accepted": 1, "rejected": 1, "duplicates": 1 } } } }, "400": { "description": "Bad Request — INVALID_IMEI, SERVICE_ID_MUST_BE_NUMBER, INVALID_BATCH_NAME, BATCH_NAME_REQUIRED, IMEI_MUST_BE_ARRAY, IMEI_REQUIRED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "401": { "description": "Unauthorized — INVALID_TOKEN, YOUR_IP_IS_NOT_PERMITED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "403": { "description": "Forbidden — LOGIN_AGAIN, YOU_ARE_NOT_ALLOWED, YOU_ARE_BLOCKED, PENDING_FOR_APPROVAL, CREDIT_LIMIT_REACHED, LOW_CREDIT, SERVICE_LIMIT_EXCEEDED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "404": { "description": "Not Found — SERVICE_NOT_FOUND", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "405": { "description": "Method Not Allowed — SERVICE_IS_DISABLED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "500": { "description": "Internal Server Error — unexpected server failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } } }, "security": [ { "api-key": [] } ], "summary": "Bulk order", "description": "Duplicates are removed within the same request. Rejected and duplicate numbers are not charged.\n\nSend the numbers in `imeis` (an array). `batchName` is required.", "tags": [ "Orders" ] } }, "/order/single": { "get": { "operationId": "get-a-single-order-by-id", "parameters": [ { "name": "id", "required": true, "in": "query", "description": "ID of the order to retrieve", "schema": { "example": "1", "type": "number" } } ], "responses": { "200": { "description": "Returns the order details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderGetSingleResponseDto" }, "example": { "id": 32344241, "imei": "357619537445062", "status": "Success", "created": "2026-10-12T22:08:44.759Z", "updated": "2026-10-12T22:08:44.775Z", "result": { "IMEI": "357619537445062", "Manufacturer": "Apple Inc", "Model Code": "A2403", "Model Name": "iPhone 12" }, "batch": { "id": 9740938, "title": "Direct order", "status": "Completed", "service": "Any Make & Model Check [TAC DB]", "user": { "username": "demouser", "role": "Main" } } } } } }, "400": { "description": "Bad Request — INVALID_ORDER_ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "401": { "description": "Unauthorized — INVALID_TOKEN, YOUR_IP_IS_NOT_PERMITED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "403": { "description": "Forbidden — LOGIN_AGAIN, YOU_ARE_NOT_ALLOWED, YOU_ARE_BLOCKED, PENDING_FOR_APPROVAL", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "404": { "description": "Not Found — ORDER_NOT_FOUND", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "500": { "description": "Internal Server Error — unexpected server failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } } }, "security": [ { "api-key": [] } ], "summary": "Get a single order by ID", "tags": [ "Orders" ] }, "post": { "operationId": "place-a-single-imei-order", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlaceSingleOrderDto" } } } }, "responses": { "201": { "description": "Single order placed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderSingleCreateResponseDto" }, "examples": { "completed": { "summary": "Finished within the wait", "value": { "id": 32344241, "imei": "357619537445062", "status": "Success", "created": "2026-10-12T22:08:44.759Z", "updated": "2026-10-12T22:08:44.775Z", "result": { "IMEI": "357619537445062", "Manufacturer": "Apple Inc", "Model Code": "A2403", "Model Name": "iPhone 12" }, "batch": { "id": 9740938, "title": "Direct order", "status": "Completed", "service": "Any Make & Model Check [TAC DB]", "user": { "username": "demouser", "role": "Main" } } } }, "processing": { "summary": "Still running after 55 seconds", "value": { "id": 32344246, "batchId": 9740943, "status": "Processing", "check_url": "https://api.imeilookup.com/order/single?id=32344246" } } } } } }, "400": { "description": "Bad Request — TAC_FAILED, INVALID_IMEI_PROVIDED, SERVICE_ID_MUST_BE_NUMBER, BATCH_NAME_REQUIRED, IMEI_REQUIRED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "401": { "description": "Unauthorized — INVALID_TOKEN, YOUR_IP_IS_NOT_PERMITED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "403": { "description": "Forbidden — LOGIN_AGAIN, YOU_ARE_NOT_ALLOWED, YOU_ARE_BLOCKED, PENDING_FOR_APPROVAL, CREDIT_LIMIT_REACHED, LOW_CREDIT", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "404": { "description": "Not Found — SERVICE_NOT_FOUND", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "405": { "description": "Method Not Allowed — SERVICE_IS_DISABLED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "500": { "description": "Internal Server Error — unexpected server failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } } }, "security": [ { "api-key": [] } ], "summary": "Single order", "tags": [ "Orders" ], "description": "Places one order. The server waits up to 55 seconds for the result and returns it sooner if it is ready; set your client timeout above that, for example 70 seconds. If the lookup is still running, the response is a small processing envelope instead of the full order. A client timeout does not mean the order failed, so do not resubmit automatically. See [Placing orders and polling](/docs/guides/orders-and-polling).\n\nSend the number in `imei` (a string). `batchName` is optional; if you send it, it cannot be an empty string, so leave the field out instead. Without it the order goes into a batch named \"Direct order\"." } }, "/order/browser": { "get": { "operationId": "place-a-single-imei-order-via-browser-url", "parameters": [ { "name": "key", "in": "query", "required": true, "description": "Your API key.", "schema": { "type": "string" } }, { "name": "service", "in": "query", "required": true, "description": "Service ID to use for the order.", "schema": { "type": "number", "example": "10" } }, { "name": "imei", "in": "query", "required": true, "description": "IMEI, serial number or MEID to check, depending on the service. Send it as a string.", "schema": { "type": "string", "example": "357619537445062" } } ], "responses": { "200": { "description": "Single order placed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderSingleCreateResponseDto" }, "examples": { "completed": { "summary": "Finished within the wait", "value": { "id": 32344241, "imei": "357619537445062", "status": "Success", "created": "2026-10-12T22:08:44.759Z", "updated": "2026-10-12T22:08:44.775Z", "result": { "IMEI": "357619537445062", "Manufacturer": "Apple Inc", "Model Code": "A2403", "Model Name": "iPhone 12" }, "batch": { "id": 9740938, "title": "Direct order", "status": "Completed", "service": "Any Make & Model Check [TAC DB]", "user": { "username": "demouser", "role": "Main" } } } }, "processing": { "summary": "Still running after 55 seconds", "value": { "id": 32344246, "batchId": 9740943, "status": "Processing", "check_url": "https://api.imeilookup.com/order/single?id=32344246" } } } } } }, "400": { "description": "Bad Request — TAC_FAILED, INVALID_IMEI_PROVIDED, SERVICE_ID_MUST_BE_NUMBER, IMEI_REQUIRED (a missing or empty key returns \"key should not be empty\")", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "401": { "description": "Unauthorized — INVALID_API_KEY (the key in the URL is not recognised)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "403": { "description": "Forbidden — YOU_ARE_NOT_ALLOWED, YOU_ARE_BLOCKED, PENDING_FOR_APPROVAL, CREDIT_LIMIT_REACHED, LOW_CREDIT", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "404": { "description": "Not Found — SERVICE_NOT_FOUND", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "405": { "description": "Method Not Allowed — SERVICE_IS_DISABLED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "500": { "description": "Internal Server Error — unexpected server failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } } }, "summary": "Browser order", "tags": [ "Orders" ], "description": "Places a single order with a GET request. The API key goes in the `key` query parameter instead of the `access-key` header.\n\n**Treat these URLs like passwords.** A URL containing an account API key can leak through copied links, browser history and server logs. Opening or refreshing the URL places another order, and it is charged like any other. Do not share these links, and do not assume repeated requests are de-duplicated: refreshes, link previews and retries can each place another order. Prefer `POST /order/single` with the `access-key` header for integrations. The IP allow-list applies to this endpoint 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. See the [Authentication guide](/docs/authentication#browser-orders).\n\nThis query parameter is named `service`, not `serviceId` as in the JSON endpoints." } }, "/batch": { "get": { "operationId": "list-batches", "parameters": [ { "name": "page", "required": true, "in": "query", "description": "Zero-based page number. Required.", "schema": { "example": "0", "type": "number", "minimum": 0 } }, { "name": "size", "required": true, "in": "query", "description": "Items per page. Required. Minimum 5 (`MIN_PAGE_SIZE`), maximum 5000 (`INVALID_PAGE_SIZE`).", "schema": { "example": "10", "type": "number", "minimum": 5, "maximum": 5000 } }, { "name": "status", "required": false, "in": "query", "description": "Filter batches by batch state: `Pending` or `Completed`. These are the only two batch states. Batch states are separate from order statuses (`Waiting`, `Processing`, `Success`, `Failed`).", "schema": { "type": "string", "example": "Completed", "enum": [ "Pending", "Completed" ] } }, { "name": "serviceId", "required": false, "in": "query", "description": "Filter batches by service ID", "schema": { "type": "number" } }, { "name": "ip", "required": false, "in": "query", "description": "Filter batches by IP address", "schema": { "type": "string" } }, { "name": "search", "required": false, "in": "query", "description": "Search batches by text", "schema": { "type": "string" } }, { "name": "title", "required": false, "in": "query", "description": "Filter batches by title", "schema": { "type": "string" } }, { "name": "batchId", "required": false, "in": "query", "description": "Filter batches by batch ID", "schema": { "type": "number" } }, { "name": "from", "required": false, "in": "query", "description": "Filter batches from this date (ISO string)", "schema": { "type": "string" } }, { "name": "to", "required": false, "in": "query", "description": "Filter batches until this date (ISO string)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Returns a paginated list of batches", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchListResponseDto" }, "example": { "total": 1, "completed": 1, "batches": [ { "id": 9740938, "ip": "203.0.113.10", "title": "Direct order", "status": "Completed", "created": "2026-10-12T22:08:44.759Z", "orders": 1, "service": "Any Make & Model Check [TAC DB]", "user": { "role": "Main", "username": "demouser" } } ] } } } }, "400": { "description": "Bad Request — INVALID_PAGE_NUMBER, PAGE_NUMBER_INVALID, INVALID_PAGE_SIZE, PAGE_SIZE_INVALID, MIN_PAGE_SIZE, BATCH_STATUS_INVALID, SERVICE_ID_INVALID, SUBUSERS_MUST_BE_LIST, SUBUSERS_ARE_INVALID, SEARCH_VALUE_IS_INVALID, INVALID_BATCH_ID_PROVIDED, FROM_DATE_REQUIRED, INVALID_DATE_PROVIDED, TO_DATE_REQUIRED, INVALID_SORT_VALUE", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "401": { "description": "Unauthorized — INVALID_TOKEN, YOUR_IP_IS_NOT_PERMITED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "403": { "description": "Forbidden — LOGIN_AGAIN, YOU_ARE_NOT_ALLOWED, YOU_ARE_BLOCKED, PENDING_FOR_APPROVAL", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "500": { "description": "Internal Server Error — unexpected server failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } } }, "security": [ { "api-key": [] } ], "summary": "List batches", "tags": [ "Batches" ] } }, "/service": { "get": { "operationId": "list-available-services", "parameters": [ { "name": "page", "required": true, "in": "query", "description": "Zero-based page number. Required.", "schema": { "example": "0", "type": "number", "minimum": 0 } }, { "name": "size", "required": true, "in": "query", "description": "Items per page. Required.", "schema": { "example": "10", "type": "number" } }, { "name": "filter", "required": false, "in": "query", "description": "Filter services by text. `filter` matches the start of the service title (not case-sensitive). Example: `filter=Apple` returns all Apple services.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Returns a paginated list of services", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceListResponseDto" }, "example": { "total": 1, "services": [ { "id": 9, "title": "Any Make & Model Check [TAC DB]", "price": 0.01, "limit": 500, "featured": false, "description": "Manufacturer and model from the TAC database", "group": { "id": 1, "title": "IMEI Services" }, "time": "Instant" } ] } } } }, "400": { "description": "Bad Request — PAGE_NUMBER_INVALID, PAGE_NUMBER_REQUIRED, PAGE_SIZE_REQUIRED, PAGE_SIZE_INVALID, FILTER_VALUE_INVALID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "401": { "description": "Unauthorized — INVALID_TOKEN, YOUR_IP_IS_NOT_PERMITED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "403": { "description": "Forbidden — LOGIN_AGAIN, YOU_ARE_NOT_ALLOWED, YOU_ARE_BLOCKED, PENDING_FOR_APPROVAL", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } }, "500": { "description": "Internal Server Error — unexpected server failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" } } } } }, "security": [ { "api-key": [] } ], "summary": "List available services", "tags": [ "Services" ] } } }, "info": { "title": "IMEILookup API", "description": "REST API reference for IMEILookup: error format and error codes.\n\n\n## Error Response Format\nApplication errors follow this JSON structure:\n```json\n{\n \"message\": \"ERROR_CODE\",\n \"statusCode\": 400\n}\n```\nThe `message` field is an application error code, or an array of codes or validation messages, so handle both a string and an array. Some responses also include an `error` field with the HTTP status text. The `statusCode` field is the HTTP status. Requests rejected before they reach the API, for example by the edge network, can use a different format.\n\n## Error Codes Reference\n\n`INVALID_API_KEY` (401) is returned only by `GET /order/browser` when the key in the URL is not recognised. A missing or empty key there returns 400 `key should not be empty`.\n\n`TAC_FAILED` and `INVALID_IMEI_PROVIDED` (single and browser orders) and `INVALID_IMEI` (bulk orders) are identifier validation errors. See [Identifiers](/docs/intro#identifiers) for what each means and what is not yet confirmed.\n\n### Common Errors (all header-key endpoints)\n\n| HTTP | Code | Meaning |\n|------|------|---------|\n| 401 | `INVALID_TOKEN` | The key format is valid but the key is not recognised |\n| 403 | `LOGIN_AGAIN` | The `access-key` header is missing, empty or not a valid key format |\n| 401 | `YOUR_IP_IS_NOT_PERMITED` | Your IP is not permitted, login to dashboard and add your IP to the allow-list |\n| 403 | `YOU_ARE_NOT_ALLOWED` | You are not allowed for this action |\n| 403 | `YOU_ARE_BLOCKED` | You are blocked, contact admin |\n| 403 | `PENDING_FOR_APPROVAL` | Your account is pending for approval |\n\n### GET /order — List Orders\n\n| HTTP | Code | Meaning |\n|------|------|---------|\n| 400 | `PAGE_NUMBER_INVALID` | Page number is invalid |\n| 400 | `PAGE_SIZE_INVALID` | Page size is invalid |\n| 400 | `INVALID_PAGE_SIZE` | Page size cannot exceed 5000 |\n| 400 | `ORDER_STATUS_INVALID` | Order status not valid |\n| 400 | `INVALID_DATE_PROVIDED` | Invalid date provided |\n| 400 | `SERVICE_ID_INVALID` | Service ID not valid |\n| 404 | `SERVICE_NOT_FOUND` | Service not found |\n| 400 | `SEARCH_MUST_BE_LIST` | Search must be a list |\n| 400 | `FILTER_VALUE_INVALID` | Filter value is invalid |\n| 400 | `INVALID_BATCH_NAME_FILTER` | Invalid batch name filter |\n| 400 | `SUBUSERS_MUST_BE_LIST` | Subusers must be a list |\n| 400 | `SUBUSERS_ARE_INVALID` | Subusers are invalid |\n| 400 | `INVALID_SORT_VALUE` | Invalid sort value |\n| 400 | `INVALID_ORDER_TYPE` | Invalid order type |\n| 403 | `CANNOT_VIEW_HISTORY` | You cannot view history, contact provider |\n\n### POST /order — Place Bulk Order\n\n| HTTP | Code | Meaning |\n|------|------|---------|\n| 400 | `INVALID_IMEI` | Invalid IMEI(s) provided |\n| 400 | `SERVICE_ID_MUST_BE_NUMBER` | Service ID must be a number |\n| 400 | `INVALID_BATCH_NAME` | Invalid batch name |\n| 400 | `BATCH_NAME_REQUIRED` | Batch name is required |\n| 400 | `IMEI_MUST_BE_ARRAY` | IMEIs must be provided in an array |\n| 400 | `IMEI_REQUIRED` | IMEI is required |\n| 403 | `CREDIT_LIMIT_REACHED` | Credit limit reached |\n| 403 | `LOW_CREDIT` | Low credit |\n| 403 | `SERVICE_LIMIT_EXCEEDED` | Service limit exceeded |\n| 404 | `SERVICE_NOT_FOUND` | Service not found |\n| 405 | `SERVICE_IS_DISABLED` | Service is disabled |\n\n### POST /order/single — Place Single Order\n\n| HTTP | Code | Meaning |\n|------|------|---------|\n| 400 | `TAC_FAILED` | TAC validation failed |\n| 400 | `INVALID_IMEI_PROVIDED` | Invalid IMEI provided |\n| 400 | `SERVICE_ID_MUST_BE_NUMBER` | Service ID must be a number |\n| 400 | `BATCH_NAME_REQUIRED` | Batch name is required |\n| 400 | `IMEI_REQUIRED` | IMEI is required |\n| 403 | `CREDIT_LIMIT_REACHED` | Credit limit reached |\n| 403 | `LOW_CREDIT` | Low credit |\n| 404 | `SERVICE_NOT_FOUND` | Service not found |\n| 405 | `SERVICE_IS_DISABLED` | Service is disabled |\n\n### GET /order/single — Get Single Order\n\n| HTTP | Code | Meaning |\n|------|------|---------|\n| 400 | `INVALID_ORDER_ID` | Invalid order ID |\n| 404 | `ORDER_NOT_FOUND` | Order not found |\n\n### GET /batch — List Batches\n\n| HTTP | Code | Meaning |\n|------|------|---------|\n| 400 | `INVALID_PAGE_NUMBER` | Invalid page number |\n| 400 | `PAGE_NUMBER_INVALID` | Page number is invalid |\n| 400 | `INVALID_PAGE_SIZE` | Page size cannot exceed 5000 |\n| 400 | `PAGE_SIZE_INVALID` | Page size is invalid |\n| 400 | `MIN_PAGE_SIZE` | Page size minimum is 5 |\n| 400 | `BATCH_STATUS_INVALID` | Batch status not valid |\n| 400 | `SERVICE_ID_INVALID` | Service ID not valid |\n| 400 | `SUBUSERS_MUST_BE_LIST` | Subusers must be a list |\n| 400 | `SUBUSERS_ARE_INVALID` | Subusers are invalid |\n| 400 | `SEARCH_VALUE_IS_INVALID` | Search value is invalid |\n| 400 | `INVALID_BATCH_ID_PROVIDED` | Invalid batch ID provided |\n| 400 | `FROM_DATE_REQUIRED` | From date is required |\n| 400 | `INVALID_DATE_PROVIDED` | Invalid date provided |\n| 400 | `TO_DATE_REQUIRED` | To date is required |\n| 400 | `INVALID_SORT_VALUE` | Invalid sort value |\n\n### GET /service — List Services\n\n| HTTP | Code | Meaning |\n|------|------|---------|\n| 400 | `PAGE_NUMBER_INVALID` | Page number is invalid |\n| 400 | `PAGE_NUMBER_REQUIRED` | Page number is required |\n| 400 | `PAGE_SIZE_REQUIRED` | Page size is required |\n| 400 | `PAGE_SIZE_INVALID` | Page size is invalid |\n| 400 | `FILTER_VALUE_INVALID` | Filter value is invalid |\n", "version": "1.0", "contact": {} }, "tags": [ { "name": "Orders" }, { "name": "Batches" }, { "name": "Services" } ], "servers": [ { "url": "https://api.imeilookup.com" } ], "components": { "securitySchemes": { "api-key": { "type": "apiKey", "in": "header", "name": "access-key", "description": "Most REST endpoints expect your API key in the `access-key` header. `GET /order/browser` is the one exception and takes the key in the `key` query parameter. The IP allow-list applies to all REST endpoints, including `GET /order/browser`. Add your server's IP address to the allow-list in the [dashboard](https://app.imeilookup.com). See the [Authentication guide](/docs/authentication)." } }, "schemas": { "ErrorResponseDto": { "type": "object", "properties": { "message": { "description": "Application error code, or an array of codes or validation messages. Handle both shapes.", "oneOf": [ { "type": "string", "example": "INVALID_API_KEY" }, { "type": "array", "items": { "type": "string" }, "example": [ "PAGE_NUMBER_REQUIRED", "PAGE_SIZE_REQUIRED" ] } ] }, "error": { "type": "string", "example": "Bad Request", "description": "HTTP status text, when present" }, "statusCode": { "type": "number", "example": 400, "description": "HTTP status code" } }, "required": [ "message", "statusCode" ] }, "Object": { "type": "object", "properties": {} }, "BatchInfo": { "type": "object", "properties": { "id": { "type": "number", "example": 123, "description": "Batch ID" }, "title": { "type": "string", "example": "My Batch", "description": "Batch title" } }, "required": [ "id", "title" ] }, "ServiceInfo": { "type": "object", "properties": { "id": { "type": "number", "example": 10, "description": "Service ID" }, "title": { "type": "string", "example": "IMEI Check Pro", "description": "Service title" }, "price": { "type": "number", "example": 0.15, "description": "Service price per check" } }, "required": [ "id", "title", "price" ] }, "OrderItem": { "type": "object", "properties": { "id": { "type": "number", "example": 32344241, "description": "Order ID" }, "imei": { "type": "string", "example": "357619537445062", "description": "Identifier submitted (IMEI, serial number or MEID)" }, "status": { "type": "string", "enum": [ "Failed", "Waiting", "Success", "Processing" ], "example": "Success", "description": "Order status. `Success` and `Failed` are final; `Waiting` and `Processing` are not. Separate from batch state." }, "created": { "type": "string", "example": "2026-10-12T22:08:44.759Z", "description": "Creation timestamp (ISO 8601)" }, "updated": { "type": "string", "example": "2026-10-12T22:08:44.775Z", "description": "Last update timestamp (ISO 8601)" }, "result": { "type": "object", "nullable": true, "description": "Service-specific key/value pairs. The keys differ per service. `null` while the order is still processing.", "example": { "IMEI": "357619537445062", "Manufacturer": "Apple Inc", "Model Code": "A2403", "Model Name": "iPhone 12" } }, "orderCost": { "type": "number", "example": 0.01, "description": "Cost recorded for this order (for example 0.01)." }, "batch": { "type": "object", "description": "Batch this order belongs to", "properties": { "id": { "type": "number", "example": 9740938 }, "title": { "type": "string", "example": "Direct order" }, "service": { "type": "string", "example": "Any Make & Model Check [TAC DB]", "description": "Service title" }, "user": { "type": "object", "properties": { "username": { "type": "string", "example": "demouser" }, "role": { "type": "string", "example": "Main" } } } } } }, "required": [ "id", "imei", "status", "created", "batch" ] }, "OrderListResponseDto": { "type": "object", "properties": { "failed": { "type": "number", "example": 0, "description": "Number of orders in Failed status across all orders that match the filters, not only the orders on the returned page. The value does not change with `page` or `size`; it changes when you add or change filters such as `from` and `to`." }, "waiting": { "type": "number", "example": 0, "description": "Number of orders in Waiting status across all orders that match the filters, not only the orders on the returned page. The value does not change with `page` or `size`; it changes when you add or change filters such as `from` and `to`." }, "success": { "type": "number", "example": 1, "description": "Number of orders in Success status across all orders that match the filters, not only the orders on the returned page. The value does not change with `page` or `size`; it changes when you add or change filters such as `from` and `to`." }, "processing": { "type": "number", "example": 0, "description": "Number of orders in Processing status across all orders that match the filters, not only the orders on the returned page. The value does not change with `page` or `size`; it changes when you add or change filters such as `from` and `to`." }, "orders": { "type": "array", "items": { "$ref": "#/components/schemas/OrderItem" } } }, "required": [ "orders" ] }, "OrderGetSingleResponseDto": { "type": "object", "description": "Current state of the order. `result` is `null` until the order finishes.", "properties": { "id": { "type": "number", "example": 32344241, "description": "Order ID" }, "imei": { "type": "string", "example": "357619537445062", "description": "Identifier submitted (IMEI, serial number or MEID)" }, "status": { "type": "string", "enum": [ "Failed", "Waiting", "Success", "Processing" ], "example": "Success", "description": "Order status. `Success` and `Failed` are final; `Waiting` and `Processing` are not. Separate from batch state." }, "created": { "type": "string", "example": "2026-10-12T22:08:44.759Z", "description": "Creation timestamp (ISO 8601)" }, "updated": { "type": "string", "example": "2026-10-12T22:08:44.775Z", "description": "Last update timestamp (ISO 8601)" }, "result": { "type": "object", "nullable": true, "description": "Service-specific key/value pairs. The keys differ per service. `null` while the order is still processing.", "example": { "IMEI": "357619537445062", "Manufacturer": "Apple Inc", "Model Code": "A2403", "Model Name": "iPhone 12" } }, "batch": { "type": "object", "description": "Batch this order belongs to", "properties": { "id": { "type": "number", "example": 9740938 }, "title": { "type": "string", "example": "Direct order" }, "status": { "type": "string", "example": "Completed", "description": "Batch state. Exactly two values exist: `Pending` and `Completed`. Separate from the order statuses `Waiting`, `Processing`, `Success` and `Failed`.", "enum": [ "Pending", "Completed" ] }, "service": { "type": "string", "example": "Any Make & Model Check [TAC DB]", "description": "Service title" }, "user": { "type": "object", "properties": { "username": { "type": "string", "example": "demouser" }, "role": { "type": "string", "example": "Main" } } } } } }, "required": [ "id", "imei", "status", "created", "batch" ] }, "PlaceBulkOrdersDto": { "type": "object", "properties": { "serviceId": { "type": "number", "description": "Service ID to use for the order", "example": 10 }, "batchName": { "type": "string", "description": "Name of the batch. Required. The maximum length and allowed characters have not been confirmed; an invalid name returns `INVALID_BATCH_NAME`.", "example": "My Batch" }, "imeis": { "description": "List of identifiers to check (IMEI, serial number or MEID, depending on the service). Send each one as a string. Duplicates are removed.", "example": [ "357619537445062", "987654321012345" ], "type": "array", "items": { "type": "string" } }, "notify": { "type": "boolean", "description": "Whether to send email notification on completion", "example": false } }, "required": [ "serviceId", "batchName", "imeis" ] }, "OrderBulkResponseDto": { "type": "object", "properties": { "batchId": { "type": "number", "example": 456, "description": "ID of the created batch" }, "accepted": { "type": "number", "example": 95, "description": "Number of accepted identifiers" }, "rejected": { "type": "number", "example": 5, "description": "Number of rejected (invalid) identifiers" }, "duplicates": { "type": "number", "example": 3, "description": "Number of duplicate identifiers removed" } }, "required": [ "batchId", "accepted", "rejected", "duplicates" ] }, "PlaceSingleOrderDto": { "type": "object", "properties": { "serviceId": { "type": "number", "example": 10, "description": "Service ID from `GET /service`. Your account may not have access to every service." }, "batchName": { "type": "string", "example": "My Batch", "description": "Optional. If sent, it cannot be an empty string (`\"\"` returns `BATCH_NAME_REQUIRED`), so leave the field out instead. Without it the order goes into a batch named \"Direct order\"." }, "imei": { "type": "string", "example": "357619537445062", "description": "Identifier to check (IMEI, serial number or MEID, depending on the service). Send it as a string." } }, "required": [ "serviceId", "imei" ] }, "OrderSingleCreateResponseDto": { "description": "Either a completed order or a processing envelope.", "oneOf": [ { "$ref": "#/components/schemas/OrderCompletedResponse" }, { "$ref": "#/components/schemas/OrderProcessingResponse" } ] }, "BatchUserInfo": { "type": "object", "properties": { "role": { "type": "string", "example": "Main", "description": "User role" }, "username": { "type": "string", "example": "john_doe", "description": "Username" } }, "required": [ "role", "username" ] }, "BatchItem": { "type": "object", "properties": { "id": { "type": "number", "example": 123, "description": "Batch ID" }, "ip": { "type": "string", "example": "192.168.1.1", "description": "Requester IP address" }, "title": { "type": "string", "example": "My Batch", "description": "Batch title" }, "status": { "type": "string", "example": "Completed", "description": "Batch state. Exactly two values exist: `Pending` and `Completed`. Separate from the order statuses `Waiting`, `Processing`, `Success` and `Failed`.", "enum": [ "Pending", "Completed" ] }, "created": { "type": "string", "example": "2025-01-15T10:30:00.000Z", "description": "Creation timestamp" }, "orders": { "type": "number", "example": 95, "description": "Number of orders in this batch" }, "service": { "type": "string", "example": "Any Make & Model Check [TAC DB]", "description": "Service title" }, "user": { "description": "Batch owner info", "allOf": [ { "$ref": "#/components/schemas/BatchUserInfo" } ] } }, "required": [ "id", "ip", "title", "status", "created", "orders", "service", "user" ] }, "BatchListResponseDto": { "type": "object", "properties": { "total": { "type": "number", "example": 45, "description": "Total number of batches matching filters" }, "completed": { "type": "number", "example": 30, "description": "Number of completed batches" }, "batches": { "description": "Array of batch objects", "type": "array", "items": { "$ref": "#/components/schemas/BatchItem" } } }, "required": [ "total", "completed", "batches" ] }, "ServiceGroupInfo": { "type": "object", "properties": { "id": { "type": "number", "example": 1, "description": "Service group ID" }, "title": { "type": "string", "example": "IMEI Services", "description": "Service group title" } }, "required": [ "id", "title" ] }, "ServiceItem": { "type": "object", "properties": { "id": { "type": "number", "example": 10, "description": "Service ID" }, "title": { "type": "string", "example": "IMEI Check Pro", "description": "Service title" }, "price": { "type": "number", "example": 0.15, "description": "Service price per check" }, "limit": { "type": "number", "example": 500, "description": "Maximum IMEIs allowed per order" }, "featured": { "type": "boolean", "example": true, "description": "Whether the service is featured" }, "description": { "type": "string", "example": "Comprehensive IMEI check including blacklist status", "description": "Service description. Some services use this field for example lookup output rather than prose." }, "group": { "description": "Service group this service belongs to", "allOf": [ { "$ref": "#/components/schemas/ServiceGroupInfo" } ] }, "time": { "type": "string", "example": "Instant", "description": "Advertised turnaround. An estimate, not a guarantee." }, "telegramTitle": { "type": "string", "description": "Short title used in other channels" } }, "required": [ "id", "title", "price", "limit", "featured", "description", "group" ] }, "ServiceListResponseDto": { "type": "object", "properties": { "total": { "type": "number", "example": 25, "description": "Total number of services" }, "services": { "description": "Array of service objects", "type": "array", "items": { "$ref": "#/components/schemas/ServiceItem" } } }, "required": [ "total", "services" ] }, "OrderCompletedResponse": { "type": "object", "description": "The order finished within the server wait period.", "properties": { "id": { "type": "number", "example": 32344241, "description": "Order ID" }, "imei": { "type": "string", "example": "357619537445062", "description": "Identifier submitted (IMEI, serial number or MEID)" }, "status": { "type": "string", "enum": [ "Failed", "Waiting", "Success", "Processing" ], "example": "Success", "description": "Order status. `Success` and `Failed` are final; `Waiting` and `Processing` are not. Separate from batch state." }, "created": { "type": "string", "example": "2026-10-12T22:08:44.759Z", "description": "Creation timestamp (ISO 8601)" }, "updated": { "type": "string", "example": "2026-10-12T22:08:44.775Z", "description": "Last update timestamp (ISO 8601)" }, "result": { "type": "object", "nullable": true, "description": "Service-specific key/value pairs. The keys differ per service. `null` while the order is still processing.", "example": { "IMEI": "357619537445062", "Manufacturer": "Apple Inc", "Model Code": "A2403", "Model Name": "iPhone 12" } }, "batch": { "type": "object", "description": "Batch this order belongs to", "properties": { "id": { "type": "number", "example": 9740938 }, "title": { "type": "string", "example": "Direct order" }, "status": { "type": "string", "example": "Completed", "description": "Batch state. Exactly two values exist: `Pending` and `Completed`. Separate from the order statuses `Waiting`, `Processing`, `Success` and `Failed`.", "enum": [ "Pending", "Completed" ] }, "service": { "type": "string", "example": "Any Make & Model Check [TAC DB]", "description": "Service title" }, "user": { "type": "object", "properties": { "username": { "type": "string", "example": "demouser" }, "role": { "type": "string", "example": "Main" } } } } } }, "required": [ "id", "imei", "status", "created", "batch" ] }, "OrderProcessingResponse": { "type": "object", "description": "The order is still running. Only these fields are returned; poll `check_url` or `GET /order/single?id=`.", "properties": { "id": { "type": "number", "example": 32344246, "description": "Order ID" }, "batchId": { "type": "number", "example": 9740943, "description": "Batch ID" }, "status": { "type": "string", "enum": [ "Processing" ], "example": "Processing", "description": "Order status. Always `Processing` in this response." }, "check_url": { "type": "string", "example": "https://api.imeilookup.com/order/single?id=32344246", "description": "URL to poll for the final result" } }, "required": [ "id", "batchId", "status", "check_url" ] } } } }