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. | 491632429751004916324297510163-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 / success0 / 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. | unknownportednot_portedassumed_not_portedassumed_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 / Success2 / Partial success - some fields populated0 / Failed |
valid_number | Does number exist. This is applicable to mobile numbers only. | unknownvalidnot_valid |
reachable | Can you call number now. This is applicable to mobile numbers only. | unknownreachableundeliverableabsentbad_numberblacklisted |
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_linefixed_line_or_mobilemobilepagerpersonal_numberpremium_rateshared_costtoll_freeuanunknownvoicemailvoip |
Roaming object
| Parameter | Description | Possible values / example |
|---|---|---|
status | The current roaming status. | unknownroamingnot_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.
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"
}