Skip to main content

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.


Phone number checks will incur extra credit usage.



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

Successful but not valid:

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


"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


successSet to true only if the lookup is successful.boolean
validSet 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
phoneThe phone number in E.164 format.string
phone_internationalThe phone number in international format.string
phone_nationalThe phone number in national format, i.e. the local format without the country code.String
carrierThe 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_riskWhether the carrier is known to be higher risk.boolean or null
country_nameFull name of the country of the carrier.string or null
country_codeTwo-letter (ISO 3166-1 alpha-2) country code for the carrier.string or null
typeA 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
reachableSet 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_hourNumber of times events have been seen with this phone number since the start of the previous hour.integer
seen_dayNumber of times events have been seen with this phone number since yesterday.integer
seen_monthNumber of times events have been seen with this phone number since the start of last month.integer
seen_quarterNumber of times events have been seen with this phone number since the start of the last calendar quarter.integer

Number types

fixedFixed line (landline) number
fixed_or_mobileEither fixed line or mobile (in a country where they can't be distinguished)
mobileMobile (cellular) number
pagerPager number
personalPersonal number
premium_ratePremium rate number
shared_costShared-cost number
toll_freeToll-free (freephone) number
uanUniversal access number (UAN)
voicemailVoicemail-only number
voipVoIP (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.