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

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"
	}
]