- 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
Response Parameters
Rate this article:
Select all that apply:
Email:
Field Definitions
Learn about the parameters returned by the Proxy & VPN Detection API. With clear definitions for every response value, you can fine tune your requests to better protect against fraud.
| Fraud Score | Risk | Description |
|---|---|---|
| < 75 | Suspicious | Has had previous reputation issues or is using a low risk proxy/VPN. |
| < 85 | High Risk | Has suspicious behavior signals. |
| < 90 | Frequent Abusive Behavior | Has demonstrated frequent abusive behavior over the past 24-72 hours. |
Consider results as high risk when fraud_score is at least 90.
Analyzing the overall Fraud Score is usually the best way to determine the user's overall risk. Fraud Scores >= 75 are suspicious and likely to be a proxy, VPN, or TOR connection, but not necessarily a fraudulent user. This could indicate that users are protecting their privacy online by browsing anonymously with a proxy connection or VPN service. Fraud Scores >= 90 are high-risk users 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_connectionvariables 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 |
| IP | The IP Address of the request. Displayed when using the Postback API to lookup a Request ID. | 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 any of the following search engines, based on hostname or IP address verification: Baidu, Google, Bing, Yahoo, Yandex, Sogou, Exabot, DuckDuckGo, Facebook, Twitter, Pinterest, Naver, UptimeRobot, AppleBot, ArchiveBot, CoccocBot, YisouBot, PetalBot, ByteDance, and MailRU. | 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. | |
| message | A generic status message, generally "success", but may contain other information 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 |
| abuse_events | Enterprise Data Point — An object containing abuse events and proxy networks recently associated with this IP address. |
transaction_details (object) fields
| Key | Description | Expected Values |
|---|---|---|
| risk_score | 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". | Float |
| risk_factors | Explanation for elevated Risk Scores to better understand why the payment or user was associated with fraudulent behavior and considered a high risk. | String |
| valid_billing_address | Physical address validation and reputation analysis. | Boolean |
| valid_shipping_address | Same as above. | Boolean |
| valid_billing_email | Light abusive check and reputation analysis for the email address. It is recommended to use our dedicated Email Verification API for deeper analysis. | Boolean |
| valid_shipping_email | Same as above. | Boolean |
| leaked_billing_email | Indicates if the email address has recently been exposed or compromised in a database breach. | Boolean |
| leaked_shipping_email | Same as above. | Boolean |
| leaked_user_data | Indicates if the user's data (including phone & address) have recently been exposed or compromised in a database breach. | Boolean |
| user_activity | 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. | String |
| 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 |
| bin_country | Country associated with the credit card BIN. | String |
| bin_bank_name | The bank or processor name associated with the credit card BIN, such as Citibank, Chase, Capital One, etc. | String |
| bin_type | 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. | String |
| risky_username | Username frequently associated with fraudulent behavior. | Boolean |
| is_prepaid_card | Status of the credit card as prepaid. | Boolean |
| fraudulent_behavior | Indicates high risk behavior patterns and a high chance of fraud. | Boolean |
| phone_name_identity_match | 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. | String |
| phone_email_identity_match | 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. | String |
| phone_address_identity_match | 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. | String |
| email_name_identity_match | 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. | String |
| name_address_identity_match | 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. | String |
| address_email_identity_match | 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. | String |
abuse_events fields
| Key | Description | Expected Values |
|---|---|---|
| name | The type of abuse event. | string Possible values: - Abusive Users - Account Takeover (ATO) - Bot Attacks - Brute Force Attacks - C2 Servers - DDOS Zombies - Email Spam - IPQS Honeypots - Malware & Phishing - Open Proxies - Payment Fraud & Chargebacks - TOR Nodes - Virtual Devices - VPN Networks - WAF Attacks - Zombies |
| last_seen | The date and time when the abuse event was last seen in ISO8601 format (Ex: 2025-03-01T16:40:34-04:00) | string |