<< Back to Categories

Phone Reputation

Phone Number Validation and Carrier Lookup

IPQS risk analysis tools enable user scoring with the IPQS Phone Validation API service using a straightforward API call. What's more, it comes with worldwide carrier support, making it a global solution. Generate a phone number reputation score to verify users, payments, and sign-ups to prevent fraudulent behavior. Detect VOIP numbers with a phone number risk score to prevent suspicious users.

Identify low-quality users and fraudulent phone numbers in real-time. Detect temporary or disposable phone numbers as well as phone numbers that have recently been involved with abusive behavior online. Phone Reputation screening is a great way to automatically prevent fake accounts and fraudulent behavior.

If you wish to verify phone numbers without passing an IP address, use our dedicated phone number validation API. You can test our phone validation service anytime with our free phone number validator tool.

Example Request

The example below incorporates scoring a phone number with an IP address. Phone numbers without a valid country code will assume the country code of the request's IP address. You can pass the user's primary information into the "billing" variables even if a transaction is not taking place.

Request Parameters

Key	Description	Expected Values
billing_country	User billing or primary country name or billing country ISO-Alpha2. (EG: United States or US)	String (optional)
billing_phone	User billing or primary 11 to 14 digit phone number. (If less than 10 digits provided, the country code will be guessed by our AI.)	Number
billing_phone_country_code	Country dialing code associated with the billing phone. Typically 1-3 digits.	Number (optional)
shipping_country	User shipping or secondary country name or shipping country ISO-Alpha2. (EG: United States or US)	String (optional)
shipping_phone_country_code	Country dialing code associated with the shipping phone. Typically 1-3 digits.	Number (optional)
shipping_phone	User shipping or secondary 11 to 14 digit phone number. (If less than 10 digits provided, the country code will be guessed by our AI.)	Number (optional)

Response Parameters

Key	Description	Expected Values
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 company such as "AT&T" or "Bell Canada".	String
shipping_phone_carrier	Same as above.	String
billing_phone_line_type	Landline, Wireless, Toll Free, VOIP, Satellite, Premium Rate, Pager, Internet Service Provider or Unknown.	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	Country dialing code associated with the phone number.	Integer
shipping_phone_country_code	Same as above.	Integer

EXAMPLE CODE

PHP
PYTHON

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

/*
* Retrieve the user's IP address. 
* You could also pull this from another source such as a database.
* 
* If you use cloudflare change REMOTE_ADDR to HTTP_CF_CONNECTING_IP
*/
$ip = isset($_SERVER['REMOTE_ADDR']) ? $_SERVER['REMOTE_ADDR'] : $_SERVER['HTTP_CLIENT_IP'];


// Retrieve additional (optional) data points which help us enhance fraud scores.
$user_agent = $_SERVER['HTTP_USER_AGENT']; 
$user_language = $_SERVER['HTTP_ACCEPT_LANGUAGE'];

// Set the strictness for this query. (0 (least strict) - 3 (most strict))
$strictness = 0;

// You may want to allow public access points like coffee shops, schools, corporations, etc...
$allow_public_access_points = 'true';

// Create parameters array.
$parameters = array(
	'user_agent' => $user_agent,
	'user_language' => $user_language,
	'strictness' => $strictness,
	'allow_public_access_points' => $allow_public_access_points
);

/* User & Transaction Scoring
* Score additional information from a user, order, or transaction for risk analysis
* All transaction parameters are optional, please remove any that are not used
* Non paid actions such as lead generation and user scoring can be substituted into the "billing" or "shipping" variables
* This feature requires a Premium plan or greater
* Premium users can also adjust transaction scoring rules: https://www.ipqualityscore.com/user/transaction/weights
*/

// Optionally pass up to 2 phone numbers per user or transaction
// Countries are optional - 2 letter country code can be included if country code is not included in the phone number
	$transaction_parameters = array(
		'billing_country' => '',
		'billing_phone' => '',
		'shipping_country' => '',
		'shipping_phone' => ''
);

