API文档

快速入门

使用HLR Lookups API 身份验证 核心概念 SDK PHP NodeJS Ruby

HLR 查询

POST /hlr-lookup POST /hlr-lookups

MNP 查询

POST /mnp-lookup POST /mnp-lookups

NT 查询

POST /nt-lookup POST /nt-lookups

路由

GET /route GET /routes GET /routing-map GET /hlr-coverage GET /mnp-coverage GET /mnp-countries GET /mccmncs

价格

GET /price GET /price-list GET /balance

工具

GET /auth-test GET /ping GET /time
旧版API文档

 

 
 

快速入门

全球移动网络基础设施运行在一个称为SS7信令网络的系统上。 该网络促进运营商之间的用户数据交换、呼叫路由、短信传输以及实时移动连接状态更新。 每个移动网络都维护着一个归属位置寄存器(HLR) - 这是一个存储其用户基本信息的核心数据库。

HLR查询技术使企业能够查询这些寄存器,并检索任何手机号码的实时连接和网络详情。 这包括手机是否开机、当前分配到哪个网络、是否已携号转网、号码是否有效或已停用,以及是否处于漫游状态。

HLR Lookups API提供对这些数据的无缝实时访问,使企业能够验证手机号码、优化路由并增强客户通信。 本文档将指导您将HLR Lookups集成到您的软件中,实现实时移动信息的自动检索。

使用HLR Lookups API

执行HLR查询快速、安全且简单。 注册并获取API密钥后,您可以通过POST /hlr-lookup进行身份验证并使用简单的HTTP POST请求启动即时查询。 或者,您可以选择快速异步API请求来处理大型数据集,结果将通过webhook回传到您的服务器,具体说明请参见概念部分。

请求示例

cURL 
curl -X POST 'https://www.hlr-lookups.com/api/v2/hlr-lookup' \
          -H "X-Digest-Key: YOUR_API_KEY" \
          -H "X-Digest-Signature: DIGEST_AUTH_SIGNATURE" \
          -H "X-Digest-Timestamp: UNIX_TIMESTAMP" \
          -d "@payload.json"

身份验证通过HTTP头提供,payload.json至少应包含以下JSON对象:

载荷示例

application/json 
{
   "msisdn": "+14156226819"
}

成功执行后,您将收到包含指定手机号码实时连接详情的响应。

成功响应 application/json

200 OK 
{
   "id":"f94ef092cb53",
   "msisdn":"+14156226819",
   "connectivity_status":"CONNECTED",
   "mccmnc":"310260",
   "mcc":"310",
   "mnc":"260",
   "imsi":"***************",
   "msin":"**********",
   "msc":"************",
   "original_network_name":"Verizon Wireless",
   "original_country_name":"United States",
   "original_country_code":"US",
   "original_country_prefix":"+1",
   "is_ported":true,
   "ported_network_name":"T-Mobile US",
   "ported_country_name":"United States",
   "ported_country_code":"US",
   "ported_country_prefix":"+1",
   "is_roaming":false,
   "roaming_network_name":null,
   "roaming_country_name":null,
   "roaming_country_code":null,
   "roaming_country_prefix":null,
   "cost":"0.0100",
   "timestamp":"2020-08-07 19:16:17.676+0300",
   "storage":"SYNC-API-2020-08",
   "route":"IP1",
   "processing_status":"COMPLETED",
   "error_code":null,
   "error_description":null,
   "data_source":"LIVE_HLR",
   "routing_instruction":"STATIC:IP1"
}

有关请求和响应属性以及连接状态的完整说明,请参见POST /hlr-lookup。

其他查询服务

移动号码携转(MNP)查询

使用MNP查询可确定网络归属和携号转网详情,无需查询实时连接状态。 如果您只需要号码的MCCMNC,请参考POST /mnp-lookup。

号码类型检测(NT)查询

通过POST /nt-lookup确定电话号码属于固定电话、移动电话、高费率号码、VoIP、寻呼机还是其他号码范围。

软件开发工具包(SDK)

HLR Lookups API适用于任何编程语言的REST客户端,我们在GitHub上发布了PHP、Ruby和NodeJS的SDK,帮助您快速上手。

工具

为确保无缝的开发体验,我们提供了全面的工具套件,包括浏览器内API请求和webhook监控、IP地址白名单、强大的身份验证选项以及身份验证测试端点。

不是开发人员?

HLR查询和号码携转查询无需任何编码即可执行。 详细了解我们的企业级网页客户端和基于浏览器的报告功能。

身份验证

为确保安全性和适当的访问控制,对 HLR Lookups API 的大多数请求都需要进行身份验证。 接口端点分为公开和受保护两类。 访问受保护的端点时,您的请求必须使用 API 密钥和密钥通过 Digest-Auth 或 Basic-Auth 方法进行身份验证。 Digest-Auth 是更安全的选项,强烈推荐使用。 使用 GET /auth-test 端点验证您的身份验证设置。

API 密钥和 API 密钥

从 API 设置 页面获取您的 API 密钥和密钥。 您还可以配置首选的身份验证方法,并启用 IP 地址白名单以增强安全性。 如果您怀疑 API 密钥已泄露,可以随时生成新的密钥。

获取 API 密钥
基本认证 摘要认证 IP白名单

标准基本认证易于实现且广泛支持。您可以通过在 HTTP 请求中传递 API 密钥和密钥作为 user:pass 对来进行身份验证。

HTTP 基本认证

cURL 
curl 'https://YOUR_API_KEY:YOUR_API_SECRET@www.hlr-lookups.com/api/v2/auth-test'

这会发送一个 Authorization 标头: 

Authorization: Basic BASE64(YOUR_API_KEY:YOUR_API_SECRET)

推荐:使用 SHA256 的 X-Basic 标头

为提高安全性,您可以发送凭据的 SHA256 哈希值,而不是直接以 base64 格式传输。 要使用此方法,请计算 YOUR_API_KEY:YOUR_API_SECRET 对的哈希值,并通过 X-Basic 标头发送:

基本认证请求

cURL 
curl 'https://www.hlr-lookups.com/api/v2/auth-test' \
  -H "X-Basic: BASIC_AUTH_HASH"

基本认证标头

键 类型 描述
X-Basic string YOUR_API_KEY:YOUR_API_SECRET 的 SHA256 哈希值。哈希中需包含冒号符号 (:)。 必填

PHP 代码示例

PHP 
$key = 'YOUR_API_KEY';
$secret = 'YOUR_API_SECRET';

$basicAuthHash = hash('sha256', $key . ':' . $secret);

Digest-Auth 是保护 HLR Lookup API 受保护端点访问的推荐方法。 每个请求必须包含以下标头:X-Digest-Key、X-Digest-Signature 和 X-Digest-Timestamp,具体说明如下。

请求示例

cURL 
curl 'https://www.hlr-lookups.com/api/v2/auth-test' \
  -H "X-Digest-Key: YOUR_API_KEY" \
  -H "X-Digest-Signature: DIGEST_AUTH_SIGNATURE" \
  -H "X-Digest-Timestamp: UNIX_TIMESTAMP"

请求标头

键 类型 描述
X-Digest-Key string 您的唯一 HLR Lookups API 密钥。 必填
X-Digest-Signature string 唯一的身份验证签名(见下文)。 必填
X-Digest-Timestamp integer 当前 Unix 时间戳(另见 GET /time)。 必填

构建签名

X-Digest-Signature 使用 SHA256 HMAC 哈希创建,以您的 API 密钥作为共享密钥。

要哈希的字符串结构如下:

ENDPOINT_PATH . UNIX_TIMESTAMP . REQUEST_METHOD . REQUEST_BODY

. 符号表示字符串连接。

摘要签名组成部分

组成部分 类型 描述
ENDPOINT_PATH string 请求的 API 端点,例如小写的 /auth-test。
UNIX_TIMESTAMP integer 当前 Unix 时间戳(必须在 30 秒内)。见 GET /time。
REQUEST_METHOD string 使用的 HTTP 方法,例如 POST 或 GET。
REQUEST_BODY string 请求正文数据。对于 GET 请求设置为 null。

代码示例

PHP PHP NodeJS NodeJS Ruby Ruby
PHP 
$path = '/auth-test'
    $timestamp = time();
    $method = 'GET';
    $body = $method == 'GET' ? null : json_encode($params);
    $secret = 'YOUR_API_SECRET';

    $signature = hash_hmac('sha256', $path . $timestamp . $method . $body, $secret);
NodeJS 
require('crypto');

    let path = '/auth-test'
    let timestamp = Date.now() / 1000 | 0;
    let method = 'GET'
    let body = method === 'GET' ? '' : JSON.stringify(params)
    let secret = 'YOUR_API_SECRET'

    let signature = crypto.createHmac('sha256', secret)
                    .update(path + timestamp + method + body)
                    .digest('hex');
Ruby 
require 'openssl'

path = '/auth-test'
timestamp = Time.now.to_i
method = 'GET'
body = method == 'GET' ? NIL : params.to_json
secret = 'YOUR_API_SECRET'

signature = OpenSSL::HMAC.hexdigest('sha256', secret, path + timestamp.to_s + method + body.to_s)

使用 API 设置 限制对特定 IP 地址的访问以增强安全性。 特别建议在生产环境中使用此功能。

返回顶部

核心概念

通过我们的 HTTP REST API 在任何编程语言或系统中实现 HLR 查询既简单又高效。 通过简单的集成流程,您可以开始实时查询移动网络,即时获取有关电话号码有效性、连接状态和路由详情的洞察。

选择合适的 API 取决于您的具体使用场景。 如果您需要实时查询结果用于 VoIP 电话、欺诈检测或 SMS 路由等应用,同步 API 是最佳选择。 但是,如果您的使用场景涉及大批量处理、批量查询或大规模数据验证,异步 API 可提供优化的性能,具备带宽效率和批量查询能力。

配置 API 使用我们的自定义路由选项之一,以优化速度、准确性和成本效益。 您还可以将查询结果存储在存储空间中,以便轻松下载 CSV 和 JSON 报告,并通过 Web 界面进行高级分析。

同步 HLR 查询 API

POST /hlr-lookup 端点每次请求处理一个移动电话号码 (MSISDN),并在 HTTP 响应体中即时返回结果。 结果以 JSON 格式返回,非常适合实时应用,包括移动号码验证、呼叫路由和 SMS 消息投递。

