The term describes where the answer comes from rather than what you get. A mobile network keeps a register of its own subscribers. A lookup is a question put to that register, through a service with access to it. What the register will say varies by network.
What is the HLR itself?
The subscriber register inside a mobile network.
GSM is the mobile standard most networks were built on before packet-based cores. In it, the Home Location Register holds the record for each subscriber belonging to that network, including which network element is serving them. Later architecture moved the same role to the Home Subscriber Server. The two names describe the same job in different generations of network.
Neither is a public directory. There is no single global register to query. No lookup returns a name or an address for a subscriber. What a lookup can obtain is routing and status information the serving network is willing to answer with.
What can a lookup actually tell you?
Which network holds the number now, what kind of line it is, and whether it is live.
| What you ask | What comes back | What it does not establish |
|---|---|---|
| Base lookup | Country, serving and issuing network, line type, whether the number has ported | Whether anyone is using it |
presence | Whether the number is registered and able to receive traffic right now | Who holds the handset |
roaming | Whether it is roaming, and on which network | Where the person is |
sim_swap | When the SIM last changed | Why it changed |
porting | When the number last moved network, and its record | Anything about the subscriber |
classification | The precise allocated service of the range, where the base lookup gives broad categories | Why the range was allocated that way |
score | A credibility score from 0 to 100 | How it was composed, which the other properties cannot give you |
A base lookup already distinguishes the network serving a number from the network that issued it. That is how a ported number is visible at all: the two differ, and a ported flag says so.
Is a live check proof of anything?
It is proof the network answered, and nothing beyond that.
A presence result reflects a real-time query to the network where the number is registered. So reachable: true means that network reported the number able to receive traffic at that moment. It does not identify the holder. It is not consent. Google's libphonenumber FAQ says the same about establishing who holds a number:
Do not rely on libphonenumber to determine whether numbers are currently assigned to a specific user and reachable.
Nor does a reachable number mean a message will arrive. Delivery depends on the sender, the route and the destination's filtering, none of which a lookup consults.
How do I read an answer nobody could give?
By the status on the property, which distinguishes three outcomes.
Each property you request reports its own status:
ok: the property was answered and its value is present.unavailable: no answer arrived, so the block isnull.inconclusive: an answer arrived that does not resolve the property.
Only ok carries a value, and only ok is billed. That leaves the distinction that matters for a signup flow. A presence block with status: unavailable means nobody could tell you. One with status: ok and reachable: false means the network said the number cannot receive traffic. Treating the first as the second turns an unanswered question into a rejected customer.
How do I run one on Bird?
Send the number, naming the properties you want.
POST /v1/lookup/phone-number takes a phone_number and an optional type array holding any of classification, porting, presence, roaming, sim_swap and score. Omit type for the base lookup alone. Each property you add is billed separately and only when it is delivered. Request presence when you need a live check rather than by default.
Branch on ok. Treat every other status as not answered. The status vocabulary is an open enum, so an unrecognized value is a future status rather than an error. Branching that way stays correct as the vocabulary grows. The lookup guide covers the flow. What phone number validation checks covers which questions each kind of check can settle.
In short
HLR is a name from network architecture, not a public database.
The Home Location Register is the subscriber register in older mobile networks, with the Home Subscriber Server filling the role in later ones.
A reachable result is not a person.
The network answering that a number can receive traffic says nothing about who holds the handset or whether they consented to hear from you.
Every answer carries its own status.
Bird reports each requested property as ok, unavailable or inconclusive, and only ok carries a value.
Unavailable and unreachable are different answers.
One means nobody could tell you. The other means the network told you the number cannot receive traffic right now.