// Format Parameters
if(is_array($transaction_parameters)){
	$formatted_parameters = http_build_query(array_merge($parameters, $transaction_parameters));
} else {
	$formatted_parameters = http_build_query($parameters);
}

// Create API URL
$url = sprintf(
	'https://www.ipqualityscore.com/api/json/ip/%s/%s?%s', 
	$key,
	$ip, 
	$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.
	
	/*
	*- Phone Reputation Scoring Example 1: We'd like to block users with an invalid phone number or high risk phone number that was recently associated with an abusive account
	* 
	* if($result['transaction_details']['valid_billing_phone'] === false || $result['transaction_details']['valid_shipping_phone'] === false || $result['transaction_details']['risky_billing_phone'] === true || $result['transaction_details']['risky_shipping_phone'] === true){
	*		exit(header("Location: https://www.ipqualityscore.com/disable-your-proxy-vpn-connection"));
	* }
	*/
	
	/*
	*- Phone Reputation Scoring Example 2: We'd like to block users with any occurrence of high risk behavior or an overall Fraud Score >= 90
	* 
	* if($result['fraud_score'] >= 90 || $result['transaction_details']['fraudulent_behavior'] === true){
	*		exit(header("Location: https://www.ipqualityscore.com/disable-your-proxy-vpn-connection"));
	* }
	*/
	
	/*
	*- Phone Reputation Scoring Example 3: We'd like to block users with an overall Fraud Score >= 90, users with VPN connections, or users with an invalid or abusive phone number
	* 
	* if($result['fraud_score'] >= 90 || $result['vpn'] === true || $result['transaction_details']['valid_billing_phone'] === false || $result['transaction_details']['valid_shipping_phone'] === false || $result['transaction_details']['risky_billing_phone'] === true || $result['transaction_details']['risky_shipping_phone'] === true){
	*		exit(header("Location: https://www.ipqualityscore.com/disable-your-proxy-vpn-connection"));
	* }
	*/

	/*
	* 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.
	*/
}

xxxxxxxxxx
 
