IPQualityScore's Phone Number Validation API enables quick user verification and chargeback defense on a global scale by analyzing phone numbers to verify their risk score, country of origin, carrier, validity, and line connection status while also detecting fraudulent activity in real time. The IPQS phone number lookup API can enrich landline and cellular numbers in over 150 countries to identify invalid phone numbers or malicious users.
Perform carrier lookups by API in any region to detect disconnected phone numbers and retrieve important carrier info including line types to determine if a number is a VOIP, landline, mobile/wireless, or prepaid line. Cell phone lookups typically to have better identity enrichment hit rates. Reverse phone number lookups can also provide a personal or company name associated with a phone number to help validate identity and prevent abusive behavior.
Test IPQS phone number reputation data with our free phone number validator, which can also retrieve spam scores and risk scores. Validating phone numbers is available through real-time on-demand phone validation API lookups with full coverage for international phone numbers.
Lookup carrier details and phone number line types such as Landline, VOIP, Wireless, Prepaid, etc. with precision accuracy worldwide. IPQS maintains current data directly from carriers on a global level. Riskier carriers and phone ranges associated with malicious behavior will display elevated Fraud Scores to enable your business logic to effectively identify threats.
Accurately verify phone numbers worldwide and retrieve a combination of carrier and line type details with risk analysis data to assess phone numbers reputation. Our system collects phone validation and verification data from a wide variety of telecom carriers, with support in over 150 countries for international phone number validation. Detect inactive and disconnected phone numbers for easy user validation similar to HLR & LRN lookups. The "active_status" will identify if the line is active, the phone is turned off, or if the subscriber is absent or disconnected. Customizable settings allow scoring to be tailored to your audience.
Lookup the owner of the phone number including first and last name or the company's name with real-time API responses. Reverse phone lookups have excellent coverage in the US and Canada and limited support internationally, including Europe and Asia. Reverse name lookups for phone numbers can help verify identity, limit abusive behavior, prevent unwanted callers, and enrich lead and contact details directly through our reverse phone lookup API.
NOTE: Do not share this key with anyone. It's like a password and can be used to make queries using our API.
The URLs below can be used to fetch the result using cURL or another utility in most languages. Please see the usage example at the bottom of the page. Simply replace "USER_PHONE_HERE" with the phone you wish to validate.
Short Phone Number Notice: If the supplied phone number is less than 10 digits and does not have any possible countries included in the API request, then it's likely the phone number will return as invalid. For best results, please ensure phone numbers are at least 10 digits long or supply at least one valid country.
NOTE: For a description of each field listed above please consult the response documentation below.
NOTE: For a description of each field listed above please consult the response documentation below.
Example errors that you may encounter when accessing our API due to an exhausted credit balance or an invalid phone number.
Custom tracking variables (such as "userID", "transactionID") established in your account settings can be passed with each API request. This allows our reporting tools to filter by specific users, products, campaigns, transactions, etc. so that you can easily match up records with your own system to identify fraudulent activity.
|strictness||How in depth (strict) do you want this reputation check to be? Stricter checks may provide a higher false-positive rate. We recommend starting at "0", the lowest strictness setting, and increasing to "1" or "2" depending on your levels of fraud.||integer, 0 - 2|
|country||You can optionally provide us with the default country or countries this phone number is suspected to be associated with. Our system will prefer to use a country on this list for verification or will require a country to be specified in the event the phone number is less than 10 digits.||string or array of strings|
|enhanced_line_check||Please contact support to activate this feature for more advanced active line checks through our HLR lookup service. This feature provides greater accuracy for identifying active or disconnected phone numbers including landline, mobile, and VOIP services.||boolean|
|enhanced_name_check||Please contact support to activate enhanced name appending for a phone number. Our standard phone validation service already includes extensive name appending data.||boolean|
Due to the nature of platform requirements or frameworks it may be necessary to request the Phone Number Validation API endpoints without passing the API key in the URL. As an alternative, IPQS allows the Phone Validation API key to be passed via GET, POST, or Headers. These requests use the following endpoints:
|Header||IPQS-KEY (Additional parameters passed as either GET or POST)||IPQS-KEY: YOUR_API_KEY_HERE|
Train your account's machine learning algorithms to better identify fraud for your audience. The following endpoint can be used to report phone numbers as fraudulent. Please only report data that has a high confidence of being abusive.
Fraud Scores >= 75 — suspicious — previous reputation issues or low risk proxy/VPN.
Fraud Scores >= 85 — high risk — suspicious behavior signals
Fraud Scores >= 90 — frequent abusive behavior over the past 24-72 hours.
Consider results as high risk when "valid" is false OR "active" is false OR "fraud_score" >= 90.Further Details on Response Results
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 overall risk of the user. Risky phone numbers and those with recent abusive behavior are directly indicated in the API results. Fraud Scores >= 75 are suspicious and are likely to be involved in suspicious or dangerous activities, but not necessarily a fraudulent user. Fraud Scores >=85 are risky users that are 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 their own unique audience, you may find better results validating phone numbers by only blocking "invalid" & "recent_abuse" phone numbers or Fraud Scores that are greater than 85-90+.
|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?||boolean, null|
|formatted||The phone number formatted in the international dialing code. N/A if not formattable.||string|
|local_format||The phone number formatted in the country's local routing rules with area code. 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 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, robo calls, fake accounts, or other unfriendly behavior?||boolean, null|
|name||The owner name of the phone number such as the first or last name or business name assigned to the phone number. Multiple names will be returned in comma separated format. Value is "N/A" if unknown.||string|
|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, Mobile, Landline, Satellite, VOIP, Premium Rate, Pager, etc...) or "N/A" if unknown.||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|
|zip_code||Zip or Postal code of the phone number if available or "N/A" if unknown.||string|
|timezone||Timezone 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. Only supported in US and CA. This data may not be 100% up to date with the latest DNC blacklists. Contact your account mangaer to enable better DNC data and TCPA litigator removal.||boolean|
|leaked||Has this phone number recently been exposed in an online database breach or act of 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 when enhanced active line checks are enabled. Contact your account manager to enable this add-on feature. These values can be "Active Line", "Disconnected Line", "Phone Turned Off", "Inconclusive Status", or "N/A" if unknown.||string|
|user_activity||Frequency at which this phone number makes legitimate purchases, account registrations, and 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|
|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|
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 1 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, either success or some form of an error notice.||string|
|success||Was the request successful?||boolean|
|request_id||A unique identifier for this request that can be used to lookup the request details or send a postback conversion notice.||string|
|errors||Array of errors which occurred while attempting to process this request.||array of strings|
Our phone number validation APIs can be enhanced by additional data sets to improve accuracy for active line status checks. This feature requires a separate data set which provides subscriber status details shared directly from the Telecom provider. If you experience any false-positives while validating phone numbers, please contact our support team so we can optimize your phone number validator API settings. Our direct partnerships with major Telecom providers allows for reliable data providers, so we can accurately identify suspicious phone numbers or disconnected lines.
IPQS makes it easy to deploy our phone number validation APIs for your website or app. First, grab your API key from your account's settings page. Then use the example phone validator API code on this page to directly integrate phone validation lookups in your business logic. Our partnerships with phone carriers allows us to accurately perform the number verification process with high quality phone data to determine invalid phone numbers in addition to line type and suspicious phone numbers with poor reputation signals.