同步 API 调用由直接的 HTTP 请求和响应组成。 您的系统每次请求提交一个 MSISDN(移动号码),并立即收到包含实时 HLR 查询结果的 JSON 格式响应。 此 API 针对需要即时验证和连接检查的使用场景进行了优化,例如欺诈检测、VoIP 呼叫路由和 SMS 网关优化。

异步HLR查询API

POST /hlr-lookups 端点专为批量和大批量处理而设计,允许您每次请求提交最多 1,000 个 MSISDN。 此 API 不会即时返回结果,而是使用自动化 Webhook 将结果逐步发送到您的服务器。 查询结果通过 HTTP POST 回调以 JSON 对象的形式返回。

异步 API 针对速度、效率和可扩展性进行了优化。 它消除了与同步调用相关的网络延迟问题,非常适合需要高吞吐量查询的企业。 您的系统每次请求最多提交 1,000 个 MSISDN,我们的平台会并行处理这些请求,并通过 HTTP Webhook 以批次形式将结果返回到您的服务器,每次回调最多返回 1,000 个结果。

SDK（软件开发工具包）

我们为 PHP、NodeJS 和 Ruby 提供的软件开发工具包（SDK）简化了集成流程，让您能够高效且轻松地连接 HLR Lookups API。

这些 SDK 提供预构建函数、身份验证处理和结构化 API 请求模板，缩短开发时间并确保最佳实践。

在 GitHub 上浏览我们的完整 SDK 列表，立即开始集成。

PHP PHP NodeJS NodeJS Ruby Ruby
PHP 徽标

PHP SDK

PHP即时API集成 
1   include('HLRLookupClient.class.php');
2
3   $client = new HLRLookupClient(
4       'YOUR-API-KEY',
5       'YOUR-API-SECRET',
6       '/var/log/hlr-lookups.log'
7   );
8
9   $params = array('msisdn' => '+14156226819');
10  $response = $client->post('/hlr-lookup', $params);
在 GitHub 上查看 README.md
NodeJS 徽标

NodeJS SDK

NodeJS即时API集成 
1   require('node-hlr-client');
2
3   let response = await client.post('/hlr-lookup', {msisdn: '+491788735000'});
4
5   if (response.status === 200) {
6      // lookup was successful
7      let data = response.data;
8   }
在 GitHub 上查看 README.md
Ruby 徽标

Ruby SDK

Ruby即时API集成 
1   require 'ruby_hlr_client/client'
2
3   client = HlrLookupsSDK::Client.new(
4       'YOUR-API-KEY',
5       'YOUR-API-SECRET',
6       '/var/log/hlr-lookups.log'
7   )
8
9   params = { :msisdn => '+14156226819' }
10  response = client.get('/hlr-lookup', params)
在 GitHub 上查看 README.md
返回顶部

POST/hlr-lookup受保护

执行同步HLR查询,直接从网络运营商获取实时的手机连接状态和携号转网数据。 此接口非常适合实时流量场景,当时效性应用需要立即验证电话号码当前是否可达(已连接)或不可用(已关机)时使用。 此外,它还可以帮助区分活跃号码与无效、未知或虚假号码。

对于无需即时结果的大数据集批量处理,建议使用专为高速批量处理优化的异步POST /hlr-lookups。

如果您主要关注获取携号转网数据(MCCMNC)且不需要实时连接状态,POST /mnp-lookup为携号转网查询提供了经济实惠的替代方案。

请求 成功响应 错误响应 状态参考
cURL 
curl -X POST 'https://www.hlr-lookups.com/api/v2/hlr-lookup' \
          -d "@payload.json"

请求参数

application/json 
{
   "msisdn":"+14156226819",
   "route":null,
   "storage":null
}

请求参数

键 类型 描述 默认值 必填
msisdn string 需要查询的手机号码(MSISDN),以国际格式提供(例如 +14156226819 或 0014156226819)。必须包含国家代码。 null 必填
route string(3) 可选的三字符标识符,用于指定此次查询的路由。设置为null或省略此参数以应用您的自定义路由映射,或让系统自动确定此次查询的最佳路由。 null 可选
storage string 可选的存储标识符,用于指定存储结果的报告,以便进行人工审核、分析和报告。系统会自动附加当前月份的时间戳。如果省略或设置为null,系统将自动按月份对结果进行分组以用于报告。 null 可选
200 OK 
{
   "id":"f94ef092cb53",
   "msisdn":"+14156226819",
   "connectivity_status":"CONNECTED",
   "mccmnc":"310260",
   "mcc":"310",
   "mnc":"260",
   "imsi":"***************",
   "msin":"**********",
   "msc":"************",
   "original_network_name":"Verizon Wireless",
   "original_country_name":"United States",
   "original_country_code":"US",
   "original_country_prefix":"+1",
   "is_ported":true,
   "ported_network_name":"T-Mobile US",
   "ported_country_name":"United States",
   "ported_country_code":"US",
   "ported_country_prefix":"+1",
   "is_roaming":false,
   "roaming_network_name":null,
   "roaming_country_name":null,
   "roaming_country_code":null,
   "roaming_country_prefix":null,
   "cost":"0.0100",
   "timestamp":"2020-08-07 19:16:17.676+0300",
   "storage":"SYNC-API-2020-08",
   "route":"IP1",
   "processing_status":"COMPLETED",
   "error_code":null,
   "error_description":null,
   "data_source":"LIVE_HLR",
   "routing_instruction":"STATIC:IP1"
}

成功响应属性

姓名 类型 描述 可为空
id string(12) 分配给此查询请求的唯一标识符。 false
msisdn string 正在查询的手机号码,以国际格式显示(例如 +14156226819 或 0014156226819)。 false
connectivity_status string 指示是否成功检索到号码的连接状态。可能的值:CONNECTED 、ABSENT 、INVALID_MSISDN 或 UNDETERMINED 。 false
mccmnc string(5|6) 五位或六位数字的移动国家代码(MCC)和移动网络代码(MNC),用于标识当前与该手机号码关联的网络。 true
mcc string(3) 三位数字的移动国家代码(MCC),用于标识手机号码注册所在的国家。 true
mnc string(2|3) 两位或三位数字的移动网络代码(MNC),用于标识手机号码所属的特定网络。 true
imsi string 国际移动用户识别码(IMSI),与此号码关联的 SIM 卡的唯一标识符。 可用性取决于网络配置。 true
msin string(10) 移动运营商数据库中的移动用户识别号(MSIN)。 可用性取决于网络配置。 true
msc string(12) 当前处理该用户通信的移动交换中心(MSC)。 可用性取决于网络配置。 true
original_network_name string 与此号码关联的原始(本地)网络运营商名称。 true
original_country_name string 手机号码最初注册所在国家的完整名称,以英文提供。 true
original_country_code string(2) 代表手机号码首次分配所在国家的两字符 ISO 国家代码。 true
original_country_prefix string 与手机号码原始国家对应的国际拨号代码(国家呼叫代码)。 true
is_ported boolean 指示手机号码是否已从其原始网络携号转网至其他运营商。 true
ported_network_name string 手机号码已携号转网至的网络运营商名称(如适用)。 true
ported_country_name string 手机号码携号转网至的国家名称(如适用)。 true
ported_country_code string(2) 代表手机号码携号转网至的国家的两字符 ISO 国家代码(如适用)。 true
ported_country_prefix string 手机号码携号转网至的国家的国际拨号代码(国家呼叫代码)(如适用)。 true
is_roaming boolean 指示手机号码当前是否在国外网络漫游。漫游状态的可用性取决于移动网络运营商。 true
roaming_network_name string 手机号码当前漫游所在的网络名称(如适用)。 true
roaming_country_name string 手机号码当前漫游所在的国家名称(如适用)。 true
roaming_country_code string(2) 手机号码当前漫游所在国家的两字符 ISO 国家代码(如适用)。 true
roaming_country_prefix string 手机号码当前漫游所在国家的国际拨号代码(国家呼叫代码)(如适用)。 true
cost string 以字符串表示的十进制值,指示以欧元计价的查询费用。 true
timestamp string 包含时区的 W3C 格式时间戳,指定查询完成的时间。 true
storage string 保存查询结果的存储名称。这对应于通过网页界面提供的报告名称和 CSV 下载。 true
route string(3) 三字符标识符,指示此查询请求使用的路由方法。 true
processing_status string 查询的处理结果。可能的值:COMPLETED(成功)、REJECTED(网络不可达,未收取费用)或 FAILED(处理过程中发生错误)。 false
error_code integer 可选的内部错误代码,为客户支持提供额外的诊断信息。 true
error_description string 对给定错误代码(如有)的简要说明,以英文纯文本形式提供。 true
data_source string 此请求使用的数据源。可能的值:LIVE_HLR(实时 HLR 查询)或 MNP_DB(静态携号转网数据库)。详情请参阅路由选项。 false
routing_instruction string 描述请求中使用的路由指令的冒号分隔字符串。第一个组件为 STATIC(当您指定路由时)或 AUTO(自动路由);第二个组件为路由标识符,对于自动路由请求,第三个组件显示路由决策所基于的来源(即 SCORE, CUSTOM_GLOBAL_COUNTRY, CUSTOM_GLOBAL_MCCMNC, CUSTOM_GLOBAL_PREFIX, CUSTOM_USER_COUNTRY, CUSTOM_USER_MCCMNC, CUSTOM_USER_PREFIX, MNP_FALLBACK, PLATFORM_DEFAULT, USER_DEFAULT)。 false
4xx/5xx 
{
    "errors":[
        "Service unavailable."
    ]
}

错误响应参数

姓名 类型 描述 可为空
errors[] string[] 解释错误的字符串列表。 false
状态 描述
CONNECTED 号码有效,目标手机当前已连接到移动网络。通话、短信及其他服务应能成功送达接收方。
ABSENT 号码有效,但目标手机已关机或暂时处于网络覆盖范围之外。消息或通话可能无法送达,直至设备重新连接到网络。
INVALID_MSISDN 号码无效或当前未分配给移动网络上的任何用户。拨打此号码的通话和消息将失败。
UNDETERMINED 无法确定该号码的连接状态。这可能是由于号码无效、SS7错误响应或与目标网络运营商缺乏连接。请检查错误代码及其描述字段以获取更多诊断信息。
返回顶部

POST/hlr-lookups受保护

启动批量异步HLR查询，从网络运营商获取实时移动电话连接性和携号转网数据。 查询结果将通过webhook推送到您的服务器。 此方法专为处理大量无需即时响应的号码而优化，例如数据库清理和验证。 对于呼叫路由或短信发送等实时应用，建议改用POST /hlr-lookup端点。

