Phone Number Validation API Documentation

Global Phone Number Validation and Carrier Lookups

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.

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. 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.

Phone Number Validation API Use Cases

Reverse Phone Number Lookup - Search a phone number owner's name with worldwide coverage rates using reverse phone lookups. Easily verify user identity to limit bad actors.
Phone Number Fraud Prevention - Phone Number Risk Scoring prevents abusive behavior from fraudulent users and high risk accounts. Prevent fraud and abuse simply by checking the phone number against our global blacklists.
Low Quality Users - Identify duplicate user accounts, stolen user data, and fake registrations. Automatically block low quality accounts.
Chargebacks & Payment Fraud - Mitigate chargebacks, high risk transactions, and all types of ecommerce fraud by detecting phone numbers associated with recent malicious behavior.
Instant Validation - Identify disconnected or inactive phone numbers to quickly validate user data to screen applications, registrations, and payments.
Bot Detection - Filter nonexistent and bogus phone numbers to stop bots, risky users, and bad leads.
Geo Filtering - Filter users by validating their phone number matches their location. Pair with IP Reputation scoring for comprehensive geo filtering.
High Risk Behavior - Analyze user phone numbers to prevent fraudulent numbers by detecting disposable SMS, temporary phone numbers, Google Voice, and VOIPs.
Lead Generation & User Data Verification - Ensure data that you are collecting is valid, accurate, and fresh to prevent fake leads.

Phone Number Carrier and Line Type Detection API

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.

Phone Number Validation API

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 carriers, with support for all regions. 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.

Reverse Phone Number Lookup API

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.

Private Key

Please login or create a free account to access your API Key.

NOTE: Do not share this key with anyone. It's like a password and can be used to make queries using our API.

Request URLs

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.

JSON:

XML:

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.

JSON Example Requests

API Lookup with US, CA and UK countries supplied
Supplying countries to our API will prefer those countries for our verification process and will use those countries in the event a short phone number is supplied to the API.

API Lookup with Strictness Set to 1
A higher strictness will increase the verification requirements and potentially increase the fraud score or other factors in the event a phone number is invalid or fraudulent.

JSON Success Response Example

{
	"message": "Phone is valid.",
	"success": true,
	"formatted": "+18007132618",
	"local_format": "(800) 713-2618",
	"valid": true,
	"fraud_score": 44,
	"recent_abuse": false,
	"VOIP": false,
	"prepaid": false,
	"risky": true,
	"active": true,
	"name": "IPQualityScore",
	"carrier": "Verizon Wireless",
	"line_type": "Toll Free",
	"country": "US",
	"region": "Nevada",
	"city": "Las Vegas",
	"timezone": "America/Los_Angeles",
	"zip_code": "89132",
	"dialing_code": 1,
	"do_not_call": false,
	"leaked": false,
	"spammer": false,
	"active_status": "Active Line",
	"user_activity": "high",
	"associated_email_addresses": {"status":"Associated emails found.","emails":["hello@ipqualityscore.com"]},
	"request_id": "4ZGSfWu9RDf3oH"
}

NOTE: For a description of each field listed above please consult the response documentation below.

XML Success Response Example

<result>
	<message>Phone is valid.</message>
	<success>true</success>
	<formatted>+18007132618</formatted>
	<local_format>(800) 713-2618</local_format>
	<valid>true</valid>
	<fraud_score>44</fraud_score>
	<recent_abuse>false</recent_abuse>
	<VOIP>false</VOIP>
	<prepaid>false</prepaid>
	<risky>true</risky>
	<active>true</active>
	<name>IPQualityScore</name>
	<carrier>Verizon Wireless</carrier>
	<line_type>Toll Free</line_type>
	<country>US</country>
	<region>Nevada</region>
	<city>Las Vegas</city>
	<timezone>America/Los_Angeles</timezone>
	<zip_code>89132</zip_code>
	<dialing_code>1</dialing_code>
	<do_not_call>false</do_not_call>
	<leaked>false</leaked>
	<spammer>false</spammer>
	<user_activity>high</user_activity>
	<active_status>Active Line</active_status>
	<request_id>0tt6tE</request_id>
</result>

NOTE: For a description of each field listed above please consult the response documentation below.

JSON Error Response Examples

Example errors that you may encounter when accessing our API due to an exhausted credit balance or an invalid phone number.

{
	"success":false,
	"message":"You have insufficient credits to make this query. Please contact IPQualityScore support if this error persists.",
	"request_id":"4OTORR352FU0p"
}

