Getting Started

The global mobile network infrastructure operates on a system known as the SS7 signaling network. This network facilitates the exchange of subscriber data, call routing, SMS transmission, and real-time mobile connectivity status updates between carriers. Each mobile network maintains a Home Location Register (HLR) — a core database that stores essential details about its subscribers.

HLR Lookup technology enables businesses to query these registers and retrieve live connectivity and network details for any mobile phone number. This includes whether the phone is switched on, which network it is currently assigned to, whether it has been ported, whether the number is valid or deactivated, and whether it is roaming.

The HLR Lookups API provides seamless, real-time access to this data, allowing businesses to verify mobile numbers, optimize routing, and enhance customer communications. This documentation will guide you through integrating HLR Lookups into your software, enabling automated retrieval of real-time mobile intelligence.

Using the HLR Lookups API

Executing HLR Lookup queries is fast, secure, and straightforward. Once you've signed up and obtained your API Key, you can authenticate and initiate instant lookups with simple HTTP POST requests, via POST /hlr-lookup. Alternatively, you can process large data sets by opting for fast asynchronous API requests with results posted back to your server via webhook, as explained in the concepts section.

Example Request

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"

Authentication is supplied via HTTP headers, and payload.json should (at a minimum) contain the following JSON object:

Example Payload

{
   "msisdn": "+14156226819"
}

Upon successful execution, you will receive a response containing real-time connectivity details for the specified mobile number.

Success Response application/json

{
   "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,
   "data_source":"LIVE_HLR",
   "routing_instruction":"STATIC:IP1"
}

For a full breakdown of request and response attributes and connectivity statuses, see POST /hlr-lookup.

Additional Lookup Services

Mobile Number Portability (MNP) Lookups

Use MNP lookups to determine network ownership and portability details without querying real-time connectivity. If you only need the MCCMNC of a number, refer to POST /mnp-lookup.

Number Type Detection (NT) Lookups

Determine whether a phone number belongs to a landline, mobile, premium-rate, VoIP, pager, or other numbering plan ranges with POST /nt-lookup.

Software Development Kits (SDKs)

The HLR Lookups API works with any REST client in any programming language and we've published SDKs for PHP, Ruby, and NodeJS on our GitHub to help you get started quickly.

Tools

To ensure a seamless development experience, we offer a comprehensive suite of tools, including in-browser API request and webhook monitoring, IP address whitelisting, robust authentication options, and an authentication test endpoint.

Not a Developer?

HLR Lookups and Number Portability Queries can be performed without any coding. Learn more about our enterprise web client and browser-based reporting features.

Authentication

To ensure security and proper access control, most requests to the HLR Lookups API require authentication. Endpoints are categorized as either public or protected. When accessing a protected endpoint, your request must be authenticated using your API key and secret via either Digest-Auth or Basic-Auth method. Digest-Auth is the more secure option and is strongly recommended. Use the GET /auth-test endpoint to verify your authentication setup.

API Key and API Secret

Obtain your API key and secret from the API settings page. You can also configure your preferred authentication method and enable IP address whitelisting for enhanced security. If you suspect that your API secret has been compromised, you can generate a new one at any time.

Basic Auth Digest Auth IP Whitelisting

Standard Basic Authentication is easy to implement and widely supported. You can authenticate by passing your API key and secret as a user:pass pair in the HTTP request.

HTTP Basic Auth

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

This sends an Authorization header:

Authorization: Basic BASE64(YOUR_API_KEY:YOUR_API_SECRET)

Recommended: X-Basic Header with SHA256

For improved security, you can send a SHA256 hash of your credentials instead of transmitting them directly as base64. To use this method, compute the hash of your YOUR_API_KEY:YOUR_API_SECRET pair and send it via the X-Basic header:

Basic Auth Request

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

Basic Authentication Headers

Key	Type	Description
`X-Basic`	string	SHA256 hash of `YOUR_API_KEY:YOUR_API_SECRET`. Include the colon symbol (:) in the hash.	mandatory

Code Example

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

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

Digest-Auth is the recommended method for securing access to protected HLR Lookup API endpoints. Each request must include the following headers: X-Digest-Key, X-Digest-Signature, and X-Digest-Timestamp, which are explained below.

Request Example

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"

Request Headers

Key	Type	Description
`X-Digest-Key`	string	Your unique HLR Lookups API Key.	mandatory
`X-Digest-Signature`	string	A unique authentication signature (see below).	mandatory
`X-Digest-Timestamp`	integer	Current Unix timestamp (also see `GET /time`).	mandatory

Constructing the Signature

The X-Digest-Signature is created using a SHA256 HMAC hash, with your API secret as the shared key.

The string to hash is structured as follows:

ENDPOINT_PATH . UNIX_TIMESTAMP . REQUEST_METHOD . REQUEST_BODY

The . symbol represents string concatenation.

Digest Signature Components

Component	Type	Description
`ENDPOINT_PATH`	string	The requested API endpoint, e.g., `/auth-test` in lowercase.
`UNIX_TIMESTAMP`	integer	Current Unix timestamp (must be within 30 seconds). See `GET /time`.
`REQUEST_METHOD`	string	The HTTP method used, e.g., `POST` or `GET`.
`REQUEST_BODY`	string	Request body data. Set to `null` for `GET` requests.

Code Examples

PHP

NodeJS

Ruby

$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);

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');

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)

Scroll Up

Concepts

Implementing HLR Lookups in any programming language or system via our HTTP REST API is straightforward and efficient. With a simple integration process, you can start querying mobile networks in real-time for instant insights into phone number validity, connectivity status, and routing details.

Selecting the appropriate API depends on your specific use case. If you require real-time lookup results for applications like VoIP telephony, fraud detection, or SMS routing, the synchronous API is the best choice. However, if your use case involves high-volume processing, bulk lookups, or large-scale data verification, the asynchronous API offers optimized performance with bandwidth efficiency and batch lookup capabilities.

Configure the API to use one of our custom routing options to optimize speed, accuracy, and cost-effectiveness. You can also store lookup results in storages for easy CSV and JSON report downloads, as well as advanced analytics via the web interface.

Synchronous HLR Lookup API

The POST /hlr-lookup endpoint processes one mobile phone number (MSISDN) per request and returns results instantly in the HTTP response body. The results are formatted as JSON and are ideal for real-time applications, including mobile number validation, call routing, and SMS message delivery.

A synchronous API call consists of a direct HTTP request and response. Your system submits a single MSISDN (mobile number) per request and receives an immediate response containing real-time HLR lookup results in JSON format. This API is optimized for use cases that require instant verification and connectivity checks, such as fraud detection, VoIP call routing, and SMS gateway optimization.

Asynchronous HLR Lookup API

The POST /hlr-lookups endpoint is designed for bulk and high-volume processing, allowing you to submit up to 1,000 MSISDNs per request. Instead of returning results instantly, this API uses automated webhooks to send results progressively to your server. Lookup results are returned as JSON objects via HTTP POST callbacks.

The asynchronous API is optimized for speed, efficiency, and scalability. It eliminates network latency issues associated with synchronous calls, making it ideal for businesses needing high-throughput lookups. Your system submits up to 1,000 MSISDNs per request, and our platform processes them in parallel, delivering results back to your server via HTTP webhooks in batches of up to 1,000 results per callback.

SDKs (Software Development Kits)

Our Software Development Kits (SDKs) for PHP, NodeJS, and Ruby streamline the integration process, allowing you to connect with the HLR Lookups API efficiently and with minimal effort.

These SDKs provide pre-built functions, authentication handling, and structured API request templates, reducing development time and ensuring best practices.

Explore our full list of available SDKs on GitHub and start integrating today.

PHP

NodeJS

Ruby

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);

View on GitHub README.md

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   }

View on GitHub README.md

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)

View on GitHub README.md

Scroll Up

POST/hlr-lookupprotected

Performs a synchronous HLR Lookup, delivering real-time mobile phone connectivity and portability data directly from network operators. This endpoint is ideal for live traffic scenarios where time-sensitive applications require immediate verification of whether a phone number is currently reachable (connected) or unavailable (switched off). Additionally, it helps distinguish active numbers from invalid, unknown, or fake ones.

For bulk processing of large datasets that do not require instant results, consider using the asynchronous POST /hlr-lookups, which is optimized for high-speed batch processing.