此端点非常适合批量处理，可识别当前可达（已连接）或不可用（手机已关机）的电话号码，同时过滤掉无效、未分配或虚假号码。 此外，它还提供实时携号转网状态（MCCMNC）以及连接性详情。

使用此端点前，请确保已配置webhook URL以异步接收查询结果。 您可以在API设置中进行配置。

请求 成功响应 错误响应 Webhooks 状态参考
cURL 
curl -X POST 'https://www.hlr-lookups.com/api/v2/hlr-lookups' \
          -d "@payload.json"

请求参数

application/json 
{
   "msisdns":["+14156226819","+491788735000","+905536939460"],
   "route":null,
   "storage":null
}

请求参数

键 类型 描述 默认值 必填
msisdns array 国际格式的移动电话号码（MSISDN）数组（例如+14156226819或0014156226819）。每个请求最多可包含1000个号码。 null 必填
route string(3) 可选的三字符标识符,用于指定此次查询的路由。设置为null或省略此参数以应用您的自定义路由映射,或让系统自动确定此次查询的最佳路由。 null 可选
storage string 可选的存储标识符,用于指定存储结果的报告,以便进行人工审核、分析和报告。系统会自动附加当前月份的时间戳。如果省略或设置为null,系统将自动按月份对结果进行分组以用于报告。 null 可选
200 OK 
{
   "accepted":[
      {
         "id":"0424928f332e",
         "msisdn":"+491788735000"
      }
   ],
   "accepted_count":1,
   "rejected":[
      {
         "id":null,
         "msisdn":"+31"
      }
   ],
   "rejected_count":1,
   "total_count":2,
   "cost":"0.01",
   "storage":"ASYNC-API-2020-08",
   "route":"IP1",
   "webhook_urls":[
      "https://your-server.com/endpoint"
   ]
}

成功响应属性

姓名 类型 描述 可为空
accepted array 包含已接受处理的唯一标识符和MSISDN的对象列表。 false
accepted_count integer 成功接受处理的MSISDN总数。 false
rejected array 包含已拒绝处理的唯一标识符和MSISDN的对象列表，通常是由于号码无效。被拒绝的条目不收取费用。 false
rejected_count integer 因验证错误而被拒绝的MSISDN总数。 false
total_count integer 提交处理的已接受和已拒绝MSISDN的总计数。 false
cost string 以字符串表示的十进制值，表示已接受查询的总费用（欧元）。 false
storage string 存储查询结果的存储库名称，用于通过Web界面进行报告和CSV下载。 false
route string(3|4) 指定此查询请求所使用路由的三位或四位字符标识符。如果请求基于号码的自动路由，则显示AUTO。 false
webhook_urls array 在API设置中配置的webhook URL。查询结果将推送到此处。 false
4xx/5xx 
{
    "errors":[
        "Service unavailable."
    ]
}

错误响应参数

姓名 类型 描述 可为空
errors[] string[] 解释错误的字符串列表。 false

处理 Webhook

提交后,我们的平台将开始处理提供的电话号码,并将结果发送到您服务器上预先指定的 webhook URL。 结果通过 HTTP POST 请求传输,请求正文中包含一个 JSON 对象。

身份验证

通过检查 X-Signatures HTTP 头来验证 webhook。

X-Signatures 头包含一个以分号分隔的签名列表。 列表中的每个签名都是使用您账户中配置的 API 密钥之一生成的。 要验证 webhook,请使用您的 API 密钥、密钥和原始 HTTP 正文生成 SHA-256 哈希值,然后将其与列表中的签名进行比对。

匹配成功即可确认请求是真实的,并使用您控制的密钥进行了签名。

PHP 代码示例

PHP 
$signaturesHeader = (getallheaders() ?? [])['X-Signatures'] ?? ''; // list of signatures
$key = getenv('AUTH_KEY'); // Your API Key
$secret = getenv('AUTH_SECRET'); // Your API Secret
$payload = file_get_contents('php://input'); // The HTTP body of the incoming POST request

// Generate the expected signature
$expectedSignature = hash('sha256', $key . $secret . $payload);

// Split the header into individual signatures
$providedSignatures = explode(';', $signaturesHeader);

// Check if any signature matches
$valid = false;
foreach ($providedSignatures as $sig) {
    if (hash_equals($expectedSignature, $sig)) {
        $valid = true;
        break;
    }
}

如果头中给出的任何签名等于对您的 API 密钥、密钥和 HTTP 正文连接字符串计算的 SHA256 哈希值,则请求有效。

确认接收

您的服务器需要返回 HTTP 状态码 200 OK 以确认成功接收。 如果返回任何其他响应代码、发生超时(10 秒)或出现任何其他传输问题,系统将在一分钟后自动重试 webhook。 如果请求继续失败,重试将遵循指数退避策略,后续尝试将在 2, 4, 8, 16, 32, 64, 128, 256, 512, 1024 分钟后进行。

此重试机制可确保将查询结果最可靠地传输到您的基础设施。 它可最大限度地降低因临时网络问题或服务器停机而导致数据丢失的风险。

Webhook 负载

HTTP POST (application/json) 
{
   "type":"HLR",
   "results":[
      {
         "id":"3b4ac4b6ed1b",
         "msisdn":"+905536939460",
         "connectivity_status":"CONNECTED",
         "mccmnc":"28603",
         "mcc":"286",
         "mnc":"03",
         "imsi":"28603XXXXXXXXXX",
         "msin":"XXXXXXXXXX",
         "msc":"XXXXXXXXXX",
         "original_network_name":"Turk Telekom (AVEA)",
         "original_country_name":"Turkey",
         "original_country_code":"TR",
         "original_country_prefix":"+90",
         "is_ported":false,
         "ported_network_name":null,
         "ported_country_name":null,
         "ported_country_code":null,
         "ported_country_prefix":null,
         "is_roaming":false,
         "roaming_network_name":null,
         "roaming_country_name":null,
         "roaming_country_code":null,
         "roaming_country_prefix":null,
         "cost":"0.0100",
         "timestamp":"2020-08-13 00:04:38.261+0300",
         "storage":"ASYNC-API-2020-08",
         "route":"IP1",
         "processing_status":"COMPLETED",
         "error_code":null,
         "error_description":null,
         "data_source":"LIVE_HLR",
         "routing_instruction":"STATIC:IP1"
      }
   ]
}

Webhook负载属性

JSON对象包含type => HLR属性以及results属性，后者包含查询对象列表，如下所述。

姓名 类型 描述 可为空
id string(12) 分配给此查询请求的唯一标识符。 false
msisdn string 正在查询的手机号码,以国际格式显示(例如 +14156226819 或 0014156226819)。 false
connectivity_status string 指示是否成功检索到号码的连接状态。可能的值:CONNECTED 、ABSENT 、INVALID_MSISDN 或 UNDETERMINED 。 false
mccmnc string(5|6) 五位或六位数字的移动国家代码(MCC)和移动网络代码(MNC),用于标识当前与该手机号码关联的网络。 true
mcc string(3) 三位数字的移动国家代码(MCC),用于标识手机号码注册所在的国家。 true
mnc string(2|3) 两位或三位数字的移动网络代码(MNC),用于标识手机号码所属的特定网络。 true
imsi string 国际移动用户识别码(IMSI),与此号码关联的 SIM 卡的唯一标识符。 可用性取决于网络配置。 true
msin string(10) 移动运营商数据库中的移动用户识别号(MSIN)。 可用性取决于网络配置。 true
msc string(12) 当前处理该用户通信的移动交换中心(MSC)。 可用性取决于网络配置。 true
original_network_name string 与此号码关联的原始(本地)网络运营商名称。 true
original_country_name string 手机号码最初注册所在国家的完整名称,以英文提供。 true
original_country_code string(2) 代表手机号码首次分配所在国家的两字符 ISO 国家代码。 true
original_country_prefix string 与手机号码原始国家对应的国际拨号代码(国家呼叫代码)。 true
is_ported boolean 指示手机号码是否已从其原始网络携号转网至其他运营商。 true
ported_network_name string 手机号码已携号转网至的网络运营商名称(如适用)。 true
ported_country_name string 手机号码携号转网至的国家名称(如适用)。 true
ported_country_code string(2) 代表手机号码携号转网至的国家的两字符 ISO 国家代码(如适用)。 true
ported_country_prefix string 手机号码携号转网至的国家的国际拨号代码(国家呼叫代码)(如适用)。 true
is_roaming boolean 指示手机号码当前是否在国外网络漫游。漫游状态的可用性取决于移动网络运营商。 true
roaming_network_name string 手机号码当前漫游所在的网络名称(如适用)。 true
roaming_country_name string 手机号码当前漫游所在的国家名称(如适用)。 true
roaming_country_code string(2) 手机号码当前漫游所在国家的两字符 ISO 国家代码(如适用)。 true
roaming_country_prefix string 手机号码当前漫游所在国家的国际拨号代码(国家呼叫代码)(如适用)。 true
cost string 以字符串表示的十进制值,指示以欧元计价的查询费用。 true
timestamp string 包含时区的 W3C 格式时间戳,指定查询完成的时间。 true
storage string 保存查询结果的存储名称。这对应于通过网页界面提供的报告名称和 CSV 下载。 true
route string(3) 三字符标识符,指示此查询请求使用的路由方法。 true
processing_status string 查询的处理结果。可能的值:COMPLETED(成功)、REJECTED(网络不可达,未收取费用)或 FAILED(处理过程中发生错误)。 false
error_code integer 可选的内部错误代码,为客户支持提供额外的诊断信息。 true
error_description string 对给定错误代码(如有)的简要说明,以英文纯文本形式提供。 true
data_source string 此请求使用的数据源。可能的值:LIVE_HLR(实时 HLR 查询)或 MNP_DB(静态携号转网数据库)。详情请参阅路由选项。 false
routing_instruction string 描述请求中使用的路由指令的冒号分隔字符串。第一个组件为 STATIC(当您指定路由时)或 AUTO(自动路由);第二个组件为路由标识符,对于自动路由请求,第三个组件显示路由决策所基于的来源(即 SCORE, CUSTOM_GLOBAL_COUNTRY, CUSTOM_GLOBAL_MCCMNC, CUSTOM_GLOBAL_PREFIX, CUSTOM_USER_COUNTRY, CUSTOM_USER_MCCMNC, CUSTOM_USER_PREFIX, MNP_FALLBACK, PLATFORM_DEFAULT, USER_DEFAULT)。 false
状态 描述
CONNECTED 号码有效,目标手机当前已连接到移动网络。通话、短信及其他服务应能成功送达接收方。
ABSENT 号码有效,但目标手机已关机或暂时处于网络覆盖范围之外。消息或通话可能无法送达,直至设备重新连接到网络。
INVALID_MSISDN 号码无效或当前未分配给移动网络上的任何用户。拨打此号码的通话和消息将失败。
UNDETERMINED 无法确定该号码的连接状态。这可能是由于号码无效、SS7错误响应或与目标网络运营商缺乏连接。请检查错误代码及其描述字段以获取更多诊断信息。
返回顶部

