IPQualityScore

Proxy Detection API Docs | VPN Detection API

Leading IP Intelligence API, Best Detection Rates

IPQualityScore's Proxy Detection API allows you to Proactively Prevent Fraud™ via a simple API that provides over 25 data points for risk analysis, geo location, and IP intelligence. This endpoint allows on-demand lookups using our IP reputation API to accurately identify threats, bots, and compromised connections including VPN detection.

Accurate Proxy Detection

IPQualityScore's proxy detection technology features the most robust accuracy rates for identifying sophisticated abuse, such as residential proxies, private VPN networks, tor nodes, anonymous proxies, botnets, and similar 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), and similar abuse.

Proxy Detection API & Fraud Prevention Use Cases
  • Low Quality Users — Identify duplicate user accounts, bogus user information, and fake registrations. Automatically prevent low quality users from hurting your ROI.
  • Chargebacks & Payment Fraud — Prevent chargebacks, high risk transactions, and all types of ecommerce 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 likeliness 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 data that you are collecting is valid, accurate, and fresh.

Proxy Detection API Accuracy & Machine Learning

Your account's multi-tiered machine learning algorithms will continuously learn from your audience to minimize false-positives and provide the greatest accuracy for Proxy Detection API lookups. If you do notice any results which you feel are inaccurate, please forward them to our support team so we can optimize your account's settings for the IP fraud risk API. Numerous options are available on a per-account level so IPQS fraud scoring algorithms can be perfectly tailored to your audience.

Proxy Detection API Coverage

Our proxy detection algorithms allow your website or app to perform on-demand IP address lookups that identify malicious traffic and detect anonymous proxies, residential proxies, tor exit nodes, data centers, hosting providers, virtual private networks, and other types of fraudulent IPs. Detect proxies and industry leading IP reputation. This application programming interface (API) also provides full support as a VPN Detection API to identify VPN providers for any IP address.

Note About Front End IP Lookups

Results produced from our front end IP address lookup tool uses the Proxy Detection API settings below. To match the front end proxy detection results, please configure your API request to use these settings. Since these settings score IP address with the lowest possible strictness levels, you may experience better performance with different values for these options.

  • allow_public_access_points=true — Allows corporate and public connections like Institutions, Hotels, Businesses, Universities, etc.
  • mobile=true — Forces the IP to be scored as a mobile device. Passing the "user_agent" will automatically detect the device type.
  • fast=true — Speeds up the API response time. Not recommended.
  • strictness=0 — Uses the lowest strictness (0-3) for Fraud Scoring. Increasing this value will expand the tests we perform. Levels 2+ have a higher risk of false-positives. We recommend using level 0 or 1 for the best results.
  • lighter_penalties=true — Lowers scoring and proxy detection for mixed quality IP addresses to prevent false-positives.
Proxy Detection API Example Look — Lowest Strictness Lookup Settings
This API request will match our front end IP lookup results with the settings above, providing the most suppressed Fraud Scores to avoid false-positives.

Private Key
Please login or create a free account to access your API Key.

NOTE: Do not share this key with anyone. It's like a password and can be used to make queries using our API.

Request URLs

The URLs below can be used to fetch the result using cURL or another utility in most languages. Please see the usage example at the bottom of the page. Simply replace "USER_IP_HERE" with the IP address you wish to analyze.

JSON:
XML:

JSON Example Requests
API Lookup with Strictness Set to 1 and Public Access Points as True
0 or 1 are our recommended levels of strictness for the most accurate results with the least false-positives. Strictness can be a value between 0 and 3.
API Lookup with Strictness Set to 1 & User Agent (Browser) / User Language for Enhanced Fraud Scoring
Including the User Agent and User Language significantly improves our accuracy for Fraud Scoring and identifying risky IP addresses.
API Lookup with Strictness Set to 1 & Custom Tracking Variables of "userID" and "transactionID"
Tracking data can be attached to your API request to associate lookups with a specific user, transaction, etc. Please only use variables set on your Custom Tracking Variables.
API Lookup with Strictness Set to 2 & Fast Mode Set to "true"
This setting is used for time-sensitive lookups that require a faster response time. Accuracy is slightly degraded with the "fast" approach, but not significantly noticeable.

Proxy Detection API JSON Success Response Example

NOTE: For a description of each field listed above please consult the response documentation below.


Proxy Detection API XML Success Response Example

NOTE: For a description of each field listed above please consult the response documentation below.


JSON Error Response Examples

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


Additional Request Options

Due to the nature of platform requirements or frameworks it may be necessary to request IPQS API endpoints without passing the API key in the URL. As an alternative, IPQS allows the API key to be passed via GET, POST, or Headers. These requests use the following endpoints:

