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