HLR Lookup API: What It Returns, How It Works, and How to Wire It In

A lot of the money wasted in A2P messaging is gone before anyone presses send. It leaks into numbers that were disconnected a couple of years back, numbers mistyped at signup, numbers quietly recycled onto another network, and numbers belonging to a handset that has been sitting switched off in somebody's drawer since March. Every one of them still passes a format check. Eleven or twelve digits, right country code, looks fine. So the message goes, the enterprise gets billed, and the delivery report comes back either empty or, worse, falsely positive.

The Home Location Register is the component that could have told you not to bother. It is the subscriber database at the heart of a GSM network, and every active SIM has a record in one of them. That record is not static. It shifts as the subscriber powers down, roams into another country, or ports to a competitor over a weekend.

The catch is that the HLR talks SS7, and you talk HTTP. You are not going to run signaling links into every operator you want to reach, and even if you had the appetite for it, the interconnect agreements alone would eat a year. So you pay somebody who already did all of that, and you reach it through an HLR Lookup API.

This is for the people who have to actually build the thing in: developers wiring validation into a product, aggregators scrubbing routing tables, platform teams tired of paying for messages that were never going to land. The wider overview lives in the HLR lookup service guide. What follows is the API.

What an HLR Lookup API Actually Does

You hand it a phone number in E.164. It runs a signaling query against whatever network that number belongs to, waits for the answer, and gives you back structured data about the number's state. Underneath, the provider is turning your HTTP request into an SS7 transaction, firing it at the right network, parsing whatever comes back, and flattening it into JSON for you.

The HTTP part is nothing. Any developer reads the request format in ten minutes and moves on. The thing you are actually paying for is that somebody else is carrying the signaling connectivity, the roaming relationships, and the fiddly logic that turns a raw MAP response into fields a normal application can branch on.

When a query resolves against a live subscriber, you find out whether the number is allocated to anyone at all, whether the handset is reachable this minute or sitting dark, and which network holds the number today. Often you also get the IMSI and the address of the serving switch, which turn out to matter more for routing and fraud work than people expect going in. Format validation can confirm a number is plausible. It cannot tell you any of that.

What the HLR Knows That Your Application Does Not

A subscriber record carries more than most people assume, and the lookup reads a slice of it. The IMSI, the International Mobile Subscriber Identity, is the thing that actually identifies the SIM inside the network. The MSISDN is the number your users dial. They are not the same, and the mapping between them is precisely what number portability breaks. The HLR also stores the MCC and MNC, the country and network codes that name the operator a subscriber currently sits on, plus the address of the MSC or VLR where the handset last checked in, which is how the network knows where to send anything addressed to it. And it holds a reachability state.

Your application has a string. That is the whole of its knowledge. The lookup exists to close that distance for one decision, and almost always that decision is a dull commercial one: is it worth spending money to message this number. If you want the longer version of how a query walks a raw MSISDN down to a confirmed subscriber, that is the subject of how a GSM HLR query helps in mobile number verification.

How an HLR Query Travels Across the Signaling Network

Most API docs skip this, and skipping it is why people are later baffled when results come back thin.

Submit a number and the provider issues a MAP operation into SS7. Nine times out of ten it is SendRoutingInfoForSM, the same interrogation an SMSC runs when it genuinely intends to deliver a message. It asks the home network, in effect, where to route an SMS for this subscriber. The home network reads its HLR and, if the subscriber exists and it feels like answering, replies with the IMSI and the serving switch.

There is a richer operation, AnyTimeInterrogation, that returns subscriber state and location in more detail. It is also the one operators are most likely to have blocked outright, because they treat it as an attack surface and would rather drop it than hand strangers a way to track their customers. So in day-to-day traffic the bulk of HLR lookup rides SendRoutingInfoForSM, and how much detail you get depends entirely on how the destination network decides to answer that one question.

A cooperative network answers in a fraction of a second. A distant or congested one takes longer, or times out. You never see any of this as the integrator; you see a request and a response. But it is worth carrying the mental model that this is a live network transaction and not a database read, because that is what accounts for the latency you will occasionally hit and the way the same number can come back detailed from one network and almost bare from the next.

What an HLR Lookup API Returns, Field by Field

Field names drift between providers. The shape does not. A clean hit against a live subscriber looks about like this

You will not get every field on every query. A network that answers SendRoutingInfoForSM but blocks the richer stuff can hand you status, IMSI, and current network while the location fields stay empty. Read a missing field as missing information. If the roaming flag is absent, that is not the network telling you the subscriber is home. It is the network telling you nothing, and those are very different inputs to a decision.

