POST/api/v6/numberinsight/batch

Batch lookup

Resolve many numbers in a single request, inline or as an asynchronous job.

Scope

Any valid API key

Usage limit

10 requests per minute

Idempotency

Supports Idempotency-Key

Synchronous mode: up to 500 numbers per request.
Asynchronous mode: plain UTF-8 text file, one number per line, each line at most 64 characters.
A job result stays available for about 90 days from creation.

Processes many numbers in a single request. There are two modes, chosen by the Content-Type.

Synchronous: application/json with { "numbers": [...] }, up to 500 numbers. Resolved inline, returns 200 with { "results": [...] }.
Asynchronous: multipart/form-data with file (plain text, one number per line) and an optional webhookUrl. Queues a job and returns 202 with a jobId.

When the asynchronous job finishes, the numberinsight.batch.completed event is dispatched and the NDJSON result becomes available through a temporary download URL exposed by the status endpoint.

The contract for the events this service emits lives in Number Insight webhooks.

Headers

Idempotency-Key

stringoptional

Optional idempotency key (1 to 255 characters from A-Za-z0-9_-). Repeating the same operation with the same key returns the original response without running it again. See the idempotency guide.

Request body

application/jsonSynchronous mode.

numbers

arrayrequired

Numbers to resolve. Same format as the single lookup.

{
  "numbers": ["3001234567", "6017430000", "+5491123456789"]
}

multipart/form-dataAsynchronous mode.

file

filerequired

Plain UTF-8 text file, one number per line (each line at most 64 characters).

webhookUrl

stringoptional

Optional URL to receive the numberinsight.batch.completed event when the job finishes.

Responses

200

Synchronous mode: resolved inline.

{
  "success": true,
  "data": {
    "results": [
      {
        "phoneNumber": {
          "e164": "+573001234567",
          "national": "3001234567",
          "raw": "3001234567"
        },
        "valid": true,
        "country": { "iso2": "CO", "callingCode": "57", "name": "Colombia", "mcc": "732" },
        "lineType": "mobile",
        "numberType": "mobile",
        "ported": false,
        "operator": { "name": "Tigo", "brand": "Tigo", "mnc": "103", "nrn": "103" },
        "area": null,
        "timezone": null,
        "portability": null,
        "zone": { "id": "103", "name": "Tigo" }
      }
    ]
  },
  "meta": {
    "requestId": "b9b1704baffab21150213c02fd853975",
    "timestamp": "2026-06-02T19:43:59+00:00",
    "responseTimeMs": 4.1
  }
}

202

Asynchronous mode: job accepted and queued.

{
  "success": true,
  "data": {
    "jobId": "4e2c8b91-3f12-4ad6-9b91-09e8e9c5e7a1",
    "status": "queued",
    "count": 12450,
    "expiresAt": "2026-09-15T14:00:00Z"
  },
  "meta": {
    "requestId": "b9b1704baffab21150213c02fd853975",
    "timestamp": "2026-06-02T19:43:59+00:00",
    "responseTimeMs": 4.1
  }
}

400

Missing numbers in synchronous mode, malformed body, or an idempotency key that does not match the format.

401

Invalid or missing credentials.

409

A request with the same idempotency key is still in progress.

413

The synchronous batch exceeded 500 numbers: use the asynchronous mode.

422

The asynchronous file is invalid (not text, lines longer than 64 characters, or empty), or the idempotency key was reused with a different body.

429

Request limit exceeded.

503

The lookup service is refreshing. Retry in a few seconds.

Possible errors

Codes this endpoint can return in error.code. The full detail lives in the catalog.

401AUTH_REQUIREDNo Bearer token was sent, and every call requires one.401AUTH_INVALID_KEYThe API key is not recognized: wrong format, revoked or expired.400BAD_REQUESTWe could not parse your request.400IDEMPOTENCY_KEY_INVALIDThe idempotency key does not match the format.409IDEMPOTENCY_IN_PROGRESSThe first request with that key is still in progress.422IDEMPOTENCY_KEY_REUSEDThe key already exists, but with a different body.429RATE_TPS_EXCEEDEDYou exceeded your organization quota for this endpoint.503INFRA_CACHE_UNAVAILABLEAn internal component is temporarily unavailable.

See the full catalog

Scope and limits

Headers

Request body

Responses

Possible errors