Response Parameters

Field Definitions

Learn about the parameters returned by the Phone Number Validation API. With clear definitions for every response value, you can fine tune your requests to better protect against fraud.

Fraud Score	Risk	Description
< 75	Suspicious	Has had previous reputation issues or is using a low risk proxy/VPN.
< 85	High Risk	Has suspicious behavior signals.
< 90	Frequent Abusive Behavior	Has demonstrated frequent abusive behavior over the past 24-72 hours.

Consider results as high risk when valid is false, active is false, or fraud_score is at least 90.

The Phone Validation API returns over 20 data points so your business logic can make the best decisions to validate phone numbers and accurately identify invalid phone numbers or risky user signals. Analyzing the validity of the phone number and overall Fraud Score is usually the best way to determine the user's overall risk. The API results directly indicate risky phone numbers and those with recent abusive behavior.

Fraud Scores >= 75 are suspicious and are likely to be involved in suspicious or dangerous activities but are not necessarily fraudulent users.
Fraud Scores >=85 are risky users likely to engage in malicious behavior.
Fraud Scores >=90 are very high-risk users that have already engaged in abuse. Scores in this threshold indicate recent or excessive abuse and fit the profile of a typical risky user.

We recommend blocking or flagging a phone number or transaction as high-risk using a combination of the fraud_score, recent_abuse, VOIP, prepaid, active, and risky variables. As every user has a unique audience, you may find better results validating phone numbers by only blocking "invalid" and "recent_abuse" phone numbers or Fraud Scores greater than 85-90+.

