Number Active Check API: Bulk Phone 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,
    "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"
}

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
total	Total numbers submitted
success	Numbers successfully checked
failure	Rows that could not be processed
result_url	Download URL when status is exported

Status codes

Status	Description
200	charge, request successful
400	free, bad request
500	free, server error