If your primary focus is retrieving mobile number portability data (MCCMNC) and you do not require live connectivity status, the POST /mnp-lookup provides a cost-effective alternative for mobile number portability queries.

Request Success Response Error Response Status Reference

curl -X POST 'https://www.hlr-lookups.com/api/v2/hlr-lookup' \
          -d "@payload.json"

Payload

{
   "msisdn":"+14156226819",
   "route":null,
   "storage":null
}

Request Params

Key	Type	Description	Default	Mandatory
`msisdn`	string	The mobile phone number (MSISDN) to be queried, provided in international format (e.g., +14156226819 or 0014156226819). Country codes must be included.	null	mandatory
`route`	string(3)	An optional three-character identifier specifying the route for this lookup. Set to `null` or omit this parameter to apply your custom routing map or let our system automatically determine the best route for this lookup.	null	optional
`storage`	string	An optional storage identifier specifying the report where results will be stored for manual review, analytics, and reporting. The system automatically appends a timestamp with the current month. If omitted or set to `null`, the system will automatically group results by month for reporting purposes.	null	optional

{
   "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,
   "data_source":"LIVE_HLR",
   "routing_instruction":"STATIC:IP1"
}

Success Response Attributes

Name	Type	Description	Nullable
`id`	string(12)	A unique identifier assigned to this lookup request.	false
`msisdn`	string	The mobile phone number being queried, formatted in international format (e.g., +14156226819 or 0014156226819).	false
`connectivity_status`	string	Indicates whether the connectivity status of the number was successfully retrieved. Possible values: `CONNECTED` , `ABSENT` , `INVALID_MSISDN` , or `UNDETERMINED` .	false
`mccmnc`	string(5\|6)	A five or six-digit Mobile Country Code (MCC) and Mobile Network Code (MNC) identifying the network currently associated with the phone number.	true
`mcc`	string(3)	A three-digit Mobile Country Code (MCC) identifying the country where the phone number is registered.	true
`mnc`	string(2\|3)	A two- or three-digit Mobile Network Code (MNC) identifying the specific network to which the phone number belongs.	true
`imsi`	string	The International Mobile Subscriber Identity (IMSI), a unique identifier for the SIM card associated with this number. Availability depends on network configuration.	true
`msin`	string(10)	The Mobile Subscription Identification Number (MSIN) within the mobile operator’s database. Availability depends on network configuration.	true
`msc`	string(12)	The Mobile Switching Center (MSC) currently handling this subscriber's communications. Availability depends on network configuration.	true
`original_network_name`	string	The original (native) network operator name associated with this number.	true
`original_country_name`	string	The full name of the country where the mobile phone number was originally registered, provided in English.	true
`original_country_code`	string(2)	The two-character ISO country code representing the country where the phone number was first assigned.	true
`original_country_prefix`	string	The international dialing code (country calling code) corresponding to the original country of the mobile phone number.	true
`is_ported`	boolean	Indicates whether the mobile number has been ported from its original network to a different operator.	true
`ported_network_name`	string	The name of the network operator to which the mobile number has been ported, if applicable.	true
`ported_country_name`	string	The name of the country where the mobile number was ported to, if applicable.	true
`ported_country_code`	string(2)	The two-character ISO country code representing the country where the mobile number was ported to, if applicable.	true
`ported_country_prefix`	string	The international dialing code (country calling code) for the country where the mobile number was ported to, if applicable.	true
`is_roaming`	boolean	Indicates whether the mobile number is currently roaming on a foreign network. Roaming status availability depends on the mobile network operator.	true
`roaming_network_name`	string	The name of the network on which the mobile number is currently roaming, if applicable.	true
`roaming_country_name`	string	The name of the country where the mobile number is currently roaming, if applicable.	true
`roaming_country_code`	string(2)	The two-character ISO country code of the country where the mobile number is currently roaming, if applicable.	true
`roaming_country_prefix`	string	The international dialing code (country calling code) of the country where the mobile number is currently roaming, if applicable.	true
`cost`	string	A decimal value represented as a string, indicating the lookup cost in EUR.	true
`timestamp`	string	A W3C-formatted timestamp including time zone, specifying when the lookup was completed.	true
`storage`	string	The name of the storage where the lookup results were saved. This corresponds to report names and CSV downloads available via the web interface.	true
`route`	string(3)	A three-character identifier indicating the routing method used for this lookup request.	true
`processing_status`	string	The processing outcome of the lookup. Possible values: `COMPLETED` (successful), `REJECTED` (network unreachable, no charge applied), or `FAILED` (error occurred during processing).	false
`error_code`	integer	An optional internal error code providing additional diagnostic information for customer support.	true
`data_source`	string	The data source used for this request. Possible values: `LIVE_HLR` (real-time HLR query) or `MNP_DB` (static mobile number portability database). Refer to routing options for details.	false
`routing_instruction`	string	A colon-delimited string describing the routing instruction used in the request. The first component is `STATIC` when you specified a route or `AUTO` for automatic routing; the second component is the route identifier, and for automatic routing requests a third component shows the origin on which the routing decision is based (i.e. `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

{
    "errors":[
        "Service unavailable."
    ]
}

Error Response Params

Name	Type	Description	Nullable
`errors[]`	string[]	A list of strings explaining the error.	false

Status	Description
CONNECTED	The number is valid, and the target handset is currently connected to the mobile network. Calls, SMS, and other services should reach the recipient successfully.
ABSENT	The number is valid, but the target handset is either switched off or temporarily out of network coverage. Messages or calls may not be delivered until the device reconnects to the network.
INVALID_MSISDN	The number is invalid or not currently assigned to any subscriber on the mobile network. Calls and messages to this number will fail.
UNDETERMINED	The connectivity status of the number could not be determined. This may be due to an invalid number, temporary network issues, or a lack of connectivity with the target network operator.

Scroll Up

POST/hlr-lookupsprotected

Initiates a batch of asynchronous HLR lookups, retrieving live mobile phone connectivity and portability data from network operators. Results are delivered via webhooks to your server. This method is optimized for processing large volumes of numbers that do not require immediate responses, such as database cleaning and verification. For real-time applications like call routing or SMS delivery, consider using the POST /hlr-lookup endpoint instead.

This endpoint is ideal for bulk processing when the goal is to identify phone numbers that are currently reachable (connected) or unavailable (phone switched off) while filtering out invalid, unassigned, or fake numbers. Additionally, it provides live portability status (MCCMNC) alongside connectivity details.

Before using this endpoint, ensure that a webhook URL is configured to receive lookup results asynchronously. You can set this up in your API settings.

Request Success Response Error Response Webhooks Status Reference

curl -X POST 'https://www.hlr-lookups.com/api/v2/hlr-lookups' \
          -d "@payload.json"

Payload

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

Request Params

Key	Type	Description	Default	Mandatory
`msisdns`	array	An array of mobile phone numbers (MSISDNs) in international format (e.g. +14156226819 or 0014156226819). You can include up to 1000 numbers per request.	null	mandatory
`route`	string(3)	An optional three-character identifier specifying the route for this lookup. Set to `null` or omit this parameter to apply your custom routing map or let our system automatically determine the best route for this lookup.	null	optional
`storage`	string	An optional storage identifier specifying the report where results will be stored for manual review, analytics, and reporting. The system automatically appends a timestamp with the current month. If omitted or set to `null`, the system will automatically group results by month for reporting purposes.	null	optional

{
   "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"
   ]
}

Success Response Attributes

Name	Type	Description	Nullable
`accepted`	array	A list of objects containing unique identifiers and MSISDNs that have been accepted for processing.	false
`accepted_count`	integer	The total number of MSISDNs successfully accepted for processing.	false
`rejected`	array	A list of objects containing unique identifiers and MSISDNs that have been rejected for processing, typically due to invalid numbers. No charge applies for rejected entries.	false
`rejected_count`	integer	The total number of MSISDNs rejected due to validation errors.	false
`total_count`	integer	The total count of accepted and rejected MSISDNs that were submitted for processing.	false
`cost`	string	A decimal value represented as a string, indicating the total cost in EUR for the accepted lookups.	false
`storage`	string	The name of the storage where the lookup results are appended, used for reporting and CSV downloads via the web interface.	false
`route`	string(3\|4)	A three or four character identifier specifying the route used for this lookup request. Contains AUTO if number-based automatic routing was requested.	false
`webhook_urls`	array	The webhook URLs configured in your API settings. Results are posted back here.	false

{
    "errors":[
        "Service unavailable."
    ]
}

Error Response Params

Name	Type	Description	Nullable
`errors[]`	string[]	A list of strings explaining the error.	false

Processing Webhooks

Once submitted, our platform begins processing the provided phone numbers and sends the results to the previously specified webhook URL on your server. The results are transmitted as an HTTP POST request with a JSON object in the request body.

Authentication

Authenticate the webhook by inspecting the X-Signatures HTTP header.

The X-Signatures header contains a semicolon-separated list of signatures. Each signature in the list is generated using one of the API secrets configured in your account. To verify the webhook, generate a SHA-256 hash using your API key, secret, and the raw HTTP body — then compare it to the signatures in the list.

A match confirms the request is authentic and signed with a secret you control.

Code Example

$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;
    }
}

The request is valid if any of the signatures given in the header equals a SHA256 hash computed over the concatenated string of your API key, secret, and the HTTP body.

Confirming Receipt

Your server is expected to respond with an HTTP status code 200 OK to confirm successful receipt. If any other response code is returned, a timeout occurs (10 seconds), or any other delivery issue arises, the system will automatically retry the webhook after one minute. If the request continues to fail, retries will follow an exponential backoff strategy, with subsequent attempts after 2, 4, 8, 16, 32, 64, 128, 256, 512, 1024 minutes.

This retry mechanism ensures maximum reliability in delivering lookup results to your infrastructure. It minimizes the risk of data loss due to temporary network issues or server downtime.

Webhook Payload

{
   "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,
         "data_source":"LIVE_HLR",
         "routing_instruction":"STATIC:IP1"
      }
   ]
}

Webhook Payload Attributes

The JSON object contains an attribute type => HLR alongside an attribute results that includes a list of lookup objects, as documented below.

Name	Type	Description	Nullable
`id`	string(12)	A unique identifier assigned to this lookup request.	false
`msisdn`	string	The mobile phone number being queried, formatted in international format (e.g., +14156226819 or 0014156226819).	false
`connectivity_status`	string	Indicates whether the connectivity status of the number was successfully retrieved. Possible values: `CONNECTED` , `ABSENT` , `INVALID_MSISDN` , or `UNDETERMINED` .	false
`mccmnc`	string(5\|6)	A five or six-digit Mobile Country Code (MCC) and Mobile Network Code (MNC) identifying the network currently associated with the phone number.	true
`mcc`	string(3)	A three-digit Mobile Country Code (MCC) identifying the country where the phone number is registered.	true
`mnc`	string(2\|3)	A two- or three-digit Mobile Network Code (MNC) identifying the specific network to which the phone number belongs.	true
`imsi`	string	The International Mobile Subscriber Identity (IMSI), a unique identifier for the SIM card associated with this number. Availability depends on network configuration.	true
`msin`	string(10)	The Mobile Subscription Identification Number (MSIN) within the mobile operator’s database. Availability depends on network configuration.	true
`msc`	string(12)	The Mobile Switching Center (MSC) currently handling this subscriber's communications. Availability depends on network configuration.	true
`original_network_name`	string	The original (native) network operator name associated with this number.	true
`original_country_name`	string	The full name of the country where the mobile phone number was originally registered, provided in English.	true
`original_country_code`	string(2)	The two-character ISO country code representing the country where the phone number was first assigned.	true
`original_country_prefix`	string	The international dialing code (country calling code) corresponding to the original country of the mobile phone number.	true
`is_ported`	boolean	Indicates whether the mobile number has been ported from its original network to a different operator.	true
`ported_network_name`	string	The name of the network operator to which the mobile number has been ported, if applicable.	true
`ported_country_name`	string	The name of the country where the mobile number was ported to, if applicable.	true
`ported_country_code`	string(2)	The two-character ISO country code representing the country where the mobile number was ported to, if applicable.	true
`ported_country_prefix`	string	The international dialing code (country calling code) for the country where the mobile number was ported to, if applicable.	true
`is_roaming`	boolean	Indicates whether the mobile number is currently roaming on a foreign network. Roaming status availability depends on the mobile network operator.	true
`roaming_network_name`	string	The name of the network on which the mobile number is currently roaming, if applicable.	true
`roaming_country_name`	string	The name of the country where the mobile number is currently roaming, if applicable.	true
`roaming_country_code`	string(2)	The two-character ISO country code of the country where the mobile number is currently roaming, if applicable.	true
`roaming_country_prefix`	string	The international dialing code (country calling code) of the country where the mobile number is currently roaming, if applicable.	true
`cost`	string	A decimal value represented as a string, indicating the lookup cost in EUR.	true
`timestamp`	string	A W3C-formatted timestamp including time zone, specifying when the lookup was completed.	true
`storage`	string	The name of the storage where the lookup results were saved. This corresponds to report names and CSV downloads available via the web interface.	true
`route`	string(3)	A three-character identifier indicating the routing method used for this lookup request.	true
`processing_status`	string	The processing outcome of the lookup. Possible values: `COMPLETED` (successful), `REJECTED` (network unreachable, no charge applied), or `FAILED` (error occurred during processing).	false
`error_code`	integer	An optional internal error code providing additional diagnostic information for customer support.	true
`data_source`	string	The data source used for this request. Possible values: `LIVE_HLR` (real-time HLR query) or `MNP_DB` (static mobile number portability database). Refer to routing options for details.	false
`routing_instruction`	string	A colon-delimited string describing the routing instruction used in the request. The first component is `STATIC` when you specified a route or `AUTO` for automatic routing; the second component is the route identifier, and for automatic routing requests a third component shows the origin on which the routing decision is based (i.e. `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

Status	Description
CONNECTED	The number is valid, and the target handset is currently connected to the mobile network. Calls, SMS, and other services should reach the recipient successfully.
ABSENT	The number is valid, but the target handset is either switched off or temporarily out of network coverage. Messages or calls may not be delivered until the device reconnects to the network.
INVALID_MSISDN	The number is invalid or not currently assigned to any subscriber on the mobile network. Calls and messages to this number will fail.
UNDETERMINED	The connectivity status of the number could not be determined. This may be due to an invalid number, temporary network issues, or a lack of connectivity with the target network operator.

Scroll Up

POST/mnp-lookupprotected

Invokes a synchronous MNP lookup and provides mobile numbering portability and network information. This endpoint is suitable if your primary goal is to extract the current MCCMNC of a given mobile phone number and pinpoint the original and current networks in real-time.

For bulk processing of large datasets that do not require instant results, consider using the asynchronous POST /mnp-lookups, which is optimized for high-speed batch processing.

MNP queries reliably determine portability and network information but do not indicate whether the target mobile phone is currently connected to a network and reachable. To extract live connectivity information, please use the POST /hlr-lookup endpoint instead.

Request Success Response Error Response

curl -X POST 'https://www.hlr-lookups.com/api/v2/mnp-lookup' \
          -d "@payload.json"

Payload

{
   "msisdn":"+14156226819",
   "route":null,
   "storage":null
}

Request Params

Key	Type	Description	Default	Mandatory
`msisdn`	string	The mobile phone number (MSISDN) to be queried, provided in international format (e.g., +14156226819 or 0014156226819). Country codes must be included.	null	mandatory
`route`	string(3)	An optional three-character identifier specifying the route for this lookup. Set to `null` or omit this parameter to apply your custom routing map or let our system automatically determine the best route for this lookup.	null	optional
`storage`	string	An optional storage identifier specifying the report where results will be stored for manual review, analytics, and reporting. The system automatically appends a timestamp with the current month. If omitted or set to `null`, the system will automatically group results by month for reporting purposes.	null	optional

{
   "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
}

Success Response Attributes

Name	Type	Description	Nullable
`id`	string(12)	A unique 12-character identifier for this lookup.	false
`msisdn`	string	The mobile phone number evaluated in this lookup request.	false
`query_status`	string	Indicates whether the retrieval of portability and network information was successful. Possible values are `OK` or `FAILED`.	false
`mccmnc`	string(5\|6)	A five- or six-character MCCMNC (mobile country code and mobile network code tuple) that identifies the network to which the mobile phone number currently belongs.	true
`mcc`	string(3)	A three-character MCC (mobile country code) representing the country associated with the mobile phone number's current network.	true
`mnc`	string(2\|3)	A two- or three-character MNC (mobile network code) that identifies the current network operator for the mobile phone number.	true
`is_ported`	boolean	Indicates if the phone number has been ported from its original network to a new operator.	true
`original_network_name`	string	An arbitrary string (in English) specifying the original network operator name of the inspected mobile phone number.	true
`original_country_name`	string	An arbitrary string (in English) indicating the original country of the inspected mobile phone number.	true
`original_country_code`	string(2)	A two-character ISO country code representing the original country of the inspected mobile phone number.	true
`original_country_prefix`	string	The dialing code of the original country associated with the inspected mobile phone number.	true
`ported_network_name`	string	Specifies the network operator to which the inspected mobile phone number has been ported, if applicable.	true
`ported_country_name`	string	Specifies the country to which the inspected mobile phone number has been ported, if applicable.	true
`ported_country_code`	string(2)	A two-character ISO country code representing the country to which the inspected mobile phone number has been ported, if applicable.	true
`ported_country_prefix`	string	The dialing code for the country to which the inspected mobile phone number has been ported, if applicable.	true
`extra`	string	An arbitrary string providing optional additional details about the phone number.	true
`cost`	string	A decimal value, represented as a string, indicating the cost in EUR for this lookup.	true
`timestamp`	string	A W3C-formatted timestamp, including time zone information, indicating when the lookup was completed.	true
`storage`	string	The storage name (or report name) to which the lookup results were appended. This is used for CSV downloads and reporting via the web interface.	true
`route`	string(3)	A three-character identifier specifying the route used for this lookup request.	true
`error_code`	integer	An optional internal error code providing additional context for customer support diagnostics.	true

{
    "errors":[
        "Service unavailable."
    ]
}

Error Response Params

Name	Type	Description	Nullable
`errors[]`	string[]	A list of strings explaining the error.	false

Scroll Up

POST/mnp-lookupsprotected

Initiates a batch of asynchronous MNP (mobile number portability) lookups, retrieving the current MCCMNC and pinpointing the original and current networks in real-time. Results are delivered via webhooks to your server. This method is optimized for processing large volumes of numbers that do not require immediate responses, such as database cleaning and verification. For real-time applications like call routing or SMS delivery, consider using the POST /mnp-lookup endpoint instead.

MNP queries reliably determine portability and network information but do not indicate whether the target mobile phone is currently connected to a network and reachable. To extract live connectivity information, please use the POST /hlr-lookups endpoint instead.

Before using this endpoint, ensure that a webhook URL is configured to receive lookup results asynchronously. You can set this up in your API settings.

Request Success Response Error Response Webhooks

curl -X POST 'https://www.hlr-lookups.com/api/v2/mnp-lookups' \
          -d "@payload.json"

Payload

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

Request Params

Key	Type	Description	Default	Mandatory
`msisdns`	array	An array of mobile phone numbers (MSISDNs) in international format (e.g. +14156226819 or 0014156226819). You can include up to 1000 numbers per request.	null	mandatory
`route`	string(3)	An optional three-character identifier specifying the route for this lookup. Set to `null` or omit this parameter to apply your custom routing map or automatically let our system automatically determine the best routes for this request.	null	optional
`storage`	string	An optional storage identifier specifying the report where results will be stored for manual review, analytics, and reporting. The system automatically appends a timestamp with the current month. If omitted or set to `null`, the system will automatically group results by month for reporting purposes.	null	optional

{
   "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"
   ]
}