{
	"message": "Invalid\/nonexistent phone number or no country specified.",
	"success": true,
	"formatted": "N\/A",
	"local_format": "N\/A",
	"valid": false,
	"fraud_score": 0,
	"recent_abuse": null,
	"VOIP": null,
	"prepaid": null,
	"risky": null,
	"active": null,
	"name": "N\/A",
	"carrier": "N\/A",
	"line_type": null,
	"country": "N\/A",
	"region": "N\/A",
	"city": "N\/A",
	"zip_code": "N\/A",
	"timezone": "N\/A",
	"dialing_code": null,
	"do_not_call": null,
	"leaked": null,
	"spammer": null,
	"request_id": "0tt6tI"
}

Additional Request Parameters

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.

Field	Description	Possible Values
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

Additional Request Options

Due to the nature of platform requirements or frameworks it may be necessary to request IPQS API endpoints without passing the API key in the URL. As an alternative, IPQS allows the API key to be passed via GET, POST, or Headers. These requests use the following endpoints:

JSON:

XML:

Method	Value	Example
GET	key	?key=YOUR_API_KEY_HERE&phone=18007132618
POST	key	key=YOUR_API_KEY_HERE&phone=18007132618
Header	IPQS-KEY (Additional parameters passed as either GET or POST)	IPQS-KEY: YOUR_API_KEY_HERE

Reporting Back Fraud & Improving Machine Learning

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.

The URL below is an example of how to report a phone number. Please include the 2 letter country code. The dialing code is optional.

Response Field Definitions

Quick Notes

Fraud Scores >= 75 - suspicious - previous reputation issues or low risk proxy/VPN.
Fraud Scores >= 85 - high risk - recent abusive behavior over the past 24-48 hours.
Recent Abuse = "high" - indicates frequent abusive behavior over the past 24-48 hours.

Further Details on Response Results

The Phone Validation API returns many data points so your business logic can make the best decisions for your audience. 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 high risk users that are likely to engage in malicious behavior. 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 only blocking "invalid" & "recent_abuse" phone numbers or Fraud Scores that are greater than 80-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?

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 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.

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

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 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.

Key	Expected Values	Description
risk_score	Float	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 compared to the overall "Fraud Score".
valid_billing_address	Boolean	Physical address validation and reputation analysis.
valid_shipping_address	Boolean	Same as above.
valid_billing_email	Boolean	Light abusive check and reputation analysis for the email address. It is recommended to use our dedicated Email Validation API for deeper analysis.
valid_shipping_email	Boolean	Same as above.
leaked_billing_email	Boolean	Indicates if the email address has recently been exposed or compromised in a database breach.
leaked_shipping_email	Boolean	Same as above.
leaked_user_data	Boolean	Indicates if the user's data (including phone & address) have recently been exposed or compromised in a database breach.
risky_billing_phone	Boolean	Reputation analysis for abusive activity associated with the phone number.
risky_shipping_phone	Boolean	Same as above.
valid_billing_phone	Boolean	Valid & active phone number with the phone carrier (not disconnected).
valid_shipping_phone	Boolean	Same as above.
billing_phone_carrier	String	Phone number provider company such as "AT&T" or "Bell Canada".
shipping_phone_carrier	String	Same as above.
billing_phone_line_type	String	Phone number line type such as Landline, Wireless, Toll Free, VOIP, Satellite, Premium Rate, Pager, Internet Service Provider, Unknown or N/A.
shipping_phone_line_type	String	Same as above.
billing_phone_country	String	2-letter country code associated with the phone number.
shipping_phone_country	String	Same as above.
billing_phone_country_code	Integer	Country dialing code associated with the phone number.
shipping_phone_country_code	Integer	Same as above.
bin_country	String	Country associated with the credit card BIN.
risky_username	Boolean	Username frequently associated with fraudulent behavior.
is_prepaid_card	Boolean	Status of the credit card as prepaid.
fraudulent_behavior	Boolean	Indicates high risk behavior patterns and a high chance of fraud.
phone_name_identity_match	String	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.
phone_email_identity_match	String	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.
phone_address_identity_match	String	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.
email_name_identity_match	String	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.
name_address_identity_match	String	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.
address_email_identity_match	String	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.

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

Example Code


const express = require('express');
const request = require('sync-request');
const app = express();
const port = 3000;


function Output(success = false, message = null, data = null) {
	this.success = success;
	this.message = message;
	this.data = null;
}


function CheckUserPhone(phone) {
	var key = 'YOUR_API_KEY_HERE';
	var url = "https://www.ipqualityscore.com/api/json/phone/" + key + "/" + phone;
	var result = get_IPQ_URL(url);
	if (result !== null) {
		return result;
	}
	else {
		// Throw error, no response received.
	}
}


