Response `phone` object

The phone object normalizes a user-provided (loosely formatted) phone number and provides information on the current network, type of number, the country, and live reachability.

It's available in the result whenever a phone is provided in the input data.

If the lookup is unsuccessful, success will be false. If the phone number cannot be reliably coerced into international format, valid will be false. The success and valid properties are always present, but other properties only exist where success and valid are true.

info

Phone number checks will incur extra credit usage.

Examples

Unsuccessful:

{
    ...
    "phone": {
        "success": false,
        "valid": null
    },
    ...
}

Successful but not valid:

{
    ...
    "phone": {
        "success": true,
        "valid": false
    },
    ...
}

Valid:

{   
    ... 
    "phone": {
        "success": true,
        "valid": true,
        "in_country": true,
        "phone": "+12126647665",
        "phone_international": "+1 212-664-7665",
        "phone_national": "(212) 664-7665",
        "carrier": "T-Mobile",
        "carrier_high_risk": false,
        "country_name": "United States",
        "country_code": "US",
        "type": "mobile",
        "reachable": true,
        "seen_hour": 1,
        "seen_day": 1,
        "seen_month": 1,
        "seen_quarter": 1
    },
    ...
}

Properties

Property	Description	Type
success	Set to `true` only if the lookup is successful.	boolean
valid	Set to `true` when the phone number is in a recognised format and can be coerced into E.164 (international) format. Set to `null` where the lookup fails.	boolean or null
phone	The phone number in E.164 format.	string
phone_international	The phone number in international format.	string
phone_national	The phone number in national format, i.e. the local format without the country code.	String
carrier	The current carrier for the phone number. If the number has been ported, the latest carrier (the current network) will be shown here.	string or null
carrier_high_risk	Whether the carrier is known to be higher risk.	boolean or null
country_name	Full name of the country of the carrier.	string or null
country_code	Two-letter (ISO 3166-1 alpha-2) country code for the carrier.	string or null
type	A string representing the likely type of phone number. See below for the possible values. Can be `null` where the type can't be determined.	string or null
reachable	Set to `true` if reachable, `false` if not reachable, and `null` if reachability can't be determined (usually because of the number type or obfuscation by the carrier).	boolean or null
seen_hour	Number of times events have been seen with this phone number since the start of the previous hour.	integer
seen_day	Number of times events have been seen with this phone number since yesterday.	integer
seen_month	Number of times events have been seen with this phone number since the start of last month.	integer
seen_quarter	Number of times events have been seen with this phone number since the start of the last calendar quarter.	integer

Number types

Type	Description
fixed	Fixed line (landline) number
fixed_or_mobile	Either fixed line or mobile (in a country where they can't be distinguished)
mobile	Mobile (cellular) number
pager	Pager number
personal	Personal number
premium_rate	Premium rate number
shared_cost	Shared-cost number
toll_free	Toll-free (freephone) number
uan	Universal access number (UAN)
voicemail	Voicemail-only number
voip	VoIP (Voice over Internet Protocol) number

Resolving phone numbers

Be sure to either provide a number in E.164 format, or set the site's country code to match the country that users are expected to be in, to ensure accurate parsing.

Otherwise, we'll still attempt to parse the number, but the ambiguity may lead to unreliable results.

About our carrier and reachability data

We make a real-time home location register (HLR) lookup over the SS7 signalling system in order to determine the current network and reachability of a phone number.

A reachable status of true means the telephone number is live and is assigned to a subscriber who has recently used their phone.

There are additional checks on reachability for fixed line numbers in the UK & Ireland, and for mobile numbers in the USA or US territories. We'll make these checks automatically and reflect the result within the reachable field.

Response phone object

Examples​

Properties​

Number types​

Resolving phone numbers​

About our carrier and reachability data​