HLR Lookup API v2 URL Structure

Base URL

To use the HLR Lookup API you use the following base URL:

https://api.hlrlookup.com/apiv2

To perform a HLR Lookup you simply add /hlr to your URL

https://api.hlrlookup.com/apiv2/hlr

Or to perform an MNP lookup you can add /mnp

https://api.hlrlookup.com/apiv2/mnp

Or to perform a VALIDATOR lookup you can add /validate

https://api.hlrlookup.com/apiv2/validate

Required POST Parameters

For all lookups you need to include your unique KEY and SECRET so we can authenticate your request.

Required Parameters	Value	Description
`api_key`	The API KEY you want to use	Your API KEY can be found by logging into your account and navigating to your settings under the Account header.
`api_secret`	The SECRET for the API KEY	Your API SECRET can be found by logging into your account and navigating to your settings under the Account header.

Note - Before using the API for the first time you may need to generate your KEY and SECRET.

Navigate to your settings under the account header when logged in. Look under the APIv2 header and hit generate to get your unique KEY and SECRET.

Using the JSON request format only, the telephone number you wish to lookup should be included in the requests section of your POST.

Required Parameters	Value	Description
`requests`	JSON request format only
`telephone_number`	JSON request	Telephone number you want to lookup when using JSON format. To lookup more than one telephone number at the same time, include multiple telephone_number elements. The results response will maintain the same order of telephone_number elements.

Required Parameters

Value

Description

requests

JSON request format only

telephone_number

JSON request

Telephone number you want to lookup when using JSON format.

To lookup more than one telephone number at the same time, include multiple telephone_number elements. The results response will maintain the same order of telephone_number elements.

Example using just the required parameters:

{
  "api_key": "your-api-key",
  "api_secret": "your-api-secret",
  "requests": [
    {
      "telephone_number": "441133910781"
    }
  ]
}

Note - This quick example uses the HLR Lookup office UK landline telephone number and won’t be charged because the optional flag to check landlines has not been submitted.

Curl example:

curl -H "Content-Type: application/json" -X POST -d `{"api_key": "your_api_key_here", "api_secret": "your_api_secret_here", "requests": [{"telephone_number": "441133910781"}]}`
https://api.hlrlookup.com/apiv2/hlr

Curl example using multiple numbers:

curl -H "Content-Type: application/json" -X POST -d `{"api_key": "your_api_key_here", "api_secret": "your_api_secret_here", "requests": [{"telephone_number": "441133910781"},
{"telephone_number": "441133910781"},
{"telephone_number": "441133910781"}]}`
https://api.hlrlookup.com/apiv2/hlr

Important Note - Up to 80 telephone numbers can be included in your request. Including more than 80 telephone numbers will result in a BAD_REQUEST error

Optional POST Parameters

Optional Parameters	Value	Description
`cache_days_private`	Integer values from 0 (no cache) up to 30 If omitted your default settings will be used	The number of days to look back in the local Private Cache for the same telephone number from this same account. Default can be set under account settings.
`cache_days_global`	Integer values from 0 (no cache) up to 30 If omitted your default settings will be used	The number of days to look back in the Global Cache for the same telephone number checked across all of HLR Lookup. Default can be set under account settings.
`save_to_cache`	YES	Allow this result to be retrievable form the Global Cache for all users if they request to check the same telephone number. Entered number also made available in your Private Cache
	NO	Do not allow this result to be retrievable from the Global Cache.
	PRIVATE If omitted your default settings will be used	Only allow the same user to retrieve this result from the Cache. Default can be set under account settings.
`output_format`	See the table for possible values: Number Formatting - Output	Additional formatting of the detected telephone number in the response field formatted_telephone_number
`input_format`	See the table for possible values: Number Formatting - Input	Any single ISO3 country code. E.G USA or FRA or GBR. This specifies which country the telephone_number should be checked against. By specifying this, customer can provide non e164 telephone_numbers. For example in their local format.
`get_ported_date`	YES	If the number is identified as a ported telephone_number and is in coverage for our ported date destinations then we will attempt a ported date lookup. There is an additional charge for a ported date lookup.
	NO	Do not attempt to retrieve the last ported date.
	No is the default if omitted	Go to the page Ported Date Feature for additional information, countries covered and charging information.
`get_landline_status`	YES	If the number is identified as a landline telephone_number and is in coverage for our landline status destinations then we will attempt a landline status check. There is an additional charge for a landline lookup and response speed is longer
	NO	Do not attempt to retrieve the last ported date.
	No is the default if omitted	Go to the page Landline Status Feature for additional information, countries covered and charging information.
`usa_status`	YES	If the telephone number is identified as a MOBILE telephone number and as belonging to the USA then we will perform a status check. Note - if the number belongs to one of the US Territories - Puerto Rico, Guam, US Virgin Islands then we will not perform a status check.
	NO	Do not attempt to retrieve the USA status.
	No is the default if omitted	Go to the page USA Status Feature for additional information and charging information.

API URL Structure

Base URL

Required POST Parameters

Optional POST Parameters