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:
Parameter | Description | Possible values |
---|---|---|
type |
HLR Lookup | hlr |
number |
The 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
.
Parameter | Description | Possible values / example |
---|---|---|
status / status_message |
The status message for your request. | 1 / success 0 / 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 |
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":"not_roaming"
}