Help Center
All buyer guides

Getting started

Routes and calls

SMS and IoT

Phone numbers and eSIMs

Tools

Reports and settings

Check a phone number with HLR Lookup

Guide 11 of 153-minute readUpdated 21 October 2026

In short: Go to Routing → HLR Lookup, enter the number in international format without + (for example 14155551234), choose the billing account and click Perform Lookup. Each lookup costs $0.05 from that account and shows the country, carrier, MCC/MNC, ported status and roaming status.

What one HLR lookup returns
  1. Phone numberInternational format, digits only
  2. then, Perform Lookup, TelecomsXchangeCharges $0.05 to the billing account
  3. then, HLR query, Mobile networksReport who serves the number right now
  4. then, Raw API Response, Lookup resultCarrier, MCC/MNC, ported and roaming status
On this page
  1. Before you start
  2. How do I look up a number?
  3. What does the result show?
  4. Where do I see what I've spent?
  5. Can I run lookups from my own system?
  6. What if something goes wrong?
  7. Common questions

An HLR lookup asks the mobile networks about a number right now: which carrier serves it, whether it has been ported, and whether the phone is roaming. Use it to clean a dialling list, check why calls to a number fail, or pick the right route before you send traffic.

Before you start#

  • Add funds to the account you'll bill the lookups to. Each lookup costs $0.05, and the account's balance plus credit limit must cover it.
  • Have the number in international format with the country code, digits only: 14155551234, not +1 (415) 555-1234.

How do I look up a number?#

  1. Go to Routing → HLR Lookup.
  2. Under Perform Lookup, enter the number in Phone Number.
  3. Choose the Billing Account. The list shows each account with its balance.
  4. Click Perform Lookup.

The cost is shown next to the button, Cost per lookup: $0.05, and is charged to the billing account as soon as the lookup is sent.

Tip

On the CDR and SDR pages, click a destination number and choose HLR Lookup: <number>. HLR Lookup opens with that number filled in; pick the billing account and click Perform Lookup.

What does the result show?#

Lookup Results has two parts:

  • Country: the flag and name of the number's country.
  • Network Information:
    • Carrier Name: the network that serves the number now, with its network type (such as mobile or landline) as a badge.
    • MCC/MNC Code: the carrier's mobile country and network code. Copy MCC/MNC copies it.
    • Ported Status: Ported when the number has moved from the network it was issued on, Original Network when it hasn't, otherwise Unknown.
    • Roaming Status: Roaming or Home Network, otherwise Unknown.
    • Lookup Cost: $0.05 USD.
HLR Lookup with a completed result: the country, carrier name and network type, MCC/MNC code, ported and roaming status and the lookup cost

Open Raw API Response for the full answer as JSON, and Copy JSON to keep it. It also includes the number in international and national format, the country's ISO codes and the original carrier.

If every field says Unknown or N/A, the networks returned no data for that number. The reason is in Raw API Response under status_message. The lookup is still charged.

Where do I see what I've spent?#

Every lookup is a −$0.05 line in Payment History with the note HLR Lookup <number> and the billing account. Filter Notes by HLR Lookup to see them all. The results aren't stored for you: copy the JSON if you need a record.

Can I run lookups from my own system?#

Yes. Call GET /buyers/hlr/lookup/{number}?i_account={account id} on the API with HTTP Digest authentication: your portal login as the username and your API Key as the password. Turn on Allow API Access in Profile & Preferences first. See Use the API for the setup and the full endpoint list.

The reply is {"status": "success", "response": {...}} with the same fields as Raw API Response, and each call is charged $0.05 to the account you name.

What if something goes wrong?#

You see What to do
Account balance insufficient to run query Add funds to the billing account or choose another one.
CLD missing, or wrong format (only digits are supported) Enter the number with the country code and digits only: no +, spaces or dashes.
Every field shows Unknown or N/A The networks have no data for the number. Check it in Raw API Response; the lookup is still charged.
Account error (API) Add i_account with the ID of one of your accounts to the request.
This API expects parameter add=1 for HLR requests Use the /buyers/hlr/lookup/{number} path, which sets it for you.

Common questions

How much does a lookup cost?

$0.05 per number, charged to the billing account you choose. The account's balance plus credit limit must cover it.

What does the result tell me?

The number's country, current carrier and network type, its MCC/MNC code, whether it has been ported away from its original network, and whether it is currently roaming. The raw response also has the number in international and national format and the original carrier.

Am I charged when the lookup finds nothing?

Yes. A lookup is charged once it has been sent, even when the network returns no data for the number. Check the number format before you run it.

Can I look up many numbers at once?

Not in the portal: it takes one number at a time. Use the API, /buyers/hlr/lookup/{number}, from your own system to run lookups in bulk.

Where can I see my past lookups?

Each lookup is a −$0.05 line in Payment History with the note "HLR Lookup" and the number. The results themselves aren't stored for you, so copy the JSON if you need to keep it.

How much does a lookup cost?
$0.05 per number, charged to the billing account you choose. The account's balance plus credit limit must cover it.
What does the result tell me?
The number's country, current carrier and network type, its MCC/MNC code, whether it has been ported away from its original network, and whether it is currently roaming. The raw response also has the number in international and national format and the original carrier.
Am I charged when the lookup finds nothing?
Yes. A lookup is charged once it has been sent, even when the network returns no data for the number. Check the number format before you run it.
Can I look up many numbers at once?
Not in the portal: it takes one number at a time. Use the API, /buyers/hlr/lookup/{number}, from your own system to run lookups in bulk.
Where can I see my past lookups?
Each lookup is a −$0.05 line in Payment History with the note "HLR Lookup" and the number. The results themselves aren't stored for you, so copy the JSON if you need to keep it.

Related guides

This guide matches platform build 83b4ebc9. Markdown version.