Success Response Attributes

Name	Type	Description	Nullable
`accepted`	array	A list of objects containing unique identifiers and MSISDNs that have been accepted for processing.	false
`accepted_count`	integer	The total number of MSISDNs successfully accepted for processing.	false
`rejected`	array	A list of objects containing unique identifiers and MSISDNs that have been rejected for processing, typically due to invalid numbers. No charge applies for rejected entries.	false
`rejected_count`	integer	The total number of MSISDNs rejected due to validation errors.	false
`total_count`	integer	The total count of accepted and rejected MSISDNs that were submitted for processing.	false
`cost`	string	A decimal value represented as a string, indicating the total cost in EUR for the accepted lookups.	false
`storage`	string	The name of the storage where the lookup results are appended, used for reporting and CSV downloads via the web interface.	false
`route`	string(3)	A three-character identifier specifying the route used for this lookup request.	false
`webhook_urls`	array	The webhook URLs configured in your API settings. Results are posted back here.	false

{
    "errors":[
        "Service unavailable."
    ]
}

Error Response Params

Name	Type	Description	Nullable
`errors[]`	string[]	A list of strings explaining the error.	false

Processing Webhooks

Once submitted, our platform begins processing the provided phone numbers and sends the results to the previously specified webhook URL on your server. The results are transmitted as an HTTP POST request with a JSON object in the request body.

