Search by task, endpoint, field, or error.

← Docs

HLR Lookup API

Assignment and reachability at the last network check.

Last-observed phone number status from a network check. Pass +14156226819 to check assignment and reachability: live says the number is assigned to a subscriber, connected says the handset was reachable at the last network check. Carrier and line type live on /carrier.

A fresh network query can take a few seconds. Recent results can be reused; a positive result is not a promise of current presence. Coverage is worldwide. Landlines answer assignment honestly: live fills, connected stays null because reachability is a handset question. Junk answers valid: false as a 200, never a 404. null means this query path did not answer the question, never no.

Checks can be reused for 7 days for mobile or unknown numbers, or 90 days for landlines or dead numbers, with up to another day of caching. Read checked_at for the original check time. This is not a current handset-presence signal.

With ?deep=true, the same lookup unit also includes network details. Outside North America these may include serving deep.network, deep.original_network, roaming status, and deep.mcc/deep.mnc. US and Canadian carriers answer status only, so those fields are null there and /carrier is the endpoint that names the network.

Lookup

GET
api.parseapi.com/hlr/{number}
Last-observed status. Optional ?country= (ISO2) for national formats
Explore
Parameters 3
numberstring · path · required

Phone number (E.164 preferred)

countrystring · query · optional

Default region for national formats without a leading +

deepboolean · query · optional

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

This metered lookup uses its included allowance or enabled on-demand billing. Copy the example to run it with your key.

SDK quickstart
import { parseAPI } from '@parseapi/sdk';

const parse = parseAPI("YOUR_API_KEY");
const result = await parse.hlr("+447712345678");
console.log(result);

Run on your server with a secret key. Calling from a browser or app?

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

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

Counts against your plan's monthly HLR allowance. Free includes 50. Each lookup on a valid number uses one, including a reused result.

Deep

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

This metered lookup uses its included allowance or enabled on-demand billing. Copy the example to run it with your key.

SDK quickstart
import { parseAPI } from '@parseapi/sdk';

const parse = parseAPI("YOUR_API_KEY");
const result = await parse.hlr("+447712345678", { deep: true });
console.log(result);

Run on your server with a secret key. Calling from a browser or app?

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

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

Questions? Email