> For the complete documentation index, see [llms.txt](https://docs.geeknums.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.geeknums.io/botim-checknumber-api-bulk-registration-check.md).

# 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                          |

{% hint style="info" %}
The amount in `estimated_amount` is calculated from the pricing configured for your account and is authoritative for that task.
{% endhint %}

## Input format

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

```
+14155552671+442071838750
```

{% stepper %}
{% step %}

## Create a task

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

```bash
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

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

{% endstep %}

{% step %}

## Check task status

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

```bash
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

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

### Exported response

```json
{  "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"  }}
```

{% endstep %}
{% endstepper %}

## 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     |

{% hint style="info" %}
Rows without a detected account have `activated=no`; profile fields are empty when no profile data is available.
{% endhint %}

## 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.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.geeknums.io/botim-checknumber-api-bulk-registration-check.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.