Phone Number Validation Endpoint

On this page, we’ll dive into the phone number validation endpoint you can use to validate any given phone number and retrieve its carrier and location information.

AI coding agents: run curl -s https://numlookupapi.com/agents.md and follow it: an API key, the first call and the right plan, step by step.

GET/v1/validate/{number}

Validate Phone Number

This endpoint validates a phone number and returns its formatting, country, location, carrier and line type.

Required attributes

Name
number
Type
string, path parameter
Description
The phone number you want to query (Either: including the country prefix, or without and you specify the country_code).

Optional attributes

Name
country_code
Type
string
Description
An ISO Alpha 2 Country Code for the phone number (e.g. US). If you specify this parameter you do not need to prepend the country prefix. A number that starts with + or 00 is already international and is looked up as sent.
Name
hlr
Type
boolean
Description
1 adds the live network status of a mobile number: whether it is reachable, whether it was ported and which network it belongs to now. Paid plans only. See Live network status (HLR) below.

Possible `line_type` values

landline
mobile
satellite
paging
special_services
premium_rate
toll_free
N/A

Carrier and line type are not a live status

carrier and line_type come from the numbering plan: they name the network the number’s range was assigned to and the kind of line it was issued for. They do not tell you whether the number is in service, whether the phone is switched on, or whether the number has since been ported to another network: a ported number keeps showing the network that issued it.

Need to know if a number is reachable or ported?
Only an HLR lookup (hlr=1) asks the mobile network itself. It is the one way to get whether the number is reachable right now (reachable), whether it was ported (ported) and which network it belongs to today (current_carrier).

Formats, number type and time zones

Every response also carries fields from the international numbering metadata (Google’s libphonenumber), which is updated with every numbering-plan change worldwide:

Name
e164_format
Type
string | null
Description
The number in E.164 format (+14158586273), the format SMS and voice providers expect.
Name
national_format
Type
string | null
Description
The number as dialled within its country, with the country’s usual grouping ((415) 858-6273, 020 7946 0000).
Name
rfc3966_format
Type
string | null
Description
The number as a tel: link (tel:+1-415-858-6273).
Name
possible
Type
boolean
Description
Whether the number has a possible length for its country. A possible number can still be unassigned, so use valid to decide.
Name
number_type
Type
string | null
Description
A finer classification next to line_type: landline, mobile, landline_or_mobile, toll_free, premium_rate, shared_cost, voip, personal_number, pager, uan, voicemail or unknown. In the US and Canada mobile and landline numbers share the same ranges, hence landline_or_mobile. Use voip to spot internet-based numbers in sign-up flows. null when the number is not valid in that metadata.
Name
timezones
Type
array
Description
The IANA time zones the number’s area lies in, e.g. ["America/Los_Angeles"]. Useful for calling or messaging at a sensible local time. Empty when unknown.

To validate many numbers at once, use the batch endpoint.

Invalid numbers

A well-formed but unrecognised number does not produce an error: the API returns HTTP 200 with "valid": false, empty strings for the formatting, country, location and carrier fields, and "line_type": "N/A".

Always check the valid field of the response, not the HTTP status code. A 422 status is only returned for malformed input, e.g. an empty number (invalid_number) or an unknown country_code (invalid_country_code) — see Request Status Codes.

Request

GET

/v1/validate/{number}

curl -G https://api.numlookupapi.com/v1/validate/+14158586273 \
    -H "apikey: YOUR-API-KEY"

Full Response

{
    "valid": true,
    "number": "14158586273",
    "local_format": "4158586273",
    "international_format": "+14158586273",
    "country_prefix": "+1",
    "country_code": "US",
    "country_name": "United States of America",
    "location": "Novato",
    "carrier": "AT&T Mobility LLC",
    "line_type": "mobile",
    "e164_format": "+14158586273",
    "national_format": "(415) 858-6273",
    "rfc3966_format": "tel:+1-415-858-6273",
    "possible": true,
    "number_type": "landline_or_mobile",
    "timezones": ["America/Los_Angeles"]
}

Response for an unrecognised number

