HLR lookup API
HLR Lookup API
An HLR (Home Location Register) lookup asks the mobile network about a number: whether the phone is reachable right now, whether the number was ported, which network serves it today and whether it is roaming. Add hlr=1 to a single or batch lookup and get the live status next to the usual validation, carrier and line type fields.
Example request and response
The HLR fields of the /v1/validate example response with hlr=1 (shortened). The batch endpoint, POST /v1/validate?hlr=1, adds the same fields to each of up to 100 numbers.
curl -G "https://api.numlookupapi.com/v1/validate/+4915112345678" \
-H "apikey: YOUR-API-KEY" \
-d hlr=1
{
"valid": true,
"country_code": "DE",
"carrier": "Telekom Deutschland GmbH",
"line_type": "mobile",
…
"reachable": "active",
"ported": true,
"original_carrier": "Telekom Deutschland GmbH",
"current_carrier": "Vodafone GmbH",
"mcc": "262",
"mnc": "02",
"roaming": false,
"hlr_supported": true,
"hlr_error": null
}
What an HLR lookup tells you
- reachable
active(switched on and reachable),absent(switched off or out of coverage),inactive(disconnected, unassigned or otherwise not in service) orunknown(no live status, always for US and Canadian numbers).- ported
- Whether the number was moved away from the network that issued it.
- original_carrier, current_carrier
- The network that issued the number, and the one it belongs to now after any porting. The usual
carrierfield names the holder of the number range;current_carrierfollows the number. - mcc, mnc
- Mobile country code and mobile network code of the current network, e.g.
262and02, for routing SMS by network. - roaming
- Whether the subscriber is on a network abroad.
- hlr_supported, hlr_error
hlr_supportedisfalsefor landlines and invalid numbers.hlr_errorissource_unavailablewhen the network did not answer in time; you then pay only the base request.
Use cases
SMS and call delivery
Skip numbers that are switched off or disconnected before you send, and route messages by the current network after porting.
Fraud and account security
Check that a number used for one-time codes is live before you rely on it, and spot numbers that are roaming.
List hygiene
Run your contact list through the batch endpoint and remove inactive mobile numbers from campaigns and CRMs.
Get an API key
HLR lookups come with every paid plan, from Basic at $9.99 a month. An answered lookup costs 21 requests of your quota: 1 for the validation and 20 for the network query. The free plan (250 requests a month) covers validation, carrier and line type, without HLR.