cURL 请求
POST /api/v1/bulk-taskscurl -X POST "https://api.carrierlookup.online/api/v1/bulk-tasks" \
-H "X-API-Key: sk_your_api_key" \
-F service_type=number_validation_batch \
-F country=US \
-F [email protected]两步接入：提交文件，再查询任务
提交后立刻返回任务号；之后按任务号查询状态，任务成功时响应里会带上结果文件的下载链接。下面每个请求都配上它自己的响应。
1. 提交文件
立即返回任务号，此时 preparing 为 true，后台正在预处理文件：去掉无效行、重复行，号码任务还会去掉没带国家码和不属于所选国家的号码，这些都不计费。按提交行数冻结余额，完成后按实际用量结算，差额退回。
响应：任务已创建
200 OK{
"code": 0,
"msg": "ok",
"data": {
"id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
"product": "number_validation_batch",
"status": "processing",
"country": "US",
"submitted_lines": 509,
"total": 509,
"invalid_cnt": 0,
"no_code_cnt": 0,
"other_country_cnt": 0,
"duplicate_cnt": 0,
"preparing": true,
"created_at": "2026-09-08T09:30:00Z"
}
}2. 查询任务
按任务号轮询。预处理完成后恒有 submitted_lines = total + invalid_cnt + no_code_cnt + other_country_cnt + duplicate_cnt，其中 total 是实际检测并计费的条数。任务成功时响应里带成功/失败计数和结果文件下载链接；预处理阶段被拒的任务为 failed，带 reason_detail，并全额退款。
cURL 请求
GET /api/v1/bulk-tasks/{id}curl "https://api.carrierlookup.online/api/v1/bulk-tasks/3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13" \
-H "X-API-Key: sk_your_api_key"响应：任务已完成
200 OK{
"code": 0,
"msg": "ok",
"data": {
"id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
"product": "number_validation_batch",
"status": "success",
"country": "US",
"submitted_lines": 509,
"total": 500,
"invalid_cnt": 3,
"no_code_cnt": 0,
"other_country_cnt": 0,
"duplicate_cnt": 6,
"preparing": false,
"success_cnt": 495,
"failure_cnt": 5,
"result_url": "https://…/result.csv",
"created_at": "2026-09-08T09:30:00Z"
}
}一个批量任务是怎么跑完的
批量不是把实时检测放大 —— 它是一次提交、后台执行、稍后取件。整个过程您不需要守着页面，任务状态和结果都留在后台。
01上传号码文件
一行一个号码的 .txt 或 .csv。文件流式提交，服务器不保存文件副本。
02预检并冻结余额
空文件、格式明显不对、行数不足等问题在上传时直接拒绝；通过后冻结余额，文件进入后台预处理：去除重复行和无效行，并校验国家一致性。预处理不通过的任务会标记为失败并全额退款；通过的只检测剩下的条目，完成后结算。
03后台执行
任务在后台跑，您可以关掉页面。失败会立即反馈并全额退款。
04下载结果文件
完成后在批量检测页下载。只按实际返回结果的号码计费，差额自动退回。
结果文件里有哪些列
下载的是一份 CSV 文件，就是完整的结果表。
结果文件的列
identifier·12345678900— 提交的号码，统一为带国家码的纯数字、不含加号和空格（例如 12345678900），是结果与客户、线索或 CRM 记录对应的稳定键。保留它可以让团队快速追溯原名单并批量回写结果；它本身不代表号码一定可联系。activated·true— 号码有效性／激活判定：true 表示本项检测命中，false 表示明确未命中。缺失结果或执行失败不能补成 false；该字段不证明身份、联系许可或电话可接通。
什么时候该用这一款
注册名单复核
批量导入注册或线索名单后，将结果与表单资料、反作弊规则及授权状态一起复核；这是异步名单检查，不替代注册时的实时验证码验证。
下载后以 identifier 关联原始记录，保留名单来源，方便人工追溯。
关联字段：identifier
名单清洗
导出后按激活信号标记记录，保留原始号码和来源字段；对无信号或异常项安排二次核查，不要直接删除业务数据。
将明确的 true、false 与缺失结果分别处理；缺失项保留在待复核队列。
分组字段：activated
CRM 数据治理
将检测日期、产品和结果写入独立 CRM 字段，方便营销、客服与数据团队在后续流程中查看同一份名单状态。
将本次结果与团队自己记录的任务日期一起保存；需要更新时重新提交任务。
回写字段：identifier · activated
号码有效性（批量）是什么？
在触达前批量检查 E.164 格式号码，返回号码与激活信号。将结果用于标记需要核查的记录、清理名单并维护 CRM 数据质量；结果仅反映返回信号，不保证电话接通或消息送达。
这款产品的使用限制
- 请按所选产品理解 activated：号码有效性／激活信号或活跃性信号，不包含具体活跃日期或频率。
- 结果不能证明身份或联系许可，也不保证电话可接通或消息可送达。
- 结果不会自动刷新。如需重新检测，请提交新任务。
关于号码有效性的常见问题
true、false 和没有结果分别代表什么？
true 是本项检测命中，false 是明确未命中；两者都是已获得的判定，不能把 false 当成执行失败或免费项。缺失结果、无法判定与执行失败应结合任务统计和最终结算单独处理，不能自动补为 false。
能判断最近几天活跃或保证送达吗？
不能。当前结果不包含活跃时间窗口、最后活跃日期、频率或互动明细，也不能保证电话接通或消息送达。请将信号与您自己的业务数据和联系许可共同使用。
是否支持实时检测？
本产品仅支持异步文件任务。实时运营商查询不返回号码有效性或活跃性信号。
文件里有无效号码会怎样？
预检阶段会剔除格式不合法的行，它们不计入计费基数。剩下的号码里，上游没能返回结果的那部分也不收费。只对真正拿到结果的号码计价。
任务要跑多久？
取决于号码量与产品类型。提交后可以关掉页面，任务在后台执行，完成后在批量检测页下载结果。
失败了钱会退吗？
会。任务失败全额退款。任务成功但部分号码没出结果，那部分自动退回。提交时冻结的余额与最终实收的差额始终会退。