// Your API Key.
$key = 'YOUR_API_KEY_HERE';
​
/*
* Retrieve the user's IP address. 
* You could also pull this from another source such as a database.
* 
* If you use cloudflare change REMOTE_ADDR to HTTP_CF_CONNECTING_IP
*/
$ip = isset($_SERVER['REMOTE_ADDR']) ? $_SERVER['REMOTE_ADDR'] : $_SERVER['HTTP_CLIENT_IP'];
​
​
// Retrieve additional (optional) data points which help us enhance fraud scores.
$user_agent = $_SERVER['HTTP_USER_AGENT']; 
$user_language = $_SERVER['HTTP_ACCEPT_LANGUAGE'];
​
// Set the strictness for this query. (0 (least strict) - 3 (most strict))
$strictness = 0;
​
// You may want to allow public access points like coffee shops, schools, corporations, etc...
$allow_public_access_points = 'true';
​
// Create parameters array.
$parameters = array(
    'user_agent' => $user_agent,
    'user_language' => $user_language,
    'strictness' => $strictness,
    'allow_public_access_points' => $allow_public_access_points
);
​
/* User & Transaction Scoring
* Score additional information from a user, order, or transaction for risk analysis
* All transaction parameters are optional, please remove any that are not used
* Non paid actions such as lead generation and user scoring can be substituted into the "billing" or "shipping" variables
* This feature requires a Premium plan or greater
* Premium users can also adjust transaction scoring rules: https://www.ipqualityscore.com/user/transaction/weights
*/
​
// Optionally pass up to 2 phone numbers per user or transaction
// Countries are optional - 2 letter country code can be included if country code is not included in the phone number
    $transaction_parameters = array(
        'billing_country' => '',
        'billing_phone' => '',
        'shipping_country' => '',
        'shipping_phone' => ''
);
​
// Format Parameters
if(is_array($transaction_parameters)){
    $formatted_parameters = http_build_query(array_merge($parameters, $transaction_parameters));
} else {
    $formatted_parameters = http_build_query($parameters);
}
​
// Create API URL
$url = sprintf(
    'https://www.ipqualityscore.com/api/json/ip/%s/%s?%s', 
    $key,
    $ip, 
    $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.
    
    /*
    *- Phone Reputation Scoring Example 1: We'd like to block users with an invalid phone number or high risk phone number that was recently associated with an abusive account
    * 
    * if($result['transaction_details']['valid_billing_phone'] === false || $result['transaction_details']['valid_shipping_phone'] === false || $result['transaction_details']['risky_billing_phone'] === true || $result['transaction_details']['risky_shipping_phone'] === true){
    *       exit(header("Location: https://www.ipqualityscore.com/disable-your-proxy-vpn-connection"));
    * }
    */
    
    /*
    *- Phone Reputation Scoring Example 2: We'd like to block users with any occurrence of high risk behavior or an overall Fraud Score >= 90
    * 
    * if($result['fraud_score'] >= 90 || $result['transaction_details']['fraudulent_behavior'] === true){
    *       exit(header("Location: https://www.ipqualityscore.com/disable-your-proxy-vpn-connection"));
    * }
    */
    
    /*
    *- Phone Reputation Scoring Example 3: We'd like to block users with an overall Fraud Score >= 90, users with VPN connections, or users with an invalid or abusive phone number
    * 
    * if($result['fraud_score'] >= 90 || $result['vpn'] === true || $result['transaction_details']['valid_billing_phone'] === false || $result['transaction_details']['valid_shipping_phone'] === false || $result['transaction_details']['risky_billing_phone'] === true || $result['transaction_details']['risky_shipping_phone'] === true){
    *       exit(header("Location: https://www.ipqualityscore.com/disable-your-proxy-vpn-connection"));
    * }
    */
​
    /*
    * 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.
    */
}

# THIS SHOULD NEVER BE USED IN PRODUCTION AS IS!

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

import hashlib
from http.server import BaseHTTPRequestHandler, HTTPServer
import json
import requests

hostName = "localhost"
serverPort = 8080

class IPQS:
    key = "YOUR_API_KEY_HERE"
    def proxy_vpn_api(self, ip: str, vars: dict = {}) -> dict:
        """Method used to lookup Proxy & VPN Detection API 

        Args:
            ip (str): IPv4 or IPV6 to lookup.
            vars (dict, optional): Reffer to https://www.ipqualityscore.com/documentation/proxy-detection-api/address-validation for variables. Defaults to {}.

        Returns:
            dict: Returns json response in an array.
        """
        url = "https://www.ipqualityscore.com/api/json/ip/%s/%s" % (self.key, ip)
        if bool(vars):
            x = requests.get(url, params = vars)
        else:   
            x = requests.get(url)
        return (json.loads(x.text))


