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.
Your account's multi-tiered machine learning algorithms will continuously learn from your audience to minimize false-positives and provide the greatest accuracy. 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. Numerous options and settings are available on a per-account level so IPQS fraud scoring algorithms can be perfectly tailored to your audience.
Results produced from our front end IP address lookup tool uses the Proxy Detection API settings below. To match the front end 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.
NOTE: Do not share this key with anyone. It's like a password and can be used to make queries using our API.
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.
NOTE: For a description of each field listed above please consult the response documentation below.
NOTE: For a description of each field listed above please consult the response documentation below.
Example errors that you may encounter when accessing our API due to an exhausted credit balance or an invalid IP address.
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:
|Header||IPQS-KEY (Additional parameters passed as either GET or POST)||IPQS-KEY: YOUR_API_KEY_HERE|
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.
|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" or "2" depending on your levels of fraud.||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|
Fraud Scores >= 75 - suspicious - previous reputation issues or low risk proxy/VPN.
Fraud Scores >= 85 - high risk - recent abusive behavior over the past 24-48 hours.
Abuse Velocity = "high" - indicates frequent abusive behavior over the past 24-48 hours.
Transaction Scoring - When transaction data is passed 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.
We return a large amount of information for each lookup so your development team can access a wealth of data when incorporating each API request into your business logic. 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. Fraud Scores >=85 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 blocking or flagging a user, transaction, or click as high risk using a combination of the "fraud_score", "abuse_velocity", "proxy", "vpn", "tor", and "recent_abuse" variables. As every user has their own unique audience, you may find better results only blocking results with Fraud Scores greater than 80-90+ or "abuse_velocity" as "high". Please note that due to mobile IP addresses being frequently abused and recycled by mobile carriers, we recommend weighing the "fraud_score", "vpn", & "tor" results more significantly than the "proxy" status for all lookups with a "mobile" result equal to true.
|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 "N/A" if unknown.||float|
|longitude||Longitude of IP address if available or "N/A" 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, compromised device, fake app install, or similar malicious behavior within the past few days.||boolean|
|abuse_velocity||Premium Account Feature - 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||Premium Account Feature - 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||Premium Account Feature - Identifies active VPN connections used by popular VPN services and private VPN servers.||boolean|
|active_tor||Premium Account Feature - 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 >= 85, but you may find it beneficial to use a higher or lower threshold.||float|
|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|
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.
|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|