Customer Quality Signal Responses
Applies to: Direct | Capture
Various customer quality checks return responses described here. Responses include the following customer quality JSON objects: addressValidationDetails, deviceFingerprintDetails, and phoneValidationDetails.
The /start endpoint request parameters determine which customer quality objects are returned by /get-results:
addressValidationDetailsis returned for aaddress_validationsignal request.deviceFingerprintDetailsis returned for adevice_fingerprintsignal request.phoneValidationDetailsis returned for aphone_validationsignal request.
Customer quality results share several other dependencies with the /start endpoint:
- For
addressValidationDetailsto be returned, theprivate_data>signalsarray must includeocr_scananddevice_fingerprint. - For
phoneValidationDetailsto be returned, theprivate_data>send_link>typevalue must besms.
addressValidationDetails
{
"addressValidationDetails": {
"type": "object",
"description": "Response data returned by an IP address validation check.",
"required": [
],
"properties": {
"data": {
"required": [
],
"properties": {
"bot_status": {
"type": "boolean",
"description": "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."
},
"success": {
"type": "boolean",
"description": "Was the request successful?"
},
"transaction_details": {
"required": [
],
"properties": {
"billing_phone_line_type": {
"type": "string",
"description": "Landline, Wireless, Toll Free, VOIP, Satellite, Premium Rate, Pager, Internet Service Provider or Unknown."
},
"address_email_identity_match": {
"type": "string",
"description": "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."
},
"valid_billing_phone": {
"type": "boolean",
"description": "Valid & active phone number with the phone carrier (not disconnected)."
},
"bin_type": {
"type": "string",
"description": "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."
},
"name_address_identity_match": {
"type": "string",
"description": "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."
},
"risk_factors": {
"type": "array",
"description": "Explanation for elevated Risk Scores to better understand why the payment or user was associated with fraudulent behavior and considered a high risk.",
"items": {
"type": "string"
}
},
"email_name_identity_match": {
"type": "string",
"description": "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."
},
"phone_name_identity_match": {
"type": "string",
"description": "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_address_identity_match": {
"type": "string",
"description": "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."
},
"fraudulent_behavior": {
"type": "boolean",
"description": "Indicates high risk behavior patterns and a high chance of fraud."
},
"risk_score": {
"type": "float",
"description": "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\"."
},
"shipping_phone_line_type": {
"type": "string",
"description": "Landline, Wireless, Toll Free, VOIP, Satellite, Premium Rate, Pager, Internet Service Provider or Unknown."
},
"phone_email_identity_match": {
"type": "string",
"description": " 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."
}
},
"type": "object"
},
"mobile": {
"type": "boolean",
"description": "Is this user agent a mobile browser? (will always be false if the user agent is not passed in the API request)"
},
"ASN": {
"type": "integer",
"description": "Autonomous System Number if one is known. Null if nonexistent."
},
"ISP": {
"type": "string",
"description": "ISP if one is known. Otherwise \"N/A\"."
},
"recent_abuse": {
"type": "boolean",
"description": "This value will indicate if there has been any recently verified abuse 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."
},
"vpn": {
"type": "boolean",
"description": "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."
},
"latitude": {
"type": "float",
"description": "Latitude of IP address if available or null if unknown."
},
"active_vpn": {
"type": "boolean",
"description": "Identifies active VPN connections used by popular VPN services and private VPN servers."
},
"longitude": {
"type": "float",
"description": "Longitude of IP address if available or null if unknown."
},
"country_code": {
"type": "string",
"description": "Two character country code of IP address or \"N/A\" if unknown."
},
"city": {
"type": "string",
"description": "City of IP address if available or \"N/A\" if unknown."
},
"fraud_score": {
"type": "float",
"description": "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."
},
"region": {
"type": "string",
"description": "Region (state) of IP address if available or \"N/A\" if unknown."
},
"frequent_abuser": {
"type": "boolean",
"description": "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."
},
"tor": {
"type": "boolean",
"description": "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."
},
"proxy": {
"type": "boolean",
"description": "Is this IP address suspected to be a proxy? (SOCKS, Elite, Anonymous, VPN, Tor, etc.)"
},
"security_scanner": {
"type": "boolean",
"description": "Indicates a verified online security scanner or endpoint by a trusted security vendor such as Tenable, Qualys, and similar providers."
},
"active_tor": {
"type": "boolean",
"description": "Identifies active TOR exits on the TOR network."
},
"trusted_network": {
"type": "boolean",
"description": "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."
},
"high_risk_attacks": {
"type": "boolean",
"description": "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."
},
"host": {
"type": "string",
"description": "Hostname of the IP address if one is available."
},
"dynamic_connection": {
"type": "boolean",
"description": "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."
},
"is_crawler": {
"type": "boolean",
"description": "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."
},
"organization": {
"type": "string",
"description": "Organization if one is known. Can be parent company or sub company of the listed ISP. Otherwise \"N/A\"."
},
"abuse_velocity": {
"type": "string",
"description": "How frequently the IP address is engaging in abuse across the threat network. Values can be \"high\", \"medium\", \"low\", or \"none\". Can be used in combination with the Fraud Score to identify bad behavior."
},
"timezone": {
"type": "string",
"description": "Timezone of IP address if available or \"N/A\" if unknown."
},
"message": {
"type": "string",
"description": "A generic status message, either success or some form of an error notice."
},
"connection_type": {
"type": "string",
"description": "Classification of the IP address connection type as \"Residential\", \"Corporate\", \"Education\", \"Mobile\", or \"Data Center\"."
},
"shared_connection": {
"type": "boolean",
"description": "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."
},
"zip_code": {
"type": "string",
"description": "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."
},
"request_id": {
"type": "string",
"description": "A unique identifier for this request."
}
},
"type": "object"
},
"result": {
"type": "boolean"
},
"success": {
"type": "boolean"
},
"message": {
"type": "string"
}
}
}
}
deviceFingerprintDetails
{
"deviceFingerprintDetails": {
"type": "object",
"description": "Response data returned by a device fingerprint check.",
"required": [
],
"properties": {
"data": {
"required": [
],
"properties": {
"proxy": {
"type": "boolean",
"description": "Returns true if the lookup is on a Proxy, VPN, or Tor connection."
},
"browser": {
"type": "string",
"description": "Browser name and version or \"N/A\" if unknown."
},
"recent_abuse": {
"type": "boolean",
"description": "This value will indicate if there has been any recently verified abuse for this user. Abuse could be a confirmed chargeback, compromised device, fake app install, or similar malicious behavior within the past few days."
},
"ip_address": {
"type": "string",
"description": "The IP Address associated with the device in IPv4 or IPv6 format."
},
"device_id": {
"type": "string",
"description": "The Device ID is generated as a hash from the user's device hardware and personal settings."
},
"active_vpn": {
"type": "boolean",
"description": "Identifies active VPN connections used by popular VPN services and private VPN servers."
},
"operating_system": {
"type": "string",
"description": "Operating system name and version or \"N/A\" if unknown."
},
"fraud_chance": {
"type": "integer",
"description": "How likely this device is to commit fraud or engage in abusive behavior. 0 = not likely, 100 = very likely. 25 is the median result. Fraud Scores >= 85 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."
},
"reasons": {
"type": "array",
"description": "Fraud Score Insights explain how this device's Fraud Score was calculated and provides further detail into enhanced Fraud Scores and penalties.",
"items": {
"type": "string"
}
},
"timezone": {
"type": "string",
"description": "Time zone of IP address if available or \"N/A\" if unknown."
},
"mobile": {
"type": "boolean",
"description": "Is this a mobile device?"
},
"region": {
"type": "string",
"description": "Region or state of IP address if available or \"N/A\" if unknown."
},
"city": {
"type": "string",
"description": "City of IP address if available or \"N/A\" if unknown."
},
"last_seen": {
"type": "string",
"description": "Time of the most recent request."
},
"model": {
"type": "string",
"description": "Model name of the device or \"N/A\" if unknown."
},
"brand": {
"type": "string",
"description": "Brand name of the device or \"N/A\" if unknown."
},
"first_seen": {
"type": "string",
"description": "Time of the first request. "
},
"isp": {
"type": "string",
"description": "Internet Service Provider of the IP address. If unavailable, then \"N/A\"."
},
"active_tor": {
"type": "boolean",
"description": "Identifies active TOR exits on the TOR network."
},
"bot_status": {
"type": "boolean",
"description": "Indicates if this device is a bot, spoofed device, or non-human request. Provides stronger confidence in decision making."
},
"vpn": {
"type": "boolean",
"description": "Is this IP suspected of being a VPN connection? (proxy will always be true if this is true)"
},
"request_id": {
"type": "string",
"description": "A unique identifier for this request."
},
"is_crawler": {
"type": "boolean",
"description": "Is this device associated with being a confirmed crawler from a mainstream search engine such as Googlebot, Bingbot, Yandex, etc."
},
"connection_type": {
"type": "string",
"description": "Classification of the IP address connection type as \"Residential\", \"Corporate\", \"Education\", \"Mobile\", or \"Data Center\"."
},
"unique": {
"type": "boolean",
"description": "Returns false if this device ID has been seen on multiple IP addresses. Returns true if we haven't seen this ID on multiple IPs."
},
"country": {
"type": "string",
"description": "Two letter country code of the IP address, example: \"US\"."
},
"tor": {
"type": "boolean",
"description": "Is this IP suspected of being a Tor connection? (proxy will always be true if this is true)"
}
},
"type": "object"
},
"result": {
"type": "boolean"
},
"message": {
"type": "string"
},
"success": {
"type": "boolean"
}
}
}
}
phoneValidationDetails
{
"phoneValidationDetails": {
"type": "object",
"description": "Response data returned by a phone validation check.",
"required": [
],
"properties": {
"data": {
"required": [
],
"properties": {
"sms_email": {
"type": "string",
"description": ""
},
"user_activity": {
"type": "string",
"description": "Frequency at which this phone number makes legitimate purchases, account registrations, and engages in legitimate user behavior online. Values can be high, medium, low, or none. Values of high or medium are strong signals of healthy usage. New phone numbers without a history of legitimate behavior will have a value as none."
},
"spammer": {
"type": "boolean",
"description": "Indicates if the phone number has recently been reported for spam or harassing calls/texts."
},
"active_status": {
"type": "string",
"description": "Additional details on the status of the subscriber connection. These values can be: Active Line, Active Line - High Confidence, Active Line - Medium Confidence, Active Line - Low Confidence, Disconnected Line, Phone Turned Off, Inconclusive Status, or N/A if unknown. The confidence level is included for active lines whenever possible."
},
"success": {
"type": "boolean",
"description": "Was the request successful?"
},
"associated_email_addresses": {
"type": "object",
"description": "Displays email addresses linked to the phone number, if available. Match rates vary by country and line type. Object value contains, \"status\", and \"emails\" as an array.",
"required": [
],
"properties": {
"emails": {
"type": "array",
"items": {
"type": "string"
}
},
"status": {
"type": "string"
}
}
},
"risky": {
"type": ["boolean", "null"],
"description": "Is this phone number associated with fraudulent activity, scams, robo calls, fake accounts, or other unfriendly behavior?"
},
"dialing_code": {
"type": "integer",
"description": "The 1 to 4 digit dialing code for this phone number or null if unknown."
},
"sms_domain": {
"type": "string",
"description": ""
},
"recent_abuse": {
"type": "boolean",
"description": "Has this phone number been associated with recent or ongoing fraud?"
},
"timezone": {
"type": "string",
"description": "Timezone of the phone number if available or \"N/A\" if unknown."
},
"mcc": {
"type": "string",
"description": "Mobile Country Codes (MCC) identify the country of a mobile phone number subscriber. This provides a corresponding number to a specific country, to facilitate routing for wireless calls and SMS messages. The MCC value is \"N/A\" when unknown or not available, such as for landline and toll-free numbers."
},
"message": {
"type": "string",
"description": "A generic status message, either success or some form of an error notice."
},
"zip_code": {
"type": "string",
"description": "Zip or Postal code of the phone number if available or \"N/A\" if unknown."
},
"active": {
"type": ["boolean", "null"],
"description": "Is this phone number a live usable phone number that is currently active?"
},
"country": {
"type": ["string", "array"],
"items": {
"type": "string"
},
"description": "The default country or countries this phone number is suspected to be associated with."
},
"do_not_call": {
"type": "boolean",
"description": "Indicates if the phone number is listed on any Do Not Call (DNC) lists. Only supported in US and CA. This data may not be 100% up to date with the latest DNC blacklists."
},
"VOIP": {
"type": ["boolean", "null"],
"description": "Is this phone number a Voice Over Internet Protocol (VOIP) or digital phone number?"
},
"carrier": {
"type": "string",
"description": "The carrier (service provider) this phone number has been assigned to or \"N/A\" if unknown."
},
"valid": {
"type": "boolean",
"description": "Is the phone number properly formatted and considered valid based on assigned phone numbers available to carriers in that country?"
},
"leaked": {
"type": "boolean",
"description": "Has this phone number recently been exposed in an online database breach or act of compromise."
},
"name": {
"type": "string",
"description": "The owner name of the phone number such as the first or last name or business name assigned to the phone number. Multiple names will be returned in comma separated format. Value is \"N/A\" if unknown."
},
"line_type": {
"type": "string",
"description": "The type of line this phone number is associated with (Toll Free, Wireless, Landline, Satellite, VOIP, Premium Rate, Pager) or \"N/A\" if unknown. Line Type can play an important role for understanding phone number reputation."
},
"fraud_score": {
"type": "integer",
"description": "The risk score which estimates how likely a phone number is to be fraudulent. Scores 85+ are risky while Fraud Scores 90+ are high risk. Maximum value is 100."
},
"request_id": {
"type": "string",
"description": "A unique identifier for this request."
},
"city": {
"type": "string",
"description": "City of the phone number if available or \"N/A\" if unknown."
},
"mnc": {
"type": "string",
"description": "Mobile Network Codes (MNC) identify the mobile carrier of a phone number subscriber. This data provides a corresponding number to a specific telecom provider, such as Orange, Vodafone, etc. to facilitate routing for wireless calls and SMS messages. The MNC value is \"N/A\" when unknown or not available, such as for landline and toll-free numbers."
},
"formatted": {
"type": "string",
"description": "The phone number formatted in the international dialing code. N/A if not formattable."
},
"prepaid": {
"type": ["boolean", "null"],
"description": "Is this phone number associated with a prepaid service plan?"
},
"region": {
"type": "string",
"description": "Region (state) of the phone number if available or \"N/A\" if unknown."
},
"local_format": {
"type": "string",
"description": "The phone number formatted in the country's local routing rules with area code. N/A if not formattable."
}
},
"type": "object"
},
"result": {
"type": "boolean"
},
"message": {
"type": "string"
},
"success": {
"type": "boolean"
}
}
}
}
Updated 4 months ago