Reading HLR Lookup API Status Without Guessing

Status is where integrations quietly go wrong, usually because somebody collapsed three outcomes into two.

Unknown subscriber means the number is not allocated to anyone. It is dead. Take it off the list and keep it off. Absent subscriber is the one people misread: the number is real and belongs to an active subscriber, but the handset is off or out of coverage right now, so it is a timing problem, and the same number may well answer an hour from now. Reachable means the handset is registered and the network will take a message for it.

The failure I see most often is treating absent and unknown as the same event. Branch on success versus failure and you will cheerfully purge thousands of perfectly good numbers because their owners happened to be on a flight, in a lift, or down a basement when the batch ran. A decent HLR Lookup API exposes error codes that map onto the actual MAP causes, and they reward being handled one at a time. A number that refuses to resolve across several tries over several days is telling you something. A single miss on a Tuesday afternoon is not.

Real-Time HLR Lookup API Calls Versus Batch Validation

Two ways to consume the API, and they are not interchangeable.

A real-time single query sits inline. User types a number at signup, you check it before you fire the verification message, you decide inside the request. That path has to be quick, and it has to fall over gracefully, because a lookup that hangs must never become a user staring at a spinner or, worse, a rejected signup. Set a hard timeout. On no answer, send anyway and flag it for later rather than blocking the person.

Batch validation is a different job with different economics. You feed in a few hundred thousand numbers from a CRM export or a marketing list nobody has touched in two years, and the API grinds through them asynchronously, posting results to a webhook or dropping them for download as they land. Here you are deliberately spending query cost to dodge send cost across a big, mostly stale list, and that trade usually pays.

The thing teams get wrong is caching, specifically caching everything on the same clock. Network identity, the MCC and MNC, and the ported flag barely move, so you can hold it for a long time. Reachability moves by the minute, so caching it is close to pointless and will have you serving a confident "reachable" for a phone that went dark three hours ago. Cache per field. Not per record.

Where an HLR Lookup API Belongs in the SMS Pipeline

Put the lookup in front of the SMSC, not behind it where you are reacting to a disappointing delivery report after the money is already spent.

At ingestion, it earns its keep in a few ways that stack. It pulls invalid and unreachable numbers out of the spend before they cost anything, which is the direct line to how HLR lookup reduces messaging costs. Knowing the current network of each destination also lets you route properly up front instead of learning the number was ported only after a message bounced off the wrong carrier, which is the chain of decisions worked through in A2P SMS routing explained.

And it cleans your statistics, which is the benefit nobody budgets for and everybody needs. Failed sends to dead numbers are noise, and that noise sits on top of your real delivery problems, hiding them. I have watched teams burn weeks hunting a delivery rate dip that turned out to be, in large part, a list full of numbers that should never have been queued. Clearing those out first is close to free, and it is near the top of the suspects list in why A2P SMS delivery rates drop.

An HLR Lookup API Is Not an MNP Lookup

This confusion causes more grief than anything else here, so let me be exact about it.

An HLR lookup interrogates the network about a subscriber's live state. An MNP lookup resolves which network a number has been ported to, and it does that against the central portability database for the market rather than by asking the network in real time. They overlap. A thorough HLR response can show a mismatch between the issuing network and the serving one, which hints at porting. But a hint is not a resolution, and treating it as one is where the trouble starts.

In a market with heavy portability, leaning on HLR data alone to decide who bills a number will misroute a real slice of your traffic, and misrouted A2P traffic is exactly where grey route leakage and failed delivery both begin. The clean split, and the cases where you genuinely need both calls, is laid out in HLR lookup vs MNP lookup. For routing work, the portability side runs through an MNP lookup API for SMS routing, and in practice the two are run together, not chosen between, which is the setup described in integrating HLR lookup and MNP services. An implementation that depends on HLR alone for ownership will leak, and that leak tends to surface downstream as the sort of avoidable failures covered in MNP error reduction.

What Quietly Degrades HLR Lookup API Accuracy

No HLR lookup is as accurate as the sales deck claims, and the reason is defensive, which makes it hard to argue with.

Operators have spent the last decade putting signaling firewalls in front of exactly this kind of interrogation. Some drop the query. Some answer it with deliberate nonsense, returning a home network response for a subscriber who is really roaming, so that an attacker cannot use the lookup to pin down where somebody is. That is sound security. It is also the ceiling on your accuracy against any well-defended network, and what a signaling firewall does to inbound interrogation is precisely what caps it.

