- About the IPQS APIs
- Proxy & VPN Detection API
- Email Verification API
- Phone Number Validation API
- Malicious URL Scanner API
- Device Fingerprint API
- Mobile Device Fingerprinting SDK
- Gaming Fraud Detection SDK
- Dark Web Leak API
- Malware File Scanner API
- Request List API
- Fraud Reporting API
- Account Management APIs
- Bulk Validation CSV
- Allowlist Blocklist APIs
- Plugins Platforms Integrations
- IP Reputation Database
- IP Address Abuse Feed
- Email Verification Database
-
Custom Integrations
- Getting Started
- Authentication
- Refresh Secret
- IP & Proxy Checks
- Email Verification Checks
- Phone Number Validity Checks
- Device Tracker
- List Device Trackers
- Device Tracker Statistics
- Login Tokens
- Overview Statistics
- Recent Proxy Statistics
- Recent Email Statistics
- Fraud Reporting
- Retrieve Requests by ID
- Country List API Documentation
- Release Notes
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.
https://www.ipqualityscore.com/api/json/ip/YOUR_API_KEY_HERE/192.0.2.110?billing_phone=5555555555&billing_country=US
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 |
// 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.")