HLR lookup results explained: absent subscriber, unknown subscriber and what to do next

"Absent subscriber" in an HLR lookup means the number exists and is assigned, but the mobile network can't reach the phone right now, usually because it is switched off, out of coverage or has been idle for days. It is temporary. "Unknown subscriber" is the opposite case: the home network has no such subscription, so the number isn't assigned. Treat the first as "retry or switch channel" and the second as "remove or re-confirm".

This guide explains the network conditions behind HLR answers, how MobileValidate folds them into four statuses, and what a sender, an OTP flow and a list-cleaning job should do with each one.

#Where do HLR answers come from?

Every mobile network keeps a register of its own subscribers, the home location register (HLR), or its successor in newer cores. Before a network delivers a call or a text to one of its subscribers, the sending side asks that register how to reach the number. An HLR lookup makes the same kind of routing query without sending anything.

The conversation between networks uses the Mobile Application Part (MAP) protocol, standardised in 3GPP TS 29.002 ^[1]. When the register can't give a route, it answers with a MAP error. Those errors are what people mean when they talk about "HLR status codes". The names are standard. The way a lookup service reports them is not, so the same condition can appear under different labels from different providers.

MobileValidate does not pass raw MAP errors through. The HLR lookup returns one normalised status with four values, plus ported, roaming, network, mcc_mnc and country. The sections below show which network conditions sit behind each value.

#What does "absent subscriber" actually mean?

The MAP specification defines absent subscriber as the case where "the subscriber has activated the detach service or the system detects the absence condition" ^[1]. In plain terms, the network knows the subscription but can't find the phone. The specification lets the network qualify the error with a reason ^[1]:

• IMSI detach. The phone told the network it was leaving, which is what happens when someone switches it off normally.
• Restricted area. The phone is in an area where the subscription doesn't allow service.
• No page response. The network paged the phone and got no answer, typical of a dead battery, a basement or a remote road.
• Purged MS. The visited network deleted its record of the phone. The specification says this can happen automatically, "e.g. because the MS has been inactive for several days" ^[1]. After a purge, the home register treats the phone as not reachable until it attaches again.

For text messages, the network reports a close relative, absent subscriber SM (MAP error 6), when "the network cannot contact the subscriber" ^[1]. The call-related absent subscriber error is code 27. The delivery receipt guide lists the codes you meet after a send.

Two things follow. First, absent is a statement about the phone, not the number. The number is assigned to someone. Second, the reason matters for timing. A switched-off phone is often back within hours. A purged record means the phone hasn't been seen for days, which is a much weaker signal that the contact is still in use.

#What does "unknown subscriber" mean?

The specification defines unknown subscriber as "no such subscription exists" (MAP error 1) ^[1]. The number may be well formed and inside a range the operator holds, but nobody has it. Common reasons are a number that was never issued, a contract that ended and hasn't been reissued yet, or a typo that happens to produce a valid-looking number.

A related error, number changed, means "the subscription does not exist for that number any more" ^[1]. Both point the same way: stop sending to this number and, if it came from a customer, ask them for the current one.

Be careful with ported numbers. A number that moved to another operator can briefly produce confusing answers while routing databases update. If a lookup says a number is not assigned but the customer used it yesterday, re-check before you delete it. Our guide on why carrier lookups go wrong after porting explains the mechanics.

#What about call barred, teleservice not provisioned and system failure?

These answers say something about the subscription or the network, not about whether the number exists.

• Call barred (MAP error 13): the operator or the subscriber has barred the traffic. The specification allows extra detail, such as a barring set by the subscriber or for operator reasons ^[1]. A suspended line can show up this way.
• Teleservice not provisioned (MAP error 11): the subscription doesn't include the service, for example a data-only SIM that can't receive SMS.
• System failure (MAP error 34): "a task cannot be performed because of a problem in the entity reporting the error or in another entity" ^[1]. It is a network problem. It says nothing about the number.

None of these answers settles whether the phone can receive your message later, so MobileValidate reports them as unknown, which is free. If a number keeps coming back unknown, try another channel rather than deleting it.

Roaming and ported are not errors. Roaming means another network is currently serving the phone. Ported means the number now belongs to a different operator from the one that first received its range. Both are normal states of a reachable number.

