HLR Lookup Documentation

The HLR Lookup Developer Hub

Welcome to the HLR Lookup help pages. Here you'll find all the information you need to get started with our API or batch upload services.
Search the docs for explanations on the results you'll receive and a breakdown of all the possible parameters available.

How to Upload a Batch

We've designed our service to make processing numbers as easy and simple as possible but there are a few rules you should follow below to ensure your results are returned without any issues.

Preparing your file.

With the exception of UK numbers, your numbers need to be saved in their international format. This means they must be preceded by the relevant country code with the leading zero removed.

You can find a list of country codes on our coverage checker page.

Save your file in one of the following file types - .xlsx .xls .txt .csv

We'll ignore any non-numerical characters from your list of numbers so feel free to leave any brackets or hyphens in your file.

You can leave any other associated data in your file, just make sure all your numbers are saved in the same column and we'll ask you wish column you want us to check when you upload your file.


Numbers not stored in their international format will be flagged as REJECTED within your results file. You are not charged for anything marked as REJECTED.


Be careful with commas. Our system converts your file into a .CSV. This means any commas we see we'll treat as a new column in your file. Issues can arise if you are uploading an excel file where inside one cell you might have a reference number that contains a comma (userid:#23,45) or maybe a name split with a comma (stable,cottage). This can cause your results .CSV to be slightly misaligned.

Uploading your file.

Navigate to the batch upload page by selecting Number Lookup > Batch Processing.

Once you have selected your file you will be presented with the following options:

  • MSISDN Column

Use the drop down to select the column within your file where you mobile numbers are stored. We will process anything stored within this column.
If your numbers are saved within different columns you will either need to edit your file or upload more than once, selecting a different column each time.

  • Personal Cache Days

Select how many days you would like us to go back if you want to utilise your Personal Cache.
For more details see - Personal and Shared Cache

  • Shared Cache Days

Select how many days you would like us to go back if you want to utilise the Shared Cache.
For more details see see - Personal and Shared Cache

  • Save to Shared Cache (check box)

Tick this box if you would like your numbers adding to our Shared Cache.
For more details see - Save to Shared Cache

  • Are you checking a UK number? (check box)

We can edit UK numbers to ensure they are in the correct format for processing. If you check this box your numbers can be in any of the following formats and we will ensure they begin with ‘44’ as per the country code for the UK.

07546 XXXXXX
00447546 XXXXXX


All non UK numbers must be preceded by their correct country code.

Running your file.

Once you have selected all of your parameters, click confirm and your file will be loaded to our system.

Your file will appear on the batch processing page.

If you want to start your batch immediately, navigate to the Action drop down menu and select Run

Your file will now start processing and you can monitor it's progress through the process bar alongside your file name.
There are 3 stages to processing. We'll firstly validate all the numbers in your file and check all of the numbers against any cache requirements you may have selected. Next we'll send your numbers to the relevant networks. Then finally we'll generate your results into your output file.

When your file is complete you can download your results by selecting Download from the Action drop down menu.


We will provide your results file in the exact same order they were originally uploaded.


For larger size files your progress bar may show 100% for a short time period before being listed as Complete. This is due to the time it takes to generate your file once all your results have been received.

Scheduling your Batch.

You can set your batch to start processing at anytime in the future. From the Action menu just click Schedule and select the date and time you wish for your batch to start.

Video Help.

Watch our short video to see how easy it is.