API 文档
实时电话号码验证 API：一个电话号码，一次请求，同一次响应返回
向 /api/v1/bulk-tasks 提交文件任务，随后轮询任务状态并下载结果。每款产品都有自己的起批量和单价。
API 接口POST
/api/v1/bulk-tasksX-API-Key 请求头code · msg · data
最后更新：2026 年 8 月 31 日service_type=phone_validation读取 data.registered
API 速览使用 API Key 提交电话号码文件、查询任务状态，并下载已完成的结果。所有接口统一使用 code / msg / data 响应结构。
快速接入
- 1.在设置中创建 API Key。
- 2.通过 GET /api/v1/balance 查询当前余额。
- 3.将号码文件提交到 /api/v1/bulk-tasks，然后按任务 ID 查询状态，完成后下载结果。
认证
使用在设置中创建的 API Key，并随每次请求一起发送。
X-API-Key: sk_your_api_key妥善保管你的 API Key
请始终从你的服务端发起请求；持有该 Key 的任何人都可以消耗你的账户余额。并发、超时与重试方式
批量任务提交后会立刻返回。请根据任务状态决定继续轮询或处理失败。
- 每个用户最多 5 个请求在处理一次任务提交占用一个请求名额。没有可用名额时，接口返回 42901 并带 Retry-After；等待后重新提交文件。
- 通过轮询获取结果提交任务会立即返回。任务处于 processing 时，轮询频率不要超过每 30 秒一次。
- 任务规模按产品确定每个产品都有自己的最小和最大文件数量，见任务章节。
错误码
40000不支持的 service_type 或字段冲突
40001JSON 请求体无效
40002电话号码无效
40100缺少或无效的 API Key
40200余额不足
42200当前形式的任务无法受理
42900次数配额已用完，或未完成订单数超限
42901所有请求名额已满；等已有请求结束后再提交。拒绝请求不扣余额，响应带 Retry-After
50303平台此刻处理中的检测已达上限，不扣费；按 Retry-After 的秒数等待后重新提交同一请求
50400本次请求未在超时预算内完成，不计费，可直接重试
50300检测服务维护中
异步批量任务
上传电话号码文件，立刻拿到任务号；之后按任务号查询状态。任务成功后，查询响应里会带上结果文件的下载链接；偶尔会暂缺，稍后再查一次即可。整套接口只有这两个动作，文件每行一个电话号码。
number_validation_batch号码有效性检测每个任务 1,000–100,000 个电话号码$0.001 / 电话号码number_activity_batch号码活跃度检测每个任务 1,000–100,000 个电话号码$0.003 / 电话号码number_high_value_batch高价值用户检测每个任务 1,000–100,000 个电话号码$0.004 / 电话号码number_ecommerce_batch电商活跃检测每个任务 1,000–100,000 个电话号码$0.003 / 电话号码global_carrier_batch全球运营商查询每个任务 1,000–100,000 个电话号码$0.001 / 电话号码
1. 提交文件
curl -X POST "https://numdetect.com/api/v1/bulk-tasks" \
-H "X-API-Key: sk_your_api_key" \
-F service_type=number_validation_batch \
-F country=US \
-F file=@numbers.txt响应：任务已创建（status 为 processing）
{
"code": 0,
"msg": "ok",
"data": {
"id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
"product": "number_validation_batch",
"status": "processing",
"country": "US",
"total": 1000,
"created_at": "2026-09-08T09:30:00Z"
}
}2. 查询任务
curl "https://numdetect.com/api/v1/bulk-tasks/3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13" \
-H "X-API-Key: sk_your_api_key"响应：任务已完成（成功时带 result_url）
{
"code": 0,
"msg": "ok",
"data": {
"id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
"product": "number_validation_batch",
"status": "success",
"country": "US",
"total": 1000,
"success_cnt": 990,
"failure_cnt": 10,
"result_url": "https://…/result.zip",
"created_at": "2026-09-08T09:30:00Z"
}
}- 一行一个电话号码。上传 .txt 或 .csv，一行一个电话号码。选择与你所需数据对应的产品码，文件数量必须符合该产品的范围。
- 不提供逐号进度。status 只有 processing、success、failed 三种。大名单需要一段时间，轮询不要快于 30 秒一次。
- 计费方式。提交时按整份文件冻结。任务结束后只对真正检测到结果的电话号码收费，其余退回；任务失败则全额退款。
- 结果文件有时效。下载链接是按需生成的，指向一个有时效的文件，请在任务完成后尽快下载。