Response Parameters

Response Field Definitions

Learn about the parameters returned by the Transaction Scoring API. With clear definitions for every response value, you can fine tune your requests to better protect against fraud.

The Transaction Scoring API returns the following variables, which provide risk analysis for users and transactions. You may also treat "billing" or "shipping" variables as a user's primary or secondary information group, even when billing is not involved, such as for lead generation or user scoring purposes.

Some variables will return null if necessary parameters were not passed with the initial API request. For example, not passing the billing_email will return valid_billing_email as null.

The risk_score is a vital component in the risk analysis process. It serves as a quick and effective way to identify suspicious user behavior, with scores of 75 or higher indicating such behavior. Scores of 90 or higher point to high-risk payment details or user data.

If you submitted a request via a different API, such as the Email Verification API, the transaction results will be returned within the transaction_details object. These variables are populated when at least 1 transaction data parameter is present in the initial API request.

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`	Physical address validation and reputation analysis.	Boolean
`billing_address_distance`		Object
`shipping_address_distance`		Object
`valid_billing_email`	Light abusive check and reputation analysis for the email address. For deeper email analysis, use our dedicated Email Verification API.	Boolean
`valid_shipping_email`	Light abusive check and reputation analysis for the email address. For deeper email analysis, use our dedicated Email Verification API.	Boolean
`leaked_billing_email`	Indicates if the email address has 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
`leaked_shipping_email`	Indicates if the email address has recently been exposed or compromised in a database breach.	Boolean
`billing_first_name`	The customer's billing first name.	String
`billing_last_name`	The customer's billing last name.	String
`billing_address_1`	The customer's billing street address part 1.	String
`billing_address_2`	The customer's billing street address part 2.	String
`billing_city`	The customer's billing city.	String
`billing_region`	The customer's shipping region or state. State must be two-letter abbreviation. (e.g., CA, FL, NY)	String
`billing_zipcode`	The customer's billing ZIP code or postcode	String / Number
`billing_country`	String	The customer's billing country name or billing country ISO-Alpha2. (EG: United States or US)
`billing_email`	The customer's billing email address.	String
`billing_phone_extension`	The customer's billing phone number extension.	Integer
`billing_phone_area`	The customer's billing phone area code.	Integer
`shipping_first_name`	The customer's shipping first name.	String
`shipping_last_name`	The customer's shipping last name.	String
`shipping_country`	The customer's shipping country name or shipping country ISO-Alpha2. (e.g., United States or US)	String
`shipping_address_1`	The customer's shipping street address part 1.	String
`shipping_address_2`	The customer's shipping street address part 2.	String
`shipping_city`	The customer's shipping city.	String
`shipping_region`	The customer's shipping region or state. State must be two-letter abbreviation. (e.g., CA, FL, NY)	String
`shipping_zipcode`	The customer's shipping ZIP code or postcode.	String / Number
`leaked_user_data`	Indicates if the user's data (including phone & address) have recently been exposed or compromised in a database breach.	Boolean
`risky_billing_phone`	Reputation analysis for abusive activity associated with the phone number.	Boolean
`risky_shipping_phone`	Reputation analysis for abusive activity associated with the phone number.	Boolean
`valid_billing_phone`	Valid & active phone number with the phone carrier (not disconnected).	Boolean
`valid_shipping_phone`	Valid & active phone number with the phone carrier (not disconnected).	Boolean
`billing_phone_carrier`	Phone number provider company such as "AT&T" or "Bell Canada".	String
`shipping_phone_carrier`	Phone number provider company such as "AT&T" or "Bell Canada".	String
`billing_phone_line_type`	Landline, Wireless, Toll Free, VOIP, Satellite, Premium Rate, Pager, Internet Service Provider or Unknown.	String
`shipping_phone_line_type`	Landline, Wireless, Toll Free, VOIP, Satellite, Premium Rate, Pager, Internet Service Provider or Unknown.	String
`billing_phone_country`	2-letter country code associated with the phone number.	String
`billing_phone_country_code`	Country dialing code associated with the phone number.	Integer
`shipping_phone_country`	2-letter country code associated with the phone number.	String
`shipping_phone_country_code`	Country dialing code associated with the phone number.	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
`avs`	One letter Address Verification Service (AVS) response code provided by the credit card processor or bank.	String
`cvv`	One letter Card Verification Value (CVV2) response code provided by the credit card processor or bank.	String
`avs_match_found`	Will return `true` if the `avs` response parameter returns any of the following AVS codes: `a`, `b`, `d`, `m`, `p`, `x`, or `y`.	Boolean
`cvv_match_found`	Will return `true` if the `cvv` response parameter returns any of the following CVV codes: `a`, `b`, `m`, `p`, `x`, or `y`.	Boolean
`recommended_action`	The action we recommend for this Transaction, based on the risk_score or your Transaction Rules. This can be one of 4 values - "approve", "review", "3ds" or "deny". By default a risk score of 75 or less will be approve, between 75 and 85 review, between 85 and 95 3DS and above 95 deny.	String
`high_risk_billing_address`	Enterprise Account Feature — Indicates the billing address has been flagged by IPQS. These addresses are typically dropshippers, package forwarding services, high risk landmarks, package delivery centers,empty lots, empty buildings, etc...	Boolean
`high_risk_shipping_address`	Enterprise Account Feature — Indicates the shipping address has been flagged by IPQS. These addresses are typically dropshippers, package forwarding services, high risk landmarks, package delivery centers,empty lots, empty buildings, etc...	Boolean
`user_flagged_billing_address`	Enterprise Account Feature — You can create blocklists for specific high risk billing addresses in your account settings. If you've blocked an address this will return true.	Boolean
`user_flagged_shipping_address`	Enterprise Account Feature — You can create blocklists for specific high risk shipping addresses in your account settings. If you've blocked an address this will return true.	Boolean
`recent_data_matches`	Returns recent matches for submitted transaction data. Each match shows the value, its type, and how many times IPQS has seen that value in the last 7 days.	Object
`recent_unique_user_values`	Returns counts of unique transaction data values associated with customer-defined variables submitted with the request.	Object

billing_address_distance fields

Key	Description	Expected Values
`miles`	The distance in miles between the customer's billing address and the location of their IP address.	Number
`kilometers`	The distance in kilometers between the customer's billing address and the location of their IP address.	Number

shipping_address_distance fields

Key	Description	Expected Values
`miles`	The distance in miles between the customer's shipping address and the location of their IP address.	Number
`kilometers`	The distance in kilometers between the customer's shipping address and the location of their IP address.	Number

recent_data_matches fields

The recent_data_matches object indicates how often IPQS has seen submitted values within the last 7 days. The matches array can return the standard types below, as well as customer-defined variables included with the request.

Type	Description
`ip_address`	The submitted IP address.
`email_address`	The submitted email address.
`billing_email_address`	The submitted billing email address.
`shipping_email_address`	The submitted shipping email address.
`billing_address`	The submitted billing address.
`shipping_address`	The submitted shipping address.
`phone_number`	The submitted phone number.
`device_id`	The submitted device ID.

Each entry in the matches array contains the following fields:

Key	Description	Expected Values
`type`	The type of value that matched. This can be one of the standard types above or a customer-defined variable passed with the request.	String
`value`	The value that matched.	String
`recent_occurrences`	The number of times IPQS has seen the value in the last 7 days.	Integer

recent_unique_user_values fields

The recent_unique_user_values object returns counts of unique transaction data values associated with customer-defined variables. For example, if a request includes userID=1234, the response can return types such as unique_userID_ip_addresses, unique_userID_email_addresses, unique_userID_phone_numbers, unique_userID_device_ids, unique_userID_billing_addresses, and unique_userID_shipping_addresses.

Each entry in the unique_values array contains the following fields:

Key	Description	Expected Values
`type`	Identifies the customer-defined variable and the type of unique value counted.	String
`recent_occurrences`	The number of unique values associated with the customer-defined variable.	Integer

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

Response Field Definitions#

billing_address_distance fields#

shipping_address_distance fields#

recent_data_matches fields#

recent_unique_user_values fields#