API URL Structure

v1 / v2

API 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.

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 -I -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 -I -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 or one of the US Territories - Puerto Rico, Guam, US Virgin Islands then we will 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.