### Get Price List Endpoint Request Example Source: https://www.hlr-lookups.com/en/api-docs Example cURL command to retrieve the pricing list from your account. ```bash curl 'https://www.hlr-lookups.com/api/v2/price-list' ``` -------------------------------- ### Get Price Endpoint Request Example Source: https://www.hlr-lookups.com/en/api-docs Example cURL command to request the price for an HLR lookup with a specific MSISDN and route type. ```bash curl 'https://www.hlr-lookups.com/api/v2/price?msisdn=+491788735000&route_type=HLR' ``` -------------------------------- ### Get Price List Endpoint Success Response Source: https://www.hlr-lookups.com/en/api-docs Example success response for the Get Price List endpoint, showing a list of pricing objects with route, country details, and price. ```json { "pricing":[ { "route":"V11", "countrycode":null, "countryname":null, "mccmnc":null, "cns":null, "route_type":"HLR", "price":"0.0090" }, { "route":"V11", "countrycode":"DE", "countryname":"Germany", "mccmnc":"26201", "cns":null, "route_type":"HLR", "price":"0.0070" }, { "route":"V11", "countrycode":"DE", "countryname":"Germany", "mccmnc":"26203", "cns":"4917821", "route_type":"HLR", "price":"0.0070" }, { "route":"V11", "countrycode":"DE", "countryname":"Germany", "mccmnc":null, "cns":null, "route_type":"HLR", "price":"0.0070" }, { "route":"PTX", "countrycode":null, "countryname":null, "mccmnc":null, "cns":null, "route_type":"MNP", "price":"0.00500" }, ... { "route":"IP1", "countrycode":null, "countryname":null, "mccmnc":null, "cns":null, "route_type":"MIX", "price":"0.01000" }, { "route":"LC1", "countrycode":null, "countryname":null, "mccmnc":null, "cns":null, "route_type":"NT", "price":"0.00500" } ] } ``` -------------------------------- ### Get Price Endpoint Success Response Source: https://www.hlr-lookups.com/en/api-docs Example success response for the Get Price endpoint, detailing the amount, MSISDN, route type, and route. ```json { "price":{ "amount":"0.01000", "msisdn":"+491788735000", "route_type":"HLR", "route":"DV8" } } ``` -------------------------------- ### MNP Coverage Response Example Source: https://www.hlr-lookups.com/en/api-docs Example of a successful response when querying MNP coverage. It lists operators with their country details and MCCMNC identifiers. ```json { "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" } } ``` -------------------------------- ### GET /price-list Source: https://www.hlr-lookups.com/en/api-docs Returns the current pricing in your account. ```APIDOC ## GET /price-list ### Description Returns the current pricing in your account. ### Method GET ### Endpoint /price-list ### Response #### Success Response (200) - **pricing** (array) - A list of pricing details for different lookup types. - **lookup_type** (string) - The type of lookup (e.g., HLR, MNP, NT). - **price** (number) - The price per lookup. - **currency** (string) - The currency of the price. ``` -------------------------------- ### Time Response Example Source: https://www.hlr-lookups.com/en/api-docs Returns a Unix timestamp representing the current server time. ```json { "time":1525898643 } ``` -------------------------------- ### Balance Response Example Source: https://www.hlr-lookups.com/en/api-docs Shows the structure of a successful balance response, detailing cached and in-flight balances. ```json { "balance":"1002.90", "in_flight_balance":"1000.40" } ``` -------------------------------- ### Get Routing Map Configuration Response Source: https://www.hlr-lookups.com/en/api-docs Example of a successful response for the 'Get Routing Map' endpoint. It outlines the routing configuration, including default route, MNP fallback, and specific rules for different routing levels. ```json { "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" } ] } } } ``` -------------------------------- ### GET /auth-test Source: https://www.hlr-lookups.com/en/api-docs Serves as an initial test for your Basic-Auth or Digest-Auth implementation. ```APIDOC ## GET /auth-test ### Description This endpoint serves as an initial test for your `Basic-Auth` or, preferably, `Digest-Auth` implementation. ### Method GET ### Endpoint /auth-test ### Request Headers #### Basic Auth - **X-Basic** (string) - SHA256 hash of `YOUR_API_KEY:YOUR_API_SECRET`. Include the colon symbol (:) in the hash. #### Digest Auth - **X-Digest-Key** (string) - Your API Key. - **X-Digest-Signature** (string) - The generated Digest Auth signature. - **X-Digest-Timestamp** (string) - The Unix timestamp used for generating the signature. ### Request Example (Basic Auth) ```bash curl 'https://www.hlr-lookups.com/api/v2/auth-test' \ -H "X-Basic: YOUR_API_KEY" ``` ### Request Example (Digest Auth) ```bash 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" ``` ``` -------------------------------- ### Webhook Payload Example Source: https://www.hlr-lookups.com/en/api-docs This is an example of the JSON payload received when a webhook is triggered for an MNP lookup. It includes details about the lookup type and results. ```json { "type":"MNP", "results":[ { "id":"e428acb1c0ae", "msisdn":"+14156226819", "query_status":"OK", "mccmnc":"310260", "mcc":"310", "mnc":"260", "is_ported":true, "original_network_name":"Verizon Wireless:6006 - SVR/2", "original_country_name":"United States", "original_country_code":"US", "original_country_prefix":"+1415", "ported_network_name":"T-Mobile US:6529 - SVR/2", "ported_country_name":"United States", "ported_country_code":"US", "ported_country_prefix":"+1", "extra":"LRN:4154250000", "cost":"0.0050", "timestamp":"2020-08-05 21:21:33.490+0300", "storage":"WEB-CLIENT-SOLO-MNP-2020-08", "route":"PTX", "error_code":null, "error_description":null } ] } ``` -------------------------------- ### Example JSON Payload for POST /nt-lookups Source: https://www.hlr-lookups.com/en/api-docs This is an example of the JSON payload structure required for the POST /nt-lookups endpoint, including an array of phone numbers. ```json { "numbers":["+14156226819","+4989702626"], "route":null, "storage":null } ``` -------------------------------- ### Get Available Routes Response Source: https://www.hlr-lookups.com/en/api-docs Example response for the 'Get Available Routes' endpoint. It shows an object containing arrays of route identifiers grouped by HLR, MNP, and NT types. ```json { "routes":{ "HLR":[ "V11", "E10", "MS9", "DV8", "SV3", "IP1" ], "MNP":[ "PTX", "IP4" ], "NT":[ "LC1" ] } } ``` -------------------------------- ### GET /price Source: https://www.hlr-lookups.com/en/api-docs Returns the lookup price for a given MSISDN. ```APIDOC ## GET /price ### Description Returns the lookup price for a given MSISDN. ### Method GET ### Endpoint /price ### Query Parameters - **msisdn** (string) - Required - The mobile phone number to get the price for. ### Response #### Success Response (200) - **price** (number) - The price per lookup for the given MSISDN. - **currency** (string) - The currency of the price. - **error_code** (string) - Error code if the lookup failed. - **error_description** (string) - Description of the error if the lookup failed. ``` -------------------------------- ### HLR Coverage API Request Example Source: https://www.hlr-lookups.com/en/api-docs Example cURL command to request HLR coverage insights for a specific country code. ```bash curl 'https://www.hlr-lookups.com/api/v2/hlr-coverage?countrycode=XX' ``` -------------------------------- ### GET /routes Source: https://www.hlr-lookups.com/en/api-docs Returns a list of available HLR, MNP, and NT routes. ```APIDOC ## GET /routes ### Description Returns a list of available HLR, MNP, and NT routes. ### Method GET ### Endpoint /routes ### Response #### Success Response (200) - **routes** (array) - A list of available routes. - **type** (string) - The type of route (e.g., HLR, MNP, NT). - **name** (string) - The name of the route. - **description** (string) - A description of the route. ``` -------------------------------- ### GET /balance Source: https://www.hlr-lookups.com/en/api-docs Returns your current account balance in EUR. ```APIDOC ## GET /balance ### Description Returns your current account balance in EUR. ### Method GET ### Endpoint /balance ### Response #### Success Response (200) - **balance** (number) - Your current account balance in EUR. ``` -------------------------------- ### MNP Countries Response Example Source: https://www.hlr-lookups.com/en/api-docs Example of a successful response listing countries that support MNP lookups. The response contains an array of two-character ISO country codes. ```json { "countries":[ "AG", "AI", "AR", "AS", "AW", "BB", "BM", ... "US", "UY", "VC", "VE", "VG", "VN" ] } ``` -------------------------------- ### GET /routing-map Source: https://www.hlr-lookups.com/en/api-docs Returns the automated routing configuration in your account. ```APIDOC ## GET /routing-map ### Description Returns the automated routing configuration in your account. ### Method GET ### Endpoint /routing-map ### Response #### Success Response (200) - **routing_map** (object) - The automated routing configuration. - **default_route** (string) - The default route. - **routes** (array) - A list of specific routing rules. - **condition** (string) - The condition for the rule. - **route** (string) - The route to use when the condition is met. ``` -------------------------------- ### API Error Response Example Source: https://www.hlr-lookups.com/en/api-docs Example of an error response from the API, indicating a service issue. This structure is common across different endpoints. ```json { "errors":[ "Service unavailable." ] } ``` -------------------------------- ### GET /ping Source: https://www.hlr-lookups.com/en/api-docs Sends a ping request to the API server to test liveliness. ```APIDOC ## GET /ping ### Description Sends a ping request to the API server to test liveliness. ### Method GET ### Endpoint /ping ### Response #### Success Response (200) - **message** (string) - A message indicating the API server is alive (e.g., "pong"). ``` -------------------------------- ### Example cURL Request for POST /nt-lookups Source: https://www.hlr-lookups.com/en/api-docs This snippet shows how to make a POST request to the /nt-lookups endpoint using cURL, sending a JSON payload. ```bash curl -X POST 'https://www.hlr-lookups.com/api/v2/nt-lookups' \ -d "@payload.json" ``` -------------------------------- ### GET /auth-test Source: https://www.hlr-lookups.com/en/api-docs Inspects Digest-Auth or Basic-Auth headers and verifies your authentication implementation. ```APIDOC ## GET /auth-test ### Description Inspects Digest-Auth or Basic-Auth headers and verifies your authentication implementation. ### Method GET ### Endpoint /auth-test ### Response #### Success Response (200) - **message** (string) - A message indicating the success or failure of the authentication test. ``` -------------------------------- ### Example Error Response Source: https://www.hlr-lookups.com/en/api-docs This JSON object represents an error response from the API, indicating a service unavailability. ```json { "errors":[ "Service unavailable." ] } ``` -------------------------------- ### GET /price-list Source: https://www.hlr-lookups.com/en/api-docs This endpoint returns the pricing details available in your account. The response includes pricing for various routes, country codes, and route types. ```APIDOC ## GET /price-list ### Description This endpoint returns the pricing in your account. ### Method GET ### Endpoint /api/v2/price-list ### Request Example ``` curl 'https://www.hlr-lookups.com/api/v2/price-list' ``` ### Response #### Success Response (200) - **pricing** (object[]) - A list of pricing objects, each containing details about a specific route and its price. - **route** (string) - The route identifier. - **countrycode** (string) - The two-letter ISO country code. - **countryname** (string) - The full country name. - **mccmnc** (string) - The MCCMNC identifying the mobile network operator. - **cns** (string) - Additional network information. - **route_type** (string) - The type of route (e.g., HLR, MNP, MIX, NT). - **price** (string) - The price for the specified route and type. #### Response Example ```json { "pricing":[ { "route":"V11", "countrycode":null, "countryname":null, "mccmnc":null, "cns":null, "route_type":"HLR", "price":"0.0090" }, { "route":"V11", "countrycode":"DE", "countryname":"Germany", "mccmnc":"26201", "cns":null, "route_type":"HLR", "price":"0.0070" } ] } ``` ### Error Response #### Error Response Params - **errors[]** (string[]) - A list of strings explaining the error. ``` -------------------------------- ### GET /route Source: https://www.hlr-lookups.com/en/api-docs Returns the HLR route that will be automatically selected for a given MSISDN. ```APIDOC ## GET /route ### Description Returns the HLR route that will be automatically selected for a given MSISDN. ### Method GET ### Endpoint /route ### Query Parameters - **msisdn** (string) - Required - The mobile phone number to get the HLR route for. ### Response #### Success Response (200) - **route** (string) - The HLR route for the given MSISDN. - **country_code** (string) - The country code of the MSISDN. - **operator_name** (string) - The name of the mobile network operator. - **mccmnc** (string) - The Mobile Country Code and Mobile Network Code. - **error_code** (string) - Error code if the lookup failed. - **error_description** (string) - Description of the error if the lookup failed. ``` -------------------------------- ### GET /time Source: https://www.hlr-lookups.com/en/api-docs Returns the current server timestamp. Use this for Digest-Auth to ensure synchronization between your client and the server. ```APIDOC ## GET /time ### Description Returns the current server timestamp. Use this for Digest-Auth to ensure synchronization between your client and the server. ### Method GET ### Endpoint /time ### Response #### Success Response (200) - **timestamp** (integer) - The current server timestamp in Unix epoch time (seconds). ``` -------------------------------- ### GET /routes Source: https://www.hlr-lookups.com/en/api-docs Returns a list of available HLR, MNP, and NT routes. Each route's features and limitations are detailed on the routing details page. ```APIDOC ## GET /routes __protected ### Description 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. ### Method GET ### Endpoint /api/v2/routes ### Request Example ```bash curl 'https://www.hlr-lookups.com/api/v2/routes' ``` ### Response #### Success Response (200) - **routes** (object) - An object with routes grouped by route type. - **HLR|MNP|NT** (string[]) - Contains a list of route identifiers. #### Response Example ```json { "routes":{ "HLR":[ "V11", "E10", "MS9", "DV8", "SV3", "IP1" ], "MNP":[ "PTX", "IP4" ], "NT":[ "LC1" ] } } ``` #### Error Response (4xx/5xx) - **errors[]** (string[]) - A list of strings explaining the error. #### Error Response Example ```json { "errors":[ "Service unavailable." ] } ``` ``` -------------------------------- ### GET /price Source: https://www.hlr-lookups.com/en/api-docs This endpoint returns the price for an HLR, MNP, or NT lookup. It requires the phone number (msisdn) and the route type. ```APIDOC ## GET /price ### Description This endpoint returns the price for an HLR, MNP, or NT lookup. ### Method GET ### Endpoint /api/v2/price ### Parameters #### Query Parameters - **msisdn** (string) - mandatory - The phone number for which to retrieve the price. In international format. - **route_type** (string) - mandatory - The route type, i.e. `HLR`, `MNP`, `NT`. - **route** (string(3)) - optional - The route for which the price should be calculated. Defaults to the route determined by automated routing. ### Request Example ``` curl 'https://www.hlr-lookups.com/api/v2/price?msisdn=+491788735000&route_type=HLR' ``` ### Response #### Success Response (200) - **price** (object) - An object with pricing details. - **amount** (string) - The amount in EUR. - **msisdn** (string) - The MSISDN for which this price applies. - **route_type** (string(2|3)) - The route type for which this price applies. - **route** (string(3)) - The route for which this price applies. #### Response Example ```json { "price":{ "amount":"0.01000", "msisdn":"+491788735000", "route_type":"HLR", "route":"DV8" } } ``` ### Error Response #### Error Response Params - **errors[]** (string[]) - A list of strings explaining the error. ``` -------------------------------- ### cURL Request for POST /hlr-lookup Source: https://www.hlr-lookups.com/en/api-docs Example of how to make a POST request to the /hlr-lookup endpoint using cURL, sending data from a JSON payload file. ```bash curl -X POST 'https://www.hlr-lookups.com/api/v2/hlr-lookup' \ -d "@payload.json" ``` -------------------------------- ### Get Price List (MNP Countries) Source: https://www.hlr-lookups.com/en/api-docs Retrieve a list of countries where only MNP lookups are supported. Use this to identify destinations where HLR queries are not available. ```curl curl 'https://www.hlr-lookups.com/api/v2/mnp-countries' ``` -------------------------------- ### Initiate Batch MNP Lookups Request Source: https://www.hlr-lookups.com/en/api-docs Use this cURL command to initiate a batch of asynchronous MNP lookups. Ensure a webhook URL is configured to receive results. ```bash curl -X POST 'https://www.hlr-lookups.com/api/v2/mnp-lookups' \ -d "@payload.json" ``` -------------------------------- ### HTTP Basic Auth Request Example Source: https://www.hlr-lookups.com/en/api-docs This cURL command demonstrates how to authenticate a request using HTTP Basic Authentication by including your API key and secret in the URL. ```bash curl 'https://YOUR_API_KEY:YOUR_API_SECRET@www.hlr-lookups.com/api/v2/auth-test' ``` -------------------------------- ### Ruby HLR Lookup Client Initialization and Request Source: https://www.hlr-lookups.com/en/api-docs Initializes the Ruby HLR Lookup client with API credentials and a log file path, then performs a GET request for an HLR lookup. ```ruby 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) ``` -------------------------------- ### PHP HLR Lookup Client Initialization and Request Source: https://www.hlr-lookups.com/en/api-docs Initializes the PHP HLR Lookup client with API credentials and a log file path, then performs a POST request for an HLR lookup. ```php 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); ``` -------------------------------- ### Get Automatically Selected Route Response Source: https://www.hlr-lookups.com/en/api-docs Example of a successful response when retrieving the automatically selected route for an HLR lookup. It details the selected route, confidence level, MCCMNC, and the origin of the decision. ```json { "route":"V11", "confidence_level":"HIGH", "mccmnc":"26203", "origin":"SCORE" } ``` -------------------------------- ### Digest Auth Request Example Source: https://www.hlr-lookups.com/en/api-docs This cURL command illustrates how to make a request using Digest Authentication, requiring the API key, a signature, and a timestamp in the headers. ```bash 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" ``` -------------------------------- ### Webhook Payload Example Source: https://www.hlr-lookups.com/en/api-docs This is an example of the JSON payload structure received by your webhook URL. It contains details about the processed phone number, including its type, state, validity, and carrier information. ```json { "type":"NT", "results":[ { "id":"9f8a52cfa7d2", "number":"+905536939460", "numbertype":" MOBILE", "state":"COMPLETED", "isvalid":"Yes", "invalidreason":null, "ispossiblyported":"Yes", "isvanitynumber":"No", "qualifiesforhlrlookup":"Yes", "originalcarrier":"Turk Telekom (AVEA)", "mccmnc":"28603", "mcc":"286", "mnc":"03", "countrycode":"TR", "regions":[ "Turkey" ], "timezones":[ "Europe\/Istanbul" ], "infotext":"This number qualifies for HLR lookups. Determine if this subscriber number is connected, absent or invalid by running an HLR lookup. This is a mobile number and might be in roaming state. Run an HLR lookup to obtain roaming information (if available). This number is possibly ported and the carrier information might be inaccurate. To obtain portability information run an HLR lookup.", "usercharge":"0.0050", "inserttime":"2020-08-13 01:57:15.897+0300", "storage":"ASYNC-API-NT-2020-08", "route":"LC1", "interface":"Async API" } ] } ``` -------------------------------- ### Example Success Response for POST /nt-lookups Source: https://www.hlr-lookups.com/en/api-docs This JSON object represents a successful response from the POST /nt-lookups endpoint, detailing accepted and rejected numbers, cost, and storage information. ```json { "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" ] } ``` -------------------------------- ### Initiate Batch HLR Lookups Source: https://www.hlr-lookups.com/en/api-docs Use this cURL command to send a POST request to initiate a batch of asynchronous HLR lookups. The payload should be provided in a separate JSON file. ```bash curl -X POST 'https://www.hlr-lookups.com/api/v2/hlr-lookups' \ -d "@payload.json" ``` -------------------------------- ### GET /hlr-coverage Source: https://www.hlr-lookups.com/en/api-docs Displays the current network coverage information for HLR lookups. ```APIDOC ## GET /hlr-coverage ### Description Displays the current network coverage information for HLR lookups. ### Method GET ### Endpoint /hlr-coverage ### Response #### Success Response (200) - **coverage** (array) - A list of countries and their HLR lookup availability. - **country_code** (string) - The country code. - **country_name** (string) - The name of the country. - **supported** (boolean) - Indicates if HLR lookups are supported in this country. ``` -------------------------------- ### GET /mnp-countries Source: https://www.hlr-lookups.com/en/api-docs Returns a list of countries in which HLR is unsupported and MNP queries are the only option. ```APIDOC ## GET /mnp-countries ### Description Returns a list of countries in which HLR is unsupported and MNP queries are the only option. ### Method GET ### Endpoint /mnp-countries ### Response #### Success Response (200) - **countries** (array) - A list of countries where MNP is the only option. - **country_code** (string) - The country code. - **country_name** (string) - The name of the country. ``` -------------------------------- ### Basic Auth Request with X-Basic Header Source: https://www.hlr-lookups.com/en/api-docs This cURL command shows how to authenticate using the X-Basic header, which contains a SHA256 hash of your API key and secret for enhanced security. ```bash curl 'https://www.hlr-lookups.com/api/v2/auth-test' \ -H "X-Basic: BASIC_AUTH_HASH" ``` -------------------------------- ### GET /ping Source: https://www.hlr-lookups.com/en/api-docs Sends a ping request to the API to test your connection to the HLR Lookups API. ```APIDOC ## GET /ping ### Description This endpoint sends a ping request to the API, providing a simple method to test your connection to the HLR Lookups API. ### Method GET ### Endpoint /ping ### Response #### Success Response (200) - **success** (boolean) - Indicates that the request was processed successfully. #### Response Example ```json { "success":true } ``` ### Error Response #### Error Response Params - **errors[]** (string[]) - A list of strings explaining the error. #### Error Response Example ```json { "errors":[ "Service unavailable." ] } ``` ```