POST/mnp-lookup受保护

执行同步MNP查询并提供移动号码携转和网络信息。 如果您的主要目标是实时提取指定手机号码的当前MCCMNC并确定原始网络和当前网络，则此端点非常适合。

对于无需即时结果的大数据集批量处理,建议使用专为高速批量处理优化的异步POST /mnp-lookups。

MNP查询可以可靠地确定携转状态和网络信息，但无法指示目标手机当前是否已连接到网络并可达。 如需提取实时连接信息，请改用POST /hlr-lookup端点。

请求 成功响应 错误响应
cURL 
curl -X POST 'https://www.hlr-lookups.com/api/v2/mnp-lookup' \
          -d "@payload.json"

请求参数

application/json 
{
   "msisdn":"+14156226819",
   "route":null,
   "storage":null
}

请求参数

键 类型 描述 默认值 必填
msisdn string 需要查询的手机号码(MSISDN),以国际格式提供(例如 +14156226819 或 0014156226819)。必须包含国家代码。 null 必填
route string(3) 可选的三字符标识符,用于指定此次查询的路由。设置为null或省略此参数以应用您的自定义路由映射,或让系统自动确定此次查询的最佳路由。 null 可选
storage string 可选的存储标识符,用于指定存储结果的报告,以便进行人工审核、分析和报告。系统会自动附加当前月份的时间戳。如果省略或设置为null,系统将自动按月份对结果进行分组以用于报告。 null 可选
200 OK 
{
   "id":"e428acb1c0ae",
   "msisdn":"+14156226819",
   "query_status":"OK",
   "mccmnc":"310260",
   "mcc":"310",
   "mnc":"260",
   "is_ported":true,
   "original_network_name":"Verizon Wireless:6006 - SVR/2",
   "original_country_name":"United States",
   "original_country_code":"US",
   "original_country_prefix":"+1415",
   "ported_network_name":"T-Mobile US:6529 - SVR/2",
   "ported_country_name":"United States",
   "ported_country_code":"US",
   "ported_country_prefix":"+1",
   "extra":"LRN:4154250000",
   "cost":"0.0050",
   "timestamp":"2020-08-05 21:21:33.490+0300",
   "storage":"WEB-CLIENT-SOLO-MNP-2020-08",
   "route":"PTX",
   "error_code":null
}

成功响应属性

姓名 类型 描述 可为空
id string(12) 此次查询的唯一12字符标识符。 false
msisdn string 本次查询请求中评估的手机号码。 false
query_status string 指示携号转网和网络信息的检索是否成功。可能的值为OK或FAILED。 false
mccmnc string(5|6) 五位或六位字符的MCCMNC(移动国家代码和移动网络代码组合),用于标识该手机号码当前所属的网络。 true
mcc string(3) 三位字符的MCC(移动国家代码),代表与该手机号码当前网络关联的国家。 true
mnc string(2|3) 两位或三位字符的MNC(移动网络代码),用于标识该手机号码的当前网络运营商。 true
is_ported boolean 指示该手机号码是否已从原始网络转网至新运营商。 true
original_network_name string 任意字符串(英文),指定被查询手机号码的原始网络运营商名称。 true
original_country_name string 任意字符串(英文),指示被查询手机号码的原始国家。 true
original_country_code string(2) 两位字符的ISO国家代码,代表被查询手机号码的原始国家。 true
original_country_prefix string 与被查询手机号码关联的原始国家的拨号代码。 true
ported_network_name string 指定被查询手机号码已转网至的网络运营商(如适用)。 true
ported_country_name string 指定被查询手机号码已转网至的国家(如适用)。 true
ported_country_code string(2) 两位字符的ISO国家代码,代表被查询手机号码已转网至的国家(如适用)。 true
ported_country_prefix string 被查询手机号码已转网至的国家的拨号代码(如适用)。 true
extra string 任意字符串,提供有关该手机号码的可选附加详细信息。 true
cost string 以字符串表示的十进制值,指示本次查询的欧元成本。 true
timestamp string W3C格式的时间戳(包含时区信息),指示查询完成的时间。 true
storage string 查询结果附加到的存储名称(或报告名称)。用于CSV下载和通过Web界面生成报告。 true
route string(3) 三位字符标识符,指定本次查询请求使用的路由。 true
error_code integer 可选的内部错误代码,为客户支持诊断提供额外上下文信息。 true
4xx/5xx 
{
    "errors":[
        "Service unavailable."
    ]
}

错误响应参数

姓名 类型 描述 可为空
errors[] string[] 解释错误的字符串列表。 false
返回顶部

POST/mnp-lookups受保护

发起批量异步MNP(移动号码携转)查询,实时获取当前MCCMNC并精准定位原始网络和当前网络。 查询结果将通过webhook推送到您的服务器。 此方法专为处理大量无需即时响应的号码而优化，例如数据库清理和验证。 对于呼叫路由或短信发送等实时应用，建议改用POST /mnp-lookup端点。

MNP查询可以可靠地确定携转状态和网络信息，但无法指示目标手机当前是否已连接到网络并可达。 如需提取实时连接信息，请改用POST /hlr-lookups端点。

使用此端点前，请确保已配置webhook URL以异步接收查询结果。 您可以在API设置中进行配置。

请求 成功响应 错误响应 Webhooks
cURL 
curl -X POST 'https://www.hlr-lookups.com/api/v2/mnp-lookups' \
          -d "@payload.json"

请求参数

application/json 
{
   "msisdns":["+14156226819","+491788735000","+905536939460"],
   "route":null,
   "storage":null
}

请求参数

键 类型 描述 默认值 必填
msisdns array 国际格式的移动电话号码（MSISDN）数组（例如+14156226819或0014156226819）。每个请求最多可包含1000个号码。 null 必填
route string(3) 可选的三字符标识符,用于指定此次查询的路由。设置为null或省略此参数以应用您的自定义路由映射,或自动让系统自动确定此请求的最佳路由。 null 可选
storage string 可选的存储标识符,用于指定存储结果的报告,以便进行人工审核、分析和报告。系统会自动附加当前月份的时间戳。如果省略或设置为null,系统将自动按月份对结果进行分组以用于报告。 null 可选
200 OK 
{
   "accepted":[
      {
         "id":"0424928f332e",
         "msisdn":"+491788735000"
      }
   ],
   "accepted_count":1,
   "rejected":[
      {
         "id":null,
         "msisdn":"+31"
      }
   ],
   "rejected_count":1,
   "total_count":2,
   "cost":"0.01",
   "storage":"ASYNC-API-2020-08",
   "route":"IP1",
   "webhook_urls":[
      "https://your-server.com/endpoint"
   ]
}

成功响应属性

姓名 类型 描述 可为空
accepted array 包含已接受处理的唯一标识符和MSISDN的对象列表。 false
accepted_count integer 成功接受处理的MSISDN总数。 false
rejected array 包含已拒绝处理的唯一标识符和MSISDN的对象列表，通常是由于号码无效。被拒绝的条目不收取费用。 false
rejected_count integer 因验证错误而被拒绝的MSISDN总数。 false
total_count integer 提交处理的已接受和已拒绝MSISDN的总计数。 false
cost string 以字符串表示的十进制值，表示已接受查询的总费用（欧元）。 false
storage string 存储查询结果的存储库名称，用于通过Web界面进行报告和CSV下载。 false
route string(3) 三位字符标识符,指定本次查询请求使用的路由。 false
webhook_urls array 在API设置中配置的webhook URL。查询结果将推送到此处。 false
4xx/5xx 
{
    "errors":[
        "Service unavailable."
    ]
}

错误响应参数

姓名 类型 描述 可为空
errors[] string[] 解释错误的字符串列表。 false

处理 Webhook

提交后,我们的平台将开始处理提供的电话号码,并将结果发送到您服务器上预先指定的 webhook URL。 结果通过 HTTP POST 请求传输,请求正文中包含一个 JSON 对象。

身份验证

通过检查 X-Signatures HTTP 头来验证 webhook。

X-Signatures 头包含一个以分号分隔的签名列表。 列表中的每个签名都是使用您账户中配置的 API 密钥之一生成的。 要验证 webhook,请使用您的 API 密钥、密钥和原始 HTTP 正文生成 SHA-256 哈希值,然后将其与列表中的签名进行比对。

匹配成功即可确认请求是真实的,并使用您控制的密钥进行了签名。

PHP 代码示例

PHP 
$signaturesHeader = (getallheaders() ?? [])['X-Signatures'] ?? ''; // list of signatures
$key = getenv('AUTH_KEY'); // Your API Key
$secret = getenv('AUTH_SECRET'); // Your API Secret
$payload = file_get_contents('php://input'); // The HTTP body of the incoming POST request

// Generate the expected signature
$expectedSignature = hash('sha256', $key . $secret . $payload);

// Split the header into individual signatures
$providedSignatures = explode(';', $signaturesHeader);

// Check if any signature matches
$valid = false;
foreach ($providedSignatures as $sig) {
    if (hash_equals($expectedSignature, $sig)) {
        $valid = true;
        break;
    }
}

如果头中给出的任何签名等于对您的 API 密钥、密钥和 HTTP 正文连接字符串计算的 SHA256 哈希值,则请求有效。

确认接收

您的服务器需要返回 HTTP 状态码 200 OK 以确认成功接收。 如果返回任何其他响应代码、发生超时(10 秒)或出现任何其他传输问题,系统将在一分钟后自动重试 webhook。 如果请求继续失败,重试将遵循指数退避策略,后续尝试将在 2, 4, 8, 16, 32, 64, 128, 256, 512, 1024 分钟后进行。

此重试机制可确保将查询结果最可靠地传输到您的基础设施。 它可最大限度地降低因临时网络问题或服务器停机而导致数据丢失的风险。

Webhook 负载

