API 文档
实时运营商查询 API：一个手机号，一次请求，同一次响应返回
核心是单号实时查询：向 /api/v1/check 提交一个手机号并带上 service_type=carrier。运营商结果在同一次响应里返回，不需要轮询，也不需要回调。同一个 API Key 还能一次提交多个号码，同步返回结果。
API 接口POST
/api/v1/checkX-API-Key 请求头code · msg · data
最后更新：2026 年 9 月 18 日service_type=carrier读取 data.extra
API 速览主接口是单号实时检测；多号、异步批量和余额接口共用同一份 API Key 约定，并统一使用 code / msg / data 响应结构。
快速接入
- 1.在设置中创建 API Key。
- 2.通过 GET /api/v1/balance 查询当前余额。
- 3.向 /api/v1/check 提交一个手机号，或向 /api/v1/batch-check 一次提交最多 100 个。
- 4.读取同步响应中的 data.extra。
认证
使用在设置中创建的 API Key，并随每次请求一起发送。
X-API-Key: sk_your_api_key妥善保管你的 API Key
请始终从你的服务端发起请求；持有该 Key 的任何人都可以消耗你的账户余额。产品与返回字段
carrier原始归属运营商查询
查一个号码最初被分配给哪家运营商，并返回线路类型与归属地。
01
单号检测
curl -X POST "https://carrierlookup.online/api/v1/check" \
-H "X-API-Key: sk_your_api_key" \
-H "Content-Type: application/json" \
-d '{ "service_type": "carrier", "identifier": "+14155552671" }' 已返回结果
{
"code": 0,
"msg": "ok",
"data": {
"service_type": "carrier",
"identifier": "+14155552671",
"registered": true,
"extra": {
"carrier": "T-Mobile USA",
"number_type": "mobile",
"country_code": "US",
"region": "California",
"city": "San Francisco"
}
}
} 无分配数据
{
"code": 0,
"msg": "ok",
"data": {
"service_type": "carrier",
"identifier": "+14155550000",
"registered": false,
"extra": {
"carrier": "",
"number_type": "",
"country_code": "",
"region": "",
"city": ""
}
}
}字段类型说明
registeredboolean该号码是否查到了号段分配数据。为 false 表示这次查询没有返回任何内容。
extra.carrierstring号码最初被分配给的运营商。不是携号转网后的当前运营商。
extra.number_typestring上游返回的线路类型；上游未给时为空。
extra.country_codestring号码所属的 ISO 国家代码。
extra.regionstring号段归属地区；上游未提供时为空。
extra.citystring号段归属城市；上游未提供时为空。
02
多号检测
计费：按手机号计算
请求中的每个手机号独立计费，单次最多提交 100 个手机号。只有成功完成检测的手机号才会消耗余额。如果余额不足以覆盖整批手机号的最高可能费用，请求会在处理前直接拒绝。
一次请求最多提交 100 个手机号，结果按提交顺序返回。
curl -X POST "https://carrierlookup.online/api/v1/batch-check" \
-H "X-API-Key: sk_your_api_key" \
-H "Content-Type: application/json" \
-d '{ "service_type": "carrier", "identifiers": ["+14155552671", "+14155550000"] }'{
"code": 0,
"msg": "ok",
"data": {
"service_type": "carrier",
"total": 2,
"succeeded": 1,
"failed": 1,
"results": [
{
"identifier": "+14155552671",
"exists": true,
"registered": true,
"extra": {
"carrier": "T-Mobile USA",
"number_type": "mobile",
"country_code": "US",
"region": "California",
"city": "San Francisco"
}
},
{
"identifier": "+14155550000",
"exists": false
}
]
}
}字段类型说明
existsboolean该手机号是否得到了结果。为 false 表示手机号格式错误、结果无法判定或本次检测失败；为 false 时，以下字段均不出现。
registeredboolean该号码是否查到了号段分配数据。仅在 exists 为 true 时出现，含义与单号查询一致。
extra.carrierstring号码最初被分配给的运营商。不是携号转网后的当前运营商。
extra.number_typestring上游返回的线路类型；上游未给时为空。
extra.country_codestring号码所属的 ISO 国家代码。
extra.regionstring号段归属地区；上游未提供时为空。
extra.citystring号段归属城市；上游未提供时为空。
并发、超时与重试方式
运营商查询采用同步响应，请根据返回码决定接收结果或稍后重试。
- 每个用户最多 5 个请求在处理单号检测与多号检测共用这个上限，一次多号请求算一个请求，与手机号数量无关。此外每个账号同时只能跑 1 个多号检测，第二个会被拒绝直到前一个结束。达到任一上限都会立即返回业务码 42901 并附带 Retry-After 响应头，不扣费，等已有请求结束后再提交即可。
- 单号 60 秒，多号 300 秒超过后返回业务码 50400，不计费；多号超时是整批失败，不返回部分结果，已扣费用全额退回。
- 多号单次最多 100 个手机号结果按提交顺序、同等长度返回。每个账号同时只跑 1 个多号检测，上一批返回后再提交下一批。
错误码
40000不支持的 service_type 或字段冲突
40001JSON 请求体无效
40002手机号无效
40100缺少或无效的 API Key
40200余额不足
42200暂时无法判定该手机号。不返回 data，且本次不计费
42900次数配额已用完，或未完成订单数超限
429015 个在处理的请求名额已满，或该账号已有一个多号检测在跑；已有请求结束后可再次提交，拒绝请求不扣余额，响应带 Retry-After
50303平台此刻处理中的检测已达上限，不扣费；按 Retry-After 的秒数等待后重新提交同一请求
50400本次检测未在超时预算内完成，不计费，可直接重试；批量超时为整批失败并全额退款
50300检测服务维护中
异步批量任务
上传号码文件后立刻拿到任务号，之后按任务号查询状态；成功后会给出结果压缩包的下载链接。
global_carrier_batch全球运营商查询每个任务 1,000–100,000 个手机号$0.001 / 手机号
1. 提交文件
curl -X POST "https://carrierlookup.online/api/v1/bulk-tasks" \
-H "X-API-Key: sk_your_api_key" \
-F service_type=global_carrier_batch \
-F country=US \
-F file=@numbers.txt响应：任务已创建（status 为 processing）
{
"code": 0,
"msg": "ok",
"data": {
"id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
"product": "global_carrier_batch",
"status": "processing",
"country": "US",
"total": 1000,
"created_at": "2026-09-08T09:30:00Z"
}
}2. 查询任务
curl "https://carrierlookup.online/api/v1/bulk-tasks/3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13" \
-H "X-API-Key: sk_your_api_key"响应：任务已完成（成功时带 result_url）
{
"code": 0,
"msg": "ok",
"data": {
"id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
"product": "global_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"
}
}- 一行一个手机号。上传 .txt 或 .csv，每行一个 E.164 格式的手机号。随文件提交 `country`：它用于补全没带国家码的号码，文件也按它校验。
- 不提供逐号进度。status 只有 processing、success、failed 三种。大名单需要一段时间，轮询不要快于 30 秒一次。
- 计费方式。提交时按整份文件冻结。任务结束后只对真正检测到结果的手机号收费，其余退回；任务失败则全额退款。
- 结果文件有时效。下载链接是按需生成的，指向一个有时效的文件，请在任务完成后尽快下载。