完整示例

以下示例均使用公开基础地址。把 YOUR_KEY_HERE 换成认证里创建的 Key，YOUR_PRODUCT_SLUG 请到批量产品列表取——批量接口一律用 slug 指定产品，不用数字 ID。

https://api.zelnum.com/api/v1

1. 查询余额

curl -X GET "https://api.zelnum.com/api/v1/balance" \
  -H "X-API-Key: YOUR_KEY_HERE"

批量任务在提交时预扣费用，所以余额不足会在提交那一刻失败，而不是做到一半才断。

2. 提交号码检测

curl -X POST "https://api.zelnum.com/api/v1/detect" \
  -H "X-API-Key: YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "product": "YOUR_PRODUCT_SLUG",
    "country": "CN",
    "phones": ["+8613800138000", "+8613900139000"]
  }'

返回 202 和 task_id。邮件类产品请完全去掉 country。

3. 上传文件检测

curl -X POST "https://api.zelnum.com/api/v1/detect/file" \
  -H "X-API-Key: YOUR_KEY_HERE" \
  -F "product=YOUR_PRODUCT_SLUG" \
  -F "country=CN" \
  -F "file=@/path/to/numbers.txt"

每行一条号码或邮箱。行数来自文件，因此 message 与数组提交不同——响应体的其余部分完全一致。

4. 查询任务进度

curl -X GET "https://api.zelnum.com/api/v1/tasks/xKj9aP3qLm7v" \
  -H "X-API-Key: YOUR_KEY_HERE"

每 3-5 秒轮询一次，直到 status 为 completed 或 failed。请盯着 last_progress_at：时间戳停止变化意味着任务卡住了，而不只是慢。

5. 获取下载链接

curl -X GET "https://api.zelnum.com/api/v1/tasks/xKj9aP3qLm7v/result" \
  -H "X-API-Key: YOUR_KEY_HERE"

请在 expires_at 之前取回该链接指向的文件——保留期一过结果文件即被删除。

需要马上查一条？

批量适合成千上万条、可以等的场景。如果只是查一个号码或邮箱、要立刻拿到结论，请改用实时调用示例。