Skip to content

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.

5 creditsValidateCSV bulkMCP
POST/v1/hlr-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"
  }
}
[01/Response]

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.
[02/Capabilities]

What HLR Lookup does

01

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.

02

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.

03

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.

04

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.

[03/Try it]

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.

POST /v1/hlr-lookup5 credits

Mobile numbers only. Landlines return a not-applicable status at no charge.

Preview mode: this page returns a sample response so you can see the shape of the data. Create a key to run it on live data.

Response

Fill in the field and run the lookup to see what comes back.

[04/Integrate]

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)
[05/Use cases]

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.

[06/Cost]

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
PlanPer 1,000 creditsPer 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
[07/FAQ]

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.

[ Validate ][ Enrich ]
[Get started]

Run HLR Lookup on your own data

Starter is $29 a month for 6,000 credits, enough for 1,200 lookups a month.

[ Screen ][ Scrape ]