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

Instructions for using the Proxy & VPN Detection API can be found below.

What is Proxy Detection?

Fraudsters have become more sophisticated within the past few years, using proxy and VPN connections to commit fraud online. The only way for companies to adequately protect themselves against modern fraud tactics is by using an advanced proxy detection service, which includes a VPN detection API that can identify malicious IP addresses so suspicious users and payments can be accurately determined.

What is a Proxy Detection API?

Proxy detection APIs provide websites and apps with a real-time IP address lookup to detect proxies, VPNs, & TOR connections. Enrich any IP address with risk data to better identify malicious IP addresses, anonymous IPs, residential proxies, and botnets. The IP address API also provides geo-location, connection type, & ISP data.

When to Use a Proxy Detection API

Using a proxy detection API is a best practice for detecting fraud and analyzing risk for account registration, transactions, clicks, and similar user actions. The API's real-time results can enrich user accounts for any platform to improve fraud detection techniques. Since the system supports live lookups, you can deploy the API for an on-demand lookup upon any user action, like submitting a form.

Proxy Detection API Use Cases

Low-Quality Users: Identify duplicate user accounts, fake user information, and fraudulent registrations.
Chargebacks & Payment Fraud: Prevent chargebacks, high-risk transactions, and all types of e-commerce fraud.
Click Fraud & Invalid Clicks: Solve click fraud quality issues with real-time click filtering and ensure only high-quality clicks. Stop all forms of invalid traffic.
IP Reputation: Analyze IP Address reputation to detect proxies, VPNs, and TOR connections and determine the probability of fraudulent activity.
Account Takeover: Monitor accounts for unusual behavior and session hijacking attempts.
Bot Detection: Filter non-human traffic in real-time with IPQS bot detection tools.
Geo Filtering: Prevent users from bypassing requirements and conditions for accessing content outside their country of residence.
High-Risk Behavior: Analyze user behavior against millions of high-risk patterns that indicate a user's intent to engage in fraudulent activity.
Lead Generation & User Data Verification: Ensure the data you are collecting is valid, accurate, and fresh.

Access the Best Reputation & Validation Data

IPQS cultivates the most accurate and up-to-date data for IP intelligence and reputation scoring. Unlike other providers, IPQS gathers data directly from our proprietary honeypots, traps, crawlers, and thousands of live sites opted into our threat intelligence network. False positives are minimized by only using fresh data and scanning billions of IP addresses every day. New threats are detected every second, so even the latest compromised IP addresses cannot harm your business.

Follow the instructions below to use the Proxy & VPN Detection API.

Using the API

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

https://ipqualityscore.com/api/json/ip/YOUR_API_KEY_HERE/USER_IP_HERE

XML

https://ipqualityscore.com/api/xml/ip/YOUR_API_KEY_HERE/USER_IP_HERE

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 allow_public_access_points request parameter sets whether the API should bypass 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.

https://ipqualityscore.com/api/json/ip/YOUR_API_KEY_HERE/192.0.2.110?strictness=1&allow_public_access_points=true

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.

https://ipqualityscore.com/api/json/ip/YOUR_API_KEY_HERE/192.0.2.110?strictness=1&user_agent=Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/126.0.0.0 Safari/537.36&user_language=en-US;

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.

https://ipqualityscore.com/api/json/ip/YOUR_API_KEY_HERE/192.0.2.110?strictness=1&userID=555&transactionID=234499

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

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