> 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-hao-ma-jian-ce-api-pi-liang-zhu-ce-jian-cha.md).

# Botim号码检测API：批量注册检查

批量检测手机号是否注册Botim。上传号码文件、轮询任务状态，并在完成后下载结果。

## 产品参数

| 参数     | 值            |
| ------ | ------------ |
| 任务类型   | `botim`      |
| 输入类型   | E.164格式的手机号码 |
| 最少有效条数 | 500          |

{% hint style="info" %}
`estimated_amount` 根据账号当前定价计算，该任务应以此预估金额为准。
{% endhint %}

## 输入格式

上传 `.txt` 或 `.csv` 文件，每行一个手机号，建议使用E.164格式。

```
+14155552671+442071838750
```

{% stepper %}
{% step %}

## 创建任务

`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"'
```

API会返回任务ID。请保存该ID，用于后续轮询任务状态。
{% endstep %}

{% step %}

## 查询任务状态

`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"'
```

持续轮询直到 `status` 变为 `exported`。`pending` 和 `processing` 均不表示任务已完成。
{% endstep %}
{% endstepper %}

## 上传响应

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

## 处理中响应

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

## 导出响应

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

## 结果字段

| 字段                  | 描述                                      | 示例           |
| ------------------- | --------------------------------------- | ------------ |
| `number` / `Number` | 输入手机号。CSV列名为 `number`，XLSX列名为 `Number`。 | +14155552671 |
| `activated`         | 该手机号是否检测到对应账号。                          | yes / no     |

{% hint style="info" %}
未检测到账号的行会返回 `activated=no`；没有画像数据时，画像字段为空。
{% endhint %}

## 结果文件处理

仅在任务导出后通过 `result_url` 下载结果包。下游处理时请保留返回的列名。

## 响应字段

| 字段                 | 描述                                            |
| ------------------ | --------------------------------------------- |
| `created_at`       | 任务创建时间。                                       |
| `updated_at`       | 任务最近更新时间。                                     |
| `task_id`          | 任务唯一标识。                                       |
| `status`           | `pending`、`processing`、`exported` 或 `failed`。 |
| `total`            | 有效输入总数。                                       |
| `success`          | 成功处理的条数。                                      |
| `failure`          | 处理失败的条数。                                      |
| `result_url`       | 任务导出后的下载地址。                                   |
| `actual_amount`    | 最终结算金额（如有）。                                   |
| `estimated_amount` | 创建任务时返回的预估金额。                                 |

## 状态码

| 状态    | 描述                        |
| ----- | ------------------------- |
| `200` | 请求成功。                     |
| `202` | 任务创建成功并应用预估费用。            |
| `400` | 文件无效、任务类型不支持，或有效条数低于最低要求。 |
| `401` | API Key缺失或无效。             |
| `402` | 账户余额不足。                   |
| `404` | 任务不存在。                    |
| `413` | 上传文件过大。                   |
| `500` | 服务器内部错误，请稍后重试。            |

## 操作说明

* 任务为异步处理，请使用返回的任务ID轮询。
* 只有格式有效且规范化后的手机号计入最低数量。
* 任务失败时按平台计费流程自动退款。


---

# 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-hao-ma-jian-ce-api-pi-liang-zhu-ce-jian-cha.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.