Workflow Overview

Bulk detection runs asynchronously: you submit numbers, receive a task_id, poll for progress, then download the result file.

Endpoints at a Glance

Endpoint	Method	Purpose
/v1/balance	GET	Check your current USD balance
/v1/detect	POST	Submit a JSON array of phone numbers
/v1/detect/file	POST	Submit a TXT/CSV file upload
/v1/tasks/{task_id}	GET	Poll task status
/v1/tasks/{task_id}/result	GET	Get the result download URL

Before You Submit

• Volume: 1,000 to 2,000,000 numbers per request.
• Number format: include the international country code, e.g. +8613800138000.
• Country: pass the ISO 3166-1 alpha-2 code (for example CN or US).

Cost is pre-deducted

Cost is pre-deducted for the full submission. Numbers that end up unchecked (prefiltered, deduplicated, or not processed upstream) are automatically refunded when the task finalizes — you only pay for numbers actually processed.