HTTP POST (application/json) 
{
    "type":"MNP",
    "results":[
        {
           "id":"e428acb1c0ae",
           "msisdn":"+14156226819",
           "query_status":"OK",
           "mccmnc":"310260",
           "mcc":"310",
           "mnc":"260",
           "is_ported":true,
           "original_network_name":"Verizon Wireless:6006 - SVR/2",
           "original_country_name":"United States",
           "original_country_code":"US",
           "original_country_prefix":"+1415",
           "ported_network_name":"T-Mobile US:6529 - SVR/2",
           "ported_country_name":"United States",
           "ported_country_code":"US",
           "ported_country_prefix":"+1",
           "extra":"LRN:4154250000",
           "cost":"0.0050",
           "timestamp":"2020-08-05 21:21:33.490+0300",
           "storage":"WEB-CLIENT-SOLO-MNP-2020-08",
           "route":"PTX",
           "error_code":null
        }
    ]
}

Webhook负载属性

JSON对象包含type => MNP属性以及results属性，后者包含查询对象列表，如下所述。

姓名 类型 描述 可为空
id string(12) 此次查询的唯一12字符标识符。 false
msisdn string 本次查询请求中评估的手机号码。 false
query_status string 指示携号转网和网络信息的检索是否成功。可能的值为OK或FAILED。 false
mccmnc string(5|6) 五位或六位字符的MCCMNC(移动国家代码和移动网络代码组合),用于标识该手机号码当前所属的网络。 true
mcc string(3) 三位字符的MCC(移动国家代码),代表与该手机号码当前网络关联的国家。 true
mnc string(2|3) 两位或三位字符的MNC(移动网络代码),用于标识该手机号码的当前网络运营商。 true
is_ported boolean 指示该手机号码是否已从原始网络转网至新运营商。 true
original_network_name string 任意字符串(英文),指定被查询手机号码的原始网络运营商名称。 true
original_country_name string 任意字符串(英文),指示被查询手机号码的原始国家。 true
original_country_code string(2) 两位字符的ISO国家代码,代表被查询手机号码的原始国家。 true
original_country_prefix string 与被查询手机号码关联的原始国家的拨号代码。 true
ported_network_name string 指定被查询手机号码已转网至的网络运营商(如适用)。 true
ported_country_name string 指定被查询手机号码已转网至的国家(如适用)。 true
ported_country_code string(2) 两位字符的ISO国家代码,代表被查询手机号码已转网至的国家(如适用)。 true
ported_country_prefix string 被查询手机号码已转网至的国家的拨号代码(如适用)。 true
extra string 任意字符串,提供有关该手机号码的可选附加详细信息。 true
cost string 以字符串表示的十进制值,指示本次查询的欧元成本。 true
timestamp string W3C格式的时间戳(包含时区信息),指示查询完成的时间。 true
storage string 查询结果附加到的存储名称(或报告名称)。用于CSV下载和通过Web界面生成报告。 true
route string(3) 三位字符标识符,指定本次查询请求使用的路由。 true
error_code integer 可选的内部错误代码,为客户支持诊断提供额外上下文信息。 true
返回顶部

POST/nt-lookup受保护

执行同步号码类型(NT)查询。 如果您的主要目标是实时判断所提供的电话号码是属于固定电话、移动电话、高费率号码、VoIP、寻呼机还是其他编号计划范围,此接口是理想的选择。

NT查询可以可靠地检测电话号码类型;但是,它们无法指示目标号码当前是否已连接到网络并可达。 要获取实时连接信息,请使用POST /hlr-lookup接口。

如果您的使用场景需要准确的网络和携号转网信息(MCCMNC),但不需要实时连接状态,请使用POST /mnp-lookup接口进行移动号码携号转网查询。

请求 成功响应 错误响应 类型参考
cURL 
curl -X POST 'https://www.hlr-lookups.com/api/v2/nt-lookup' \
          -d "@payload.json"

请求参数

application/json 
{
   "number":"+14156226819",
   "route":null,
   "storage":null
}

请求参数

键 类型 描述 默认值 必填
number string 国际格式的电话号码(例如 +4989702626 或 004989702626)。 null mandatory
route string(3) 可选的三字符标识符,用于指定此查询的路由。设置为null或省略此参数将应用您的自定义路由映射,或让我们的系统自动确定此请求的最佳路由。 null 可选
storage string 可选的存储标识符,用于指定存储结果的报告,以便进行人工审核、分析和报告。系统会自动附加当前月份的时间戳。如果省略或设置为null,系统将自动按月份对结果进行分组以用于报告。 null 可选
200 OK 
{
     "id":"2ed0788379c6",
     "number":"+4989702626",
     "number_type":"LANDLINE",
     "query_status":"OK",
     "is_valid":true,
     "invalid_reason":null,
     "is_possibly_ported":false,
     "is_vanity_number":false,
     "qualifies_for_hlr_lookup":false,
     "mccmnc":null,
     "mcc":null,
     "mnc":null,
     "original_network_name":null,
     "original_country_name":"Germany",
     "original_country_code":"DE",
     "regions":[
        "Munich"
     ],
     "timezones":[
        "Europe/Berlin"
     ],
     "info_text":"This is a landline number.",
     "cost":"0.0050",
     "timestamp":"2015-12-04 10:36:41.866283+00",
     "storage":"SYNC-API-NT-2015-12",
     "route":"LC1"
}

成功响应属性

姓名 类型 描述 可为空
id string(12) 分配给此查询请求的唯一标识符。 false
number string 在此次查询请求中评估的电话号码。 false
number_type string 检测到的号码类型。可能的值包括：LANDLINE , MOBILE , MOBILE_OR_LANDLINE , TOLL_FREE , PREMIUM_RATE , SHARED_COST , VOIP , PAGER , UAN , VOICEMAIL , UNKNOWN 。 false
query_status string 指示是否成功获取号码类型信息。成功时返回 OK，查询失败时返回 FAILED。 false
is_valid boolean 指示电话号码在语法上是否有效。 true
invalid_reason string 一个英文纯文本消息，说明电话号码被视为无效的原因（例如 "too short" 或 "invalid prefix"），如果号码有效则为 null。 true
is_possibly_ported boolean 指示电话号码是否可能已从原运营商携号转网至其他运营商。如需获取确定的携号转网信息，请使用 MNP 查询。 true
is_vanity_number boolean 指示电话号码是否为虚荣号码，即包含字母字符。 true
qualifies_for_hlr_lookup boolean 指示电话号码是否符合通过 HLR 查询进行额外查询的条件。 true
mccmnc string(5|6) 一个五位或六位字符串，表示 MCCMNC 元组（移动国家代码和移动网络代码），用于标识移动电话号码的原始网络。 true
mcc string(3) 一个三位字符串，表示 MCC（移动国家代码），用于标识与电话号码原始移动网络关联的国家。 true
mnc string(2|3) 一个两位或三位字符串，表示 MNC（移动网络代码），用于标识电话号码的原始移动网络运营商。 true
original_network_name string 一个任意的英文纯文本字符串，指定所检查移动电话号码的原始网络运营商名称。 true
original_country_name string 一个任意的英文纯文本字符串，指定与所检查移动电话号码关联的原始国家。 true
original_country_code string(2) 一个两字符 ISO 国家代码，指示所检查移动电话号码的原始国家。 true
regions array 一个可读的英文字符串列表，指定与此电话号码关联的地理区域。 true
timezones array 与此电话号码关联的时区列表（采用 Olson 格式）。 true
info_text string 一个任意字符串，可能包含有关电话号码的其他信息。 true
cost string 一个以字符串表示的十进制值，指示此次查询的费用（以欧元计）。 true
timestamp string 一个 W3C 格式的时间戳（包含时区），指示查询完成的时间。 true
storage string 指定已附加查询结果的存储名称。这对应于通过 Web 界面用于 CSV 下载和分析的报告名称。 true
route string(3) 三位字符标识符,指定本次查询请求使用的路由。 true
4xx/5xx 
{
    "errors":[
        "Service unavailable."
    ]
}

错误响应参数

姓名 类型 描述 可为空
errors[] string[] 解释错误的字符串列表。 false
类型 描述
LANDLINE 固定电话号码。
MOBILE 移动电话号码。可进行HLR查询以获取额外的连接状态、网络、携号转网和漫游信息。
MOBILE_OR_LANDLINE 固定电话或移动电话号码。可能符合HLR查询条件。
TOLL_FREE 免费电话号码。
PREMIUM_RATE 高额收费电话号码，需支付额外费用。
SHARED_COST 分摊费用电话号码。通常比高额收费电话号码便宜。
VOIP 网络电话号码。包括TSoIP电话号码(基于IP的电话服务)。
PAGER 寻呼机号码。通常不具备语音功能。
UAN 通用接入号码(企业号码)。可路由至特定办公地点,但允许企业使用统一号码对外联系。
VOICEMAIL 语音信箱号码。
UNKNOWN 无法确定号码类型。
返回顶部

POST/nt-lookups 受保护

此接口发起一系列异步号码类型查询,查询结果通过webhook回传至您的服务器。 如果您的主要目标是判断给定电话号码属于固定电话、移动电话、高额收费、VoIP、寻呼机还是其他号码计划范围,此接口非常适合。 此接口专为快速处理大批量号码而优化,非常适合批量操作(如数据库清理)。 对于实时流量和时效性要求高的应用场景,请改用POST /nt-lookup接口。

调用此接口前,您需要在API设置中指定webhook URL。

请求 成功响应 错误响应 Webhooks 类型参考
cURL 
curl -X POST 'https://www.hlr-lookups.com/api/v2/nt-lookups' \
          -d "@payload.json"

请求参数

application/json 
{
   "numbers":["+14156226819","+4989702626"],
   "route":null,
   "storage":null
}

请求参数

键 类型 描述 默认值 必填
numbers array 国际格式的电话号码数组(例如+14156226819或004989702626)。每次请求最多可包含1000个号码。 null 必填
route string(3) 可选的三字符标识符,用于指定此次查询的路由。设置为null或省略此参数将应用您的自定义路由映射,或让系统自动确定此请求的最佳路由。 null 可选
storage string 可选的存储标识符,用于指定存储结果的报告,以便进行人工审核、分析和报告。系统会自动附加当前月份的时间戳。如果省略或设置为null,系统将自动按月份对结果进行分组以用于报告。 null 可选
200 OK 
{
   "accepted":[
      {
         "id":"9f8a52cfa7d2",
         "number":"+905536939460"
      }
   ],
   "accepted_count":1,
   "rejected":[
      {
         "id":null,
         "number":"+31"
      }
   ],
   "rejected_count":2,
   "total_count":3,
   "cost":0.005,
   "storage":"ASYNC-API-NT-2020-08",
   "route":"LC1",
   "webhook_urls":[
      "https://your-server.com/endpoint"
   ]
}

