HLR lookup API for live mobile number status
Query the mobile network's Home Location Register to learn whether a number is active, unreachable or dead, which network serves it and whether it is roaming. 5 credits per lookup.
{
"success": true,
"data": {
"phone_number": "+15125550142",
"status": "active",
"country": "US",
"current_network": {
"name": "Example Wireless",
"mcc": "310",
"mnc": "999"
},
"original_network": {
"name": "Contoso Mobile",
"mcc": "310",
"mnc": "998"
},
"ported": true,
"roaming": false
},
"meta": {
"credits_used": 5,
"credits_remaining": 999,
"cached": false,
"request_id": "req_8f3a2c1e9b7d"
}
}What you get back
The fields most teams branch on. The full response is in the sample on this page and in the API reference.
statusStatusactive, absent, dead or not_applicable. Active means the network knows the subscriber and can reach the handset.current_network.nameCurrent networkThe operator serving the number at the time of the query.current_network.mccMCCMobile country code of the serving network.current_network.mncMNCMobile network code of the serving network. With the MCC it identifies one operator.original_network.nameOriginal networkThe operator the number range was first allocated to.portedPortedtrue when the current network differs from the original one.roamingRoamingtrue when the subscriber is attached to a network outside their home country.countryCountryISO country code the number belongs to.What HLR Lookup does
An answer from the network itself
An HLR query asks the operator's subscriber database about one number. The reply reflects the network's view at that moment, not a list compiled weeks ago.
Three statuses that drive a decision
Active numbers are registered and reachable. Absent numbers exist but the handset is off or out of coverage, so try again later. Dead numbers are disconnected or were never assigned, so remove them.
Network, porting and roaming in one reply
Each result carries the MCC and MNC of the serving network, the original network and a ported flag. A roaming flag tells you when the subscriber is attached to a network abroad.
No charge for landlines
HLR only exists on mobile networks. If you send a fixed-line number, the status comes back as not_applicable and no credits are used.
See the response before you sign up
Fill in the request and run it. The dashboard has the same form, plus history, bulk upload and live data.
Fill in the field and run the lookup to see what comes back.
One POST request
Send JSON with a Bearer key. The same key works for all 79 products.
curl -X POST https://api.1lookup.dev/v1/hlr-lookup \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"phone_number":"+15125550142"}'- Endpoint
POST /v1/hlr-lookup- Base URL
https://api.1lookup.dev- Request
phone_number- Price
- 5 credits
- Coverage
- Global mobile networks
- Bulk
- CSV upload and bulk API
- Cache
- Repeats within 7 days are free
- Also via
- Dashboard and MCP server (run_lookup)
What teams use it for
Remove dead numbers before an SMS send
Run the list through HLR, drop every dead number and hold the absent ones for a later attempt. Your messaging budget goes to handsets that can receive the text.
Route messages by serving network
Use the MCC and MNC to choose a route for each message. Ported numbers are the ones that static prefix tables get wrong.
Check a number before sending a passcode
Query status when a user enters a mobile number. If it is dead, ask for another number instead of sending a code that will never arrive.
Re-qualify aged leads
Numbers go out of service over time. A pass over an old lead file shows which contacts still have a live handset before your team spends dialing time on them.
HLR applies to mobile numbers only. Route quality varies by country, so the detail returned is not identical on every network.
5 credits
Credits come with your plan and work on every product. Requests that fail on our side are never charged. Beyond your plan, extra credits are pay as you go.
See pricing| Plan | Per 1,000 credits | Per 1,000 lookups |
|---|---|---|
| Starter $29/mo | $4.83 | $24.17 |
| Growth $99/mo | $3.96 | $19.80 |
| Pro $299/mo | $3.32 | $16.61 |
| Scale $799/mo | $2.66 | $13.32 |
HLR Lookup questions
What is an HLR lookup?
The Home Location Register is the database a mobile operator uses to keep track of its subscribers. An HLR lookup queries it for one number and reports whether the subscriber is active, which network serves it and whether it is roaming.
What is the difference between absent and dead?
Absent means the number is valid but the handset could not be reached at the time of the query, usually because it is switched off or out of coverage. Dead means the network reports the number as disconnected or unassigned.
How many credits does it use?
Five credits per mobile number. Landlines return not_applicable and cost nothing. Because a repeat within 7 days is answered from cache, add "fresh": true when you need a new network query for a number you checked recently.
Does it work in every country?
Coverage spans mobile networks worldwide, but route quality varies by country. Some operators answer in more detail than others, so test the markets you care about before you depend on a field.
When should I use Carrier Lookup instead?
Use Carrier Lookup when you only need the current operator and the ported flag. It reads number portability data instead of querying the live network, and it costs 3 credits.
Related products
Carrier Lookup
Current carrier, original carrier and porting history for a mobile number.
Phone Validation
Validity, carrier, line type, porting, DNC status and a risk level for any number.
Phone Spam Check
Spam, robocall and fraud risk score for a number, with the reasons behind it.
Run HLR Lookup on your own data
Starter is $29 a month for 6,000 credits, enough for 1,200 lookups a month.