JSON:
XML:
Method Value Example
GET key ?key=YOUR_API_KEY_HERE&ip=35.215.153.139&strictness=2&fast=1
POST key key=YOUR_API_KEY_HERE&ip=35.215.153.139&strictness=2&fast=1
Header IPQS-KEY (Additional parameters passed as either GET or POST) IPQS-KEY: YOUR_API_KEY_HERE

Additional Request Parameters

Custom tracking variables (such as "userID", "transactionID") established in your account settings can be passed with each API request. This allows our reporting tools to filter by specific users, products, campaigns, transactions, etc. so that you can easily match up records with your own system to identify fraudulent activity. It is strongly recommended to pass the "user_agent" (browser) and "user_language" to provide the most accurate "fraud_score" results. Our algorithms automatically adjust scoring based on the device type, so if you are unable to pass the user agent, please inform our system of mobile devices by passing "mobile" as true. It is also recommended to set "allow_public_access_points" as true to avoid false-positives with corporate ranges and public hotspots.

Field Description Possible Values
strictness How in depth (strict) do you want this query to be? Higher values take longer to process and may provide a higher false-positive rate. We recommend starting at "0", the lowest strictness setting, and increasing to "1" depending on your levels of fraud. Levels 2+ are VERY strict and will produce false-positives. integer, 0 - 3
user_agent You can optionally provide us with the user agent string (browser). This allows us to run additional checks to see if the user is a bot or running an invalid browser. This allows us to evaluate the risk of the user as judged in the "fraud_score". string
user_language You can optionally provide us with the user's language header. This allows us to evaluate the risk of the user as judged in the "fraud_score". string
fast When this parameter is enabled our API will not perform certain forensic checks that take longer to process. Enabling this feature greatly increases the API speed without much impact on accuracy. This option is intended for services that require decision making in a time sensitive manner and can be used for any strictness level. boolean, string (true or false)
mobile You can optionally specify that this lookup should be treated as a mobile device. Recommended for mobile lookups that do not have a user agent attached to the request. NOTE: This can cause unexpected and abnormal results if the device is not a mobile device. boolean, string (true or false)
allow_public_access_points 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. boolean, string (true or false)
lighter_penalties Is your scoring too strict? Enable this setting to lower detection rates and Fraud Scores for mixed quality IP addresses. If you experience any false-positives with your traffic then enabling this feature will provide better results. boolean, string (true or false)
transaction_strictness Adjusts the weights for penalties applied due to irregularities and fraudulent patterns detected on order and transaction details that can be optionally provided on each API request. This feature is only beneficial if you are passing order and transaction details. A table is available further down the page with supported transaction variables. integer, 0 - 2

Reporting Back Fraud & Improving Machine Learning

Train your account's machine learning algorithms to better identify fraud for your audience. This data will improve future scoring of IP address reputation through the Proxy Detection API. The following endpoint can be used to report IP addresses as fraudulent. Please only report data that has a high confidence of being abusive.

The URL below is an example of how to report an IP address.

Proxy Detection API Response Field Definitions
Quick Notes

Fraud Scores >= 75 — suspicious — previous reputation issues or low risk proxy/VPN.
Fraud Scores >= 88 or 90 — high risk — recent abusive behavior over the past 24-48 hours.
"Abuse Velocity" = "high" — indicates frequent abusive behavior over the past 24-48 hours.
"Frequent Abuser" = "true" — confirms a history of abusive behavior over the past 6 months or more.
"High Risk Attacks" = "true" — identifies open proxies and anonymous IPs engaged in online attacks like scraping, ATO, brute forcing, bot submissions.

Transaction Scoring — When transaction data is passed with the API request for payments or users, the "Risk Score" will be populated. Risk Scores >= 75 — suspicious — unusual behavior or dubious user data.
Fraud Scores >= 90 — high risk — recent reputation issues like abuse associated with a name, email, phone number, payment method, etc.

Fraud Scores
Further Details on Response Results

Analyzing the overall Fraud Score is usually the best way to determine the overall risk of the user. Fraud Scores >= 75 are suspicious and likely to be a proxy, VPN, or TOR connection, but not necessarily a fraudulent user. This could indicate a user protecting their privacy online by browsing anonymously with a proxy connection or VPN service. Fraud Scores >=88 or 90 are high risk users that are likely to engage in malicious behavior. Scores in this threshold indicate recent or excessive abuse and fit the profile of a typical risky user.

We recommend also using additional risk data points such as "bot_status", "frequent_abuser", "high_risk_attacks", "recent_abuse", and "abuse_velocity" in your decision making for further granularity. The "connection_type", "shared_connection", and "dynamic_connection" also play an important role in determining the best business logic for your audience.


