Skip to main content

Placing orders and polling

Most lookups finish within one request. Some take longer. This guide explains what the API returns in each case and how to handle it without creating duplicate (and duplicate-charged) orders.

Order statuses​

An order has one of these statuses. They are the only values orderStatus accepts on GET /order.

StatusMeaningFinal?
WaitingThe order is queued.No
ProcessingThe lookup is running.No
SuccessThe lookup finished and has a result.Yes
FailedThe lookup failed.Yes

Keep polling while the status is Waiting or Processing; stop at Success or Failed. Pending is not an order status. Filtering orders by Pending returns ORDER_STATUS_INVALID.

Batch states​

A batch has its own state, separate from the statuses of the orders inside it. A batch has exactly two states: Pending and Completed. For example, an order can be Processing while its batch is Pending. Use the batch status filter on GET /batch for batch states and orderStatus on GET /order for order statuses; do not use one vocabulary in the other filter.

Success and processing responses​

POST /order/single waits up to 55 seconds for the result. It returns the result sooner if it is ready. It returns one of two shapes. This applies to the single-order endpoint only, not to bulk orders or DHRU.

Success within the wait:

{
  "id": 123456,
  "batchId": 789,
  "status": "Success",
  "result": "..."
}

Still processing after the wait:

{
  "id": 123456,
  "batchId": 789,
  "status": "Processing",
  "check_url": "https://api.imeilookup.com/order/single?id=123456"
}

Check status rather than assuming the order finished. For a processing order, fetch GET /order/single?id=ORDER_ID until it reaches Success or Failed.

The exact fields are on the endpoint page; the examples above show the shape.

Set your client timeout above 55 seconds​

Because the API can hold a request for up to 55 seconds, a client timeout at or below that can fire while the order is still running. Use a longer timeout for POST /order/single, for example 70 seconds. The 55 seconds is a waiting limit for the HTTP request. It is not an order expiry, and it does not cancel the order or charge you again.

Never resubmit automatically​

A timeout, dropped connection or 5xx does not mean the order failed. The order may have been created. If your code retries the POST on its own, you can create (and be charged for) a second order.

Instead, recover the order:

  1. Send each request with a unique batchName (for example your own job ID).

  2. After an ambiguous failure, look the order up:

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

  3. Only submit again if no matching order exists.

Polling example​

Poll with a delay and a limit, and stop on a final status.

async function waitForOrder(id, apiKey, { intervalMs = 3000, maxAttempts = 40 } = {}) {
  for (let attempt = 0; attempt < maxAttempts; attempt++) {
    const res = await fetch(`https://api.imeilookup.com/order/single?id=${id}`, {
      headers: { 'access-key': apiKey },
    });
    if (!res.ok) throw new Error(`HTTP ${res.status}`);
    const order = await res.json();
    if (order.status === 'Success' || order.status === 'Failed') return order;
    await new Promise((resolve) => setTimeout(resolve, intervalMs));
  }
  throw new Error(`Order ${id} still not finished; check it later`);
}

The 3-second interval is only an illustration. When the loop gives up, the order is not cancelled. Fetch it again later.

Bulk orders​

POST /order accepts several identifiers in one request and creates a batch. The response counts what happened to the submitted list. For example, sending one valid identifier twice plus one invalid identifier reports:

{
  "accepted": 1,
  "rejected": 1,
  "duplicates": 1
}

Accepted means the order was created, not that the lookup succeeded. Fetch the batch or its orders to see the final status of each one.

In that example the counts add up to the three submitted entries. Duplicates are removed within the same request, and rejected and duplicate numbers are not charged.

Failed orders are not charged.

Last updated on