function get_IPQ_URL(url) {
	try {
		var response = request('GET', url);
		return JSON.parse(response.getBody());
	}
	catch (error) {
		return null;
	}
}

function ValidPhone(phone) {
	var phone_result = CheckUserPhone(phone);
	
	if (phone_result !== null) {
		if (typeof phone_result !== 'undefined' && phone_result['valid'] === true) {
			return true;
		}
	}
		
	return false;
}

app.get('/', (req, res) => {
	var phone = req.phone;
	console.log(phone);
	if (ValidPhone(phone) === false) {
		return res.send(new Output(true, 'Invalid or nonexistent phone number.'));
	}
	else {
		return res.send(new Output(true, 'Valid phone number.'));
	}
});


app.listen(port, () => {
	console.log(`Example app listening on port ${port}!`)
});

// Your API Key.
$key = 'YOUR_API_KEY_HERE';

/*
* User's phone.
*/
$phone = '18007132618';

// Retrieve additional (optional) data points which help us enhance fraud scores and ensure data is processed correctly.
$countries = array('US', 'CA');
	
// Create parameters array.
$parameters = array(
	'country' => $countries
);

/* User & Transaction Scoring
* Score additional information from a user, order, or transaction for risk analysis
* Please see the documentation and example code to include this feature in your scoring:
* https://www.ipqualityscore.com/documentation/phone-number-validation-api/transaction-scoring
* This feature requires a Premium plan or greater
*/

// Format Parameters
$formatted_parameters = http_build_query($parameters);

// Create API URL
$url = sprintf(
	'https://www.ipqualityscore.com/api/json/phone/%s/%s?%s', 
	$key,
	$phone, 
	$formatted_parameters
);

// Fetch The Result
$timeout = 5;

$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, $url);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($curl, CURLOPT_FOLLOWLOCATION, 1);
curl_setopt($curl, CURLOPT_CONNECTTIMEOUT, $timeout);

$json = curl_exec($curl);
curl_close($curl);

// Decode the result into an array.
$result = json_decode($json, true);

// Check to see if our query was successful.
if(isset($result['success']) && $result['success'] === true){
	// NOTICE: If you want to use one of the examples below, remove
	// any lines containing /*, */ and *-, then remove * from any of the
	// the remaining lines.

	/*
	*- Example 1: We'd like to block all invalid phone numbers and send them to Google.
	* 
	* if($result['valid'] === false || $result['active'] === false){
	*		exit(header("Location: https://google.com"));
	* }
	*/
	
	/*
	*- Example 2: We'd like to block all invalid or abusive phone numbers.
	*
	* if($result['valid'] === false || $result['fraud_score'] >= 90){
	*		exit(header("Location: https://google.com"));
	* }
	*/
	
	/*
	* If you are confused with these examples or simply have a use case
	* not covered here, please feel free to contact IPQualityScore's support
	* team. We'll craft a custom piece of code to meet your requirements.
	*/
}

import json
import requests

# You may need to install Requests pip
# python -m pip install requests

class IPQS:
    key =  'YOUR_API_KEY_HERE'
    def phone_number_api(self, phonenumber: str, vars: dict = {}) -> dict:
        url = 'https://www.ipqualityscore.com/api/json/phone/%s/%s' %(self.key, phonenumber)
        x = requests.get(url, params = vars)
        return (json.loads(x.text))


if __name__ == "__main__":
    """
    User's phone.
    """
    phone = '18007132618'

    #Retrieve additional (optional) data points which help us enhance fraud scores and ensure data is processed correctly.
    countries = {'US', 'CA'};
        

    #custom feilds
    additional_params = {
        'country' : countries
    }

    """
    User & Transaction Scoring
    
    Score additional information from a user, order, or transaction for risk analysis
    Please see the documentation and example code to include this feature in your scoring:
    https://www.ipqualityscore.com/documentation/phone-number-validation-api/transaction-scoring
    This feature requires a Premium plan or greater
    """
    ipqs = IPQS()
    result  = ipqs.phone_number_api(phone, additional_params)

    # Check to see if our query was successful.
    if 'success' in result and result['success']:
        """
        - Example 1: We'd like to block all invalid phone numbers and send them to Google.
         
        if $result['valid'] == False:
        	print('This is not a valid number');
        }
        """
        
        """
        - Example 2: We'd like to block all invalid or abusive phone numbers.
        
        if $result['valid'] == False or $result['recent_abuse'] == True:
        	print('This is not a valid number or is abusive');
        }
        """
        
        """
        If you are confused with these examples or simply have a use case
        not covered here, please feel free to contact IPQualityScore's support
        team. We'll craft a custom piece of code to meet your requirements.
        """