<< Back to Categories

Getting Started

About the Proxy & VPN Detection API

The IPQS proxy detection technology provides accuracy rates for identifying sophisticated abuse, such as:

Residential proxies
Private VPN networks
Tor nodes
Anonymous proxies
Botnets
Malicious IP addresses or risky IP ranges abused by bots

The Proxy Detection API can prevent advanced fraudsters such as chargebacks, fake account registrations, account takeover (ATO) attacks, and similar abuse.

You can try out IPQS proxy and VPN detection right now using our free tool.

API Request URLs

You can use the following URLs to submit IP addresses to the Proxy Detection API. Replace "USER_IP_HERE" with the IP address to analyze.

JSON

XML

Example Requests

Strictness Set to 1 and Public Access Points Allowed

The strictness request parameter defines how in depth (strict) the query should be. Higher values take longer to process and may provide a higher false-positive rate. For the most accurate results with the least number of false-positives, use a strictness of 0 or 1.

The puclic_access_pair request parameter sets whether the API should bypasses certain checks for IP addresses from research institutions, schools, and some corporations. By setting this request parameter to true, you can better accommodate audiences that frequently use public connections.

Strictness Set to 1, a Specified User Agent, and a Specified User Language

You can include the User Agent (user_agent) and User Language (user_language) to significantly improves the accuracy of fraud scoring.

Strictness Set to 1 and Custom Tracking Variables of “userID” and “transactionID”

You can attach tracking data to API requests to associate lookups with specific users, transactions, and more. Only use variables set in your Custom Tracking Variables.

Example 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":"Success.",
	"success":true,
	"proxy":false,
	"ISP":"Mediacom Cable",
	"organization":"Mediacom Cable",
	"ASN":30036,
	"host":"192-0-2-110.client.mchsi.com",
	"country_code":"US",
	"city":"Houston",
	"region":"Texas",
	"is_crawler":false,
	"connection_type":"Residential",
	"latitude":29.7079,
	"longitude":-95.401,
	"zip_code":"77001",
	"timezone":"America Matamoros",
	"vpn":false,
	"tor":false,
	"active_vpn":false,
	"active_tor":false,
	"recent_abuse":true,
	"frequent_abuser":false,
	"high_risk_attacks":false,
	"abuse_velocity":"medium",
	"bot_status":false,
	"shared_connection":true,
	"dynamic_connection":false,
	"security_scanner":false,
	"trusted_network":false,
	"mobile":false,
	"fraud_score":25,
	"operating_system": "Mac 10.6",
	"browser": "Chrome 122.0",
	"device_model": "iPad",
	"device_brand": "Apple",
	"transaction_details":{
		"valid_billing_address":false,
		"valid_shipping_address":false,
		"valid_billing_email":false,
		"valid_shipping_email":false,
		"risky_billing_phone":false,
		"risky_shipping_phone":false,
		"billing_phone_carrier":"AT&T",
		"shipping_phone_carrier	":"Rogers Canada",
		"billing_phone_line_type":"Wireless",
		"shipping_phone_line_type":"Landline",
		"billing_phone_country":"US",
		"billing_phone_country_code":"1",
		"shipping_phone_country":"US",
		"shipping_phone_country_code":"1",
		"fraudulent_behavior":false,
		"bin_country":"US",
		"bin_type":"Credit",
		"bin_bank_name":"CITIBANK N.A.",
		"risk_score":17,
		"risk_factors":["Billing phone number is inactive.", "Billing email is associated with recent chargebacks."],
		"is_prepaid_card":false,
		"risky_username":false,
		"valid_billing_phone":true,
		"valid_shipping_phone":false,
		"leaked_billing_email":true,
		"leaked_shipping_email":false,
		"leaked_user_data":true,
		"user_activity":"high",
		"phone_name_identity_match":"Match",
		"phone_email_identity_match":"Mismatch",
		"phone_address_identity_match":"No Match",
		"email_name_identity_match":"Unknown",
		"name_address_identity_match":"Match",
		"address_email_identity_match":"Match"
	},
	"request_id":"0w8WYS"
}

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

