1. Home
  2. Docs
  3. Gateway
  4. HTTP Api
  5. HLR Lookup

HLR Lookup

Get detailed information about a mobile phone number with a query in the HLR database. The query is possible for numbers from almost all countries/networks worldwide. Read more about our number validation products.

Please issue the request to the following URL:
https://gateway.sms77.io/api/lookup

Required parameters

In addition to the data for authentication, the following parameters are required:

ParameterDescriptionPossible values
typeHLR Lookuphlr
numberThe number to query. The format is almost arbitrary – our gateway automatically formats the number correctly.491632429751
00491632429751
0163-2429751

To check multiple phone numbers in an API call, enter each number separated by a comma. You will receive a JSON array with the respective HLR results.

Response

You get back the HLR information in a JSON formatted form. If the number is invalid, you’ll receive the error code 202. If other errors occur you’ll receive the code 600.

ParameterDescriptionPossible values / example
status / status_messageThe status message for your request.1 / success
0 / error
international_format_numberThe requested number international format.491632429751
international_formattedInternational number.+49 163 2429751
national_format_numberThe requested number in the national domestic format.0163 2429751
country_codeTwo character country code. This is in ISO 3166-1 alpha-2 format.DE
country_code_iso3Three character country code. This is in ISO 3166-1 alpha-3 format.DEU
country_nameThe full name of the country for the requested number in English.Germany
country_prefixThe numeric prefix for the country of the number.49
portedIf the user has changed carrier for number. The assumed status means that the information supplier has replied to the request but has not said explicitly that the number is ported.unknown
ported
not_ported
assumed_not_ported
assumed_ported
current_carrierInformation about the network number is currently connected to.Carrier object
original_carrierInformation about the network number was initially connected to.Carrier object
lookup_outcome / lookup_outcome_messageShows if all information about a phone number has been returned.1 / Success
2 / Partial success - some fields populated
0 / Failed
valid_numberDoes number exist. This is applicable to mobile numbers only.unknown
valid
not_valid
reachableCan you call number now. This is applicable to mobile numbers only.unknown
reachable
undeliverable
absent
bad_number
blacklisted
roamingInformation about the roaming status for number.Roaming object

Carrier object

ParameterDescriptionPossible values / example
network_codeThe carrier’s network code. This is a combined value of MCC and MNC.26203
nameThe name of the network.E-Plus Mobilfunk
countryCountry code of the network.DE
network_typeThe type of network for the requested number.fixed_line
fixed_line_or_mobile
mobile
pager
personal_number
premium_rate
shared_cost
toll_free
uan
unknown
voicemail
voip

Roaming object

ParameterDescriptionPossible values / example
statusThe current roaming status.unknown
roaming
not_roaming
roaming_country_codeOnly returned if number is roaming. The country code of the roaming network.CH
roaming_network_codeOnly returned if number is roaming. The network code of the roaming network.22803
roaming_network_nameOnly returned if number is roaming. The network name of the roaming network.Salt Mobile SA

It may happen that the roaming query returns “No roaming” even though the number is in roaming. This usually means that home routing has been activated by the network operator. Home Routing ensures that the network reports the number as at home, regardless of where it is currently located.

Example

Here the HLR database is searched for the number 01632429751:

Request:
https://gateway.sms77.io/api/lookup?p=api-key&type=hlr&number=491632429751

Response:

{
   "status_message":"Success",
   "lookup_outcome":0,
   "lookup_outcome_message":"Success",
   "international_format_number":"491632429751",
   "international_formatted": "+49 163 2429751",
   "national_format_number":"0163 2429751",
   "country_code":"DE",
   "country_code_iso3":"DEU",
   "country_name":"Germany",
   "country_prefix":"49",
   "current_carrier":{
      "network_code":"26203",
      "name":"E-Plus Mobilfunk",
      "country":"DE",
      "network_type":"mobile"
   },
   "original_carrier":{
      "network_code":"26203",
      "name":"E-Plus Mobilfunk",
      "country":"DE",
      "network_type":"mobile"
   },
   "valid_number":"valid",
   "reachable":"reachable",
   "ported":"assumed_not_ported",
   "roaming":{
      "status":"not_roaming"
   }
}
Was this article helpful to you? Yes 1 No 1
Menu