Authentication

Authenticate the webhook by inspecting the X-Signatures HTTP header.

The X-Signatures header contains a semicolon-separated list of signatures. Each signature in the list is generated using one of the API secrets configured in your account. To verify the webhook, generate a SHA-256 hash using your API key, secret, and the raw HTTP body — then compare it to the signatures in the list.

A match confirms the request is authentic and signed with a secret you control.

Code Example

$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;
    }
}

The request is valid if any of the signatures given in the header equals a SHA256 hash computed over the concatenated string of your API key, secret, and the HTTP body.

Confirming Receipt

Your server is expected to respond with an HTTP status code 200 OK to confirm successful receipt. If any other response code is returned, a timeout occurs (10 seconds), or any other delivery issue arises, the system will automatically retry the webhook after one minute. If the request continues to fail, retries will follow an exponential backoff strategy, with subsequent attempts after 2, 4, 8, 16, 32, 64, 128, 256, 512, 1024 minutes.

This retry mechanism ensures maximum reliability in delivering lookup results to your infrastructure. It minimizes the risk of data loss due to temporary network issues or server downtime.

Webhook Payload

{
    "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 Payload Attributes

The JSON object contains an attribute type => MNP alongside an attribute results that includes a list of lookup objects, as documented below.

Name	Type	Description	Nullable
`id`	string(12)	A unique 12-character identifier for this lookup.	false
`msisdn`	string	The mobile phone number evaluated in this lookup request.	false
`query_status`	string	Indicates whether the retrieval of portability and network information was successful. Possible values are `OK` or `FAILED`.	false
`mccmnc`	string(5\|6)	A five- or six-character MCCMNC (mobile country code and mobile network code tuple) that identifies the network to which the mobile phone number currently belongs.	true
`mcc`	string(3)	A three-character MCC (mobile country code) representing the country associated with the mobile phone number's current network.	true
`mnc`	string(2\|3)	A two- or three-character MNC (mobile network code) that identifies the current network operator for the mobile phone number.	true
`is_ported`	boolean	Indicates if the phone number has been ported from its original network to a new operator.	true
`original_network_name`	string	An arbitrary string (in English) specifying the original network operator name of the inspected mobile phone number.	true
`original_country_name`	string	An arbitrary string (in English) indicating the original country of the inspected mobile phone number.	true
`original_country_code`	string(2)	A two-character ISO country code representing the original country of the inspected mobile phone number.	true
`original_country_prefix`	string	The dialing code of the original country associated with the inspected mobile phone number.	true
`ported_network_name`	string	Specifies the network operator to which the inspected mobile phone number has been ported, if applicable.	true
`ported_country_name`	string	Specifies the country to which the inspected mobile phone number has been ported, if applicable.	true
`ported_country_code`	string(2)	A two-character ISO country code representing the country to which the inspected mobile phone number has been ported, if applicable.	true
`ported_country_prefix`	string	The dialing code for the country to which the inspected mobile phone number has been ported, if applicable.	true
`extra`	string	An arbitrary string providing optional additional details about the phone number.	true
`cost`	string	A decimal value, represented as a string, indicating the cost in EUR for this lookup.	true
`timestamp`	string	A W3C-formatted timestamp, including time zone information, indicating when the lookup was completed.	true
`storage`	string	The storage name (or report name) to which the lookup results were appended. This is used for CSV downloads and reporting via the web interface.	true
`route`	string(3)	A three-character identifier specifying the route used for this lookup request.	true
`error_code`	integer	An optional internal error code providing additional context for customer support diagnostics.	true

Scroll Up

POST/nt-lookupprotected

Invokes a synchronous number type (NT) lookup. This endpoint is ideal if your primary goal is to determine whether the provided phone numbers belong to landline, mobile, premium rate, VoIP, pager, or other numbering plan ranges in real-time.

NT queries reliably detect the phone number type; however, they do not indicate whether the target number is currently connected to a network and reachable. To extract live connectivity information, please use the POST /hlr-lookup endpoint.

If your use case requires accurate network and portability information (MCCMNC) but not live connectivity status, please use the POST /mnp-lookup endpoint for mobile number portability queries.

Request Success Response Error Response Type Reference

curl -X POST 'https://www.hlr-lookups.com/api/v2/nt-lookup' \
          -d "@payload.json"

Payload

{
   "number":"+14156226819",
   "route":null,
   "storage":null
}

Request Params

Key	Type	Description	Default	Mandatory
`number`	string	A phone number in international format (e.g. +4989702626 or 004989702626).	null	mandatory
`route`	string(3)	An optional three-character identifier specifying the route for this lookup. Set to `null` or omit this parameter to apply your custom routing map or let our system automatically determine the best routes for this request.	null	optional
`storage`	string	An optional storage identifier specifying the report where results will be stored for manual review, analytics, and reporting. The system automatically appends a timestamp with the current month. If omitted or set to `null`, the system will automatically group results by month for reporting purposes.	null	optional

{
     "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"
}

Success Response Attributes

Name	Type	Description	Nullable
`id`	string(12)	A unique identifier assigned to this lookup request.	false
`number`	string	The phone number that was evaluated during this lookup request.	false
`number_type`	string	The detected number type. Possible values include: `LANDLINE` , `MOBILE` , `MOBILE_OR_LANDLINE` , `TOLL_FREE` , `PREMIUM_RATE` , `SHARED_COST` , `VOIP` , `PAGER` , `UAN` , `VOICEMAIL` , `UNKNOWN` .	false
`query_status`	string	Indicates whether the number type information was successfully obtained. Returns `OK` if successful, or `FAILED` if the lookup failed.	false
`is_valid`	boolean	Indicates whether the phone number is syntactically valid.	true
`invalid_reason`	string	A plain text message in English specifying why the phone number is considered invalid (e.g. "too short" or "invalid prefix"), or `null` if the number is valid.	true
`is_possibly_ported`	boolean	Indicates whether the phone number may have been ported from its original operator to a different carrier. For definitive portability information, use MNP lookups.	true
`is_vanity_number`	boolean	Indicates whether the phone number is a vanity number, meaning it includes alphabetic characters.	true
`qualifies_for_hlr_lookup`	boolean	Indicates whether the phone number is eligible for additional queries through HLR lookups.	true
`mccmnc`	string(5\|6)	A five or six character string representing the MCCMNC tuple (mobile country code and mobile network code) that identifies the original network of the mobile phone number.	true
`mcc`	string(3)	A three character string representing the MCC (mobile country code) that identifies the country associated with the original mobile network of the phone number.	true
`mnc`	string(2\|3)	A two or three character string representing the MNC (mobile network code) that identifies the original mobile network operator of the phone number.	true
`original_network_name`	string	An arbitrary English plain text string specifying the original network operator name of the inspected mobile phone number.	true
`original_country_name`	string	An arbitrary English plain text string specifying the original country associated with the inspected mobile phone number.	true
`original_country_code`	string(2)	A two-character ISO country code indicating the original country of the inspected mobile phone number.	true
`regions`	array	A list of human-readable strings in English that specify the geographic region(s) associated with this phone number.	true
`timezones`	array	A list of timezones (in Olson format) associated with this phone number.	true
`info_text`	string	An arbitrary string that may contain additional information about the phone number.	true
`cost`	string	A decimal value represented as a string, indicating the cost (in EUR) of this lookup.	true
`timestamp`	string	A W3C-formatted timestamp (including time zone) indicating when the lookup was completed.	true
`storage`	string	Specifies the storage name where the lookup results have been appended. This corresponds to the report name used for CSV downloads and analytics via the web interface.	true
`route`	string(3)	A three-character identifier specifying the route used for this lookup request.	true

{
    "errors":[
        "Service unavailable."
    ]
}

Error Response Params

Name	Type	Description	Nullable
`errors[]`	string[]	A list of strings explaining the error.	false

Type	Description
LANDLINE	Landline phone number.
MOBILE	Mobile phone number. Qualifies for HLR lookups to obtain additional connection status, network, portability and roaming information.
MOBILE_OR_LANDLINE	Landline or mobile phone number. Might qualify for HLR lookup.
TOLL_FREE	Toll free phone number.
PREMIUM_RATE	Premium rate phone number with additional charges.
SHARED_COST	Shared cost phone number. Typically less expensive than premium rate phone numbers.
VOIP	Voice over IP phone number. Includes TSoIP phone numbers (Telephony Service over IP).
PAGER	Pager phone number. Typically no voice functionality.
UAN	Univeral Access Number (Company Number). Might be routed to specific offices but allows one number to be used for the company.
VOICEMAIL	Voicemail phone number.
UNKNOWN	Number type could not be determined.

Scroll Up

POST/nt-lookups protected

This endpoint invokes a series of asynchronous number type lookups with results posted back to your server via webhook. It is suitable if your primary goal is to determine whether given phone numbers belong to landline, mobile, premium rate, VoIP, pager, or other numbering plan ranges. Optimized for fast processing of large volumes of numbers, this endpoint is ideal for bulk operations (e.g. database sanitization). For live traffic and time-critical use cases, please use the POST /nt-lookup endpoint instead.

You need to specify a webhook URL in your API settings as a pre-requisite to invoke this endpoint.

Request Success Response Error Response Webhooks Type Reference

curl -X POST 'https://www.hlr-lookups.com/api/v2/nt-lookups' \
          -d "@payload.json"

Payload

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

Request Params

Key	Type	Description	Default	Mandatory
`numbers`	array	An array of phone numbers in international format (e.g. +14156226819 or 004989702626). A maximum of 1000 numbers can be included per request.	null	mandatory
`route`	string(3)	An optional three-character identifier specifying the route for this lookup. Set to `null` or omit this parameter to apply your custom routing map or let our system automatically determine the best route for this request.	null	optional
`storage`	string	An optional storage identifier specifying the report where results will be stored for manual review, analytics, and reporting. The system automatically appends a timestamp with the current month. If omitted or set to `null`, the system will automatically group results by month for reporting purposes.	null	optional

{
   "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"
   ]
}