<?xml version="1.0" encoding="UTF-8"?>
<result>
	 <proxy>false</proxy>
	 <ISP>Mediacom Cable</ISP>
	 <organization>Mediacom Cable</organization>
	 <ASN>30036</ASN>
	 <host>192-0-2-110.client.mchsi.com</host>
	 <country_code>US</country_code>
	 <city>Houston</city>
	 <region>Texas</region>
	 <is_crawler>false</is_crawler>
	 <connection_type>residential</connection_type>
	 <latitude>29.7079</latitude>
	 <longitude>-95.401</longitude>
	 <zip_code>77001</zip_code>
	 <timezone>America Matamoros</timezone>               
	 <vpn>false</vpn>
	 <tor>false</tor>
	 <active_vpn>false</active_vpn>
	 <active_tor>false</active_tor>
	 <recent_abuse>false</recent_abuse>
	 <abuse_velocity>medium</abuse_velocity>
	 <bot_status>false</bot_status>
	 <mobile>false</mobile>
	 <fraud_score>25</fraud_score>
	 <frequent_abuser>false</frequent_abuser>
	 <high_risk_attacks>false</high_risk_attacks>
	 <shared_connection>true</shared_connection>
	 <dynamic_connection>false</dynamic_connection>
	 <security_scanner>false</security_scanner>
	 <trusted_network>false</trusted_network>
	 <operating_system>Mac 10.6</operating_system>
	 <browser>Chrome 122.0</browser>
	 <request_id>0w8WYS</request_id>
	 <device_model>iPad</device_model>
	 <device_brand>Apple</device_brand>          
	 <message>Success</message>
	 <success>true</success>
</result>

Error Responses

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

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