Field	Description	Possible Values
valid	Is the phone number properly formatted and considered valid based on assigned phone numbers available to carriers in that country?	boolean
active	Is this phone number a live, usable phone number that is currently active? This feature requires a separate data set that provides subscriber status details shared directly from the Telecom provider. Contact your account manager or support to enable this add-on feature, which determines if a phone number is reachable or disconnected using our HLR lookup service and carrier signals.	boolean, null
formatted	The phone number formatted in the international dialing code. Returns "N/A" if not formattable.	string
local_format	The phone number formatted in the country's local routing rules with area code. Returns "N/A" if not formattable.	string
fraud_score	The IPQS risk score which estimates how likely a phone number is to be fraudulent. Scores 85+ are risky, while Fraud Scores 90+ are high risk.	integer, 0 - 100
recent_abuse	Has this phone number been associated with recent or ongoing fraud?	boolean, null
VOIP	Is this phone number a Voice Over Internet Protocol (VOIP) or a digital phone number?	boolean, null
prepaid	Is this phone number associated with a prepaid service plan?	boolean, null
risky	Is this phone number associated with fraudulent activity, scams, robocalls, fake accounts, or other unfriendly behavior?	boolean, null
name	The name of the owner associated with the phone number, such as the first or last name or business name assigned to the phone number. The API will return multiple names in comma-separated format. Value is "N/A" if unknown.	string
identity_data	Enterprise Data Point — An object containing enhanced identity enrichment sourced from highly authoritative data sources such as credit bureaus, telcos, utility companies, and similar organizations. Enriches name, age, and related email addresses, phone numbers, and physical addresses. Each entry in identity_data represents one person. Each field may return multiple values. For example, the first_name field may return multiple values if the person has ever changed their name. If any data is unavailable, it will return either a "null" value or an empty array.
carrier	The carrier (service provider) this phone number has been assigned to or "N/A" if unknown.	string
line_type	The type of line this phone number is associated with (Toll-Free, Wireless, Landline, Satellite, VOIP, Premium Rate, Pager) or "N/A" if unknown. Line Type can play an important role in understanding phone number reputation.	string
country	The two-character country code for this phone number.	string
region	Region (state) of the phone number if available or "N/A" if unknown.	string
city	City of the phone number if available or "N/A" if unknown.	string
accurate_country_code	Indicates whether the phone number's dialing code matches any of the provided country code(s).	boolean
zip_code	Zip or Postal code of the phone number if available or "N/A" if unknown.	string
timezone	Time zone of the phone number if available or "N/A" if unknown.	string
dialing_code	The 1 to 4-digit dialing code for this phone number or "null" if unknown.	integer
do_not_call	Indicates if the phone number is listed on any Do Not Call (DNC) lists. This parameter is only supported in the USA and Canada. This data may not be 100% current with the latest DNC blocklists. Contact your account manager to enable better DNC data and removal of TCPA litigators.	boolean
leaked	Has this phone number recently been exposed in an online database breach or compromise?	boolean
spammer	Indicates if the phone number has recently been reported for spam or harassing calls/texts.	boolean
active_status	Additional details on the status of the subscriber connection will be provided when enhanced active line checks are enabled. Contact your account manager or support to enable this add-on feature, which determines if a phone number is reachable or disconnected using our HLR lookup service and carrier signals. These values can be: - "Active Line" - "Active Line - High Confidence" - "Active Line - Medium Confidence" - "Active Line - Low Confidence" - "Disconnected Line" - "Phone Turned Off" - "Inconclusive Status" - or "N/A" if unknown. The confidence level is included for active lines whenever possible.	string
user_activity	The frequency at which this phone number makes legitimate purchases or account registrations and otherwise engages in legitimate user behavior online. Values can be "high", "medium", "low", or "none". Values of "high" or "medium" are strong signals of healthy usage. New phone numbers without a history of legitimate behavior will have a value as "none". This field is restricted to higher plan tiers.	string
mcc	Mobile Country Codes (MCC) identify the country of a mobile phone number subscriber. This provides a corresponding number to a specific country to facilitate routing for wireless calls and SMS messages. The MCC value is "N/A" when unknown or unavailable, such as for landline and toll-free numbers.	string (typically 3 digit number) or "N/A"
mnc	Mobile Network Codes (MNC) identify the mobile carrier of a phone number subscriber. This data provides a corresponding number to a specific telecom provider, such as Orange, Vodafone, and more, to facilitate routing for wireless calls and SMS messages. The MNC value is "N/A" when unknown or unavailable, such as for landline and toll-free numbers.	string (typically 3 digit number) or "N/A"
associated_email_addresses	Displays email addresses linked to the phone number, if available in our data sources. Match rates vary by country and line type. This field is restricted to upgraded plans. Object value contains "status" and "emails" as an array.	object
sms_email	Carrier provided email address that allows emailing to a mobile device. Generally, this value will be 'N/A' if not available or the combined Phone Number and the carrier domain.	string
transaction_details (object)	Additional scoring variables for risk analysis are available when transaction scoring data is passed through the API request. These variables are also useful for scoring user data such as physical addresses, phone numbers, usernames, and transaction details. The data points below are populated when at least one transaction data parameter is present in the initial API request. The following transaction variables are "null" when the necessary transaction parameters are not passed with the initial API request. For instance, not passing the "billing_email" will return "valid_billing_email" as null.
message	A generic status message, generally "success" or an error notice, but may contain other information.	string
success	Was the request successful?	boolean
request_id	A unique identifier for this request that can be used to look up the request details or send a postback conversion notice.	string
errors	An array of errors that occurred while attempting to process this request.	array of strings
tcpa_blacklist	Indicates if the phone number is known to be or associated with repeated TCPA plaintiffs (individuals who frequently file TCPA lawsuits).	boolean
sms_pumping	An array indicating the likelihood that the phone number is engaged in SMS pumping fraud. SMS pumping is a type of attack where perpetrators artificially inflate the volume of traffic sent to websites and app touchpoints protected by SMS authentication. Contact your account manager or support to enable this add-on feature.
number_recycling	An array detailing if the phone number has recently changed owners or moved between providers.

identity_data fields

Note

This data is available through an optional add-on feature. Contact your account manager or our support team to enable it.

Field	Description	Possible Values
names	An object containing names associated with the phone number.	first_name: Their first name. last_name: Their last name. middle_name: Their middle name.
addresses	An object containing physical addresses associated with the phone number.	address: The street address. city: The city. region: The state or region. postal_code: The postal code. country: The country.
email_addresses	An object containing other email addresses associated with the phone number.	email: The email address. first_seen: When the email address was first created. last_seen: When the email address was last used.
phone_numbers	An object containing phone numbers associated with the phone number.	formatted_phone_number: The full phone number, including country code. country: The country associated with the phone number.
age	An object containing ages of people associated with the phone number.	human: How many years old the person is. birthday_iso: Their date of birth in ISO format. birthday_timestamp: Their birthday in timestamp format. birthdate_certanty: Whether we are certain the birthdate is correct.

transaction_details (object) fields