Success Response Attributes

Name	Type	Description	Nullable
`accepted`	array	An array of objects, each containing a unique identifier and a phone number that has been accepted for processing.	false
`accepted_count`	integer	The total count of phone numbers accepted for processing.	false
`rejected`	array	An array of objects, each containing a unique identifier and a phone number that was rejected for processing. Typically, these numbers are invalid, and no charge is applied.	false
`rejected_count`	integer	The total count of phone numbers that were rejected for processing.	false
`total_count`	integer	The total count of accepted and rejected phone numbers that were submitted for processing.	false
`cost`	string	A string representing a decimal value that indicates the cost in EUR for these lookups.	false
`storage`	string	The name of the storage (report) where the lookup results have been appended. This name is used for CSV downloads and analytics via the web interface.	false
`route`	string(3)	A three-character identifier that specifies the route used for this lookup request.	false
`webhook_urls`	array	The webhook URLs configured in your API settings. Results are posted back here.	false

{
    "errors":[
        "Service unavailable."
    ]
}

Error Response Params

Name	Type	Description	Nullable
`errors[]`	string[]	A list of strings explaining the error.	false

Processing Webhooks

Once submitted, our platform begins processing the provided phone numbers and sends the results to the previously specified webhook URL on your server. The results are transmitted as an HTTP POST request with a JSON object in the request body.

Authentication

Authenticate the webhook by inspecting the X-Signatures HTTP header.

The X-Signatures header contains a semicolon-separated list of signatures. Each signature in the list is generated using one of the API secrets configured in your account. To verify the webhook, generate a SHA-256 hash using your API key, secret, and the raw HTTP body — then compare it to the signatures in the list.

A match confirms the request is authentic and signed with a secret you control.

Code Example

$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;
    }
}

The request is valid if any of the signatures given in the header equals a SHA256 hash computed over the concatenated string of your API key, secret, and the HTTP body.

Confirming Receipt

