Getting Started

Introduction

The following documentation will enable you to get started with HLR Lookup's easy to use APIs.

Our APIs allow you to integrate obtaining the status of your phone numbers into your own code or internal infrastructure without having to access your account on the HLR Lookup Portal.

These docs will walk you through how to make a HLR Lookup, what you should expect to see in the response, what the response means and how you can use the API to request additional information.

If you have any questions not covered in this Knowledge Base, we've answered some of our most common questions on our FAQ page. If you still need help just get in touch, we're always happy to help.

Coverage

Our aim is to have the the most comprehensive coverage as possible.

The HLR Lookup team are constantly adapting and updating our routing to introduce new countries to our coverage or to replace destinations that may have been lost.

Due to this our Coverage List changes regularly and we advise clients to check the coverage levels for the country / network they wish to check.

There are some Network Operators where it is not possible to obtain the current status of the mobile numbers that belong to them. This is marked on our Coverage Checker as Only MCC MNC information available.

If you check a number where this is the coverage level we can achieve then in your result you will see NOT_AVAILABLE_NETWORK_ONLY

If no coverage is available, meaning it is not possible for us to obtain any information, then your result will show NO_COVERAGE and you will not be charged.

For a more detailed explanation on the result types you will receive please visit our API RESULTS page.

API Testing Suite

The testing suite is extremely useful and allows you to integrate the API without incurring any billable charges.

The credentials for using the testing suite are:

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

api_key = speedtest
api_secret = speedtest

CURL example of the full request:

curl -s -H "Content-Type: application/json" -X POST -d '{"api_key":"speedtest",
"api_secret":"speedtest", "requests":[{"telephone_number": "441133910781"}]}'
https://testing.hlrlookup.com/apiv2/hlr

We've detailed the full capabilities of the Testing Suite in these docs - Testing Suite

Please refer to these for a more detailed explanation of how you can test your API without using any credits.

Once you're successfully performing HLR Lookups with the testing credentials it's a simple URL and credential change to move into production.

Balance Checking

You can use the API to check your balance at any time. All you need is your KEY and SECRET

CURL example of the balance check request:

Request Type: POST

curl -s -H "Content-Type: application/json" -X POST -d '{"api_key":"your_api_key",
"api_secret":"your_api_secret"}'
https://api.hlrlookup.com/apiv2/balance

This request will return the amount of credits you have left on your balance.

Example balance check response:

{
    "body": {
        "Status": "OK",
        "Credits": 15000
    }

API Response Format

JSON is unordered. Do not try and integrate by iterating over the JSON response and expect fields to remain in the same order. Fields often do change order, even if it looks like they do not.

We add free features to the service by including new additional response fields. We do this in a way which will not break existing integrations as we will not change existing fields, we will only add new fields.

If a new feature is introduced which would incur an increase in charging, then it is added as an optional feature (e.g. ​get_ported_date​) and you must explicitly include the request for this feature when the request is sent to us.

Speed and Throughput

Different telephone networks take different amounts of time to respond. Typically you can expect UK telephone networks to take under 1 second to respond to us and then the round trip latency between your request location and our service is added.

Our service uses AWS and is optimised to reduce latency by automatically directing your request to your nearest AWS edge location. Once the request is inside the AWS infrastructure it is routed over private networks to our service.

High throughput can be achieved by initiating a higher number of requests per second. For example, if a telephone network is slow (e.g. Guinea) and takes 10 seconds to respond, you could initiate 20 requests each second to us and receive a throughput of 20 requests per second after an initial 10-second lag.

You do not wait for a response before initiating a new request.

Each customer is rate limited internally at 210 concurrent requests, regardless of how long each request takes. To maintain longevity for the HLR Lookup service, on the telephone network side, we balance requests per network at different throughput rates (see “429 Too Many Requests”).

We run an optional cache system which can significantly reduce latency by returning results recently checked across the global hlrlookup.com system.

429 Too Many Requests

Because some telephone networks are unable to handle a large throughput of requests per second (e.g. > 300/second) we have been experimenting with throttling requests depending on network conditions to specific telephone networks at that time.

If we detect that a telephone network is slowing down, or is returning errors due to too many requests, then we will back off our requests and the API will return a HTTP 429 error message. You will need to resubmit the telephone number you tried as we did not send it to the telephone network.

You can choose to reduce the number of requests overall per second or only for that network if you know the original network in advance (ask your account manager about our e164 validation service to detect which network a telephone number was assigned to without performing a HLR Lookup).

Most clients submit less than 50 requests per second to us and in the vast majority of cases this will not result in 429 Too Many Requests, however you should add the ability to handle HTTP 429 errors returned from the API to allow for future increases in your traffic.

Free integration code assistance

We have an internal team of HLR coders who would absolutely love to help with integrating our API. If you get stuck, need any help, need anything confirming or would like us to review your code for free please send an email to support@hlrlookup.com or raise a ticket through your account on portal.hlrlookup.com.

We support TLS for email - if you know that you support this then it is safe to include your api_key and api_secret in email, otherwise please remove keys/secrets from email.

Our technical team are all currently UK based and work 9am-5pm Monday-Friday. You might not get a response unless it is between these hours.