What is an HLR lookup?

A network check of whether a number is assigned and whether a handset is reachable. The API returns the result of that check and reuses cached results between checks.

What is the difference between live and connected?

live says the number was assigned at the last network check. connected says the handset was reachable at that check. A switched-off phone can be live: true and connected: false.

What about landlines?

Landlines answer the live question. Assigned numbers come back live: true, dead ones live: false. connected stays null, since reachability is a handset question landlines do not have.

Which numbers get the network fields?

Add deep=true for network and roaming detail returned by checks outside the North American Numbering Plan (NANP). A field returns null when the check does not supply it. The same HLR lookup unit covers core and detail, with no additional charge.

This query path did not answer the question. null never means no.

What does a lookup cost?

One HLR lookup from the monthly allowance per valid number, including cached results and unknown status. Free includes 50 a month. See Plans for additional lookup rates. A failed network request uses no unit.

How recent is the network check?

Prior checks are reused for 7 days for mobile, VoIP, and unknown types, or 90 days for landline, toll-free, and disconnected numbers. A cached response can remain for up to another day. connected describes the last check, not the current moment.

Who serves the number?

Carrier, line type, and burner are GET /carrier.

Just need validation?

GET /phone validates and formats any number. 245 countries and regions.

Drop a phone CSV on /bulk. HLR is a toggle on the quote, priced per unique number. Dead numbers surface before you dial or text them.

GET /hlr/{number}

HLR lookup API

Check a phone number's assignment and network reachability.

Example response

GET /hlr/+447712345678?deep=true

{
  "phone": "+447712345678",
  "valid": true,
  "country": "GB",
  "live": true,
  "connected": true,
  
}

50 free lookups a month. Additional lookups are priced by your plan.

What comes back.

live

Number is assigned to a subscriber. false = dead number, null = the network did not answer

connected

Handset was reachable at the last check. false = switched off or out of coverage, null = unknown

deep.roaming

Subscriber is roaming on a foreign network. Fills on live HLR queries, null on US and Canadian numbers

deep.roaming_network

Network the subscriber is roaming on, when roaming

deep.roaming_country

ISO 3166-1 alpha-2 country the subscriber is roaming in, when roaming

deep.network

Current serving network name. Fills on live HLR queries, null on US and Canadian numbers (use /carrier there)

deep.original_network

Network the number was originally issued on. Fills on live HLR queries

deep.mcc

Mobile Country Code of the current network. Fills on live HLR queries

deep.mnc

Mobile Network Code of the current network. Fills on live HLR queries

Pass a phone number

Any country. E.164, or a national format with ?country=.

The network answers

live says assigned, connected says reachable at the last check. Add deep=true for available network and roaming detail in the same lookup, with no additional charge.

Clean a list

Drop a phone CSV. Dead numbers surface before you dial or text them.

Coverage

Worldwide status lookups. Assignment and reachability from network checks.

Assigned and reachable.

Read assignment and reachability together to understand the last check.

live: true · connected: true: Assigned and reachable at the last check.
live: true · connected: false: Still assigned. The handset was unreachable at that check.
live: false · connected: false: The check reported an unassigned number.
live: null · connected: null: No status was established. Unknown stays unknown.

Landlines can confirm assignment with connected: null. Results may reuse an earlier check.

5
network verdicts: Worldwide
status lookups: 50
free lookups a month: On demand
see Plans for rates

Check whether a phone number is assigned and reachable. live is assignment; connected is reachability at the last network check. Add deep=true for available network and roaming detail, included in the same lookup with no additional charge.

Results are cached between checks. Each valid lookup uses one HLR unit, including cache hits and unknown status. Free includes 50 a month; see Plans for additional rates. Landlines answer assignment, with connected null. Carrier and real line type belong to /carrier.

SPEED

How long /hlr takes.

Median time to first byte over the last seven days. Warm requests, measured every 30 minutes. Live verification and other request variants can take longer.

102ms

252ms

APAC

322ms

LatAm

227ms

339ms

See live status →

Check before you dial.

Number assignment and network reachability. Checks have their own allowance.

Start includes 1M API requests a month for $20/mo.

250 live status checks included per month.

Get started Compare plans Read the docs

Make your first request.

One key works across the APIs. Copy a request in your language and get JSON back.

curl "https://api.parseapi.com/hlr/+447712345678" \
  -H "X-API-Key: YOUR_API_KEY"

// Example response · 200
{
  "phone": "+447712345678",
  "valid": true,
  "country": "GB",
  "live": true,
  "connected": true
}

?deep=true Roaming and network diagnostics, included in the same status lookup. Included in the same lookup, with no additional charge.

API reference SDKs Keys and authentication

Every response field

Response fields

phone: Normalized number (+ country code, no spaces), or null if invalid
valid: Number is valid
country: ISO 3166-1 alpha-2 country
live: Number is assigned to a subscriber. false = dead number, null = the network did not answer
connected: Handset was reachable at the last check. false = switched off or out of coverage, null = unknown

Deep fields

deep.roaming: Subscriber is roaming on a foreign network. Fills on live HLR queries, null on US and Canadian numbers
deep.roaming_network: Network the subscriber is roaming on, when roaming
deep.roaming_country: ISO 3166-1 alpha-2 country the subscriber is roaming in, when roaming
deep.network: Current serving network name. Fills on live HLR queries, null on US and Canadian numbers (use /carrier there)
deep.original_network: Network the number was originally issued on. Fills on live HLR queries
deep.mcc: Mobile Country Code of the current network. Fills on live HLR queries
deep.mnc: Mobile Network Code of the current network. Fills on live HLR queries

QUESTIONS

What is an HLR lookup?: A network check of whether a number is assigned and whether a handset is reachable. The API returns the result of that check and reuses cached results between checks.
What is the difference between live and connected?: live says the number was assigned at the last network check. connected says the handset was reachable at that check. A switched-off phone can be live: true and connected: false.
What about landlines?: Landlines answer the live question. Assigned numbers come back live: true, dead ones live: false. connected stays null, since reachability is a handset question landlines do not have.
Which numbers get the network fields?: Add deep=true for network and roaming detail returned by checks outside the North American Numbering Plan (NANP). A field returns null when the check does not supply it. The same HLR lookup unit covers core and detail, with no additional charge.
What does null mean?: This query path did not answer the question. null never means no.
What does a lookup cost?: One HLR lookup from the monthly allowance per valid number, including cached results and unknown status. Free includes 50 a month. See Plans for additional lookup rates. A failed network request uses no unit.
How recent is the network check?: Prior checks are reused for 7 days for mobile, VoIP, and unknown types, or 90 days for landline, toll-free, and disconnected numbers. A cached response can remain for up to another day. connected describes the last check, not the current moment.
Who serves the number?: Carrier, line type, and burner are GET /carrier.
Just need validation?: GET /phone validates and formats any number. 245 countries and regions.
Can I run a list?: Drop a phone CSV on /bulk. HLR is a toggle on the quote, priced per unique number. Dead numbers surface before you dial or text them.

Live status

Assignment and reachability at the last network check.

Have a list?

Drop a phone CSV. Live status flags the disconnected numbers. See your exact price before paying.

Drop a CSV, Excel, or Numbers file

or choose a file

Bulk phone validation