Description
What is an HLR lookup?
An HLR lookup is a query to a mobile network's Home Location Register (HLR), the database where an operator keeps the master record of its subscribers. Asking it about a number in E.164 format reveals whether the number is assigned, whether the subscriber is reachable right now, which network the number belongs to after porting and, on some networks, whether it is roaming. On 4G and 5G cores the same role is played by the HSS and UDM, but the industry still calls the check an HLR lookup.
Lookup providers usually send the query over the SS7 signalling network using the same MAP operation an SMSC uses to route an SMS (SendRoutingInfoForSM), then translate the network's answer into JSON: whether the query succeeded, a reachability verdict, the original and current network codes (MCC and MNC; India uses MCC 404 and 405), a ported flag and an error such as unknown subscriber or absent subscriber. Many providers also sell cheaper MNP lookups, which only read number-portability data, and format checks against the numbering plan that never touch the network.
The value is in timing. An SMS Delivery Report tells you, after you have paid to send, that a number failed; an HLR lookup tells you before. That makes it useful for cleaning lists, routing correctly after porting with Least-Cost Routing, and spotting SMS Pumping (Artificially Inflated Traffic) aimed at unallocated ranges. Its limits matter as much: some operators restrict or block lookups, results can be cached or stale, and an HLR has no idea whether a number uses WhatsApp. The Cloud API has no such pre-check either; an unreachable number shows up as Error 131026 (Message Undeliverable) after a send.
Key takeaways
- An HLR lookup asks a number's home network whether it exists, whether it is reachable now and which network serves it.
- It is a pre-send check, unlike a delivery report, which only says what happened after a message went out.
- Typical results: validity, reachability, ported status, original and current network (MCC/MNC) and sometimes roaming.
- Coverage varies by operator, so treat 'unknown' and timeouts as uncertain, not as invalid numbers.
- An HLR knows nothing about WhatsApp; only a send and its status webhook show whether a number can receive it.
Mechanics
How does an HLR lookup work?
step 1 — Normalise the number
Convert the input to E.164 (for India, +91 followed by ten digits) and reject anything that fails numbering-plan checks before paying for a lookup.
step 2 — Call the lookup API
Your server sends the number to a lookup provider over HTTPS. Endpoints and field names differ by provider; there is no standard API.
step 3 — The provider queries the home network
It sends a MAP SendRoutingInfoForSM, or an equivalent, over SS7 to the number's HLR, which answers with routing data or an error.
step 4 — Read the verdict
Typical fields are validity, reachability, a ported flag, original and current MCC/MNC and an error such as unknown or absent subscriber.
step 5 — Act, then cache briefly
Suppress invalid numbers, retry absent ones later, route by current network and cache results for a limited time, because reachability changes by the hour.
Usage
An HLR lookup in code
# There is no standard HLR API: the host and fields below are illustrative.curl -s "https://hlr.example.com/v1/lookup?msisdn=919812345678" \-H "Authorization: Bearer {HLR_API_KEY}"
Properties
An HLR lookup: key facts and limits
- Queries
- The home network's HLR (HSS or UDM on 4G and 5G)
- Signalling
- SS7 MAP, typically SendRoutingInfoForSM
- Typical answers
- Valid, reachable, ported, roaming, current MCC/MNC
- India's MCCs
- 404 and 405
- Common errors
- Unknown subscriber, absent subscriber, barred
- Best moments to use
- Sign-up, list import, before large campaigns
- WhatsApp check
- None: an HLR can't tell you if a number uses WhatsApp
Caveats
Common mistakes with an HLR lookup
Treating 'absent' as invalid
Absent subscriber means the phone is off or out of coverage right now. Retry later or send anyway; only unknown subscriber means the number isn't assigned.
Caching results for months
Numbers port, are disconnected and get reissued. Cache reachability for hours and validity for days or weeks, then look up again.
Expecting full coverage
Some operators restrict or rate-limit lookups, and some answer with partial data. Treat no answer as unknown and fall back to sending.
Using HLR as a WhatsApp check
A valid, reachable mobile number may still not be on WhatsApp. Send, and read the status webhook: a 131026 failure is the WhatsApp-side answer.
Looking up untrusted input without limits
Every lookup costs money, and bots can script your sign-up form to burn them. Validate the format first and rate-limit per IP and device.
Example
Example: A Kolkata lender cleaning a CRM import
Before sending repayment reminders, a Kolkata lender runs HLR lookups on 1.2 lakh numbers imported from branch spreadsheets. About 6% come back as unknown subscribers and are flagged for branch staff to correct; 9% have ported, so their SMS route is updated; 3% are absent and are left in the send with a later retry. The reminders then go out as a WhatsApp utility template, and the few numbers that fail with 131026 because they aren't on WhatsApp fall back to SMS (figures illustrative).
Why it matters
Why does an HLR lookup matter?
Every message sent to a dead or mistyped number costs money and drags down delivery metrics, and every fraudulent sign-up aimed at a premium or unallocated range costs more. A lookup at the moment a number enters your system (sign-up, CRM import, before a large campaign) stops that waste at the source and tells you which network to route to. For developers it is also a debugging tool: when a delivery report says undelivered, the HLR shows whether the subscriber was absent, the number unknown or the route wrong.
Notes
Best practices for an HLR lookup
- Run a free format and numbering-plan check before every paid lookup.
- Look up once at capture and again before large campaigns, not before every message.
- Store the current MCC/MNC with the contact so SMS routes follow ported numbers.
- Some providers also report a recent SIM change, a useful SIM Swap Fraud signal before sending OTPs.
Questions
HLR FAQs
- Does an HLR lookup alert the phone owner?
- No. The query goes to the operator's network, not to the handset, so nothing rings or appears on the phone. Treat the result as personal data all the same and use it only for delivery and fraud prevention.
- How accurate are HLR lookups?
- Accurate where the network answers fully, less so elsewhere. Some operators block or limit queries, return cached data or hide portability, so read 'unknown' and timeouts as uncertain rather than invalid.
- What is the difference between an HLR lookup and an MNP lookup?
- An HLR lookup queries the live network for status and reachability; an MNP lookup only reads number-portability data to tell you which operator now holds a number. MNP is cheaper and enough for routing; HLR also tells you whether the number is active.
- Can an HLR lookup tell me whether a number has WhatsApp?
- No. The HLR knows about the mobile subscription, not apps. The WhatsApp Cloud API has no pre-check either: send the message, and a 131026 failure in the status webhook tells you the number couldn't receive it.