#How do these conditions map to MobileValidate's four statuses?

The API reduces the conditions above to four values. The exact error a network sends varies by operator, and some operators mask details, so the table shows the typical case. The rule is simple: only answers that settle the question are conclusive. Everything else is unknown.

reachable, unreachable and invalid are conclusive answers, so they are billed. unknown is free, as are inputs that can't be parsed as a phone number (number_status: invalid_number), numbers from unsupported countries and duplicates in the same request. See pricing for current prices.

Note the difference between the two kinds of "invalid". number_status: invalid_number means the digits can't form a real number, so no network is asked. status: invalid means a network was asked and said the number isn't assigned.

#What should you do with each result?

The right action depends on what you are about to do with the number. Here is a starting point for three common jobs.

A few rules sit behind the table.

Unreachable is temporary. Don't treat one unreachable answer as a dead number. For live flows, retry within minutes to hours. For lists, re-check after a few days. A number that stays unreachable across several checks spread over two or more weeks is a candidate for re-confirmation by e-mail or in your app. Numbers also age out of use and get reissued, which our post on number recycling and list decay covers.

Unknown is not bad. Some operators don't answer external queries, and some answers time out. Blocking users on unknown punishes real customers for a network gap. Treat it as "no information" and let your other controls decide.

Invalid deserves one confirmation. Before you delete a long-standing customer's number, re-check it once, or ask the customer. A fresh port or a routing glitch can produce a false "not assigned" for a short time.

Landlines have no HLR. If your data mixes fixed and mobile numbers, run a carrier lookup first and send only mobile numbers to the HLR check. A landline has no home location register to answer.

#How fresh does an HLR answer need to be?

Reachability changes minute to minute, so an HLR answer is only as good as its checked_at time. Repeat checks inside your account's freshness window can be served from cache for free (cached: true, billed: false). Before a one-time passcode, send max_age: 0 to force a fresh network query. That query is billed and rate limited. For weekly list hygiene, a cached answer from the last day or two is usually enough.

If you only need to know which network a number is on today, for routing or least-cost decisions, the MNP lookup answers that at a lower price. Use the HLR lookup when live reachability is the question. Our comparison of HLR vs MNP vs number validation goes through the choice.

#How do you test these outcomes without real numbers?

Test keys return fixed answers for reserved test numbers, so you can build every branch of your decision logic before you go live. With a test key, +447700900001 returns reachable, +447700900002 unreachable, +447700900003 unknown, +447700900004 pending then reachable, +447700900005 unsupported_country, and +447700900006 reachable with ported: true. Test lookups are never billed. The test mode docs and the lookups reference show the full response shape.

const hlr = result.checks["number.hlr"];
if (hlr.status !== "completed") {
  // unknown, pending or unsupported_country: not billed; don't block on it
} else if (hlr.attributes.status === "invalid") {
  askForCurrentNumber();          // not assigned
} else if (hlr.attributes.status === "unreachable") {
  offerOtherChannel();            // absent: switched off or out of reach, retry later
} else {
  sendCode();                     // reachable, including roaming and ported
}

#What does an HLR lookup never tell you?

It never tells you who holds the number, where they are, or whether the current holder is the person who gave you the number. MobileValidate returns roaming as true or false only, and never returns the IMSI, the serving switch, the cell or any location detail. Use the lookup on numbers you have a lawful reason to process, such as your own customers. The acceptable use policy applies, and anyone can object to checks of their number through the opt-out form.

Whether a number has changed hands is a separate question. In the United States, the FCC's Reassigned Numbers Database answers it, and our RND explainer shows how to use it next to a network check.

#What are the key takeaways?

• Absent subscriber means the number is assigned but the phone can't be reached now: switched off, out of coverage, not answering pages or inactive for days. Retry or switch channel.
• Unknown subscriber means no such subscription exists. Stop sending and re-confirm the number.
• Call barred, service not provisioned and system failure describe the subscription or the network, not whether the number exists.
• MobileValidate reduces these conditions to reachable, unreachable, invalid and unknown. The first three are conclusive and billed. unknown is free and should never block a user.
• One unreachable answer isn't a dead number. Look for a pattern across checks spread over weeks.
• HLR checks work only for mobile numbers, and they never reveal location or SIM identifiers.