Submit Numbers

POST/v1/detect

Submit an array of phone numbers or email addresses for detection. Processed asynchronously. Cost is pre-deducted; unchecked rows are automatically refunded.

Returns HTTP 202 Accepted.

Parameters

Field	Type	Required	Description
product	string	Yes	Product slug. See the bulk product list.
country	string	Required for phone	ISO 3166-1 alpha-2 country code, for example CN or US — the full list is on the Country Codes page. Omit it for email products.
phones	array	Yes	Array of phone numbers or email addresses from a single series.

How many rows

The submission must meet the selected product’s minimum — 500, 1,000 or 2,000 depending on the product, and shown in the bulk product list — and stay under the platform maximum of 2,000,000. A submission below the minimum is rejected as too_few_numbers.

Country is a phone-only field

Email has no country dimension. Sending country with an email product fails validation. This is the mirror of the realtime endpoints, where country is optional but must be omitted for email.

Response Example

{
  "mode": "async",
  "task_id": "xKj9aP3qLm7v",
  "idempotent_replay": false,
  "message": "Task queued. Poll GET /api/v1/tasks/xKj9aP3qLm7v for progress.",
  "recovery_pending": false,
  "summary": {
    "total": 5000,
    "cost_deducted": 0.500000
  }
}

Response fields

Field	Type	Description
mode	string	Always async for bulk submissions.
task_id	string	Token you poll and download with. This is the {token} path parameter of the task endpoints.
idempotent_replay	boolean	true when the submission reused an earlier task instead of creating a new one.
recovery_pending	boolean	true when the task is queued but its accounting is still being reconciled.
message	string	Human-readable next step.
summary.total	integer	Rows accepted.
summary.cost_deducted	number	Amount pre-deducted for the submission.

Store task_id — it is the only handle you get on the work, and it is not recoverable from your numbers afterwards.

Next

• Submit a file instead of an array
• Poll task status until the work finishes