Botim性别年龄检测API

检测Botim注册状态，并为已注册手机号补充性别和年龄数据。

产品参数

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

estimated_amount 根据账号当前定价计算，该任务应以此预估金额为准。

输入格式

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

+14155552671
+442071838750

创建任务

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

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

上传响应

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

查询任务状态

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

持续轮询直到 status 变为 exported。pending 和 processing 均不表示任务已完成。

处理中响应

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

导出响应

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

结果字段

字段	描述	示例
number / Number	输入手机号。CSV列名为 number，XLSX列名为 Number。	+14155552671
activated	该手机号是否检测到对应账号。	yes / no
gender	已注册Botim账号检测到的性别。	Male / Female / Unknown
age	已注册Botim账号检测到的年龄或年龄段。	25-34

未检测到账号的行会返回 activated=no；没有画像数据时，画像字段为空。

结果文件处理

仅在任务导出后通过 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轮询。
• 只有格式有效且规范化后的手机号计入最低数量。
• 任务失败时按平台计费流程自动退款。