成功响应属性

姓名 类型 描述 可为空
accepted array 对象数组,每个对象包含唯一标识符和已接受处理的电话号码。 false
accepted_count integer 已接受处理的电话号码总数。 false
rejected array 对象数组,每个对象包含唯一标识符和被拒绝处理的电话号码。通常这些号码无效,不会产生费用。 false
rejected_count integer 被拒绝处理的电话号码总数。 false
total_count integer 提交处理的已接受和被拒绝电话号码的总数。 false
cost string 表示这些查询费用的十进制字符串值,单位为欧元。 false
storage string 查询结果已附加到的存储(报告)名称。此名称用于通过Web界面下载CSV和查看分析数据。 false
route string(3) 三字符标识符,指定此次查询请求使用的路由。 false
webhook_urls array 在API设置中配置的webhook URL。查询结果将推送到此处。 false
4xx/5xx 
{
    "errors":[
        "Service unavailable."
    ]
}

错误响应参数

姓名 类型 描述 可为空
errors[] string[] 解释错误的字符串列表。 false

处理 Webhook

提交后,我们的平台将开始处理提供的电话号码,并将结果发送到您服务器上预先指定的 webhook URL。 结果通过 HTTP POST 请求传输,请求正文中包含一个 JSON 对象。

身份验证

通过检查 X-Signatures HTTP 头来验证 webhook。

X-Signatures 头包含一个以分号分隔的签名列表。 列表中的每个签名都是使用您账户中配置的 API 密钥之一生成的。 要验证 webhook,请使用您的 API 密钥、密钥和原始 HTTP 正文生成 SHA-256 哈希值,然后将其与列表中的签名进行比对。

匹配成功即可确认请求是真实的,并使用您控制的密钥进行了签名。

PHP 代码示例

PHP 
$signaturesHeader = (getallheaders() ?? [])['X-Signatures'] ?? ''; // list of signatures
$key = getenv('AUTH_KEY'); // Your API Key
$secret = getenv('AUTH_SECRET'); // Your API Secret
$payload = file_get_contents('php://input'); // The HTTP body of the incoming POST request

// Generate the expected signature
$expectedSignature = hash('sha256', $key . $secret . $payload);

// Split the header into individual signatures
$providedSignatures = explode(';', $signaturesHeader);

// Check if any signature matches
$valid = false;
foreach ($providedSignatures as $sig) {
    if (hash_equals($expectedSignature, $sig)) {
        $valid = true;
        break;
    }
}

如果头中给出的任何签名等于对您的 API 密钥、密钥和 HTTP 正文连接字符串计算的 SHA256 哈希值,则请求有效。

确认接收

您的服务器需要返回 HTTP 状态码 200 OK 以确认成功接收。 如果返回任何其他响应代码、发生超时(10 秒)或出现任何其他传输问题,系统将在一分钟后自动重试 webhook。 如果请求继续失败,重试将遵循指数退避策略,后续尝试将在 2, 4, 8, 16, 32, 64, 128, 256, 512, 1024 分钟后进行。

此重试机制可确保将查询结果最可靠地传输到您的基础设施。 它可最大限度地降低因临时网络问题或服务器停机而导致数据丢失的风险。

Webhook 负载

HTTP POST (application/json) 
{
   "type":"NT",
   "results":[
      {
         "id":"9f8a52cfa7d2",
         "number":"+905536939460",
         "numbertype":"MOBILE",
         "state":"COMPLETED",
         "isvalid":"Yes",
         "invalidreason":null,
         "ispossiblyported":"Yes",
         "isvanitynumber":"No",
         "qualifiesforhlrlookup":"Yes",
         "originalcarrier":"Turk Telekom (AVEA)",
         "mccmnc":"28603",
         "mcc":"286",
         "mnc":"03",
         "countrycode":"TR",
         "regions":[
            "Turkey"
         ],
         "timezones":[
            "Europe\/Istanbul"
         ],
         "infotext":"This number qualifies for HLR lookups. Determine if this subscriber number is connected, absent or invalid by running an HLR lookup. This is a mobile number and might be in roaming state. Run an HLR lookup to obtain roaming information (if available). This number is possibly ported and the carrier information might be inaccurate. To obtain portability information run an HLR lookup.",
         "usercharge":"0.0050",
         "inserttime":"2020-08-13 01:57:15.897+0300",
         "storage":"ASYNC-API-NT-2020-08",
         "route":"LC1",
         "interface":"Async API"
      }
   ]
}

Webhook负载属性

JSON对象包含type => NT属性以及results属性，后者包含查询对象列表，如下所述。

姓名 类型 描述 可为空
id string(12) 分配给此查询请求的唯一标识符。 false
number string 在此次查询请求中评估的电话号码。 false
number_type string 检测到的号码类型。可能的值包括：LANDLINE , MOBILE , MOBILE_OR_LANDLINE , TOLL_FREE , PREMIUM_RATE , SHARED_COST , VOIP , PAGER , UAN , VOICEMAIL , UNKNOWN 。 false
query_status string 指示是否成功获取号码类型信息。成功时返回 OK，查询失败时返回 FAILED。 false
is_valid boolean 指示电话号码在语法上是否有效。 true
invalid_reason string 一个英文纯文本消息，说明电话号码被视为无效的原因（例如 "too short" 或 "invalid prefix"），如果号码有效则为 null。 true
is_possibly_ported boolean 指示电话号码是否可能已从原运营商携号转网至其他运营商。如需获取确定的携号转网信息，请使用 MNP 查询。 true
is_vanity_number boolean 指示电话号码是否为虚荣号码，即包含字母字符。 true
qualifies_for_hlr_lookup boolean 指示电话号码是否符合通过 HLR 查询进行额外查询的条件。 true
mccmnc string(5|6) 一个五位或六位字符串，表示 MCCMNC 元组（移动国家代码和移动网络代码），用于标识移动电话号码的原始网络。 true
mcc string(3) 一个三位字符串，表示 MCC（移动国家代码），用于标识与电话号码原始移动网络关联的国家。 true
mnc string(2|3) 一个两位或三位字符串，表示 MNC（移动网络代码），用于标识电话号码的原始移动网络运营商。 true
original_network_name string 一个任意的英文纯文本字符串，指定所检查移动电话号码的原始网络运营商名称。 true
original_country_name string 一个任意的英文纯文本字符串，指定与所检查移动电话号码关联的原始国家。 true
original_country_code string(2) 一个两字符 ISO 国家代码，指示所检查移动电话号码的原始国家。 true
regions array 一个可读的英文字符串列表，指定与此电话号码关联的地理区域。 true
timezones array 与此电话号码关联的时区列表（采用 Olson 格式）。 true
info_text string 一个任意字符串，可能包含有关电话号码的其他信息。 true
cost string 一个以字符串表示的十进制值，指示此次查询的费用（以欧元计）。 true
timestamp string 一个 W3C 格式的时间戳（包含时区），指示查询完成的时间。 true
storage string 指定已附加查询结果的存储名称。这对应于通过 Web 界面用于 CSV 下载和分析的报告名称。 true
route string(3) 三位字符标识符,指定本次查询请求使用的路由。 true
类型 描述
LANDLINE 固定电话号码。
MOBILE 移动电话号码。可进行HLR查询以获取额外的连接状态、网络、携号转网和漫游信息。
MOBILE_OR_LANDLINE 固定电话或移动电话号码。可能符合HLR查询条件。
TOLL_FREE 免费电话号码。
PREMIUM_RATE 高额收费电话号码，需支付额外费用。
SHARED_COST 分摊费用电话号码。通常比高额收费电话号码便宜。
VOIP 网络电话号码。包括TSoIP电话号码(基于IP的电话服务)。
PAGER 寻呼机号码。通常不具备语音功能。
UAN 通用接入号码(企业号码)。可路由至特定办公地点,但允许企业使用统一号码对外联系。
VOICEMAIL 语音信箱号码。
UNKNOWN 无法确定号码类型。
返回顶部

GET/route受保护

获取在运行HLR查询时未指定route参数的情况下自动选择的路由。

自动路由选择基于可通过GET /hlr-coverage端点获取的路由映射表,该映射表主要来源于GET /routing-map。 您可以在账户设置中自定义路由映射表并定义自定义规则。

请求 成功响应 错误响应
cURL 
curl 'https://www.hlr-lookups.com/api/v2/route?msisdn=+491788735000'

请求参数

键 类型 描述 默认值 必填
msisdn string 用于获取自动选择路由信息的MSISDN号码。 null 必填
200 OK 
{
   "route":"V11",
   "confidence_level":"HIGH",
   "mccmnc":"26203",
   "origin":"SCORE"
}

成功响应属性

姓名 类型 描述 可为空
route string 推荐路由。 false
confidence_level string 选择此路由的置信度级别，即LOW、NORMAL、HIGH、MNP_FALLBACK。 false
mccmnc string 该号码基于编号计划的MCCMNC。 false
origin string 路由决策所基于的来源,即SCORE, CUSTOM_GLOBAL_COUNTRY, CUSTOM_GLOBAL_MCCMNC, CUSTOM_GLOBAL_PREFIX, CUSTOM_USER_COUNTRY, CUSTOM_USER_MCCMNC, CUSTOM_USER_PREFIX, MNP_FALLBACK, PLATFORM_DEFAULT, USER_DEFAULT false
4xx/5xx 
{
    "errors":[
        "Service unavailable."
    ]
}

错误响应参数

姓名 类型 描述 可为空
errors[] string[] 解释错误的字符串列表。 false
返回顶部

GET/routes受保护

此端点返回可用的 HLR、MNP 和 NT 路由列表。 每条路由及其功能和限制在路由详情页面中说明。

请求 成功响应 错误响应
cURL 
curl 'https://www.hlr-lookups.com/api/v2/routes'
200 OK 
{
   "routes":{
      "HLR":[
         "V11",
         "E10",
         "MS9",
         "DV8",
         "SV3",
         "IP1"
      ],
      "MNP":[
         "PTX",
         "IP4"
      ],
      "NT":[
         "LC1"
      ]
   }
}

成功响应属性

姓名 类型 描述 可为空
routes object 按路由类型分组的路由对象。 false
HLR|MNP|NT string[] 包含路由标识符列表。 false
4xx/5xx 
{
    "errors":[
        "Service unavailable."
    ]
}

错误响应参数

姓名 类型 描述 可为空
errors[] string[] 解释错误的字符串列表。 false
返回顶部