class MyServer(BaseHTTPRequestHandler):
    """This is an example basic web server. we limited it to handle "/" path only."""

    def do_GET(self):
        if self.path == "/":
            ipqs = IPQS()
            
            header_items= dict(self.headers.items())
            parameters = {
                'user_agent'                    : header_items['User-Agent'],
                'user_language'                 : header_items['Accept-Language'].split(',')[0],
                'strictness'                    : 0,
                'allow_public_access_points'    : 1,
                'lighter_penalties'             : 0
            }

            transaction_parameters = {
                'billing_country' : '',
                'billing_phone' : '',
                'shipping_country' : '',
                'shipping_phone' : '',
            }

            """
            User & Transaction Scoring
            Score additional information from a user, order, or transaction for risk analysis
            All transaction parameters are optional, please remove any that are not used
            Non paid actions such as lead generation and user scoring can be substituted into the "billing" or "shipping" variables
            This feature requires a Premium plan or greater
            Premium users can also adjust transaction scoring rules: https://www.ipqualityscore.com/user/transaction/weights
            


            Optionally pass up to 2 phone numbers per user or transaction
            Countries are optional - 2 letter country code can be included if country code is not included in the phone number
            
            transaction_parameters = {
                'billing_country' : '',
                'billing_phone' : '',
                'shipping_country' : '',
                'shipping_phone' : '',
            }
            """            
            result = ipqs.proxy_vpn_api(self.client_address[0],{**parameters, **transaction_parameters})

            if 'success' in result and result['success'] == True:
                """
                # Phone Reputation Scoring Example 1: We'd like to block users with an invalid phone number or high risk phone number that was recently associated with an abusive account
                
                if $result['transaction_details']['valid_billing_phone'] == False || $result['transaction_details']['valid_shipping_phone'] == False || $result['transaction_details']['risky_billing_phone'] == True || $result['transaction_details']['risky_shipping_phone'] == True:
                    self.send_response(303)
                    self.send_header('Content-type', 'text/html')
                    self.send_header('Location','https://www.ipqualityscore.com/disable-your-proxy-vpn-connection')
                    self.end_headers()
                    return
                """
                
                """
                # Phone Reputation Scoring Example 2: We'd like to block users with any occurrence of high risk behavior or an overall Fraud Score >= 90
                
                if $result['fraud_score'] >= 90 || $result['transaction_details']['fraudulent_behavior'] == True:
                    self.send_response(303)
                    self.send_header('Content-type', 'text/html')
                    self.send_header('Location','https://www.ipqualityscore.com/disable-your-proxy-vpn-connection')
                    self.end_headers()
                    return
                """
                
                """
                # Phone Reputation Scoring Example 3: We'd like to block users with an overall Fraud Score >= 90, users with VPN connections, or users with an invalid or abusive phone number
                
                if $result['fraud_score'] >= 90 || $result['vpn'] == True || $result['transaction_details']['valid_billing_phone'] == False || $result['transaction_details']['valid_shipping_phone'] == False || $result['transaction_details']['risky_billing_phone'] == True || $result['transaction_details']['risky_shipping_phone'] == True:
                    self.send_response(303)
                    self.send_header('Content-type', 'text/html')
                    self.send_header('Location','https://www.ipqualityscore.com/disable-your-proxy-vpn-connection')
                    self.end_headers()
                    return
                }
                """

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



            self.send_response(200)
            self.send_header("Content-type", "text/html")
            self.end_headers()

if __name__ == "__main__":        
    webServer = HTTPServer((hostName, serverPort), MyServer)
    print("Server started http://%s:%s" % (hostName, serverPort))

    try:
        webServer.serve_forever()
    except KeyboardInterrupt:
        pass

    webServer.server_close()
    print("Server stopped.")

xxxxxxxxxx
 
# THIS SHOULD NEVER BE USED IN PRODUCTION AS IS!
​
# You may need to install Requests pip
# python -m pip install requests
​
import hashlib
from http.server import BaseHTTPRequestHandler, HTTPServer
import json
import requests
​
hostName = "localhost"
serverPort = 8080
​
class IPQS:
    key = "YOUR_API_KEY_HERE"
    def proxy_vpn_api(self, ip: str, vars: dict = {}) -> dict:
        """Method used to lookup Proxy & VPN Detection API 
​
        Args:
            ip (str): IPv4 or IPV6 to lookup.
            vars (dict, optional): Reffer to https://www.ipqualityscore.com/documentation/proxy-detection-api/address-validation for variables. Defaults to {}.
​
        Returns:
            dict: Returns json response in an array.
        """
        url = "https://www.ipqualityscore.com/api/json/ip/%s/%s" % (self.key, ip)
        if bool(vars):
            x = requests.get(url, params = vars)
        else:   
            x = requests.get(url)
        return (json.loads(x.text))