{
	"success":false,
	"message":"Invalid IPv4 address, IPv6 address or hostname. Please check the IP\/Hostname and try again.",
	"request_id":"4OTORR4EWpl0m"
}

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 CheckUserIP(ip_address, user_agent, language) {
	var key = 'YOUR_API_KEY_HERE';
	var strictness = 1; // This optional parameter controls the level of strictness for the lookup. Setting this option higher will increase the chance for false-positives as well as the time needed to perform the IP analysis. Increase this setting if you still continue to see fraudulent IPs with our base setting (level 1 is recommended) or decrease this setting for faster lookups with less false-positives. Current options for this parameter are 0 (fastest), 1 (recommended), 2 (more strict), or 3 (strictest).
	var allow_public_access_points = 'true'; // Bypasses certain checks for IP addresses from education and research institutions, schools, and some corporate connections to better accommodate audiences that frequently use public connections. This value can be set to true to make the service less strict while still catching the riskiest connections.
	var url = "https://www.ipqualityscore.com/api/json/ip/" + key + "/" + ip_address + "?user_agent=" + user_agent + "&user_language=" + language + "&strictness=" + strictness + "&allow_public_access_points=" + allow_public_access_points;
	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 ValidIP(ip_address, user_agent, language) {
	var allowCrawlers = true; // Allow verified search engine crawlers from Google, Bing, Yahoo, DuckDuckGo, Baidu, Yandex, and similar major search engines. This setting is useful for preventing SEO penalties on front end placements.
	var fraudScoreMinBlock = 75; // Minimum Fraud Score to determine a fraudulent or high risk user
	var fraudScoreMinBlockForMobiles = 75; // Minimum Fraud Score to determine a fraudulent or high risk user for MOBILE Devices
	var lowerPenaltyForMobiles = false; // Prevents false positives for mobile devices - if set to true, this will only block VPN connections, Tor connections, and Fraud Scores greater than the minimum values set above for mobile devices. This setting is meant to provide greater accuracy for mobile devices due to mobile carriers frequently recycling and sharing mobile IP addresses. Please be sure to pass the "user_agent" (browser) for this feature to work. This setting ensures that the riskiest mobile connections are still blacklisted.
	
	var ip_result = CheckUserIP(ip_address, user_agent, language);
	
	if (ip_result !== null) {
		if (allowCrawlers === true) {
			if (typeof ip_result !== 'undefined' && ip_result['is_crawler'] === true) {
				return false;
			}
		}
		if (ip_result['mobile'] === true && lowerPenaltyForMobiles === true) {
			if (typeof ip_result['fraud_score'] !== 'undefined' && ip_result['fraud_score'] >= fraudScoreMinBlockForMobiles) {
				return true;
			}
			else if (typeof ip_result['vpn'] !== 'undefined' && ip_result['vpn'] === true) {
				return ip_result['vpn'];
			}
			else if (typeof ip_result['tor'] !== 'undefined' && ip_result['tor'] === true) {
				return ip_result['tor'];
			}
			else {
				return false;
			}	
		}
		else {
			if (typeof ip_result['fraud_score'] !== 'undefined' &&  ip_result['fraud_score'] >= fraudScoreMinBlock) {
				return true;
			}
			else if (typeof ip_result['proxy'] !== 'undefined'){
				return ip_result['proxy'];
			}
			else {
				// Throw error, response is invalid.
			}
		}
	}
	else {
	    return false;
	}
}


app.enable('trust proxy'); // Allows Accurate Usage of req.ip


app.get('/', (req, res) => {
	var ip_address = req.ip;
	var user_agent = req.headers['user-agent'];
	var language = req.headers['accept-language'];
	console.log(ip_address + ":: " + user_agent + " :: " + language);
	if (ValidIP(ip_address, user_agent, language) === true) {
		return res.send(new Output(true, 'Proxy, VPN, or Risky User'));
	}
	else {
		return res.send(new Output(true, 'Clean IP/User'));
	}
});


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

// 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.
* 
*/
$ip = isset($_SERVER['HTTP_CF_CONNECTING_IP']) ? $_SERVER['HTTP_CF_CONNECTING_IP'] : $_SERVER['REMOTE_ADDR'];


// 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 = 1;

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

// Reduce scoring penalties for mixed quality IP addresses shared by good and bad users.
$lighter_penalties = 'false';

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

/* 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/proxy-detection-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/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.

	/*
	*- Example 1: We'd like to block all proxies and send them to Google.
	* 
	* if($result['proxy'] === true){
	*		exit(header("Location: https://www.ipqualityscore.com/disable-your-proxy-vpn-connection"));
	* }
	*/
	
	/*
	*- Example 2: We'd like to block all proxies, but allow legitimate
	*- crawlers like Google on our site:
	*
	* if($result['proxy'] === true && $result['is_crawler'] === false){
	*		exit(header("Location: https://www.ipqualityscore.com/disable-your-proxy-vpn-connection"));
	* }
	*/

	/*
	*- Example 3: We'd like to block only visitors with a fraud score, 
	*- over 80, but allow crawlers such as Google:
	* 
	* if($result['fraud_score'] >= 80 && $result['is_crawler'] === false){
	*		exit(header("Location: https://www.ipqualityscore.com/disable-your-proxy-vpn-connection"));
	* }
	*/

	/*
	*- Example 4: We'd like to block only visitors which are a proxy with a 
	*- fraud score over 80, but allow crawlers such as Google:
	* 
	* if(
	* 	$result['proxy'] === true && 
	* 	$result['fraud_score'] >= 80 && 
	*		$result['is_crawler'] === false
	*	){
	*		exit(header("Location: https://www.ipqualityscore.com/disable-your-proxy-vpn-connection"));
	* }
	*/
	
	/*
	*- Example 5: We'd like to block only visitors which are using tor.
	* 
	* if($result['tor'] === 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 payment_transaction_fraud_prev(self, ip: str, vars: dict = {}) -> dict:
        """Method used to lookup Payment & Transaction Fraud Prevention API 

        Args:
            ip (str): _description_
            vars (dict, optional): Reffer to https://www.ipqualityscore.com/documentation/proxy-detection-api/transaction-scoring for variables.. Defaults to {}.

        Returns:
            dict: _description_
        """
        if not bool(vars):
            return {}

        url = "https://www.ipqualityscore.com/api/json/ip/%s/%s" %(self.key, ip)
        x = requests.get(url, params = vars)
        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,
                # You may want to allow public access points like coffee shops, schools, corporations, etc...
                'allow_public_access_points'    : 'true',
                # Reduce scoring penalties for mixed quality IP addresses shared by good and bad users.
                'lighter_penalties'             : 'false'
            }


         
            result = ipqs.payment_transaction_fraud_prev(self.client_address[0],parameters)

            if 'success' in result and 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 proxies and send them to Google.
                """

                if result['proxy'] == 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
                
                """
                Example 2: We'd like to block all proxies, but allow legitimate
                crawlers like Google on our site:
                
                if result['proxy'] == True and result['is_crawler'] == False:
                	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
                """
                
                """
                Example 3: We'd like to block only visitors with a fraud score,
                of 80 or over, but allow crawlers such as Google:
                
                if result['fraud_score'] >= 80 and result['is_crawler'] == False:
                	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
                """
                
                """
                Example 4: We'd like to block only visitors which are a proxy with a
                fraud score of 80 and over, but allow crawlers such as Google:

                if result['proxy'] == True and result['tor'] == True or result['fraud_score'] >= 80 or result['is_crawler'] == False:
                	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
                """

                """
                Example 5: We'd like to block only visitors which are using tor.
                
                if result['tor'] == 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(500)
            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