API 文档 — BulkChecker

认证说明

所有接口均需在请求头携带 API Key。

http

X-API-Key: YOUR_API_KEY

API Key 可在控制台「API 中心」页面查看或重新生成。密钥仅在生成时完整显示一次，请立即保存。

响应格式

所有接口统一返回 JSON。

json

{
  "mode": "async",
  "task_id": "xKj9aP3qLm7v",
  "message": "Task queued.",
  "summary": {
    "total": 5000,
    "cost_deducted": 0.500000
  }
}

GET /v1/balance

查询余额

查询当前账号的可用 USDT 余额。

响应示例

json

{ "balance": "5.230000" }

POST /v1/detect

提交检测（号码数组）

提交号码数组发起检测任务，异步处理。费用按提交总数预扣，完成后自动退回无法检测部分。

单次提交数量 1,000 ~ 2,000,000 条号码。号码格式需包含国际区号，如 +8613800138000。

请求参数

字段	类型	必填	说明
product	string	是	产品 slug，见产品列表。
country	string	是	ISO 3166-1 二位国家码，例如 CN、US。
phones	array	是	号码数组，1,000 到 2,000,000 条。

响应示例

json

{
  "mode": "async",
  "task_id": "xKj9aP3qLm7v",
  "message": "Task queued. Poll GET /api/v1/tasks/xKj9aP3qLm7v for progress.",
  "summary": {
    "total": 5000,
    "cost_deducted": 0.500000
  }
}

POST /v1/detect/file

提交检测（上传文件）

上传 TXT 或 CSV 文件批量检测，每行一个号码，最大 50 MB。

请求参数

Content-Type: multipart/form-data

字段	类型	必填	说明
product	string	是	产品 slug
country	string	是	ISO 国家码
file	file	是	TXT 或 CSV，每行一条号码，最大 50 MB。

响应示例

json

{
  "mode": "async",
  "task_id": "qH5rZ7Lp3Wm9",
  "message": "File queued (10000 numbers). Poll GET /api/v1/tasks/qH5rZ7Lp3Wm9 for progress.",
  "summary": {
    "total": 10000,
    "cost_deducted": 1.000000
  }
}

GET /v1/tasks/{task_id}

查询任务进度

轮询任务执行状态，建议间隔 3-5 秒，直到 status 为 completed 或 failed。

响应示例

json

{
  "task_id": "xKj9aP3qLm7v",
  "status": "completed",
  "progress": 100,
  "product": "whatsapp-active",
  "country": "CN",
  "total": 5000,
  "processed": 5000,
  "valid": 3800,
  "invalid": 1200,
  "unknown": 0,
  "cost_deducted": "0.500000",
  "cost_refunded": "0.000000",
  "result_available": true,
  "result_expires_at": "2026-05-02T10:00:00+00:00",
  "created_at": "2026-05-01T10:00:00+00:00"
}

任务状态

status	说明
pending	已提交，等待分配资源。
processing	检测进行中。
completed	已完成，可下载结果。
failed	执行失败。

GET /v1/tasks/{task_id}/result

获取下载地址

任务完成后获取结果文件下载链接，结果文件默认保留 7 天（由系统设置 result_retention_days 控制）。

响应示例

json

{
  "task_id": "xKj9aP3qLm7v",
  "download_url": "https://api.bulkchecker.io/api/v1/tasks/xKj9aP3qLm7v/download",
  "expires_at": "2026-05-02T10:00:00+00:00",
  "summary": {
    "total": 5000,
    "valid": 3800,
    "invalid": 1200,
    "unknown": 0
  }
}

错误码

请求失败时 HTTP 状态码与 message 字段说明如下。

HTTP	错误信息	处理建议
401	Unauthenticated	检查 X-API-Key 请求头是否正确携带。
402	Insufficient balance.	账户余额不足，请充值后重试。
404	Not found	task_id 不存在或不属于当前账号。
422	参数验证失败	检查必填字段、号码格式和文件类型。
429	Too Many Requests	检测接口限速 10 次/分钟，请降低请求频率。

产品列表

提交任务时 product 字段填写以下 slug 值。

产品名称	Slug
Amazon 注册检测	`amazonValid`
Amazon 邮箱检测	`amazonemailValid`
Apple ID 注册检测	`appleidValid`
Apple ID 邮箱检测	`appleidEmailValid`
BAND 注册检测	`bandValid`
Binance 注册检测	`binanceValid`
Binance 邮箱检测	`binanceEmailValid`
CoinW 注册检测	`coinwValid`
CoinW 邮箱检测	`coinwEmailValid`
Facebook 注册检测	`fbValid`
Facebook 邮箱检测	`fbemailValid`
HLR 查询	`hlr-lookup`
HTX 注册检测	`htxValid`
HTX 邮箱检测	`htxEmailValid`
iMessage 注册检测	`imessageValid`
Instagram 注册检测	`instagram`
Instagram 邮箱检测	`insEmailValid`
KuCoin 注册检测	`kucoinValid`
KuCoin 邮箱检测	`kucoin`
LINE 性别年龄	`lineGender`
LINE 注册检测	`lineValid`
Linkedn全格式	`linkednAll`
号码检测	`linkedn`
Microsoft 注册检测	`microsoftValid`
RCS 注册检测	`RCSValid`
Signal 注册检测	`signalValid`
Snapchat 注册检测	`snapchatValid`
Telegram 全格式	`tgGender`
Telegram 注册检测	`tgValid`
Telegram 活跃检测	`tgActive`
TikTok 用户名查询	`tkUsername`
Viber 注册检测	`viberValid`
Viber 活跃检测	`viberActive`
WhatsApp 全格式	`wsGender`
WhatsApp 注册检测	`wsValid`
WhatsApp 活跃检测	`wsActive`
Zalo 性别年龄	`zaloGender`
Zalo 注册检测	`zaloValid`
互联网活跃筛选	`internet-activity-filter`
号码状态检测	`phone-status-check`
手机型号检测	`phone-model-detection`
空号检测（中国）	`cnActiveNumber`

完整示例

以下为 cURL 完整调用示例，复制后替换 YOUR_API_KEY 和参数即可运行。

1. 查询余额

bash

curl -X GET "https://api.bulkchecker.io/api/v1/balance" \
  -H "X-API-Key: YOUR_API_KEY"

2. 提交号码检测

bash

curl -X POST "https://api.bulkchecker.io/api/v1/detect" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "product": "whatsapp-active",
    "country": "CN",
    "phones": ["+8613800138000", "+8613900139000"]
  }'

3. 上传文件检测

bash

curl -X POST "https://api.bulkchecker.io/api/v1/detect/file" \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "product=whatsapp-active" \
  -F "country=CN" \
  -F "file=@/path/to/numbers.txt"

4. 查询任务进度

bash

curl -X GET "https://api.bulkchecker.io/api/v1/tasks/xKj9aP3qLm7v" \
  -H "X-API-Key: YOUR_API_KEY"

5. 获取下载链接

bash

curl -X GET "https://api.bulkchecker.io/api/v1/tasks/xKj9aP3qLm7v/result" \
  -H "X-API-Key: YOUR_API_KEY"