Which means accuracy varies wildly by where you are querying. A quiet operator with a relaxed signaling posture hands you a rich, honest answer. A large carrier running aggressive filtering gives you something thin, cached, or inferred from secondary sources, and does not tell you which. Anyone promising uniform global accuracy has shown you a brochure rather than a network.

So for anything high stakes, raw HLR data on its own is the wrong tool. What you want is a blended read that folds signaling results together with portability data and historical reputation, which is the territory of phone number intelligence for SMS delivery. The HLR Lookup API is an input into that. An important one. Not the whole picture.

Integrating an HLR Lookup API Without Building a Bottleneck

A handful of decisions separate an integration that helps from one that quietly becomes a liability.

Deal with the timeout before you write the happy path. A live signaling query will, sooner or later, hang, and your code needs a defined answer for that moment that is not "freeze the user." Fail open on inline signup, fall to a review queue on fraud flows, and keep a timeout from ever reaching the user as an error.

Normalise before you query, because garbage in gets you a confident answer about the wrong number. Parse to E.164, apply the right country code when you were handed a national format, and throw out anything you cannot normalise rather than wasting a paid query on it.

Then respect the rate limits, and expect to be pushed back on. These APIs sit on finite signaling capacity. Fire two million numbers at one in parallel and you will be queued, throttled, or bounced, so build for asynchronous batch delivery instead of assuming raw parallelism will carry you.

Log the entire response, not just the yes or no you acted on. The day finance asks why you skipped a number, or a user swears blind their working phone got marked invalid, the raw MAP level answer is the only thing that ends the argument. And set your cache TTLs per field, for the reason already covered, so that the slow-moving network identity and the fast-moving reachability are not living on the same timer.

Fraud Signals That Show Up in HLR Data

The query you run to validate a number for messaging doubles as a cheap fraud input, which is why fraud teams end up leaning on the same API the delivery people do.

A roaming flag on a subscriber who has never roamed, appearing right before a high-value transaction, is worth a pause. An IMSI that has changed recently on a number you have records for can point to a SIM swap, which is one of the harder attacks to spot from the application side and one the telecom fraud management guide treats as a primary signal. A batch of supposedly fresh signups riddled with absent subscribers smells generated rather than collected. And a serving country that disagrees with the number's home market in ways that make no commercial sense lines up with the patterns catalogued in SMS fraud in telecom networks.

On its own, none of this convicts anyone. HLR data is a signal and not a verdict, and anybody treating it as a verdict will generate a lot of angry false positives. But you are paying for the query already if you run validation, so pushing what it returns into a risk score is about as close to free intelligence as this work gets.

What to Ask Before You Pick an HLR Lookup API

On the pricing page, every HLR Lookup API provider looks the same. They stop looking the same the moment you put real traffic through them, and a few questions get you there faster.

Start with coverage, but ask it honestly. Not how many countries are on the map, but what the real accuracy is against the specific networks your traffic goes to, because a provider that is excellent in one region can be guessing in another and will not volunteer which. Find out whether they actually separate absent from unknown, since one that collapses them will keep deleting good numbers out from under you. Press on what happens when a network blocks interrogation, and whether a blocked query comes back as an honest "no data" or gets dressed up as a success. Get a latency distribution under load rather than the median on a slow afternoon. And check whether HLR and MNP come through a single integration, because you are going to need both before long.

The managed side of running these at volume, the signaling connectivity and interconnect relationships that decide real accuracy more than any feature list does, runs through Almuqeet's HLR and MNP services, with the blended intelligence layer that sits above raw lookups covered under phone number intelligence.

Closing

An HLR Lookup API is a narrow tool, and it earns its place in two fairly unglamorous ways. It keeps you from spending on numbers that were never going to receive anything, and it tells you where a number actually lives so you can route to it correctly. The fraud signals, the delivery diagnostics, the list hygiene, all of that falls out of those two things rather than standing on its own.

What it is not is a complete picture, and the places it falls short are not edge cases. The accuracy ceiling against defended networks is real. The gap between what the HLR knows and what the portability database owns is real. Anyone selling the lookup as a single source of truth has not run it against a hard destination recently. So run it as one input among several, pair it with MNP, keep every response in your logs, and whatever you do, handle the three status outcomes as three outcomes instead of two.

Almuqeet operates HLR and MNP lookup infrastructure for operators, aggregators, and enterprises, down to the signaling connectivity and the managed operations behind it. If you want a read on what your current validation is missing, the quickest test is to push a sample of your own list through a real lookup and lay the results next to your delivery reports. The gap is usually wider than the team expects it to be.

Frequently Asked Questions About HLR Lookup APIs