{
    "valid": false,
    "number": "14158586273",
    "local_format": "",
    "international_format": "",
    "country_prefix": "",
    "country_code": "",
    "country_name": "",
    "location": "",
    "carrier": "",
    "line_type": "N/A",
    "e164_format": "+14158586273",
    "national_format": "(415) 858-6273",
    "rfc3966_format": "tel:+1-415-858-6273",
    "possible": true,
    "number_type": null,
    "timezones": []
}

GET/v1/validate/{number}?hlr=1

Live network status (HLR)

Add hlr=1 to look a mobile number up in its network’s home location register (HLR): whether the phone is reachable right now, whether the number was ported to another network, and which network it belongs to today. A lookup without hlr=1 cannot tell you any of this: its carrier and line_type come from the numbering plan, not from the network. Use it to skip unreachable or disconnected numbers before you send an SMS or place a call, or to route messages by the current network.

It applies to valid mobile numbers, including North American numbers whose number_type is landline_or_mobile. North American numbers have no live status: their reachable is unknown, and the carrier and porting come from the porting database. For any other number the fields below are null, with "hlr_supported": false, and nothing extra is charged.

Billing
Available on paid plans only; on the free plan hlr=1 returns 403 with the error code plan_upgrade_required. An answered HLR lookup costs 20 requests on top of the base request (X-Cost: 21). If the network does not answer in time, the response carries "hlr_error": "source_unavailable" and costs only the base request. Your quota must cover the full cost before the lookup runs; otherwise the request returns 429 with quota.required.

Response fields

With hlr=1 these fields follow the usual ones, always all of them:

Name
reachable
Type
string | null
Description
active (switched on and reachable), absent (switched off or out of coverage), inactive (disconnected, unassigned or otherwise not in service) or unknown (no live status, always for North American numbers).
Name
ported
Type
boolean | null
Description
Whether the number was ported away from the network that issued it.
Name
original_carrier
Type
string | null
Description
The network that issued the number.
Name
current_carrier
Type
string | null
Description
The network the number belongs to now, after any porting. carrier names the holder of the number range; current_carrier follows the number.
Name
mcc
Type
string | null
Description
The current network’s mobile country code (MCC), e.g. 262.
Name
mnc
Type
string | null
Description
The current network’s mobile network code (MNC), e.g. 02. A string, since it can start with 0.
Name
roaming
Type
boolean | null
Description
Whether the number is roaming in another network.
Name
hlr_supported
Type
boolean
Description
Whether HLR lookups apply to this number. false for landlines and other non-mobile numbers, and for invalid numbers.
Name
hlr_error
Type
string | null
Description
source_unavailable when the lookup applied but got no answer in time; the other HLR fields are then null and no extra cost is charged. null otherwise.

A field is null when the network did not report it.

Request

GET

/v1/validate/{number}?hlr=1

curl -G https://api.numlookupapi.com/v1/validate/+4915112345678 \
    -H "apikey: YOUR-API-KEY" \
    -d hlr=1

Response

{
    "valid": true,
    "number": "4915112345678",
    "local_format": "015112345678",
    "international_format": "+4915112345678",
    "country_prefix": "+49",
    "country_code": "DE",
    "country_name": "Germany (Federal Republic of)",
    "location": "",
    "carrier": "Telekom Deutschland GmbH",
    "line_type": "mobile",
    "e164_format": "+4915112345678",
    "national_format": "01511 2345678",
    "rfc3966_format": "tel:+49-1511-2345678",
    "possible": true,
    "number_type": "mobile",
    "timezones": ["Europe/Berlin"],
    "reachable": "active",
    "ported": true,
    "original_carrier": "Telekom Deutschland GmbH",
    "current_carrier": "Vodafone GmbH",
    "mcc": "262",
    "mnc": "02",
    "roaming": false,
    "hlr_supported": true,
    "hlr_error": null
}

Phone Number Validation Endpoint

Validate Phone Number

Required attributes

Optional attributes

Possible line_type values

Carrier and line type are not a live status

Formats, number type and time zones

Invalid numbers

Request

Full Response

Response for an unrecognised number

Live network status (HLR)

Response fields

Request

Response

Possible `line_type` values