GET/routing-map受保护

检索当前应用于您账户的HLR查询自动路由配置。 当您提交HLR查询时未指定route参数时,将使用此默认配置。 您可以在账户设置中自定义路由映射并创建自定义规则。

配置层级从国家级规则级联到MCCMNC级规则,最后到单个电话号码前缀映射。 实际应用中,单个电话号码前缀映射优先于冲突的MCCMNC分配,而MCCMNC分配又会覆盖国家级规则。 请注意,启用MNP回退时将覆盖任何冲突的自定义规则。

请求 成功响应 错误响应
cURL 
curl 'https://www.hlr-lookups.com/api/v2/routing-map'
200 OK 
{
   "routing":{
      "map":{
         "defaultRoute":"V11",
         "mnpFallback":true,
         "mccmncs":[
            {
               "mccmnc":20201,
               "countrycode":"GR",
               "route":"E10",
               "mno":"Cosmote",
               "confidence":"HIGH",
               "origin":"SCORE"
            }
         ],
         "prefixes":[
            {
               "countrycode":"DE",
               "cns":"+4917821",
               "route":"DV8",
               "mccmnc":"26203",
               "mno":"O2"
            }
         ],
         "countries":[
            {
               "countrycode":"US",
               "route":"DV8"
            }
         ]
      }
   }
}

成功响应属性

姓名 类型 描述 可为空
default_route string 当无法为MSISDN确定首选路由选项且没有自定义路由规则适用时使用的默认路由。 false
mnp_fallback boolean 指示是否启用MNP回退。启用后,当网络不支持HLR查询(连接状态不可用)时,系统将执行MNP查询。 false
mccmncs array MCCMNC代码到其自动选择路由的映射。为给定MCCMNC中的号码执行HLR查询时,将使用相应的路由。 false
mccmnc string(5|6) 五位或六位字符的MCCMNC（移动国家代码和移动网络代码组合），用于标识移动网络运营商。 false
countrycode string(2) 两位字符的ISO国家代码,标识网络所属国家。 false
route string(3) 为该网络选择的路由。 false
mno string 该网络面向消费者运营的品牌名称。 false
confidence string 选择的置信度级别。可能的值为:HIGH、NORMAL、LOW、MNP_REDIRECT。如果是后者,系统会将此网络的流量重定向到MNP(如果您的账户启用了此行为)。否则使用账户中的默认路由。 false
origin string 选择所基于的来源。可能的值为:SCORE, CUSTOM_GLOBAL_COUNTRY, CUSTOM_GLOBAL_MCCMNC, CUSTOM_GLOBAL_PREFIX, CUSTOM_USER_COUNTRY, CUSTOM_USER_MCCMNC, CUSTOM_USER_PREFIX, MNP_FALLBACK, PLATFORM_DEFAULT, USER_DEFAULT false
prefixes array 您账户中配置的基于前缀的自定义路由规则列表(如有)。 false
countrycode string(2) 两位字符的ISO国家代码,标识前缀所属国家。 false
cns string 路由规则适用的前缀。 false
route string(3) 为该前缀选择的路由。 false
mccmnc string(5|6) 五位或六位字符的MCCMNC（移动国家代码和移动网络代码组合），用于标识移动网络运营商。 true
mno string 该网络面向消费者运营的品牌名称。 true
countries array 您账户中配置的基于国家的自定义规则列表(如有)。 false
countrycode string(2) 两位字符的ISO国家代码,标识国家。 false
route string(3) 为该国家选择的路由。 false
4xx/5xx 
{
    "errors":[
        "Service unavailable."
    ]
}

错误响应参数

姓名 类型 描述 可为空
errors[] string[] 解释错误的字符串列表。 false
返回顶部

GET/hlr-coverage 受保护

返回HLR覆盖洞察以支持数据驱动的决策制定。此端点帮助您分析移动网络的实时HLR路由选项，识别目标区域最有效的路径，并配置自动路由。

来自GET /route的推荐路由基于此处检索的覆盖数据。 覆盖数据也可在网络覆盖页面查看。 您可以在账户设置中进一步自定义路由映射并定义规则。

我们建议您熟悉此指南以帮助解读结果。

请求 成功响应 错误响应 状态参考
cURL 
curl 'https://www.hlr-lookups.com/api/v2/hlr-coverage?countrycode=XX'

请求参数

键 类型 描述 默认值 必填
countrycode string(2) 必填的两字母ISO国家代码，用于筛选结果，仅返回与指定国家关联的记录。 null 必填
sample_size string 可选参数，指定样本大小。可能的值为LARGE、MEDIUM、SMALL。较大的样本覆盖更长的时间范围，较小的样本覆盖最近的时间范围。 LARGE 可选
200 OK 
{
   "name":"Germany",
   "countrycode":"DE",
   "prefix":"+49",
   "mccs":[
      "262"
   ],
   "carriers":[
      {
         "mno":"Telekom",
         "mccmnc":"26201",
         "mcc":"262",
         "mnc":"01 ",
         "routes":[
            {
               "route":"V11",
               "selected":true,
               "selection_confidence":"HIGH",
               "n":361579,
               "CONNECTED":275273,
               "CONNECTED_PCT":76.13,
               "ABSENT":21529,
               "ABSENT_PCT":5.95,
               "INVALID_MSISDN":62582,
               "INVALID_MSISDN_PCT":17.3,
               "UNDETERMINED":2195,
               "UNDETERMINED_PCT":0.6
            },
            {
               "route":"E10",
               "selected":false,
               "selection_confidence":null,
               "n":122600,
               "CONNECTED":13721,
               "CONNECTED_PCT":11.19,
               "ABSENT":133,
               "ABSENT_PCT":0.1,
               "INVALID_MSISDN":55,
               "INVALID_MSISDN_PCT":0.04,
               "UNDETERMINED":108691,
               "UNDETERMINED_PCT":88.65
            }
         ]
      }
   ]
}

成功响应属性

姓名 类型 描述 可为空
name string 所选国家的英文名称（纯文本）。 false
countrycode string(2) 所选国家的两字符ISO国家代码。 false
prefix string 所选国家的国际拨号前缀。 false
mccs string[] 与所选国家关联的MCC（移动国家代码）列表。 false
carriers object[] 包含特定路由连接指标的运营商对象列表。 false
mno string 移动网络运营商的英文名称（纯文本）。 false
mccmnc string 移动网络运营商的MCCMNC。 false
mcc string 移动网络运营商的MCC（移动国家代码）。 false
mnc string 移动网络运营商的MNC（移动网络代码）。 false
routes object[] 特定路由连接结果列表。 false
route string 连接信息适用的路由。 false
selected bool 指示这是否为自动路由选择的路由。 false
selection_confidence string 选择此路由的置信度级别，即LOW、NORMAL、HIGH、MNP_FALLBACK。 如果这不是选定的路由，则包含null。 true
n int 此样本中的查询总数。 false
CONNECTED int 返回CONNECTED状态的HLR查询数量。 false
CONNECTED_PCT float 返回CONNECTED状态的HLR查询百分比。 false
ABSENT int 返回ABSENT状态的HLR查询数量。 false
ABSENT_PCT float 返回ABSENT状态的HLR查询百分比。 false
INVALID_MSISDN int 返回INVALID_MSISDN状态的HLR查询数量。 false
INVALID_MSISDN_PCT float 返回INVALID_MSISDN状态的HLR查询百分比。 false
UNDETERMINED int 返回UNDETERMINED状态的HLR查询数量。 false
UNDETERMINED_PCT float 返回UNDETERMINED状态的HLR查询百分比。 false
4xx/5xx 
{
    "errors":[
        "Service unavailable."
    ]
}

错误响应参数

姓名 类型 描述 可为空
errors[] string[] 解释错误的字符串列表。 false
状态 描述
CONNECTED 号码有效,目标手机当前已连接到移动网络。通话、短信及其他服务应能成功送达接收方。
ABSENT 号码有效,但目标手机已关机或暂时处于网络覆盖范围之外。消息或通话可能无法送达,直至设备重新连接到网络。
INVALID_MSISDN 号码无效或当前未分配给移动网络上的任何用户。拨打此号码的通话和消息将失败。
UNDETERMINED 无法确定该号码的连接状态。这可能是由于号码无效、SS7错误响应或与目标网络运营商缺乏连接。请检查错误代码及其描述字段以获取更多诊断信息。
返回顶部

GET/mnp-coverage受保护

此接口返回当前支持移动号码携号转网查询的移动网络运营商列表及其对应的MCCMNC标识符。

请求 成功响应 错误响应
cURL 
curl 'https://www.hlr-lookups.com/api/v2/mnp-coverage?countrycode=XX'

请求参数

