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
numbers string | list mandatory
Mobile numbers to be included in the HLR application. Numbers must be included in E.164 international format with the country code and without "+" or "00". May contain a single number or a list of numbers separated by commas with a maximum of 100 numbers.
Example:
numbers=573058156414,528130939475
,51918213400 type string
Type of HLR check.
Check type valuesformat
Number format validation. Cost: 0.01 credits per issue. network
Validation of the format and obtaining the current network or operator of the number. Cost: 0.75 credits. status
Query number status, validate format and obtain current network. Cost: 0.1 credits per number. Default value. - Expand all
RESULT
The result of any HLR API request is obtained in
JSON
format with the values detailed below: result string
Successful or unsuccessful result of the request. Values:
ok
ko
numbers array
Result information by number included in the request. The format and data obtained are detailed in RESULT BY NUMBER.
error string
Description in case of error. No value in case the request is successful. Values:
requiredfields
internalerror
numberslimit
nocredits
invalidauth
invalidauth
.
See more information about Errors.count integer
Number of requests processed.
credits float
Number of credits that have been consumed by all HLR request checks.
- Expand all
RESULT BY NUMBER
msisdn string
Mobile number in international format E.164 without "+" or "00".
status string
Indicates the availability of the number.
Values of the state of a numberactive
Recently available and active. absent
Valid but without recent network connection. not_active
Incorrect or no active subscription. not_mobile
The format does not correspond to a mobile number. unknown
Temporary error in HLR request. It has not been possible to obtain a status due to some incident on the network or the device. A subsequent query may return a successful result ( active
,absent
, ornot_active
).error
HLR request failed. Due to the configuration of the mobile subscription, the device or the operator, it is not possible to obtain information from this number. format string
Indicates whether this is a number with a valid format. Values:
valid
error
error
.type string
Phone number type. Values:
mobile
fixed
fixedormobile
tollfree
premium
shared
voip
personal
pager
uan
voicemail
unknown
unknown
.country_name string
Name of the country to which the number belongs.
country_code string
Telephone prefix of the country to which the number belongs.
country_iso string
ISO code of the country to which the number belongs.
network string
Name of the operator's current network. In case the status is different from
active
the network corresponding to the prefix or format of the number is returned.mcc string
MCC code (Mobile Country Code) of the country according to the E.212 ITU-T encoding.
mnc string
MNC code (Mobile Network Code) of network or mobile operator according to E.212 ITU-T encoding. In case the status is different from
active
the network code corresponding to the prefix or number format is returned.
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
{ "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 }
{ "result":"ko", "error":"invalidauth" }
Errors
The error codes that may be returned by a request to the HLR API are described below.
HTTP Code | JSON Errors | Description |
---|---|---|
200 | Request processed correctly. | |
400 | requiredfields typeerror numberslimit | Error in one of the request parameters. Mandatory fields with no value, incorrect type parameter value or number list size greater than 100. |
401 | invalidauth | Incorrect credentials (username or token). |
402 | nocredits | The account does not have sufficient balance for the HLR request. |
500 | internalerror | Temporary error or incidence in the service. |
Support resources
We recommend that you consult and take into account the following help resources in your integration:
- Description, manual and code examples of the SMS sending API.
- Technical guide to an OTP validation or authentication process by SMS.
- All LabsMobile API versions and functionalities.
- First Steps to API Integration Tutorial
- Create a demo account
- Recommendations and best practices in any integration.
- Plugins, modules and extensions.
- Need help? Contact our technicians