​
​
class MyServer(BaseHTTPRequestHandler):
    """This is an example basic web server. we limited it to handle "/" path only."""
​
    def do_GET(self):
        if self.path == "/":
            ipqs = IPQS()
            
            header_items= dict(self.headers.items())
            parameters = {
                'user_agent'                    : header_items['User-Agent'],
                'user_language'                 : header_items['Accept-Language'].split(',')[0],
                'strictness'                    : 0,
                'allow_public_access_points'    : 1,
                'lighter_penalties'             : 0
            }
​
            transaction_parameters = {
                'billing_country' : '',
                'billing_phone' : '',
                'shipping_country' : '',
                'shipping_phone' : '',
            }
​
            """
            User & Transaction Scoring
            Score additional information from a user, order, or transaction for risk analysis
            All transaction parameters are optional, please remove any that are not used
            Non paid actions such as lead generation and user scoring can be substituted into the "billing" or "shipping" variables
            This feature requires a Premium plan or greater
            Premium users can also adjust transaction scoring rules: https://www.ipqualityscore.com/user/transaction/weights
            
​
​
            Optionally pass up to 2 phone numbers per user or transaction
            Countries are optional - 2 letter country code can be included if country code is not included in the phone number
            
            transaction_parameters = {
                'billing_country' : '',
                'billing_phone' : '',
                'shipping_country' : '',
                'shipping_phone' : '',
            }
            """            
            result = ipqs.proxy_vpn_api(self.client_address[0],{**parameters, **transaction_parameters})
​
            if 'success' in result and result['success'] == True:
                """
                # Phone Reputation Scoring Example 1: We'd like to block users with an invalid phone number or high risk phone number that was recently associated with an abusive account
                
                if $result['transaction_details']['valid_billing_phone'] == False || $result['transaction_details']['valid_shipping_phone'] == False || $result['transaction_details']['risky_billing_phone'] == True || $result['transaction_details']['risky_shipping_phone'] == True:
                    self.send_response(303)
                    self.send_header('Content-type', 'text/html')
                    self.send_header('Location','https://www.ipqualityscore.com/disable-your-proxy-vpn-connection')
                    self.end_headers()
                    return
                """
                
                """
                # Phone Reputation Scoring Example 2: We'd like to block users with any occurrence of high risk behavior or an overall Fraud Score >= 90
                
                if $result['fraud_score'] >= 90 || $result['transaction_details']['fraudulent_behavior'] == True:
                    self.send_response(303)
                    self.send_header('Content-type', 'text/html')
                    self.send_header('Location','https://www.ipqualityscore.com/disable-your-proxy-vpn-connection')
                    self.end_headers()
                    return
                """
                
                """
                # Phone Reputation Scoring Example 3: We'd like to block users with an overall Fraud Score >= 90, users with VPN connections, or users with an invalid or abusive phone number
                
                if $result['fraud_score'] >= 90 || $result['vpn'] == True || $result['transaction_details']['valid_billing_phone'] == False || $result['transaction_details']['valid_shipping_phone'] == False || $result['transaction_details']['risky_billing_phone'] == True || $result['transaction_details']['risky_shipping_phone'] == True:
                    self.send_response(303)
                    self.send_header('Content-type', 'text/html')
                    self.send_header('Location','https://www.ipqualityscore.com/disable-your-proxy-vpn-connection')
                    self.end_headers()
                    return
                }
                """
​
                """
                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.
                """
​
​
​
            self.send_response(200)
            self.send_header("Content-type", "text/html")
            self.end_headers()
​
if __name__ == "__main__":        
    webServer = HTTPServer((hostName, serverPort), MyServer)
    print("Server started http://%s:%s" % (hostName, serverPort))
​
    try:
        webServer.serve_forever()
    except KeyboardInterrupt:
        pass
​
    webServer.server_close()
    print("Server stopped.")

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