Number Active Check API: Bulk Number Activity Detection

Detect the activity level of phone numbers in your uploaded list using big data analytics combined with device system, carrier, and internet behavior APIs. Improves SMS delivery success rates and reduces operational costs. Uses task_type active_check and the same batch polling flow as other checkers.

Upload detection file — example:

curl --location 'https://api.checknumber.ai/v1/tasks' \
--header 'X-API-Key: API-KEY' \
--form 'file=@"./numbers.txt"' \
--form 'task_type="active_check"'

Check task status — example:

curl --location 'https://api.checknumber.ai/v1/gettasks' \
--header 'X-API-Key: API-KEY' \
--form 'task_id="task_id"'

Response after upload succeeds

{
    "task_id": "d4g8o46p2jvh04o9uolg",
    "status": "pending",
    "total": 5000,
    "estimated_amount": {
        "amount": "0.500000",
        "currency": "USD"
    },
    "message": "Task created successfully",
    "created_at": "2025-11-21T15:58:08.916446594Z"
}

Response while processing

{
    "created_at": "2025-11-21T08:27:09.933Z",
    "updated_at": "2025-11-21T08:27:10.241Z",
    "task_id": "d4g24nep2jvh04o9uoh0",
    "user_id": "wfi7wGPS4B4PdtTMox5Y",
    "status": "processing",
    "total": 5000,
    "success": 2500,
    "failure": 0
}

Response when finished (exported)

{
    "created_at": "2025-11-21T08:27:09.933Z",
    "updated_at": "2025-11-21T08:27:10.241Z",
    "task_id": "d4g24nep2jvh04o9uoh0",
    "user_id": "wfi7wGPS4B4PdtTMox5Y",
    "status": "exported",
    "total": 5000,
    "success": 5000,
    "failure": 0,
    "result_url": "https://example-link-to-results.zip",
    "actual_amount": {
      "amount": "2.000000",
      "currency": "USD"
    }
}

Upload file request URL

POST https://api.checknumber.ai/v1/tasks

Upload file request parameters

Parameter	Description
`file`	`file`, one phone number per line (E.164 recommended, e.g. `+14155552671`)
`task_type`	`string`, set to `active_check`

Check task status request URL

POST https://api.checknumber.ai/v1/gettasks

Check task status request parameters

Parameter	Description
`task_id`	`string`, Task ID returned from task creation

Result fields

Field	Description
`Number`	Phone number in E.164 format
`ActiveStatus`	Activity level of the number: `active`, `inactive`, or `unknown`

Response format

Field	Description
`created_at`	Timestamp when task was created
`updated_at`	Timestamp of last task status update
`task_id`	Unique task identifier
`user_id`	User ID
`status`	`pending` · `processing` · `exported` · `failed` (refunded automatically)
`total`	Total numbers submitted
`success`	Numbers successfully checked
`failure`	Rows that could not be processed
`result_url`	Download URL when `status` is `exported`
`actual_amount`	(Optional) Actual charged amount, returned after the task is settled
`estimated_amount`	(Create response) Estimated amount for the task; the final charge is settled when the task completes

Status codes

Status	Description
`200`	`free`, Request successful (e.g. status query)
`202`	`charge`, Task created successfully; the estimated amount is deducted
`400`	`free`, Bad request: invalid parameters or file format, unsupported task type, or fewer valid entries than the minimum batch size
`401`	`free`, Missing or invalid API key
`402`	`free`, Insufficient account balance
`404`	`free`, Task not found
`413`	`free`, Uploaded file too large
`500`	`free`, Internal server error, retry later