Botim CheckNumber API: Bulk Registration Check

Check whether phone numbers are registered on Botim. Submit a batch file, poll the task, and download the exported results.

Product parameters

Parameter	Value
Task type	botim
Input type	Phone number in E.164 format
Minimum valid entries	500

The amount in estimated_amount is calculated from the pricing configured for your account and is authoritative for that task.

Input format

Upload a .txt or .csv file with one phone number per line. E.164 format is recommended.

+14155552671
+442071838750

Create a task

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

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

The API returns a task ID. Keep it and use it to poll the task status.

Upload response

{
  "task_id": "d4g8o46p2jvh04o9uolg",
  "status": "pending",
  "total": 500,
  "estimated_amount": {
    "amount": "0.250000",
    "currency": "USD"
  },
  "message": "Task created successfully"
}

Check task status

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

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

Poll until status becomes exported. pending and processing are not completed states.

Processing response

{
  "task_id": "d4g8o46p2jvh04o9uolg",
  "status": "processing",
  "total": 500,
  "success": 250,
  "failure": 0
}

Exported response

{
  "task_id": "d4g8o46p2jvh04o9uolg",
  "status": "exported",
  "total": 500,
  "success": 500,
  "failure": 0,
  "result_url": "https://example-link-to-results.zip",
  "actual_amount": {
    "amount": "0.250000",
    "currency": "USD"
  }
}

Result fields

Field	Description	Example
number / Number	Input phone number. The CSV column is number; the XLSX column is Number.	+14155552671
activated	Whether an account was detected for the number.	yes / no

Rows without a detected account have activated=no; profile fields are empty when no profile data is available.

Result file handling

Download the result package from result_url only after the task is exported. Preserve the returned column names in downstream processing.

Response fields

Field	Description
created_at	Task creation timestamp.
updated_at	Latest task update timestamp.
task_id	Unique task identifier.
status	pending, processing, exported, or failed.
total	Total valid input values.
success	Values processed successfully.
failure	Values that failed processing.
result_url	Download URL after export.
actual_amount	Final settled amount, when available.
estimated_amount	Estimated amount returned at task creation.

Status codes

Status	Description
200	Request successful.
202	Task created and estimated charge applied.
400	Invalid file, unsupported task type, or fewer valid entries than the minimum.
401	Missing or invalid API key.
402	Insufficient balance.
404	Task not found.
413	Uploaded file is too large.
500	Internal server error; retry later.

Operational notes

• The task is asynchronous; poll with the returned task ID.
• Only valid, normalized phone numbers count toward the minimum batch size.
• A failed task is refunded automatically according to the platform billing flow.