Your server is expected to respond with an HTTP status code 200 OK to confirm successful receipt. If any other response code is returned, a timeout occurs (10 seconds), or any other delivery issue arises, the system will automatically retry the webhook after one minute. If the request continues to fail, retries will follow an exponential backoff strategy, with subsequent attempts after 2, 4, 8, 16, 32, 64, 128, 256, 512, 1024 minutes.

This retry mechanism ensures maximum reliability in delivering lookup results to your infrastructure. It minimizes the risk of data loss due to temporary network issues or server downtime.

Webhook Payload

{
   "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 Payload Attributes

The JSON object contains an attribute type => NT alongside an attribute results that includes a list of lookup objects, as documented below.

Name	Type	Description	Nullable
`id`	string(12)	A unique identifier assigned to this lookup request.	false
`number`	string	The phone number that was evaluated during this lookup request.	false
`number_type`	string	The detected number type. Possible values include: `LANDLINE` , `MOBILE` , `MOBILE_OR_LANDLINE` , `TOLL_FREE` , `PREMIUM_RATE` , `SHARED_COST` , `VOIP` , `PAGER` , `UAN` , `VOICEMAIL` , `UNKNOWN` .	false
`query_status`	string	Indicates whether the number type information was successfully obtained. Returns `OK` if successful, or `FAILED` if the lookup failed.	false
`is_valid`	boolean	Indicates whether the phone number is syntactically valid.	true
`invalid_reason`	string	A plain text message in English specifying why the phone number is considered invalid (e.g. "too short" or "invalid prefix"), or `null` if the number is valid.	true
`is_possibly_ported`	boolean	Indicates whether the phone number may have been ported from its original operator to a different carrier. For definitive portability information, use MNP lookups.	true
`is_vanity_number`	boolean	Indicates whether the phone number is a vanity number, meaning it includes alphabetic characters.	true
`qualifies_for_hlr_lookup`	boolean	Indicates whether the phone number is eligible for additional queries through HLR lookups.	true
`mccmnc`	string(5\|6)	A five or six character string representing the MCCMNC tuple (mobile country code and mobile network code) that identifies the original network of the mobile phone number.	true
`mcc`	string(3)	A three character string representing the MCC (mobile country code) that identifies the country associated with the original mobile network of the phone number.	true
`mnc`	string(2\|3)	A two or three character string representing the MNC (mobile network code) that identifies the original mobile network operator of the phone number.	true
`original_network_name`	string	An arbitrary English plain text string specifying the original network operator name of the inspected mobile phone number.	true
`original_country_name`	string	An arbitrary English plain text string specifying the original country associated with the inspected mobile phone number.	true
`original_country_code`	string(2)	A two-character ISO country code indicating the original country of the inspected mobile phone number.	true
`regions`	array	A list of human-readable strings in English that specify the geographic region(s) associated with this phone number.	true
`timezones`	array	A list of timezones (in Olson format) associated with this phone number.	true
`info_text`	string	An arbitrary string that may contain additional information about the phone number.	true
`cost`	string	A decimal value represented as a string, indicating the cost (in EUR) of this lookup.	true
`timestamp`	string	A W3C-formatted timestamp (including time zone) indicating when the lookup was completed.	true
`storage`	string	Specifies the storage name where the lookup results have been appended. This corresponds to the report name used for CSV downloads and analytics via the web interface.	true
`route`	string(3)	A three-character identifier specifying the route used for this lookup request.	true

Type	Description
LANDLINE	Landline phone number.
MOBILE	Mobile phone number. Qualifies for HLR lookups to obtain additional connection status, network, portability and roaming information.
MOBILE_OR_LANDLINE	Landline or mobile phone number. Might qualify for HLR lookup.
TOLL_FREE	Toll free phone number.
PREMIUM_RATE	Premium rate phone number with additional charges.
SHARED_COST	Shared cost phone number. Typically less expensive than premium rate phone numbers.
VOIP	Voice over IP phone number. Includes TSoIP phone numbers (Telephony Service over IP).
PAGER	Pager phone number. Typically no voice functionality.
UAN	Univeral Access Number (Company Number). Might be routed to specific offices but allows one number to be used for the company.
VOICEMAIL	Voicemail phone number.
UNKNOWN	Number type could not be determined.

Scroll Up

GET/routeprotected

Retrieves the route that will be automatically selected when you run an HLR lookup without specifying the route parameter.

Automatic route selection is based on the routing map retrievable with the GET /hlr-coverage endpoint, which is primarily derived from GET /routing-map. You can customize your routing map and define custom rules in your account settings.

Request Success Response Error Response

curl 'https://www.hlr-lookups.com/api/v2/route?msisdn=+491788735000'

Request Params

Key	Type	Description	Default	Mandatory
`msisdn`	string	The MSISDN for which to retrieve the automatically selected routing information.	null	mandatory

{
   "route":"V11",
   "confidence_level":"HIGH",
   "mccmnc":"26203",
   "origin":"SCORE"
}

Success Response Attributes

Name	Type	Description	Nullable
`route`	string	The recommended route.	false
`confidence_level`	string	The confidence level with which this route was selected, i.e. `LOW`, `NORMAL`, `HIGH`, `MNP_FALLBACK`.	false
`mccmnc`	string	The numbering plan based MCCMNC for this number.	false
`origin`	string	The origin on which the routing decision is based, i.e. `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

{
    "errors":[
        "Service unavailable."
    ]
}

Error Response Params

Name	Type	Description	Nullable
`errors[]`	string[]	A list of strings explaining the error.	false

Scroll Up

GET/routesprotected

This endpoint returns a list of available HLR, MNP, and NT routes. Each route, along with its features and limitations, is explained on the routing details page.

Request Success Response Error Response

curl 'https://www.hlr-lookups.com/api/v2/routes'

{
   "routes":{
      "HLR":[
         "V11",
         "E10",
         "MS9",
         "DV8",
         "SV3",
         "IP1"
      ],
      "MNP":[
         "PTX",
         "IP4"
      ],
      "NT":[
         "LC1"
      ]
   }
}

Success Response Attributes

Name	Type	Description	Nullable
`routes`	object	An object with routes grouped by route type.	false
`HLR\|MNP\|NT`	string[]	Contains a list of route identifiers.	false

{
    "errors":[
        "Service unavailable."
    ]
}

Error Response Params

Name	Type	Description	Nullable
`errors[]`	string[]	A list of strings explaining the error.	false

Scroll Up

GET/routing-mapprotected

Retrieves the automated routing configuration currently applied to HLR Lookups for your account. This default configuration is used whenever you submit HLR lookups without specifying a route parameter. You can customize your routing map and create custom rules in your account settings.

The configuration hierarchy cascades from country-level rules to MCCMNC-level rules, and finally to individual phone number prefix mappings. In practice, this means that individual phone number prefix mappings take precedence over conflicting MCCMNC assignments, which in turn override country-level rules. Please note that MNP fallback overrides any conflicting custom rules while enabled.

Request Success Response Error Response

curl 'https://www.hlr-lookups.com/api/v2/routing-map'

{
   "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"
            }
         ]
      }
   }
}

Success Response Attributes

Name	Type	Description	Nullable
`default_route`	string	The default route used when no preferred routing option can be determined for an MSISDN and no custom routing rules apply.	false
`mnp_fallback`	boolean	Indicates whether MNP fallback is enabled. When enabled and HLR queries are unsupported by a network (connectivity status unavailable), the system will perform an MNP lookup instead.	false
`mccmncs`	array	A mapping of MCCMNC codes to their automatically selected routes. When performing an HLR lookup for a number in a given MCCMNC, the corresponding route is used.	false
`mccmnc`	string(5\|6)	A five- or six-character MCCMNC (mobile country code and mobile network code combination) identifying the mobile network operator.	false
`countrycode`	string(2)	A two charatcer ISO country code, identifying the network's country.	false
`route`	string(3)	The selected route for the network.	false
`mno`	string	The consumer-facing brand under which this network operates.	false
`confidence`	string	The confidence level with which the selection was made. Possible values are: HIGH, NORMAL, LOW, MNP_REDIRECT. In case of the latter, the system redirects traffic to this network to MNP, if this behavior is enabled in your account. Otherwise it uses the default route in the account.	false
`origin`	string	The origin on which the selection is based. Possible values are: `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	A list of custom prefix-based routing rules configured in your account, if any.	false
`countrycode`	string(2)	A two charatcer ISO country code, identifying the prefix's country.	false
`cns`	string	The prefix to which the routing rule applies.	false
`route`	string(3)	The selected route for the prefix.	false
`mccmnc`	string(5\|6)	A five- or six-character MCCMNC (mobile country code and mobile network code combination) identifying the mobile network operator.	true
`mno`	string	The consumer-facing brand under which this network operates.	true
`countries`	array	A list of custom country-based rules configured in your account, if any.	false
`countrycode`	string(2)	A two charatcer ISO country code, identifying the country.	false
`route`	string(3)	The selected route for the country.	false

{
    "errors":[
        "Service unavailable."
    ]
}

Error Response Params

Name	Type	Description	Nullable
`errors[]`	string[]	A list of strings explaining the error.	false

Scroll Up

GET/hlr-coverage protected

Returns HLR coverage insights to support data-driven decision making. This endpoint helps you analyze real-time HLR routing options across mobile networks, identify the most effective paths for your target regions, and configure your automatic routing.

Recommended routes from GET /route are based on the coverage data retrieved here. Coverage data is also available on the network coverage page. You can further customize your routing map and define rules in your account settings.

We recommend to familiarize yourself with this guide to help interpreting the results.

Request Success Response Error Response Status Reference

curl 'https://www.hlr-lookups.com/api/v2/hlr-coverage?countrycode=XX'

Request Params

Key	Type	Description	Default	Mandatory
`countrycode`	string(2)	An mandatory two-letter ISO country code used to filter results, returning only records associated with the specified country.	null	mandatory
`sample_size`	string	An optional parameter specifying a sample size. Possible values are `LARGE`, `MEDIUM`, `SMALL`. Larger samples cover a longer time frame, smaller samples cover a very recent time frame.	LARGE	optional

{
   "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
            }
         ]
      }
   ]
}

