cURL 请求
POST /api/v1/bulk-taskscurl -X POST "https://carrierlookup.online/api/v1/bulk-tasks" \
-H "X-API-Key: sk_your_api_key" \
-F service_type=carrier_batch \
-F country=US \
-F file=@numbers.txt接口约定
两步接入：提交文件，再查询任务
提交后立刻返回任务号；之后按任务号查询状态，任务成功时响应里会带上结果文件的下载链接。下面每个请求都配上它自己的响应。
1. 提交文件
按有效行数冻结相应余额，任务进入后台执行，完成后按实际用量结算。
响应：任务已创建
200 OK{
"code": 0,
"msg": "ok",
"data": {
"id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
"product": "carrier_batch",
"status": "processing",
"country": "US",
"total": 1000,
"created_at": "2026-09-08T09:30:00Z"
}
}2. 查询任务
按任务号轮询。任务成功时响应里带成功/失败计数和结果文件下载链接。
cURL 请求
GET /api/v1/bulk-tasks/{id}curl "https://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": "carrier_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"
}
}执行方式
一个批量任务是怎么跑完的
批量不是把实时检测放大 —— 它是一次提交、后台执行、稍后取件。整个过程你不需要守着页面，任务状态和结果都留在后台。
01上传号码文件
一行一个号码的 .txt 或 .csv。文件流式提交，服务器不保存文件副本。
02预检并冻结余额
先校验格式与国家一致性，再按有效行数冻结余额，完成时结算。预检不通过不扣费。
03后台执行
任务在后台跑，你可以关掉页面。失败会立即反馈并全额退款。
04下载结果文件
完成后在批量检测页下载。只按实际返回结果的号码计费，差额自动退回。
结果字段
结果文件里有哪些列
下载的是一个 zip，里面是完整的结果表。
结果文件的列
number·17253100591— 提交并写入结果文件的原始号码。carrier·T-Mobile— 号码最初被分配给的运营商；不代表携号转网后的当前运营商。underlying_carrier— 平台返回的底层运营商信息；未提供时为空。number_type·Fixed Line or Mobile— 平台返回的线路类型，例如固定电话或移动号码。country_code·US— 号码归属的 ISO 国家代码。region·NV— 号段归属地区；平台未提供时为空。city·LAS VEGAS— 号段归属城市；平台未提供时为空。
适用场景
什么时候该用这一款
名单分群
将整份号码名单按原始运营商、线路类型和归属国家或地区整理，形成可下载的数据分组。
路由成本核对
利用批量结果中的运营商和地区字段核对内部路由、采购或成本记录，减少逐条查询。
数据库清理
发现缺失原始归属运营商、地区或城市信息的号码记录，为资料补全和人工复核建立清单。也可将空值、信息不完整和与现有资料不一致的记录分开整理，避免它们混入后续的数据分析。
建议处理：先标记待复核记录，再导出清单交由数据管理员补全；完成后重新入库或重新查询。
直接答案
全球运营商查询（批量）是什么？
批量运营商查询面向一千条起步的名单：上传文件后任务在后台执行，完成后下载结果压缩包。上传时选定号码所属国家：它会随文件一起提交，用于补全没带国家码的号码，文件也按它校验。
能力边界
这款产品的使用限制
- 结果描述的是号码最初被分配到的网络。它不跟踪携号转网，因此未必是当前为该号码提供服务的运营商。
- 它不是可达性检测，也不是身份认证：既不说明号码是否在用，也不说明归属于谁。
- 检测不会向文件里的任何号码发送内容 —— 查询针对的是号段分配数据。
- 结果反映任务执行那一刻的状态。需要最新状态请重新提交；已存结果不会自动刷新。
- 下载链接会过期。任务完成后尽快取文件；链接失效后重新查询该任务可拿到新链接。
适用判断
什么时候用批量，什么时候实时更合适
| 实时检测 | 批量检测 | |
|---|---|---|
| 号码数量 | 单号 1 个；多号一次可提交多个，具体上限见 API 文档 | 一次跑完整份大名单——当前数量区间见价格页 |
| 拿到结果 | 当场出结果：单号与 API 多号在同一次响应里，网页多号逐个返回 | 任务跑完后下载结果文件 |
| 国家 | 无需选择 —— 每个号码自带国家码，一次请求里可以混放 | 每个任务选定一个国家，上传时选，随文件一起提交 |
| 结果形态 | JSON，逐号字段 | 结果文件（zip，含完整表与分组名单） |
| 典型用途 | 表单校验、客服复核、发送前实时拦截 | 名单清洗、投放前筛选、存量数据治理 |
产品常见问题
关于全球运营商查询的常见问题
什么时候用批量，什么时候用实时检测？
整份大名单用批量。号码不多时用实时检测：同一次请求就出结果，不需要等任务调度。
文件里有无效号码会怎样？
预检阶段会剔除格式不合法的行，它们不计入计费基数。剩下的号码里，上游没能返回结果的那部分也不收费。只对真正拿到结果的号码计价。
任务要跑多久？
取决于号码量与产品类型。提交后可以关掉页面，任务在后台执行，完成后在批量检测页下载结果。
失败了钱会退吗？
会。任务失败全额退款。任务成功但部分号码没出结果，那部分自动退回。提交时冻结的余额与最终实收的差额始终会退。