Key	Description	Expected Values
risk_score	Confidence that this user or transaction is exhibiting malicious behavior. Scores are 0 - 100, with 75+ as suspicious and 90+ as high risk. This value uses different calculations with less weight on the IP reputation than the overall "Fraud Score".	Float
valid_billing_address	Physical address validation and reputation analysis.	Boolean
valid_shipping_address	Same as above.	Boolean
valid_billing_email	Light abusive check and reputation analysis for the email address. We recommend using our dedicated Email Validation API for deeper analysis.	Boolean
valid_shipping_email	Same as above.	Boolean
leaked_billing_email	Indicates if the email address was recently exposed or compromised in a database breach.	Boolean
leaked_shipping_email	Same as above.	Boolean
leaked_user_data	Indicates if the user's data (including phone & address) have recently been exposed or compromised in a database breach.	Boolean
risky_billing_phone	Reputation analysis for abusive activity associated with the phone number.	Boolean
risky_shipping_phone	Same as above.	Boolean
valid_billing_phone	Valid & active phone number with the phone carrier (not disconnected).	Boolean
valid_shipping_phone	Same as above.	Boolean
billing_phone_carrier	Phone number provider such as "AT&T" or "Bell Canada".	String
shipping_phone_carrier	Same as above.	String
billing_phone_line_type	Phone number line type, such as Landline, Wireless, Toll-Free, VOIP, Satellite, Premium Rate, Pager, Internet Service Provider, Unknown, or N/A.	String
shipping_phone_line_type	Same as above.	String
billing_phone_country	2-letter country code associated with the phone number.	String
shipping_phone_country	Same as above.	String
billing_phone_country_code	The country dialing code associated with the phone number.	Integer
shipping_phone_country_code	Same as above.	Integer
bin_country	The country associated with the credit card BIN.	String
risky_username	Is the username frequently associated with fraudulent behavior?	Boolean
is_prepaid_card	Is the credit card prepaid?	Boolean
fraudulent_behavior	Indicates high-risk behavior patterns and a high chance of fraud.	Boolean
phone_name_identity_match	Enterprise Account Feature — Indicates a reverse identity match between the billing phone number and first/last name. Values: "Unknown" - no checks processed, "Match" - positive identity match, "Mismatch" - data matches another user, "No Match" - could not pair identity data.	String
phone_email_identity_match	Enterprise Account Feature — Indicates a reverse identity match between the billing phone number and email address. Values: "Unknown" - no checks processed, "Match" - positive identity match, "Mismatch" - data matches another user, "No Match" - could not pair identity data.	String
phone_address_identity_match	Enterprise Account Feature — Indicates a reverse identity match between the billing phone number and physical address. Values: "Unknown" - no checks processed, "Match" - positive identity match, "Mismatch" - data matches another user, "No Match" - could not pair identity data.	String
email_name_identity_match	Enterprise Account Feature — Indicates a reverse identity match between the billing email address and first/last name. Values: "Unknown" - no checks processed, "Match" - positive identity match, "Mismatch" - data matches another user, "No Match" - could not pair identity data.	String
name_address_identity_match	Enterprise Account Feature — Indicates a reverse identity match between the billing first/last name and physical address. Values: "Unknown" - no checks processed, "Match" - positive identity match, "Mismatch" - data matches another user, "No Match" - could not pair identity data.	String
address_email_identity_match	Enterprise Account Feature — Indicates a reverse identity match between the billing physical address and email address. Values: "Unknown" - no checks processed, "Match" - positive identity match, "Mismatch" - data matches another user, "No Match" - could not pair identity data.	String

sms_pumping fields

Note

This data is available through an optional add-on feature. Contact your account manager or our support team to enable it.

Field	Description	Possible Values
risk_score	A score indicating the likelihood of an SMS pumping attack.	integer, 0 - 100
message	A string describing the risk of SMS Pumping attack.	"High risk of SMS pumping attack."
velocity	A string indicating the risk value.	"low", "medium", "high"

number_recycling fields

Field	Description	Possible Values
recently_recycled	Indicates if the phone number has recently been reassigned to a new owner.	Boolean
last_ported_date	The date when the phone number was last transferred to a new carrier, if any.	A date in timestamp format
ported	Indicates if the number has been transferred to a new carrier from its original carrier of record.	Boolean

Ready to eliminate fraud?

Start fighting fraud now with 1,000 Free Lookups!

We're happy to answer any questions or concerns.

Chat with our fraud detection experts any day of the week.

Call us at: (800) 713-2618

Schedule a Demo Sign Up