NumDetect API: submit phone lists and download task results

1. 1.Create an API key in Settings.
2. 2.Call GET /api/v1/balance to check the current balance.
3. 3.Upload a number file to /api/v1/bulk-tasks, then poll the task by ID and download the result when ready.

Use an API key created in Settings and send it with every request.

X-API-Key: sk_your_api_key

Bulk task submissions are accepted before work starts. Use the returned task status to decide whether to keep polling or handle a failure.

• 5 requests in flight per userA task submission uses one request slot. If the account has no slot available, the API returns 42901 with Retry-After; wait and submit the file again.
• Poll instead of waitingSubmitting a task returns immediately. Poll its status no more than once every 30 seconds while it is processing.
• Task size follows the productEach product has its own minimum and maximum file size, shown in the task section.

Submit a .txt or .csv phone list and get a task id straight away. Check the task by that id; once it succeeds, the response carries the result file download link.

• number_validation_batchPhone Number Validation1,000–100,000 phone numbers per task$0.001 per phone number
• number_activity_batchNumber Activity1,000–100,000 phone numbers per task$0.003 per phone number
• number_high_value_batchHigh-Value Users1,000–100,000 phone numbers per task$0.004 per phone number
• number_ecommerce_batchE-commerce Active1,000–100,000 phone numbers per task$0.003 per phone number
• global_carrier_batchGlobal carrier lookup1,000–100,000 phone numbers per task$0.001 per phone number

curl -X POST "https://numdetect.com/api/v1/bulk-tasks" \
  -H "X-API-Key: sk_your_api_key" \
  -F service_type=number_validation_batch \
  -F country=US \
  -F file=@numbers.txt

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "number_validation_batch",
    "status": "processing",
    "country": "US",
    "total": 1000,
    "created_at": "2026-09-08T09:30:00Z"
  }
}

curl "https://numdetect.com/api/v1/bulk-tasks/3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13" \
  -H "X-API-Key: sk_your_api_key"

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "number_validation_batch",
    "status": "success",
    "country": "US",
    "total": 1000,
    "success_cnt": 990,
    "failure_cnt": 10,
    "result_url": "https://…/result.zip",
    "created_at": "2026-09-08T09:30:00Z"
  }
}

• One phone number per line.Upload a .txt or .csv with one phone number per line. Use the product code that matches the enrichment you need; the submitted file must meet that product's size limits.
• No per-phone number progress.status is processing, success or failed. Large lists take a while; do not poll more often than once every 30 seconds.
• Billing.The full file is reserved on submit. When the task finishes you are charged only for the phone numbers that were actually checked and the rest is refunded. A failed task is refunded in full.
• Result files expire.The download link is generated on demand and points at a time-limited file. Download the result soon after the task finishes.