Gateway

  2. Home
  4. Gateway
  6. HTTP API
  8. 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 make 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:
Name Description Example values
type HLR Lookup hlr
number The number(s) to query.
Enter multiple numbers separated by a comma.
The format is almost arbitrary – our gateway automatically formats the number correctly.		 491632429751
00491632429751
0163-2429751
491632429751,491771783130

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

Response object

You get back the HLR information in a JSON formatted format. If the number is invalid, you’ll receive the error code 202. If other errors occur you’ll receive the code 600.
Parameter Description Possible values / example
status The status for your request. 1
0
status_message The status message for your request. success
error
international_format_number The requested number international format. 491632429751
international_formatted International number. +49 163 2429751
national_format_number The requested number in the national domestic format. 0163 2429751
country_code Two character country code. This is in ISO 3166-1 alpha-2 format. DE
country_code_iso3 Three character country code. This is in ISO 3166-1 alpha-3 format. DEU
country_name The full name of the country for the requested number in English. Germany
country_prefix The numeric prefix for the country of the number. 49
ported If 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_carrier Information about the network number is currently connected to. Carrier object
original_carrier Information about the network number was initially connected to. Carrier object
lookup_outcome / lookup_outcome_message Shows if all information about a phone number has been returned. 1 / Success
2 / Partial success - some fields populated
0 / Failed
valid_number Does number exist. This is applicable to mobile numbers only. unknown
valid
not_valid
reachable Can you call number now. This is applicable to mobile numbers only. unknown
reachable
undeliverable
absent
bad_number
blacklisted
roaming Information about the roaming status for number. Roaming object
gsm_code GSM Code of the HLR query. See GSM Codes
gsm_message Bedeutung des GSM Codes. See GSM Codes

Carrier object
Parameter Description Possible values / example
network_code The carrier’s network code. This is a combined value of MCC and MNC. 26203
name The name of the network. E-Plus Mobilfunk
country Country code of the network. DE
network_type The 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
Parameter Description Possible values / example
status The current roaming status. unknown
roaming
not_roaming
roaming_country_code Only returned if number is roaming. The country code of the roaming network. CH
roaming_network_code Only returned if number is roaming. The network code of the roaming network. 22803
roaming_network_name Only 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.

Examples

Looking up a single phone number

In this example the HLR database will be queried for the phone number +491632429751. A single object gets returned.

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

Response:

{
   "status": true,
   "status_message": "success",
   "lookup_outcome": true,
   "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": "not_roaming",
   "gsm_code": "0",
   "gsm_message": "No error"
}

Looking up multiple phone numbers

In this example we will be querying the HLR database for the numbers +491632429751 and +491771783130. An array of objects gets returned.

Request:
https://gateway.sms77.io/api/lookup?p=YOUR_API_KEY&type=hlr&number=491632429751,491771783130

Response:

[
	{
		"status": true,
		"status_message": "success",
		"lookup_outcome": true,
		"lookup_outcome_message": "success",
		"international_format_number": "491771783130",
		"international_formatted": "+49 177 1783130",
		"national_format_number": "0177 1783130",
		"country_code": "DE",
		"country_name": "Germany",
		"country_prefix": "49",
		"current_carrier": {
			"network_code": "26207",
			"name": "Telefónica Germany GmbH & Co. oHG (O2)",
			"country": "DE",
			"network_type": "mobile"
		},
		"original_carrier": {
			"network_code": "26207",
			"name": "Telefónica Germany GmbH & Co. oHG (O2)",
			"country": "DE",
			"network_type": "mobile"
		},
		"valid_number": "valid",
		"reachable": "reachable",
		"ported": "assumed_not_ported",
		"roaming": "not_roaming",
		"gsm_code": "0",
		"gsm_message": "No error"
	},
	{
		"status": true,
		"status_message": "success",
		"lookup_outcome": true,
		"lookup_outcome_message": "success",
		"international_format_number": "491632429751",
		"international_formatted": "+49 163 2429751",
		"national_format_number": "0163 2429751",
		"country_code": "DE",
		"country_name": "Germany",
		"country_prefix": "49",
		"current_carrier": {
			"network_code": "26207",
			"name": "Telefónica Germany GmbH & Co. oHG (O2)",
			"country": "DE",
			"network_type": "mobile"
		},
		"original_carrier": {
			"network_code": "26207",
			"name": "Telefónica Germany GmbH & Co. oHG (O2)",
			"country": "DE",
			"network_type": "mobile"
		},
		"valid_number": "valid",
		"reachable": "reachable",
		"ported": "assumed_not_ported",
		"roaming": "not_roaming",
		"gsm_code": "0",
		"gsm_message": "No error"
	}
]