<< Back to Categories

Getting Started

About the Phone Number Validation API

The IPQS Phone Number Validation API enables you to quickly analyze phone numbers to verify their risk score, country of origin, carrier, validity, owner information, and line connection status. This enables you to verify users, improve chargeback defense, and detect fraudulent activity in real-time. The IPQS Phone Number Validation API can research landline and cellular numbers in over 150 countries to identify invalid phone numbers or malicious users.

API Request URLs

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

XML

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.

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.

Example API Responses

Success Responses

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

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>
</result>

Error Responses

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

EXAMPLE CODE

NODEJS
PHP
PYTHON

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 5,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