号码状态查询 API
通过本接口，您可以对全球范围内的手机号码进行状态查询，获取号码的有效性、归属运营商、漫游、转网等详细信息。该 API 提供两种服务级别：Basic 和 Premium。
-
Basic：提供基础数据（如国家代码、原始归属运营商、号码格式验证）。需要注意的是，Basic 仅返回号码在未转网 (MNP) 之前所属的原始运营商信息；如果您需要获取号码被转网后的现网运营商信息，请升级到 Premium。
-
Premium：在 Basic 基础上，可进一步获取号码在当前网络状态下的运营商、是否可达、是否漫游、是否转网等信息；但这一部分数据依赖目标国家/地区电信法规和用户隐私保护政策，无法保证所有国家和所有运营商都能完整提供。
1. 调用方式
调用方式
- HTTP Method：
GET - 请求地址：
https://api.paasoo.cn/lookup
2. 请求示例
Basic:
cURL
curl -X GET "https://api.paasoo.cn/lookup?key=API_KEY&secret=API_SECRET&number=8618911111111"
Premium:
cURL
curl -X GET "https://api.paasoo.cn/lookup?key=API_KEY&secret=API_SECRET&number=8618911111111&service=premium"
说明
认证参数：通过 key 和 secret 进行身份验证。
默认服务等级：若未指定 service，则默认为 basic。
3. 请求参数说明
| 参数 | 类型 | 必填 | 描述 | 示例 |
|---|---|---|---|---|
| key | string | 是 | API Key（字母或数字构成，共 8 位），用于唯一标识您的账户。可在PaaSoo 客户端后台获取。 | Abcdefgh |
| secret | string | 是 | API Secret（字母或数字构成，共 8 位），与 key 配合使用以进行身份验证。可在PaaSoo 客户端后台获取。 | Abc123EF |
| number | string | 是 | 待查询手机号码。 建议使用完整国际格式（如 8618911111111）。 无需在区号或号码前补充其它前导字符。 | 8618911111111 |
| service | string | 否 | 指定查询服务级别: basic 或 premium。 不传时默认为 basic。 | premium |
4. 响应说明
Basic: 仅提供号码最初（未转网前）的运营商信息，无法返回实时转网信息。
Premium: 基于最大的努力（best effort）为您提供当前运营商信息、漫游、转网等更多状态，但并非所有地区均可查询到完整或最新数据，受限于各地电信监管及隐私保护要求。
4.1 响应参数说明
| 参数 | 类型 | 服务 | 描述 |
|---|---|---|---|
| requestId | string | basic / premium | 查询请求的唯一 ID，可用于日志追踪。 |
| number | string | basic / premium | 原始传入的待查询电话号码。 |
| format | integer | basic / premium | 号码格式的有效性：
|
| errorCode | string | basic / premium | 请求的错误编码：
|
| errorDesc | string | basic / premium | 与 errorCode 对应的描述信息。 |
| cc | string | basic / premium | 待查询号码对应的国家或地区代码，如 86。 |
| countryIso | string | basic / premium | 国家或地区名称缩写，如 CN。 |
| operator | string | basic / premium | 号码归属的运营商名称。在 Basic 版本，此处仅返回号码在原始网络（未转网）时的运营商信息；如要获取现网运营商信息，请使用 Premium。 |
| mccmnc | string | premium | 运营商网络编码 (MCC+MNC)，如 46003；若无法查询到，不一定返回。 |
| reachable | string | premium | 号码可达性：
|
| ported | string | premium | 是否转网：
|
| portedFrom | string | premium | 转网前的网络名称和网络编码信息，例如 China Telecom 46003； 若无法获取或未转网则为空或 unknown。 |
| imsi | string | premium | IMSI 编码信息；若无法获取，则返回 unknown。 |
4.2 Basic (默认) 响应示例
{
"requestId": "900249-0c1a64-d000",
"number": "8618911111111",
"format": 0,
"errorCode": "00",
"errorDesc": "Successful",
"cc": "86",
"countryIso": "CN"
}
4.3 Premium 响应示例
{
"requestId": "900249-0c0aba-2000",
"number": "8618911111111",
"format": 1,
"errorCode": "00",
"errorDesc": "Successful",
"cc": "86",
"countryIso": "CN",
"mccmnc": "46003",
"operator": "China Telecom",
"reachable": "reachable",
"ported": "not ported",
"portedFrom": "",
"imsi": "unknown"
}
5. 错误码与常见问题
- 00 - Successful：调用成功。
- 01 - Insufficient balance：当前剩余余额不足，需要充值或升级账户。
- 02 - Wrong credentials：账号或密码错误，请检查
key、secret。 - 03 - Missing parameters：参数缺失或不合法，请检查请求示例。
- 07 - IP limit：您的请求来源 IP 不在白名单中。
- 08 - No allow hlr：当前用户账号未订阅 Premium 版本的 HLR 查询服务。
- 13 - Daliy quota exceeded：基础版当日可查询次数用尽。
- 99 - Other error：系统繁忙或其他未知错误。
6. 最佳实践与注意事项
- 服务选择：
- Basic：仅能获取号码原始运营商信息。若您对转网后运营商等动态信息有需求，请使用 Premium。
- Premium：基于最大的努力 (best effort) 获取当前运营商、漫游、转网等信息；该功能在部分国家或地区可能受限于当地电信监管与用户隐私保护规定，导致部分信息无法获取。
- 号码格式：建议传入完整国际格式号码，去掉任何前置的 + 或 0 等前导符。
- 安全性：强烈建议使用 HTTPS 协议，结合 IP 白名单或其他技术手段来保护 API Key 和 Secret。
- 账号余额：确保在调用前有足够余额，如需更高配额或更高级别服务，请联系 PaaSoo 获取支持。
- 请求频率：若频繁调用，请控制并发或设置合理延时，以避免超出服务限额。
- 传输延迟：Premium 查询可提供实时的号码状态，但仍应注意网络时延及目标运营商联调时效。
技术支持
如在 API 对接过程中遇到任何技术问题或业务疑问，欢迎随时联系我们的开发者支持团队：support@paasoo.com。我们将竭诚为您提供技术协助。