注册并联系客服，免费领取 100 次检测。免费注册
CarrierLookup
接口参考

CarrierLookup API 文档

所有端点共用同一个 API Key 与余额。

项目值
Base URLhttps://api.carrierlookup.online
鉴权头X-API-Key: sk_your_api_key
响应结构{ code, msg, data }

本页不列价格；每款产品按成功检测计费。 查看定价

认证

使用在设置中创建的 API Key，并随每次请求一起发送。

鉴权头
X-API-Key: sk_your_api_key

妥善保管您的 API Key请始终从您的服务端发起请求；持有该 Key 的任何人都可以消耗您的账户余额。

同步检测

POST/api/v1/checkPOST/api/v1/batch-check

提交一个手机号，或在一次请求里提交最多 100 个，结果都在同一次响应里返回，不需要轮询也不需要回调。无法判定时返回 422 与业务码 42200，且不计费。多号请求保持提交顺序、每个标识独立计费，整批限时 300 秒，超时则整批失败并全额退款。

请求参数

字段类型说明
service_typestring产品码，取下面列出的任一产品。
identifierstring单号检测用：一个手机号。服务端会做归一化。
identifiersstring[]多号检测用：1~100 个手机号，响应按此顺序返回。

本类产品

原始归属运营商查询

carrier手机号

查一个号码最初被分配给哪家运营商，并返回线路类型与归属地。

单号检测

POST/api/v1/check
请求
curl -X POST "https://api.carrierlookup.online/api/v1/check" \
  -H "X-API-Key: sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "service_type": "carrier", "identifier": "+12345678900" }'
{
  "code": 0,
  "msg": "ok",
  "data": {
    "service_type": "carrier",
    "identifier": "+12345678900",
    "carrier": "T-Mobile",
    "underlying_carrier": "",
    "number_type": "Fixed Line or Mobile",
    "country_code": "US",
    "region": "OH",
    "city": "AKRON"
  }
}
响应字段
字段类型说明
carrierstring号码最初被分配给的运营商。不是携号转网后的当前运营商。
underlying_carrierstring上游返回的底层运营商（与号段分配的运营商不同时才有值）；上游未提供时为空串。
number_typestring上游返回的线路类型；上游未给时为空。
country_codestring号码所属的 ISO 国家代码。
regionstring号段归属地区；上游未提供时为空。
citystring号段归属城市；上游未提供时为空。

多号检测

POST/api/v1/batch-check
请求
curl -X POST "https://api.carrierlookup.online/api/v1/batch-check" \
  -H "X-API-Key: sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "service_type": "carrier", "identifiers": ["+12345678900", "12345"] }'
响应
{
  "code": 0,
  "msg": "ok",
  "data": {
    "service_type": "carrier",
    "total": 2,
    "succeeded": 1,
    "failed": 1,
    "results": [
      {
        "identifier": "+12345678900",
        "exists": true,
        "carrier": "T-Mobile",
        "underlying_carrier": "",
        "number_type": "Fixed Line or Mobile",
        "country_code": "US",
        "region": "OH",
        "city": "AKRON"
      },
      {
        "identifier": "12345",
        "exists": false
      }
    ]
  }
}
响应字段
字段类型说明
existsboolean该号码是否得到了结果。为 false 表示号码格式错误、结果无法判定或本次检测失败；为 false 时，以下字段均不出现。
carrierstring号码最初被分配给的运营商。不是携号转网后的当前运营商。
underlying_carrierstring上游返回的底层运营商（与号段分配的运营商不同时才有值）；上游未提供时为空串。
number_typestring上游返回的线路类型；上游未给时为空。
country_codestring号码所属的 ISO 国家代码。
regionstring号段归属地区；上游未提供时为空。
citystring号段归属城市；上游未提供时为空。

异步检测

POST/api/v1/bulk-tasksGET/api/v1/bulk-tasks/{id}

上传文件后立刻拿到任务号，之后按任务号查询；成功的响应里带 result_url 结果下载链接。对外只有提交与查询两个动作，轮询间隔不要短于 30 秒。

请求参数

字段类型说明
service_typestring批量产品码，取下面列出的任一产品。
countrystringISO 3166-1 国家码（如 US）。号码类任务必填：每个号码都要带国家码并属于这个国家（不符合的号码会被排除、不计费），也用它选路。multipart 时必须排在 file 之前。
filefile.txt 或 .csv，每行一个标识，不超过 max_file_bytes（默认 20MB）。
Idempotency-Keyheader可选，≤128 字符。同一个 key 重放返回原任务，不会重复建单。

本类产品

全球运营商查询

carrier_batch手机号每任务 1,000–500,000

上传整份号码文件，批量返回每个号码的运营商、底层运营商、线路类型、国家、地区与城市——与实时运营商查询的字段一致。

提交任务

POST/api/v1/bulk-tasks
请求
curl -X POST "https://api.carrierlookup.online/api/v1/bulk-tasks" \
  -H "X-API-Key: sk_your_api_key" \
  -F service_type=carrier_batch \
  -F country=US \
  -F [email protected]
响应
{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "carrier_batch",
    "status": "processing",
    "country": "US",
    "submitted_lines": 1015,
    "total": 1015,
    "invalid_cnt": 0,
    "no_code_cnt": 0,
    "other_country_cnt": 0,
    "duplicate_cnt": 0,
    "preparing": true,
    "created_at": "2026-09-08T09:30:00Z"
  }
}

查询任务

GET/api/v1/bulk-tasks/{id}
请求
curl "https://api.carrierlookup.online/api/v1/bulk-tasks/3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13" \
  -H "X-API-Key: sk_your_api_key"
响应
{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "carrier_batch",
    "status": "success",
    "country": "US",
    "submitted_lines": 1015,
    "total": 1000,
    "invalid_cnt": 3,
    "no_code_cnt": 0,
    "other_country_cnt": 0,
    "duplicate_cnt": 12,
    "preparing": false,
    "success_cnt": 990,
    "failure_cnt": 10,
    "result_url": "https://…/result.csv",
    "created_at": "2026-09-08T09:30:00Z"
  }
}
结果列
字段示例说明
identifier12345678900提交的号码，统一为带国家码的纯数字，不含加号和空格（例如 12345678900）。
carrierT-Mobile号码最初被分配给的运营商。不是携号转网后的当前运营商。
underlying_carrier上游返回的底层运营商（与号段分配的运营商不同时才有值）；上游未提供时为空串。
number_typeFixed Line or Mobile上游返回的线路类型，例如 Fixed Line or Mobile；上游未给时为空。
country_codeUS号码所属的 ISO 国家代码。
regionCA号段归属地区；上游未提供时为空。
cityLOS ANGELES号段归属城市；上游未提供时为空。

余额查询

GET/api/v1/balance

查询账户当前余额（USD micros）。只读接口：不产生检测记录，也不扣费。

余额查询

GET/api/v1/balance
请求
curl "https://api.carrierlookup.online/api/v1/balance" \
  -H "X-API-Key: sk_your_api_key"
响应
{
  "code": 0,
  "msg": "ok",
  "data": {
    "balance_micros": 12500000
  }
}

并发、超时与重试方式

运营商查询采用同步响应，请根据返回码决定接收结果或稍后重试。

字段说明
每个用户最多 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查询服务维护中