Register and try for FREE without any obligation
 EN
Login Sign up
ES
  • Home
  • SMS API

API HLR Lookup

LabsMobile's API HLR Lookup is designed for technicians and customers who want to check the availability of a cell phone number.

The most common applications of the HLR API are:

  • The updating and debugging of a mobile database
  • The real-time status check of a mobile number in a registration or authentication process.

This documentation explains the integration process in detail. Read more about the HLR services and their benefits.

To start an integration with the HLR Lookup API the following requirements are essential:

  • A LabsMobile account associated with a username (registration email). Create an account here.
  • API token used as password and generated from the API Settings section of your account.
  • URL of the HLR API endpoint and the values of the parameters listed below.

To be taken into account

LabsMobile's API HLR is a REST API using the HTTP GET protocol with a common base URL for all requests: https://api.labsmobile.com/hlr.

It is recommended to use a URL that includes the HTTPS protocol in any version of our API.

Important A maximum of 10 requests per second is established. Misuse, abuse or a higher volume of requests will result in a temporary or permanent blocking of the account and/or IP address.

Authentication

The authentication method used in the OTP API is Basic Auth HTTP.

This type of authentication consists of username:tokenapi credentials that are included in the HTTP request header encoded in base64().

Example of authentication header value:
Authorization: Basic 9yewaXic21vYmlsZqS5jmSk04enFTbUU=

HLR Query

HLR application for one or more cell phone numbers.

This HLR query provides the status or availability of the number and related information: current operator, format, type of number, country of subscription, etc.

ENDPOINT

GET https://api.labsmobile.com/hlr

  • PARAMETERS

  • Expand all

    RESULT

    The result of any HLR API request is obtained in JSON format with the values detailed below:

  • Expand all

    RESULT BY NUMBER

Example HLR query 
curl --user myUsername:myToken -X GET \
  'https://api.labsmobile.com/hlr/?numbers=573058156414%2C528130939475%2C51918213400'\
  -H 'Cache-Control: no-cache' \
              
CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "GET");
curl_easy_setopt(hnd, CURLOPT_URL, "https://api.labsmobile.com/hlr/?numbers=573058156414,528130939475,51918213400");
curl_easy_setopt(hnd, CURLOPT_HTTPAUTH, (long)CURLAUTH_BASIC);
curl_easy_setopt(hnd, CURLOPT_USERNAME, "myUsername");
curl_easy_setopt(hnd, CURLOPT_PASSWORD, "myToken");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "Cache-Control: no-cache");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

CURLcode ret = curl_easy_perform(hnd);

            
var client = new RestClient("https://api.labsmobile.com/hlr/?numbers=573058156414,528130939475,51918213400");
client.Authenticator = new HttpBasicAuthenticator("myUsername", "myToken");
var request = new RestRequest(Method.GET);
request.AddHeader("Cache-Control", "no-cache");
IRestResponse response = client.Execute(request);
            
HttpResponse<String> response = Unirest.get("https://api.labsmobile.com/hlr/?numbers=573058156414,528130939475,51918213400")
  .basicAuth("myUsername","myToken")
  .header("Cache-Control", "no-cache")
  .asString();
            
<?php 
$auth_basic = base64_encode("myUsername:myToken");

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api.labsmobile.com/hlr/?numbers=573058156414,528130939475,51918213400",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => array(
    "Authorization: Basic ".$auth_basic,
    "Cache-Control: no-cache",
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

            
import http.client, base64
usrPass = "myUsername:myToken"
b64Val = base64.b64encode(bytes(usrPass, 'utf-8'))

conn = http.client.HTTPConnection("api.labsmobile.com")

payload = ""
headers = {
    'Authorization': "Basic %s" % b64Val.decode('utf-8'),
    'Cache-Control': "no-cache"
    }

conn.request("GET", "/json/hlr/?numbers=573058156414,528130939475,51918213400", payload, headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

            
const axios = require('axios');
let data = '';

let config = {
  method: 'get',
  maxBodyLength: Infinity,
  url: `https://api.labsmobile.com/hlr/?numbers=573058156414,528130939475,51918213400`,
  headers: { 
    'Content-Type': 'application/json', 
    'Authorization': 'Basic ' + Buffer.from("myUsername:myToken").toString('base64')
  },
  data : data
};

axios.request(config)
.then((response) => {
  console.log(JSON.stringify(response.data));
})
.catch((error) => {
  console.log(error);
});

            
require 'uri'
require 'net/http'
require 'base64'

url = URI("https://api.labsmobile.com/hlr/?numbers=573058156414,528130939475,51918213400")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Basic ' + Base64::encode64("myUsername:myToken")
request["Cache-Control"] = 'no-cache'

response = http.request(request)
puts response.read_body
Positive result 
{
  "result":"ok",
  "error":"",
  "numbers":[
  {
    "msisdn":"573058156414",
    "status":"active",
    "country_name":"Colombia",
    "country_code":"57",
    "country_iso":"CO",
    "network":"Colombia Movil SA(TIGO)",
    "mcc":"732",
    "mnc":"103",
    "format":"valid",
    "type":"mobile"
  },
  {
    "msisdn":"528130939475",
    "status":"active",
    "country_name":"Mexico",
    "country_code":"52",
    "country_iso":"MX",
    "network":"Radiomovil Dipsa(TELCEL)",
    "mcc":"334",
    "mnc":"020"
    "format":"valid",
    "type":"fixedormobile"
  },
  {
    "msisdn":"51918213400",
    "status":"not_active",
    "country_name":"Peru",
    "country_code":"51",
    "country_iso":"PE",
    "network":"Viettel Peru SAC",
    "mcc":"716",
    "mnc":"015"
    "format":"valid",
    "type":"mobile"
  }],
  "count":3,
  "credits":0.3
}
Wrong result 
{
  "result":"ko",
  "error":"invalidauth"
}

Errors

The error codes that may be returned by a request to the HLR API are described below.

HLR API Error Codes
HTTP CodeJSON ErrorsDescription
200Request processed correctly.
400requiredfields typeerror numberslimitError in one of the request parameters. Mandatory fields with no value, incorrect type parameter value or number list size greater than 100.
401invalidauthIncorrect credentials (username or token).
402nocreditsThe account does not have sufficient balance for the HLR request.
500internalerrorTemporary error or incidence in the service.

Support resources

We recommend that you consult and take into account the following help resources in your integration: