电话运营商查询 API：一次请求，一个原始运营商结果
将一个 E.164 格式号码发送至运营商查询 API，读取原始运营商和号码类型，并处理空结果、无法判定及超时情况。
本文为开发人员提供单号码电话运营商查询 API 的调用指南，涵盖请求发送、结果读取、错误处理以及何时切换至多号码请求。
电话运营商查询 API 从您的服务器接收一个电话号码，并返回该号码段最初分配的运营商及其相关背景信息。使用 CarrierLookup 时，受信任的后端将一个 E.164 格式号码发送至 POST /api/v1/check 并携带 X-API-Key 请求头，即可同步获得结果：原始运营商、底层运营商、号码类型、国家代码以及分配的地区和城市。该运营商信息为原始分配结果，而非携号转网后的网络。包含空字段的已完成结果仍属于已完成的查询，而无法判定的查询则会返回非零的业务代码。若单次调用需查询最多 100 个号码，请切换至 POST /api/v1/batch-check。
电话运营商查询 API 的返回内容
许多运营商查询页面混淆了两个不同的问题：该号码段最初分配给了谁，以及谁在今天提供服务。CarrierLookup 旨在回答前者。其运营商结果指明了根据国家编号计划最初分配该号码块的运营商。在存在携号转网的国家，用户可以在更换服务提供商的同时保留原号码，正如 FCC 携号转网指南 所述，因此原始运营商与当前服务提供商可能不同。
一个以通俗语言描述的已完成单号码结果包含：
- 原始运营商：该号码段最初分配的运营商。
- 底层运营商：该运营商背后的网络（若有可用值）。
- 号码类型：号码段的类型，例如移动电话或固定电话。
- 国家代码、地区和城市：号码段的分配地，而非个人或设备的当前位置。
请将这些信息视为用于分组、路由测试和审查的分配背景。运营商结果并不表明号码处于服务状态、能否接收呼叫或短信，也不代表该号码属于特定个人。
向运营商查询 API 发送一个号码
单号码路由是一个简短的同步请求。典型的集成遵循以下五个步骤：
- 将密钥保存在受信任的服务器上。 REST API 通过 X-API-Key 请求头进行身份验证。请从您的后端或作业运行程序中调用，切勿在浏览器或移动应用代码中调用，以免密钥被窃取。
- 将输入标准化为 E.164 格式。 ITU-T E.164 建议书 定义了国际格式。CarrierLookup 要求包含前导加号、国家代码和用户号码，且不含空格、连字符或括号。例如，英国号码 020 7946 0000 应转换为 +442079460000。当已知记录的国家/地区时，可以使用 libphonenumber 等库来解析本地格式。
- 发送至 POST /api/v1/check。 每次请求一个号码。无需单独选择国家，因为国家代码已包含在号码中。
- 等待同步响应。 结果会在同一响应中返回；无需轮询。
- 存储带有查询日期的结果。 分配数据对于号码段而言是稳定的，但记录每次查询的执行时间有助于简化审计。
如果输入因格式问题被拒绝，请修正号码后重新发送。格式拒绝并不代表运营商信息缺失。
读取已完成、空结果和无法判定的结果
最常见的集成错误是将三种不同的结果视为一种。请先根据业务代码进行分支判断，然后再处理具体数值。
| 结果 | 响应显示内容 | 处理方式 |
|---|---|---|
| 已完成且有值 | 成功代码，且填充了运营商、类型和分配值 | 将数值写入您的记录 |
| 已完成但为空 | 成功代码，部分或全部运营商字段为空 | 存储为“不可用”；这仍是一次已完成的、计费的查询 |
| 无法判定 | 非零业务代码及消息 | 不要将空值存储为结果；稍后重试或转入审查 |
| 格式被拒绝 | 关于输入的错误信息 | 修正号码；这不是“无运营商”的答案 |
根据上表，需遵循两条规则。其次，无法判定的查询并非成功的空结果，因此切勿将其中的空字段写入您的 CRM。失败或无法判定的查询不会扣费，而已完成的查询即使字段为空也会扣费。
底层运营商、地区或城市等可选字段在已完成的结果中可能为空。请在设计架构时确保每个字段均可独立为空。
处理超时、并发和余额
公共 API 文档规定了一组使用控制，而非每分钟的配额。一个账户拥有五个共享的同步请求并发槽位，且同一时间只能运行一个多号码请求。单号码请求的文档化超时上限为 60 秒，因此请将 HTTP 客户端的超时时间设置得略高于此值，而非仅设置几秒。
实际处理建议：
- 使用队列而非并发洪流。 如果您的注册或导入作业产生突发流量，请保持一个小型的任务池，以确保并发查询数不超过五个。
- 间隔重试无法判定的结果。 使用延迟和重试上限；频繁的立即重试通常无效。
- 记录业务代码和消息。 它们比单纯的 HTTP 状态码更能解释失败原因。
- 在不消耗余额的情况下读取余额。 GET /api/v1/balance 可免费返回剩余余额，适合在大规模作业前进行预检。
关于您账户的当前限制，请查阅 API 文档，而非硬编码假设；API 不会发布固定的每日请求上限。
何时切换至 POST /api/v1/batch-check 或文件任务
单号码路由适用于事件驱动的工作：表单提交、新的 CRM 记录、支持人员检查单个联系人。一旦作业需要定期同时处理多个号码，每个号码调用一次会增加开销。
- POST /api/v1/batch-check 支持在一次同步请求中处理 1 到 100 个 E.164 号码，且号码可来自不同国家。结果按输入顺序返回，因此您可以按位置映射每一行。每一行都包含一个 exists 标志；false 表示该行没有正常结果，并不代表号码无效或已断开连接。如果多号码请求超时，整个请求将失败且不返回部分结果，预扣金额将全额退回，因此请保持批次适中并重试该批次。
- 仪表板 支持无需代码即可进行最多 500 个号码的同步多号码查询。
- 批量文件任务 适用于完整列表：针对选定国家/地区异步上传 TXT 或 CSV 文件，轮询直至生成单个 CSV 文件。适用各产品的限制；请参阅 API 文档。
AI 助手也可以通过官方 MCP 端点使用相同的查询功能，该端点涵盖单号码和多号码检查，但不包含文件任务。
常见问题解答
团队如何区分空的运营商结果和失败的查询？
在读取任何数值之前，请先检查业务代码。带有空运营商字段的成功代码表示查询已完成，应存储为“不可用”。非零代码表示查询无法判定或失败；不应将其作为结果写入，记录可稍后重试或送交审查。将这两条路径分开处理，可避免将有效的记录标记为缺失数据。
运营商查询 API 是否显示号码当前使用的网络？
不显示。运营商数值是号码段最初分配的运营商。在用户携号转网后，即使服务已转移到其他地方，结果中的原始运营商仍保持不变。需要分配背景以进行分组、路由测试或审查的团队可直接使用该信息；它不应被视为当前服务网络或联系方式。
前端是否应直接调用运营商查询 API？
不应该。X-API-Key 请求头授予了对账户余额的访问权限，因此调用应在受信任的服务器上进行。一种常见的模式是前端将电话号码提交给您自己的后端，由后端将其标准化为 E.164，调用 POST /api/v1/check，存储结果并仅返回界面显示所需的内容。
了解更多
选择符合您工作流程下一步的产品信息。