键 类型 描述 默认值 必填
countrycode string(2) 可选的两位ISO国家代码，用于筛选MCCMNC结果，仅返回指定国家的相关数据。 null 可选
200 OK 
{
   "items":[
      {
         "country_name":"Germany",
         "country_code":"DE",
         "mccmnc":"26201",
         "mcc":"262",
         "mnc":"01 ",
         "brand":"Telekom",
         "operator":"Telekom Deutschland GmbH"
      },
      {
         "country_name":"Germany",
         "country_code":"DE",
         "mccmnc":"26202",
         "mcc":"262",
         "mnc":"02 ",
         "brand":"Vodafone",
         "operator":"Vodafone D2 GmbH"
      }
}

成功响应属性

姓名 类型 描述 可为空
items[] array 移动网络运营商列表。 false
country_name string 国家的英文名称。 false
country_code string(2) 两位ISO国家代码。 false
mccmnc string(5|6) 五位或六位字符的MCCMNC（移动国家代码和移动网络代码组合），用于标识移动网络运营商。 false
mcc string(3) 三位字符的MCC（移动国家代码），代表网络所属国家。 false
mnc string(2|3) 两位或三位字符的MNC（移动网络代码），代表特定的移动网络运营商。 false
brand string 该网络面向消费者运营的品牌名称。 true
operator string 移动网络运营商的法定名称。 true
4xx/5xx 
{
    "errors":[
        "Service unavailable."
    ]
}

错误响应参数

姓名 类型 描述 可为空
errors[] string[] 解释错误的字符串列表。 false
返回顶部

GET/price-list受保护

此接口返回仅支持MNP查询的国家列表，这些目的地不支持HLR查询。

请求 成功响应 错误响应
cURL 
curl 'https://www.hlr-lookups.com/api/v2/mnp-countries'
200 OK 
{
   "countries":[
      "AG",
      "AI",
      "AR",
      "AS",
      "AW",
      "BB",
      "BM",
      ...
      "US",
      "UY",
      "VC",
      "VE",
      "VG",
      "VN"
   ]
}

成功响应属性

姓名 类型 描述 可为空
countries string[] 双字符ISO国家代码列表。 false
4xx/5xx 
{
    "errors":[
        "Service unavailable."
    ]
}

错误响应参数

姓名 类型 描述 可为空
errors[] string[] 解释错误的字符串列表。 false
返回顶部

GET/mccmncs受保护

此接口返回移动网络运营商的完整列表，包括其对应的MCCMNC标识符及其他相关信息。

请求 成功响应 错误响应
cURL 
curl 'https://www.hlr-lookups.com/api/v2/mccmncs?countrycode=XX'

请求参数

键 类型 描述 默认值 必填
countrycode string(2) 可选的两字母ISO国家代码，用于筛选MCCMNC结果，仅返回与指定国家相关的记录。 null 可选
200 OK 
{
   "items":[
      {
         "country_name":"Germany",
         "country_code":"DE",
         "mccmnc":"26201",
         "mcc":"262",
         "mnc":"01 ",
         "brand":"Telekom",
         "operator":"Telekom Deutschland GmbH"
      },
      {
         "country_name":"Germany",
         "country_code":"DE",
         "mccmnc":"26202",
         "mcc":"262",
         "mnc":"02 ",
         "brand":"Vodafone",
         "operator":"Vodafone D2 GmbH"
      }
}

成功响应属性

姓名 类型 描述 可为空
items object[] 移动网络运营商列表。 false
country_name string 英文完整国家名称。 false
country_code string(2) 代表移动运营商所在国家的两字母ISO国家代码。 false
mccmnc string(5|6) 由五位或六位字符组成的MCCMNC字符串，用于唯一标识移动网络运营商。 false
mcc string(3) 三位字符的移动国家代码（MCC），用于标识移动网络所在的国家。 false
mnc string(2|3) 两位或三位字符的移动网络代码（MNC），用于指定给定MCC内的移动网络。 false
brand string 网络运营的商业品牌名称，即消费者所熟知的品牌。 true
operator string 移动网络运营商的正式名称，通常为管理该网络的法律实体。 true
parent_mccmnc string(5|6) 由五位或六位字符组成的MCCMNC字符串，代表母公司移动网络运营商（如有）。 true
4xx/5xx 
{
    "errors":[
        "Service unavailable."
    ]
}

错误响应参数

姓名 类型 描述 可为空
errors[] string[] 解释错误的字符串列表。 false
返回顶部

GET/price受保护

此接口返回HLR、MNP或NT查询的价格。

请求 成功响应 错误响应
cURL 
curl 'https://www.hlr-lookups.com/api/v2/price?msisdn=+491788735000&route_type=HLR'

请求参数

键 类型 描述 默认值 必填
msisdn string 需要查询价格的电话号码，需使用国际格式。 null 必填
route_type string 路由类型，即HLR、MNP、NT。 null 必填
route string(3) 应计算价格的路由。默认为自动路由确定的路由。 null 可选
200 OK 
{
   "price":{
      "amount":"0.01000",
      "msisdn":"+491788735000",
      "route_type":"HLR",
      "route":"DV8"
   }
}

成功响应属性

姓名 类型 描述 可为空
price object 包含价格详情的对象。 false
amount string 以欧元计价的金额。 false
msisdn string 此价格适用的MSISDN。 false
route_type string(2|3) 此价格适用的路由类型。 false
route string(3) 此价格适用的路由。 false
4xx/5xx 
{
    "errors":[
        "Service unavailable."
    ]
}

错误响应参数

姓名 类型 描述 可为空
errors[] string[] 解释错误的字符串列表。 false
返回顶部

GET/price-list受保护

此接口返回您账户中的定价信息。

请求 成功响应 错误响应
cURL 
curl 'https://www.hlr-lookups.com/api/v2/price-list'
200 OK 
{
   "pricing":[
      {
         "route":"V11",
         "countrycode":null,
         "countryname":null,
         "mccmnc":null,
         "cns":null,
         "route_type":"HLR",
         "price":"0.0090"
      },
      {
         "route":"V11",
         "countrycode":"DE",
         "countryname":"Germany",
         "mccmnc":"26201",
         "cns":null,
         "route_type":"HLR",
         "price":"0.0070"
      },
      {
         "route":"V11",
         "countrycode":"DE",
         "countryname":"Germany",
         "mccmnc":"26203",
         "cns":"4917821",
         "route_type":"HLR",
         "price":"0.0070"
      },
      {
         "route":"V11",
         "countrycode":"DE",
         "countryname":"Germany",
         "mccmnc":null,
         "cns":null,
         "route_type":"HLR",
         "price":"0.0070"
      },
      {
         "route":"PTX",
         "countrycode":null,
         "countryname":null,
         "mccmnc":null,
         "cns":null,
         "route_type":"MNP",
         "price":"0.00500"
      },
      ...
      {
         "route":"IP1",
         "countrycode":null,
         "countryname":null,
         "mccmnc":null,
         "cns":null,
         "route_type":"MIX",
         "price":"0.01000"
      },
      {
         "route":"LC1",
         "countrycode":null,
         "countryname":null,
         "mccmnc":null,
         "cns":null,
         "route_type":"NT",
         "price":"0.00500"
      }
   ]
}

成功响应属性

姓名 类型 描述 可为空
pricing object[] 包含定价信息的对象列表。 false
route string 此定价适用的路由。 false
countrycode string 对应路由的双字符ISO国家代码(如适用)。 true
countryname string 与国家代码对应的英文国家名称(如适用)。 true
mccmnc string 对应路由的MCCMNC代码(如适用)。优先于国家级定价。 true
cns string 对应路由的拨号前缀(如适用)。优先于国家级定价和MCCMNC级定价。 true
route_type string 对应的路由类型,即 HLR、MNP、NT。 false
route_type string 对应的欧元价格。 false
4xx/5xx 
{
    "errors":[
        "Service unavailable."
    ]
}

错误响应参数

姓名 类型 描述 可为空
errors[] string[] 解释错误的字符串列表。 false
返回顶部

GET/balance受保护

此接口可查询您当前的账户余额，让您能够根据账户信用状态自动化相关流程。 它与您在支付页面配置的低余额通知邮件无缝衔接。

请求 成功响应 错误响应
cURL 
curl 'https://www.hlr-lookups.com/api/v2/balance'
200 OK 
{
    "balance":"1002.90"
}

成功响应属性

姓名 类型 描述 可为空
balance string 您当前的账户余额（单位：欧元）。字符串类型的十进制数值。 false
4xx/5xx 
{
    "errors":[
        "Service unavailable."
    ]
}

错误响应参数

姓名 类型 描述 可为空
errors[] string[] 解释错误的字符串列表。 false
返回顶部

GET/ping公开

此接口向API发送ping请求，提供一种简单的方法来测试您与HLR Lookups API的连接。

请求 成功响应 错误响应
cURL 
curl 'https://www.hlr-lookups.com/api/v2/ping'
200 OK 
{
    "success":true
}

成功响应属性

姓名 类型 描述 可为空
success boolean 表示请求已成功处理。 false
4xx/5xx 
{
    "errors":[
        "Service unavailable."
    ]
}

错误响应参数

姓名 类型 描述 可为空
errors[] string[] 解释错误的字符串列表。 false
返回顶部

GET/time公开

此端点返回一个Unix时间戳，表示HLR Lookups服务器的当前时间。 使用它来同步您的服务器时钟，以便在生成用于身份验证的Digest-Auth签名时，确保纠正您的服务器时间与HLR Lookups服务器时间之间的任何差异。

请求 成功响应 错误响应
cURL 
curl 'https://www.hlr-lookups.com/api/v2/time'
200 OK 
{
    "time":1525898643
}

成功响应属性

姓名 类型 描述 可为空
time integer 表示HLR Lookups服务器当前时间的Unix时间戳。 false
4xx/5xx 
{
    "errors":[
        "Service unavailable."
    ]
}

错误响应参数

姓名 类型 描述 可为空
errors[] string[] 解释错误的字符串列表。 false
返回顶部

GET/auth-test受保护

此端点用于初步测试您的Basic-Auth或更推荐的Digest-Auth实现。

基本认证请求 摘要认证请求 成功响应 错误响应
cURL 
curl 'https://www.hlr-lookups.com/api/v2/auth-test' \
  -H "X-Basic: YOUR_API_KEY"

请求标头

键 类型 描述
X-Basic string YOUR_API_KEY:YOUR_API_SECRET 的 SHA256 哈希值。哈希中需包含冒号符号 (:)。
cURL (Digest-Auth) 
curl 'https://www.hlr-lookups.com/api/v2/auth-test' \
  -H "X-Digest-Key: YOUR_API_KEY" \
  -H "X-Digest-Signature: DIGEST_AUTH_SIGNATURE" \
  -H "X-Digest-Timestamp: UNIX_TIMESTAMP"

请求标头

键 类型 描述
X-Digest-Key string 您的HLR Lookups API密钥
X-Digest-Signature string 唯一的摘要认证签名(请参阅身份验证)
X-Digest-Timestamp integer 当前Unix时间戳(另请参阅GET /time)
200 OK 
{
    "success":true
}

成功响应属性

姓名 类型 描述 可为空
success boolean 表示请求已成功处理。 false
4xx/5xx 
{
    "errors":[
        "Service unavailable."
    ]
}

错误响应参数

姓名 类型 描述 可为空
errors[] string[] 解释错误的字符串列表。 false
返回顶部

旧版API文档

请注意，旧版API已弃用，并计划在未来停止服务。我们强烈建议您尽早升级至最新版本。

如果您在2013年至2020年初期间实施了我们的HLR查询API，则您使用的是旧版API。在这种情况下，请参阅我们的旧版API文档。

旧版API文档

借助一流的 HLR Lookups 平台提升您的移动智能


联系我们
语言한국어ภาษาไทยBahasa IndonesiaČeštinaDanskDeutschEestiEnglishEspañolFilipinoFrançaisItalianoLatviešuLietuviųMagyarNederlandsNorskPolskiPortuguêsRomânăSuomiSvenskaTiếng ViệtTürkçeΕλληνικάБългарскиРуccкийУкраїнськаहिन्दीবাংলা日本語简体中文繁体中文
© Velocity Made Good Ltd. 2013-2026 · 服务条款 · 隐私政策 · 数据处理协议
旋转加载器 透明 GIF