Getting Started

About the Phone Number Validation API

The IPQS Phone Number Validation API offers rapid analysis to determine the risk core, country of origin, carrier, validity, owner information, and connection status of phone numbers. By using this API, you can authenticate users, improve chargeback defense, and detect fraudulent activities in real-time. It can investigate landline and cellular numbers in over 150 countries, identifying invalid numbers and potential fraudsters.

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 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. Phone number validation is available through real-time, on-demand phone validation API lookups, with full coverage for international phone numbers.

Accurately verify phone numbers worldwide and retrieve a combination of carrier and line type details with risk analysis data to assess the reputation of phone numbers. Our system collects phone validation and verification data from various 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. Identify if the line is active, the phone is turned off, or the subscriber is absent or disconnected. Customizable settings allow you to tailor scoring to your audience.

Protect your business from SMS Pumping attacks. These types of fraud target SMS verification endpoints by generating fake traffic to premium-rate numbers, driving up costs for your business. By validating line types, detecting high-risk carriers, and identifying suspicious traffic patterns, the API helps block these fraudulent attempts before they result in revenue loss or inflated SMS fees.

Instructions for using the Phone Number Validation API can be found below.

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.

Phone Number Carrier and Line Type Detection API

Look up carrier details and phone number line types, such as landline, VOIP, wireless, and prepaid, with precision and 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 identify threats effectively.

Phone Number Validation API Use Cases

Reverse Phone Number Lookup: Search for the 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 blocklists.
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 e-commerce 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 invalid 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: Validate phone numbers to ensure the data you collect is valid, accurate, and fresh to prevent fake leads.
SMS Pumping Protection: Block artificially inflated SMS traffic by identifying high-cost premium-rate numbers, risky carriers, and suspicious usage patterns before attackers can exploit your verification system.

Follow the instructions below to use the Phone Number Validation API.

Using the API

You can use the following URLs to submit phone numbers to the Phone Number Verification API. Replace USER_PHONE_HERE with the phone number to validate.

Note

If the supplied phone number is less than 10 digits and does not have any possible countries included in the API request, then the API will like return the number as invalid. For best results, please ensure phone numbers are at least 10 digits long or supply at least one valid country.

JSON

https://www.ipqualityscore.com/api/json/phone/YOUR_API_KEY_HERE/USER_PHONE_HERE

XML

https://www.ipqualityscore.com/api/xml/phone/YOUR_API_KEY_HERE/USER_PHONE_HERE

Example API Requests

API Lookup with US, CA, and UK countries supplied
Countries supplied to our API will be preferred for our verification process and will be used in the event a short phone number is supplied to the API.

https://www.ipqualityscore.com/api/json/phone/YOUR_API_KEY_HERE/18007132618?country[]=US&country[]=UK&country[]=CA

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

https://www.ipqualityscore.com/api/json/phone/YOUR_API_KEY_HERE/18007132618?strictness=1

Example API Success Response in JSON

This is an example success response in JSON format. Details about each of these variables can be found in Response Parameters.

{
	"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",
	"accurate_country_code": true,
	"dialing_code": 1,
	"do_not_call": false,
	"leaked": false,
	"spammer": false,
	"active_status": "Active Line - High Confidence",
	"user_activity": "high",
	"associated_email_addresses": {"status":"Associated emails found.","emails":["hello@ipqualityscore.com"]},
	"mnc":"N/A",
	"mcc":"N/A",
	"request_id": "4ZGSfWu9RDf3oH",
	"tcpa_blacklist": false,
	"sms_pumping": {"risk_score":0,"message":"Low risk of SMS pumping attack.","velocity":"low"}
}

Example API Success Response in XML

This is an example success response in XML format. Details about each of these variables can be found in Response Parameters.

<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>
   <accurate_country_code>true</accurate_country_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>
   <mcc>N/A</mcc>
   <mnc>N/A</mnc>
   <request_id>0tt6tE</request_id>
   <tcpa_blacklist>false</tcpa_blacklist>
   <sms_pumping>
      <risk_score>0</risk_score>
      <message>Low risk of SMS pumping attack.</message>
      <velocity>low</velocity>
   </sms_pumping>
</result>

Error Response for Exhausted Credit Balance

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

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

Error Response for Invalid Phone Number

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

{
	"message": "Invalid/nonexistent phone number or no country specified.",
	"success": false,
	"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",
	"accurate_country_code": false,
	"timezone": "N/A",
	"dialing_code": null,
	"do_not_call": null,
	"leaked": null,
	"spammer": null,
	"request_id": "0tt6tI"
}

Next Steps

Tailor your API requests to match your specific needs with additional request parameters and other advanced options. Or learn more about each of the variables included in the responses you receive.

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

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