Knowledge Base

HLR Lookup request using our API

The following documentation will help you get started with using our API to Lookup your numbers in real time to find out the current status and network information.

We recommend you submit all requests over HTTPS to ensure all requests are encrypted and privacy is ensured.

Base URL

Method           GET

Required Parameters:

apikey – Your API key can be obtained from your account settings

password – Your Account Password

msisdn – The number you wish to check

Try it – Copy this link into your browser and replace $key, $password and $msisdn with your own details.$key&password=$password&msisdn=$msisdn

A Successful HLR Lookup of a valid number will result in one credit being removed from your balance.

Don’t forget you can query your balance at any time by sending a /balance request.

TIP – If you wish to send multiple requests at once you can append multiple MSISDNs separated by a comma
(e.g. “447777123456,4477777123999”). This is limited to a maximum of 80 MSISDNs per request.



Within your API request you can also dictate the Cache Levels you wish to utilise.

Adding these parameters to your request will override the Default Cache Settings found on your Account Setting page.

If no Cache Parameters are used then the default levels you have set in your Account Settings will be used.

You can check these here – My Account Settings

Add the following parameters to your GET request to use the Cache


Header Information
personalcache A value between 0 and 30 that relates to the number of days you want to check against your Personal Cache
sharedcache A value between 0 and 30 that relates to the number of days you want to check against the Global Cache
savetoshared Set to 'on' to save this result to the Global Cache of results. Set to 0 or 'off' to not save your result


Try it – Copy this link into your browser and replace $key, $password, $msisdn, and the cache values with your own details.$key&password=$password&msisdn=$msisdn&personalcache=10&sharedcache=10&savetoshared=on

This will perform a HLR lookup of one number, first checking if you have previously had a result for that number within 10 days, and then checking if the number has been checked by another user of HLR Lookup who have allowed their results to be added to the Global Cache. This result will also be added to the Global Cache.


Copy our code examples below to integrate a real time HLR Lookup into your own code

// Copy & paste the code snippet below
const axios = require('axios');

await axios.get('',
            apikey: 'Your API KEY goes here',
            password: 'Your PASSWORD goes here',
            msisdn: 'The number to check goes here'

}).then(function (response)
}).catch(function (error)
// Copy & paste the code snippet below
function hlr_lookup($key, $password, $msisdn)
      $curl = curl_init("$key&password=$password&msisdn=$msisdn");

      curl_setopt($curl, CURLOPT_HEADER, 0);
      curl_setopt($curl, CURLOPT_POST, 0);
      curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);

      $response = curl_exec($curl);

      return $response;
# Python example for performing a HLR Lookup using the API
# This example uses the 'requests' package for HTTP operations. 
#(Install with "pip install requests")

import json
import requests

apikey = "Your API KEY goes here"
password = "Your PASSWORD goes here"

# Telephone number to lookup, including country code
msisdn = "447777123456"

url = "{0}&password={1}&msisdn={2}"
url = url.format(apikey, password, msisdn)

# Perform GET request
response = requests.get(url)
print("response.content: ", response.content)

# If request succeeded, parse JSON and use result
if response.status_code == 200:
# Parse JSON result and access individual fields
json_result = json.loads(response.content)
print("status: ", json_result["status"])
print("type: ", json_result["type"])
// Copy & paste the code snippet below
public void hlr_lookup(string key, string password, string msisdn)
      WebRequest webRequest = WebRequest.Create("" + key + "&password=" + password + "&msisdn=" + msisdn);
      webRequest.Method = "GET";

      WebResponse webResp = webRequest.GetResponse();