Success Response Attributes

Name	Type	Description	Nullable
`name`	string	The selected country name in English plain text.	false
`countrycode`	string(2)	The two-character ISO country code of the selected country.	false
`prefix`	string	The international dialing prefix of the selected country.	false
`mccs`	string[]	A list of MCCs (mobile country codes) associated with the selected country.	false
`carriers`	object[]	A list of carrier objects with route-specific connectivity metrics.	false
`mno`	string	The mobile network operator name in English plain text.	false
`mccmnc`	string	The mobile network operator's MCCMNC.	false
`mcc`	string	The mobile network operator's MCC (mobile country code).	false
`mnc`	string	The mobile network operator's MNC (mobile network code).	false
`routes`	object[]	A list of route-specific connectivity results.	false
`route`	string	The route to which the connectivity information applies.	false
`selected`	bool	Indicates whether this is the selected route for automated routing.	false
`selection_confidence`	string	The confidence level with which this route was selected, i.e. `LOW`, `NORMAL`, `HIGH`, `MNP_FALLBACK`. Contains null if this is not the selected route.	true
`n`	int	The total number of lookups in this sample.	false
`CONNECTED`	int	The number of HLR lookups that returned a CONNECTED status.	false
`CONNECTED_PCT`	float	The percentage of HLR lookups that returned a CONNECTED status.	false
`ABSENT`	int	The number of HLR lookups that returned an ABSENT status.	false
`ABSENT_PCT`	float	The percentage of HLR lookups that returned an ABSENT status.	false
`INVALID_MSISDN`	int	The number of HLR lookups that returned an INVALID_MSISDN status.	false
`INVALID_MSISDN_PCT`	float	The percentage of HLR lookups that returned an INVALID_MSISDN status.	false
`UNDETERMINED`	int	The number of HLR lookups that returned an UNDETERMINED status.	false
`UNDETERMINED_PCT`	float	The percentage of HLR lookups that returned an UNDETERMINED status.	false

{
    "errors":[
        "Service unavailable."
    ]
}

Error Response Params

Name	Type	Description	Nullable
`errors[]`	string[]	A list of strings explaining the error.	false

Status	Description
CONNECTED	The number is valid, and the target handset is currently connected to the mobile network. Calls, SMS, and other services should reach the recipient successfully.
ABSENT	The number is valid, but the target handset is either switched off or temporarily out of network coverage. Messages or calls may not be delivered until the device reconnects to the network.
INVALID_MSISDN	The number is invalid or not currently assigned to any subscriber on the mobile network. Calls and messages to this number will fail.
UNDETERMINED	The connectivity status of the number could not be determined. This may be due to an invalid number, temporary network issues, or a lack of connectivity with the target network operator.

Scroll Up

GET/mnp-coverageprotected

This endpoint returns a list of mobile network operators, along with their corresponding MCCMNC identifiers, that are currently supported for mobile number portability lookups.

Request Success Response Error Response

curl 'https://www.hlr-lookups.com/api/v2/mnp-coverage?countrycode=XX'

Request Params

Key	Type	Description	Default	Mandatory
`countrycode`	string(2)	An optional two-letter ISO country code used to filter the MCCMNC results, returning only data relevant to the specified country.	null	optional

{
   "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"
      }
}

Success Response Attributes

Name	Type	Description	Nullable
`items[]`	array	A list of mobile network operators.	false
`country_name`	string	The country name in English.	false
`country_code`	string(2)	A two-letter ISO country code.	false
`mccmnc`	string(5\|6)	A five- or six-character MCCMNC (mobile country code and mobile network code combination) identifying the mobile network operator.	false
`mcc`	string(3)	A three-character MCC (mobile country code) representing the country of the network.	false
`mnc`	string(2\|3)	A two- or three-character MNC (mobile network code) representing the specific mobile network operator.	false
`brand`	string	The consumer-facing brand under which this network operates.	true
`operator`	string	The legal name of the mobile network operator.	true

{
    "errors":[
        "Service unavailable."
    ]
}

Error Response Params

Name	Type	Description	Nullable
`errors[]`	string[]	A list of strings explaining the error.	false

Scroll Up

GET/price-listprotected

This endpoint returns a list of countries where only MNP lookups are supported, and HLR queries are unavailable for these destinations.

Request Success Response Error Response

curl 'https://www.hlr-lookups.com/api/v2/mnp-countries'

{
   "countries":[
      "AG",
      "AI",
      "AR",
      "AS",
      "AW",
      "BB",
      "BM",
      ...
      "US",
      "UY",
      "VC",
      "VE",
      "VG",
      "VN"
   ]
}

Success Response Attributes

Name	Type	Description	Nullable
`countries`	string[]	A list of two-character ISO country codes.	false

{
    "errors":[
        "Service unavailable."
    ]
}

Error Response Params

Name	Type	Description	Nullable
`errors[]`	string[]	A list of strings explaining the error.	false

Scroll Up

GET/mccmncsprotected

This endpoint returns a comprehensive list of mobile network operators along with their corresponding MCCMNC identifiers and additional contextual information.

Request Success Response Error Response

curl 'https://www.hlr-lookups.com/api/v2/mccmncs?countrycode=XX'

Request Params

Key	Type	Description	Default	Mandatory
`countrycode`	string(2)	An optional two-letter ISO country code used to filter MCCMNC results, returning only records associated with the specified country.	null	optional

{
   "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"
      }
}

Success Response Attributes

Name	Type	Description	Nullable
`items`	object[]	A list of mobile network operators.	false
`country_name`	string	The full country name in English.	false
`country_code`	string(2)	A two-letter ISO country code representing the country of the mobile operator.	false
`mccmnc`	string(5\|6)	A five- or six-character string representing the MCCMNC, which uniquely identifies the mobile network operator.	false
`mcc`	string(3)	A three-character Mobile Country Code (MCC) that identifies the country where the mobile network operates.	false
`mnc`	string(2\|3)	A two- or three-character Mobile Network Code (MNC) that specifies the mobile network within the given MCC.	false
`brand`	string	The commercial brand name under which the network operates and is recognized by consumers.	true
`operator`	string	The official name of the mobile network operator, typically the legal entity managing the network.	true
`parent_mccmnc`	string(5\|6)	A five- or six-character string representing the MCCMNC of the parent mobile network operator, if any.	true

{
    "errors":[
        "Service unavailable."
    ]
}

Error Response Params

Name	Type	Description	Nullable
`errors[]`	string[]	A list of strings explaining the error.	false

Scroll Up

GET/priceprotected

