Phone number status · Contact-list cleanup

HLR Lookup API

Find unassigned numbers.
Keep your list useful.

Check number assignment and handset reachability in one request. Give your CRM or contact-cleaning workflow a clear status to act on.

Get startedExplore the API

Status from the last network check. Recent checks may be reused.

Explore a status result

GET /hlr/+447712345678?deep=true

{
  "phone": "+447712345678",
  "valid": true,
  "country": "GB",
  "live": true,
  "connected": true,
  
    "roaming": false,
    "roaming_network": null,
    "roaming_country": null,
    "network": "Example Mobile",
    "original_network": "Example Mobile",
    "mcc": "234",
    "mnc": "30"
  }
}

Illustrative network results. No paid lookup is made.

A number in. A useful status out.

One request.
Clear decisions.

Explore the complete response for each status. Add deep=true when you need available network and roaming detail.

Illustrative network results. Selecting an example makes no paid lookup.

Assigned and reachable at the check.

live and connected are both true. These are illustrative results; an actual lookup may reuse an earlier check.

Request

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

Example response

JSON200 OK
{
  "phone": "+447712345678",
  "valid": true,
  "country": "GB",
  "live": true,
  "connected": true,
  
    "roaming": false,
    "roaming_network": null,
    "roaming_country": null,
    "network": "Example Mobile",
    "original_network": "Example Mobile",
    "mcc": "234",
    "mnc": "30"
  }
}

Two questions. Two fields.

Assigned?
Reachable?

Use live to identify numbers reported as unassigned. Use connected for handset reachability at that check. An assigned phone can be unreachable.

Both fields describe the last observation. A status check does not guarantee that a call or message will be delivered.

live
true means assigned. false means reported as unassigned. null means unconfirmed.
connected
true means reachable at the check. false means unreachable at that check. null means unconfirmed.
valid
Checks the numbering plan. An input can be valid even when the number is unassigned.

Optional network detail

More context.
Same lookup.

Add deep=true to see the available network and roaming diagnostics from that observation. Assignment and reachability stay in the response.

Details depend on country, network and check type. Fields stay null when unavailable, including for +1 North American numbers.

HLR response details
Serving network
The network returned by the check, with its mobile country and network codes when supplied.
Original network
The network that originally issued the number, when supplied.
Roaming status
Whether the subscriber was roaming on a foreign network at the check. Unknown stays null.
Roaming destination
The returned roaming network and country, when supplied.

From one contact to a whole list

Use it where
your contacts live.

Call HLR from your application or upload a phone list to Bulk. Filter on the assignment result and keep unknown contacts available for review.

Clean a file with Bulk

Validate and format

Phone handles numbering-plan validation and formatting. Use it when you only need a clean number.

Phone API

Get carrier and line type

Carrier supplies carrier identity and line type when available, with its own lookup allowance.

Carrier API

From the first request to your app

Your contacts.
Your stack.

Send a number with its + country code, or add a country hint for national input. One API key connects HLR with the rest of ParseAPI.

HLR API reference

HTTP, SDKs and MCP

Copy a request above, use a server SDK, or give your agent the HLR lookup through MCP.

Explore the response fields

Response fields

phonestring or null
Normalized number (+ country code, no spaces), or null if invalid
validboolean
Number matches the numbering plan; this does not confirm assignment
countrystring or null
ISO 3166-1 alpha-2 country
liveboolean or null
Assignment at the last check. true = assigned, false = unassigned, null = unconfirmed
connectedboolean or null
Handset reachability at the last check. false = unreachable at that check; null = unconfirmed

Deep fields

deep.roamingboolean or null
Subscriber was roaming on a foreign network at the check. Live HLR queries only; null for +1 North American numbers
deep.roaming_networkstring or null
Network the subscriber is roaming on, when roaming
deep.roaming_countrystring or null
ISO 3166-1 alpha-2 country the subscriber is roaming in, when roaming
deep.networkstring or null
Serving network name returned by the check. Live HLR queries only; null for +1 North American numbers (use /carrier there)
deep.original_networkstring or null
Network the number was originally issued on. Fills on live HLR queries
deep.mccstring or null
Mobile Country Code of the current network. Fills on live HLR queries
deep.mncstring or null
Mobile Network Code of the current network. Fills on live HLR queries

Before you build.

What does an HLR lookup tell me?

It returns phone-number assignment and handset reachability from the last network check. live describes assignment; connected describes reachability. valid checks the numbering plan and does not establish assignment.

How recent is the result?

Prior checks may be reused for 7 days for mobile, VoIP and unknown line types, or 90 days for landline, toll-free and unassigned numbers. A cached response can remain for up to another day. Use the result for contact-list cleanup; it is a last-observed status, not a current handset-presence signal.

What does null mean?

The field is unconfirmed. An unknown status is different from live: false, which reports an unassigned number. An unreachable handset can still have live: true.

Which numbers have network and roaming details?

Deep fields fill when a live HLR check supplies them outside the +1 North American Numbering Plan. Coverage varies by country and network. These fields stay null for +1 numbers and database-only answers. Use Carrier for carrier and line-type information.

What does a lookup cost?

Each valid-number lookup uses one HLR unit, including cached results and a completed check with unknown status. Deep is included in that same unit. Invalid input and a failed network request use no HLR unit. Free includes 50 a month; Plans shows paid allowances and optional on-demand rates.

Can I check a phone list?

Upload your file to Bulk and select HLR on the quote. Bulk shows its own price per unique number before you run the file.

Can I use HLR in a native app?

Call HLR through your backend with a server key. Native app keys do not support HLR. Keep your secret key on the server.

How do I send a national number?

Add an ISO country code, such as country=GB for 07712345678. International numbers beginning with + already carry their country calling code.

HLR API pricing

Start with your next list.

HLR has its own monthly lookup allowance. Network details are included in the same lookup. Choose more capacity and optional on-demand usage on Plans.

Free

Start with a free API key.

Room to grow

Choose your allowance on Plans.

Valid-number lookups use one unit, including cached and unknown results. Invalid input and failed network requests use no HLR unit. Bulk files have a separate quote.

Get startedCompare plans