Search by task, endpoint, field, or error.

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. Results describe assignment and reachability at the last completed network check. Recent results can be reused. 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 returned an unknown result.

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. Results retain the assignment and reachability recorded by that check.

The selected lookup includes its available network details in the same unit. Outside North America these may include serving network, original_network, roaming status, and mcc/mnc. US and Canadian carriers answer status only, so those fields are null there and /carrier is the endpoint that names the network.

LookupCopy link

GET /hlr/{number}API Explorer ↗

Last-observed status. Optional ?country= (ISO2) for national formats

Parameters

numberstring · path · required

Phone number (E.164 preferred)

countrystring · query · optional

Default region for national formats without a leading +

Example

Request

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

const parse = parseAPI("YOUR_API_KEY");
const result = await parse.hlr("+447712345678");
console.log(result);
Example response
{
  "phone": "+447712345678",
  "valid": true,
  "country": "GB",
  "live": true,
  "connected": true,
  "roaming": false,
  "roaming_network": null,
  "roaming_country": null,
  "network": "EE",
  "original_network": "EE",
  "mcc": "234",
  "mnc": "30"
}
Open in API Explorer ↗

Response fields

phoneLink to phonestring or null
Normalized number (+ country code, no spaces), or null if invalid
validLink to validboolean
Number matches the numbering plan; this does not confirm assignment
countryLink to countrystring or null
ISO 3166-1 alpha-2 country
liveLink to liveboolean or null
Assignment at the last check. true = assigned, false = unassigned, null = unconfirmed
connectedLink to connectedboolean or null
Handset reachability at the last check. false = unreachable at that check; null = unconfirmed
roamingLink to roamingboolean or null
Subscriber was roaming on a foreign network at the check. Live HLR queries only; null for +1 North American numbers
roaming_networkLink to roaming_networkstring or null
Network the subscriber is roaming on, when roaming
roaming_countryLink to roaming_countrystring or null
ISO 3166-1 alpha-2 country the subscriber is roaming in, when roaming
networkLink to networkstring or null
Serving network name returned by the check. Live HLR queries only; null for +1 North American numbers (use /carrier there)
original_networkLink to original_networkstring or null
Network the number was originally issued on. Fills on live HLR queries
mccLink to mccstring or null
Mobile Country Code of the current network. Fills on live HLR queries
mncLink to mncstring or null
Mobile Network Code of the current network. Fills on live HLR queries

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