Search by task, endpoint, field, or error.

← Docs

HLR Lookup API

Assignment and reachability at the last network check.

Live phone number status from the mobile network. Pass +14156226819 and the operator's home location register answers directly: 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.

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}
Live status for a number. 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 lookup uses included units and overage. 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
}

This lookup uses included units and overage. 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("+447700900123");
console.log(result);

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

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

This lookup uses included units and overage. 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("+14155550199");
console.log(result);

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

Example response
{
  "phone": "+14155550199",
  "valid": true,
  "country": "US",
  "live": false,
  "connected": false
}

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

Counts against your plan's monthly HLR allowance. Free includes 50. Each lookup on a valid number uses one. A repeat on the same number within a day serves from cache and still uses one.

Deep

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

This lookup uses included units and overage. 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.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? Email