This endpoint returns the price for an HLR, MNP, or NT lookup.

Request Success Response Error Response

curl 'https://www.hlr-lookups.com/api/v2/price?msisdn=+491788735000&route_type=HLR'

Request Params

Key	Type	Description	Default	Mandatory
`msisdn`	string	The phone number for which to retrieve the price. In international format.	null	mandatory
`route_type`	string	The route type, i.e. `HLR`, `MNP`, `NT`.	null	mandatory
`route`	string(3)	The route for which the price should be calculated. Defaults to the route determined by automated routing.	null	optional

{
   "price":{
      "amount":"0.01000",
      "msisdn":"+491788735000",
      "route_type":"HLR",
      "route":"DV8"
   }
}

Success Response Attributes

Name	Type	Description	Nullable
`price`	object	An object with pricing details.	false
`amount`	string	The amount in EUR.	false
`msisdn`	string	The MSISDN for which this price applies.	false
`route_type`	string(2\|3)	The route type for which this price applies.	false
`route`	string(3)	The route for which this price applies.	false

{
    "errors":[
        "Service unavailable."
    ]
}

Error Response Params

Name	Type	Description	Nullable
`errors[]`	string[]	A list of strings explaining the error.	false

Scroll Up

GET/price-listprotected

This endpoint returns the pricing in your account.

Request Success Response Error Response

curl 'https://www.hlr-lookups.com/api/v2/price-list'

{
   "pricing":[
      {
         "route":"V11",
         "countrycode":null,
         "mccmnc":null,
         "cns":null,
         "route_type":"HLR",
         "price":"0.0090"
      },
      {
         "route":"V11",
         "countrycode":"DE",
         "mccmnc":"26201",
         "cns":null,
         "route_type":"HLR",
         "price":"0.0070"
      },
      {
         "route":"V11",
         "countrycode":"DE",
         "mccmnc":"26203",
         "cns":"4917821",
         "route_type":"HLR",
         "price":"0.0070"
      },
      {
         "route":"V11",
         "countrycode":"DE",
         "mccmnc":null,
         "cns":null,
         "route_type":"HLR",
         "price":"0.0070"
      },
      {
         "route":"PTX",
         "countrycode":null,
         "mccmnc":null,
         "cns":null,
         "route_type":"MNP",
         "price":"0.00500"
      },
      ...
      {
         "route":"IP1",
         "countrycode":null,
         "mccmnc":null,
         "cns":null,
         "route_type":"MIX",
         "price":"0.01000"
      },
      {
         "route":"LC1",
         "countrycode":null,
         "mccmnc":null,
         "cns":null,
         "route_type":"NT",
         "price":"0.00500"
      }
   ]
}

Success Response Attributes

Name	Type	Description	Nullable
`pricing`	object[]	A list of objects with pricing information.	false
`route`	string	The route to which this pricing applies.	false
`countrycode`	string	The two-character ISO countrycode to which this pricing applies for the corresponding route, if any.	true
`mccmnc`	string	The MCCMNC to which this pricing applies for the corresponding route, if any. Overrides country-level pricing.	true
`cns`	string	The dialing prefix to which this pricing applies for the corresponding route, if any. Overrides country-level pricing and MCCMNC-level pricing.	true
`route_type`	string	The corresponding route type, i.e. `HLR`, `MNP`, `NT`.	false
`route_type`	string	The corresponding price in EUR.	false

{
    "errors":[
        "Service unavailable."
    ]
}

Error Response Params

Name	Type	Description	Nullable
`errors[]`	string[]	A list of strings explaining the error.	false

Scroll Up

GET/balanceprotected

This endpoint retrieves your current account balance, allowing you to automate processes based on your credit status. It works seamlessly with the low credit notification emails that you can configure on your payments page.

Request Success Response Error Response

curl 'https://www.hlr-lookups.com/api/v2/balance'

{
    "balance":"1002.90"
}

Success Response Attributes

Name	Type	Description	Nullable
`balance`	string	Your current account balance in EUR. A decimal value of type string.	false

{
    "errors":[
        "Service unavailable."
    ]
}

Error Response Params

Name	Type	Description	Nullable
`errors[]`	string[]	A list of strings explaining the error.	false

Scroll Up

GET/pingpublic

This endpoint sends a ping request to the API, providing a simple method to test your connection to the HLR Lookups API.

Request Success Response Error Response

curl 'https://www.hlr-lookups.com/api/v2/ping'

{
    "success":true
}

Success Response Attributes

Name	Type	Description	Nullable
`success`	boolean	Indicates that the request was processed successfully.	false

{
    "errors":[
        "Service unavailable."
    ]
}

Error Response Params

Name	Type	Description	Nullable
`errors[]`	string[]	A list of strings explaining the error.	false

Scroll Up

GET/timepublic

This endpoint returns a Unix timestamp representing the current time on the HLR Lookups server. Use it to synchronize your server's clock when generating the Digest-Auth signature for authentication, ensuring any discrepancies between your server time and the HLR Lookups server time are corrected.

Request Success Response Error Response

curl 'https://www.hlr-lookups.com/api/v2/time'

{
    "time":1525898643
}

Success Response Attributes

Name	Type	Description	Nullable
`time`	integer	Unix timestamp representing the current HLR Lookups server time.	false

{
    "errors":[
        "Service unavailable."
    ]
}

Error Response Params

Name	Type	Description	Nullable
`errors[]`	string[]	A list of strings explaining the error.	false

Scroll Up

GET/auth-testprotected

This endpoint serves as an initial test for your Basic-Auth or, preferably, Digest-Auth implementation.

Basic Auth Request Digest Auth Request Success Response Error Response

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

Request Headers

Key	Type	Description
`X-Basic`	string	SHA256 hash of `YOUR_API_KEY:YOUR_API_SECRET`. Include the colon symbol (:) in the hash.

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"

Request Headers

Key	Type	Description
`X-Digest-Key`	string	Your HLR Lookups API Key
`X-Digest-Signature`	string	Unique Digest-Auth signature (see authentication)
`X-Digest-Timestamp`	integer	Current Unix timestamp (also see `GET /time`)

{
    "success":true
}

Success Response Attributes

Name	Type	Description	Nullable
`success`	boolean	Indicates that the request was processed successfully.	false

{
    "errors":[
        "Service unavailable."
    ]
}

Error Response Params

Name	Type	Description	Nullable
`errors[]`	string[]	A list of strings explaining the error.	false

Scroll Up

Legacy API Docs

Please note that the legacy API is deprecated and is scheduled for retirement in the future. We highly recommend upgrading to the latest version at your earliest convenience.

If you implemented our HLR Lookups API between 2013 and early 2020, you are using our legacy API. Please refer to our legacy API documentation in that case.

Legacy API Docs

API Documentation

Getting Started

HLR Lookups

MNP Lookups

NT Lookups

Routing

Pricing

Tools

Getting Started

Using the HLR Lookups API

Example Request

Example Payload

Success Response application/json

Additional Lookup Services

Mobile Number Portability (MNP) Lookups

Number Type Detection (NT) Lookups

Software Development Kits (SDKs)

Tools

Not a Developer?

Authentication

API Key and API Secret

HTTP Basic Auth

Recommended: X-Basic Header with SHA256

Basic Auth Request

Basic Authentication Headers

Code Example

Request Example

Request Headers

Constructing the Signature

Digest Signature Components

Code Examples

Concepts

Synchronous HLR Lookup API

Asynchronous HLR Lookup API

SDKs (Software Development Kits)

PHP SDK

NodeJS SDK

Ruby SDK

POST/hlr-lookupprotected

Payload

Request Params

Success Response Attributes

Error Response Params

POST/hlr-lookupsprotected

Payload

Request Params

Success Response Attributes

Error Response Params

Processing Webhooks

Authentication

Code Example

Confirming Receipt

Webhook Payload

Webhook Payload Attributes

POST/mnp-lookupprotected

Payload

Request Params

Success Response Attributes

Error Response Params

POST/mnp-lookupsprotected

Payload

Request Params

Success Response Attributes

Error Response Params

Processing Webhooks

Authentication

Code Example

Confirming Receipt

Webhook Payload

Webhook Payload Attributes

POST/nt-lookupprotected

Payload

Request Params

Success Response Attributes

Error Response Params

POST/nt-lookups protected

Payload

Request Params

Success Response Attributes

Error Response Params