Field Description Possible Values
proxy Is this IP address suspected to be a proxy? (SOCKS, Elite, Anonymous, VPN, Tor, etc.) boolean
host Hostname of the IP address if one is available. string
ISP ISP if one is known. Otherwise "N/A". string
Organization Organization if one is known. Can be parent company or sub company of the listed ISP. Otherwise "N/A". string
ASN Autonomous System Number if one is known. Null if nonexistent. integer
country_code Two character country code of IP address or "N/A" if unknown. string
city City of IP address if available or "N/A" if unknown. string
region Region (state) of IP address if available or "N/A" if unknown. string
timezone Timezone of IP address if available or "N/A" if unknown. string
latitude Latitude of IP address if available or null if unknown. float
longitude Longitude of IP address if available or null if unknown. float
zip_code Postal code of IP address if available or "N/A" if unknown. IP addresses can relate to multiple postal codes in a city, so we recommend performing analysis of similar postal codes nearby. string
is_crawler Is this IP associated with being a confirmed crawler from a mainstream search engine such as Googlebot, Bingbot, Yandex, etc. based on hostname or IP address verification. boolean
connection_type Classification of the IP address connection type as "Residential", "Corporate", "Education", "Mobile", or "Data Center". string
recent_abuse This value will indicate if there has been any recently verified abuse across our network for this IP address. Abuse could be a confirmed chargeback, account takeover attack, compromised device, fake application or registration, digital impersonation (stolen user data), bot attack, or similar malicious behavior within the past few days. boolean
abuse_velocity How frequently the IP address is engaging in abuse across the IPQS threat network. Values can be "high", "medium", "low", or "none". Can be used in combination with the Fraud Score to identify bad behavior. string
bot_status Indicates if bots or non-human traffic has recently used this IP address to engage in automated fraudulent behavior. Provides stronger confidence that the IP address is suspicious. boolean
vpn Is this IP suspected of being a VPN connection? This can include data center ranges which can become active VPNs at any time. The "proxy" status will always be true when this value is true. boolean
tor Is this IP suspected of being a TOR connection? This can include previously active TOR nodes and exits which can become active TOR exits at any time. The "proxy" status will always be true when this value is true. boolean
active_vpn Identifies active VPN connections used by popular VPN services and private VPN servers. boolean
active_tor Identifies active TOR exits on the TOR network. boolean
mobile Is this user agent a mobile browser? (will always be false if the user agent is not passed in the API request) boolean
fraud_score The overall fraud score of the user based on the IP, user agent, language, and any other optionally passed variables. Fraud Scores >= 75 are suspicious, but not necessarily fraudulent. We recommend flagging or blocking traffic with Fraud Scores >= 90, but you may find it beneficial to use a higher or lower threshold. float
frequent_abuser Enterprise Data Point — Identifies IP addresses with a consistent history of abusive behavior across 6 months or more. This data point can be helpful in identifying anonymous IP addresses which are frequently used for malicious behavior, compared to an IP address that may be briefly compromised by malware and only temporarily active in a botnet or residential proxy network. boolean
high_risk_attacks Enterprise Data Point — Confirms if this IP address has engaged in malicious abuse such as phishing, brute forcing, DDoS, credential stuffing & account takeover, scraping, form submission spam, and similar attacks. This data point has a high correlation with anonymous proxies, open proxies, public VPNs, and easily accessible anonymizers. boolean
shared_connection Enterprise Data Point — Designates IP addresses which are likely to have more than a few users active on the IP address at the same time, such as mobile networks, corporate exit points, and similar connections. This can also include libraries, coffee shops, hotel lobbies, dormitories, hospitals and medical centers, company VPNs, etc. boolean
dynamic_connection Enterprise Data Point — Indicates IP addresses with dynamic assignment protocols, which means that a user on this IP address will likely be assigned a different IP address by this provider in the near future. boolean
security_scanner Enterprise Data Point — Indicates a verified online security scanner or endpoint by a trusted security vendor such as Tenable, Qualys, and similar providers. boolean
trusted_network Enterprise Data Point — Identifies company networks and corporate access points which have low abuse rates and high security protocols. IP addresses on these networks may still be compromised by malware, however the network overall will be considered trusted if this value is true. boolean
request_id A unique identifier for this request that can be used to lookup the request details or send a postback conversion notice. string
operating_system Operating system name and version or "N/A" if unknown. Requires the "user_agent" variable in the API Request. string
browser Browser name and version or "N/A" if unknown. Requires the "user_agent" variable in the API Request. string
device_brand Brand name of the device or "N/A" if unknown. Requires the "user_agent" variable in the API Request. string
device_model Model name of the device or "N/A" if unknown. Requires the "user_agent" variable in the API Request. string
transaction_details (object) Additional scoring variables for risk analysis are available when transaction scoring data is passed through the API request. These variables are also useful for scoring user data such as physical addresses, phone numbers, usernames, and transaction details. The data points below are populated when at least 1 transaction data parameter is present in the initial API request. The following transaction variables are "null" when the necessary transaction parameters are not passed with the initial API request. For instance, not passing the "billing_email" will return "valid_billing_email" as null.
Key Expected Values Description
risk_score Float Confidence that this user or transaction is exhibiting malicious behavior. Scores are 0 - 100, with 75+ as suspicious and 90+ as high risk. This value uses different calculations with less weight on the IP reputation compared to the overall "Fraud Score".
risk_factors String Explanation for elevated Risk Scores to better understand why the payment or user was associated with fraudulent behavior and considered a high risk.
valid_billing_address Boolean Physical address validation and reputation analysis.
valid_shipping_address Boolean Same as above.
valid_billing_email Boolean Light abusive check and reputation analysis for the email address. It is recommended to use our dedicated Email Validation API for deeper analysis.
valid_shipping_email Boolean Same as above.
leaked_billing_email Boolean Indicates if the email address has recently been exposed or compromised in a database breach.
leaked_shipping_email Boolean Same as above.
leaked_user_data Boolean Indicates if the user's data (including phone & address) have recently been exposed or compromised in a database breach.
user_activity String Frequency at which this user makes legitimate purchases, account registrations, and engages in legitimate customer behavior online. Values can be "high", "medium", "low", or "none". Values of "high" or "medium" are strong signals of healthy usage. New user data without a history of legitimate behavior will have a value as "none". This field is restricted to higher plan tiers.
risky_billing_phone Boolean Reputation analysis for abusive activity associated with the phone number.
risky_shipping_phone Boolean Same as above.
valid_billing_phone Boolean Valid & active phone number with the phone carrier (not disconnected).
valid_shipping_phone Boolean Same as above.
billing_phone_carrier String Phone number provider company such as "AT&T" or "Bell Canada".
shipping_phone_carrier String Same as above.
billing_phone_line_type String Landline, Wireless, Toll Free, VOIP, Satellite, Premium Rate, Pager, Internet Service Provider or Unknown.
shipping_phone_line_type String Same as above.
billing_phone_country String 2-letter country code associated with the phone number.
shipping_phone_country String Same as above.
billing_phone_country_code Integer Country dialing code associated with the phone number.
shipping_phone_country_code Integer Same as above.
bin_country String Country associated with the credit card BIN.
bin_bank_name String The bank or processor name associated with the credit card BIN, such as Citibank, Chase, Capital One, etc.
bin_type String Type of card associated with the credit card BIN. Values can be "Credit", "Debit", "Prepaid", or "Virtual". Prepaid and Virtual credit cards carry slightly higher risk.
risky_username Boolean Username frequently associated with fraudulent behavior.
is_prepaid_card Boolean Status of the credit card as prepaid.
fraudulent_behavior Boolean Indicates high risk behavior patterns and a high chance of fraud.
phone_name_identity_match String Enterprise Account Feature — Indicates a reverse identity match between the billing phone number and first/last name. Values: "Unknown" — no checks processed, "Match" — positive identity match, "Mismatch" — data matches another user, "No Match" — could not pair identity data.
phone_email_identity_match String Enterprise Account Feature — Indicates a reverse identity match between the billing phone number and email address. Values: "Unknown" — no checks processed, "Match" — positive identity match, "Mismatch" — data matches another user, "No Match" — could not pair identity data.
phone_address_identity_match String Enterprise Account Feature — Indicates a reverse identity match between the billing phone number and physical address. Values: "Unknown" — no checks processed, "Match" — positive identity match, "Mismatch" — data matches another user, "No Match" — could not pair identity data.
email_name_identity_match String Enterprise Account Feature — Indicates a reverse identity match between the billing email address and first/last name. Values: "Unknown" — no checks processed, "Match" — positive identity match, "Mismatch" — data matches another user, "No Match" — could not pair identity data.
name_address_identity_match String Enterprise Account Feature — Indicates a reverse identity match between the billing first/last name and physical address. Values: "Unknown" — no checks processed, "Match" — positive identity match, "Mismatch" — data matches another user, "No Match" — could not pair identity data.
address_email_identity_match String Enterprise Account Feature — Indicates a reverse identity match between the billing physical address and email address. Values: "Unknown" — no checks processed, "Match" — positive identity match, "Mismatch" — data matches another user, "No Match" — could not pair identity data.
message A generic status message, either success or some form of an error notice. string
success Was the request successful? boolean
errors Array of errors which occurred while attempting to process this request. array of strings

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 an Proxy Detection API?

Using a proxy detection API is a best practice to detect fraud and analyze risk for account registration, transactions, clicks, and similar user actions. Real-time results provided by the IP address Application Programming Interface (API) can enrich user accounts for any platform to improve fraud detection techniques. Since the system supports live lookups, it can deployed for an on-demand lookup upon any user action like submitting a form.

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 including a VPN detection API that can identify malicious IP addresses so suspicious users and payments can be accurately identified.

Example Code