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 is valid
countrystring or null
ISO 3166-1 alpha-2 country
liveboolean or null
Number is assigned to a subscriber. false = dead number, null = the network did not answer
connectedboolean or null
Handset was reachable at the last check. false = switched off or out of coverage, null = unknown

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 is roaming on a foreign network. Fills on live HLR queries, null on US and Canadian 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
Current serving network name. Fills on live HLR queries, null on US and Canadian 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