minFraud API Responses

Headers

The Content-Type for a successful response varies based on the service as outlined below:

Service	Content-Type
Score	`application/vnd.maxmind.com-minfraud-score+json; charset=UTF-8; version=2.0`
Insights	`application/vnd.maxmind.com-minfraud-insights+json; charset=UTF-8; version=2.0`
Factors	`application/vnd.maxmind.com-minfraud-factors+json; charset=UTF-8; version=2.0`

Errors may be returned with the Content-Type set to application/vnd.maxmind.com-error+json; charset=UTF-8; version=2.0. If this is the case, then the body of the response contains a JSON document with two keys, code and error. See the Errors section for more details.

A Content-Length header will be provided.

Errors

When the server returns an error (4xx or 5xx), the response may include a JSON document in the body. This document is a single object with the keys code and error. The code field is a static error code for machine use. The value of any given code will never change, though codes can be added or removed. The error field is a human-readable description of the error and may change at any time.

Not all errors include a JSON body. An error in content negotiation will not include a body, nor will many 5xx errors, which typically happen outside of our web service request handling code. You should check the Content-Type type of an error response before attempting to decode the body as JSON.

In addition to the errors documented below, client code should also be prepared to handle any valid HTTP 4xx or 5xx status code.

Code	HTTP Status	Description
`JSON_INVALID`	400 Bad Request	We cannot decode the body as a JSON object.
`REQUEST_INVALID`	400 Bad Request	The request body is valid JSON but contains no valid input values.
`AUTHORIZATION_INVALID`	401 Unauthorized	You have supplied an invalid MaxMind account ID and/or license key in the Authorization header.
`LICENSE_KEY_REQUIRED`	401 Unauthorized	You have not supplied a MaxMind license key in the Authorization header.
`ACCOUNT_ID_REQUIRED`	401 Unauthorized	You have not supplied a MaxMind account ID in the Authorization header.
`INSUFFICIENT_FUNDS`	402 Payment Required	The license key you have provided does not have sufficient funds to use this service. Please purchase more service credits.
`PERMISSION_REQUIRED`	403 Forbidden	You do not have permission to use the service. Please contact our support team for more information.
(none)	403 Forbidden	This status is returned when the request body is larger than 20,000 bytes.
(none)	415 Unsupported Media Type	Your request included a `Content-Type` header that is not supported. For `GET` requests, this means the web service cannot return content of that type. For `PUT` and `POST` queries, this means the web service cannot parse a request body of that type.
(none)	503 Service Not Available	There is a problem with the web service server. You can try this request again later.

Response Body

All services return data as a JSON document. The document that is returned always consists of an object (aka map or hash).

Keys with undefined or empty values will not be included in the returned document.

The data returned in the document will be in UTF-8 encoding.

Note that a given key and value may be omitted from the response entirely if there is no relevant information to include. For example, if you do not pass any information about the credit card in your request, then the response will not contain a credit_card key or value.

For full examples of response bodies, select one of the following:

minFraud Score Body Example
minFraud Insights Body Example
minFraud Factors Body Example
Error Body Example

Top-Level Fields

1{
2  ...
3  "id": "5bc5d6c2-b2c8-40af-87f4-6d61af86b6ae",
4  "risk_score": 0.01,
5  "funds_remaining": 25,
6  "queries_remaining": 5000
7  ...
8}

Key	Value Type	Description
`id`	string	This is the minFraud ID, a UUID that identifies the minFraud response. Use this ID to search your minFraud logs or when making support requests to MaxMind. format: UUID minFraud Score minFraud Insights minFraud Factors
`risk_score`	decimal	This field contains the overall risk score, from 0.01 to 99. A higher score indicates a higher risk of fraud. For example, a score of 20 indicates a 20% chance that a transaction is fraudulent. We never return a risk score of 0, since all transactions have the possibility of being fraudulent. Likewise we never return a risk score of 100. Learn more about the overall risk score on our Knowledge Base. min: 0.01, max: 99 minFraud Score minFraud Insights minFraud Factors
`funds_remaining`	decimal	The approximate US dollar value of the funds remaining on your MaxMind account. min: 0 minFraud Score minFraud Insights minFraud Factors
`queries_remaining`	integer	The approximate number of queries remaining for the service before your account runs out of funds. min: 0 minFraud Score minFraud Insights minFraud Factors

IP Address

For minFraud Score, this object only contains the risk for the IP address. For minFraud Insights and Factors, the object is the GeoIP2 Insights response body with four modifications:

risk has been added directly to the ip_address object
local_time has been added to the location sub-object
The maxmind object is not present. See below for descriptions.
minFraud Insights and Factors return the following anonymous IP outputs:
- is_anonymous
- is_anonymous_vpn
- is_hosting_provider
- is_public_proxy
- is_residential_proxy
- is_tor_exit_node

See the GeoIP2 Insights response body for more information.

  1{
  2  "risk": 0.01,
  3  "city": {
  4    "confidence": 25,
  5    "geoname_id": 54321,
  6    "names": {
  7      "de": "Los Angeles",
  8      "en": "Los Angeles",
  9      "es": "Los Ángeles",
 10      "fr": "Los Angeles",
 11      "ja": "ロサンゼルス市",
 12      "pt-BR": "Los Angeles",
 13      "ru": "Лос-Анджелес",
 14      "zh-CN": "洛杉矶"
 15    }
 16  },
 17  "continent": {
 18    "code": "NA",
 19    "geoname_id": 123456,
 20    "names": {
 21      "de": "Nordamerika",
 22      "en": "North America",
 23      "es": "América del Norte",
 24      "fr": "Amérique du Nord",
 25      "ja": "北アメリカ",
 26      "pt-BR": "América do Norte",
 27      "ru": "Северная Америка",
 28      "zh-CN": "北美洲"
 29    }
 30  },
 31  "country": {
 32    "confidence": 75,
 33    "geoname_id": 6252001,
 34    "is_in_european_union": true,
 35    "iso_code": "US",
 36    "names": {
 37      "de": "USA",
 38      "en": "United States",
 39      "es": "Estados Unidos",
 40      "fr": "États-Unis",
 41      "ja": "アメリカ合衆国",
 42      "pt-BR": "Estados Unidos",
 43      "ru": "США",
 44      "zh-CN": "美国"
 45    }
 46  },
 47  "location": {
 48    "accuracy_radius": 20,
 49    "average_income": 50321,
 50    "latitude": 37.6293,
 51    "local_time": "2015-04-26T01:37:17-08:00",
 52    "longitude": -122.1163,
 53    "metro_code": 807,
 54    "population_density": 7122,
 55    "time_zone": "America/Los_Angeles"
 56  },
 57  "postal": {
 58    "code": "90001",
 59    "confidence": 10
 60  },
 61  "registered_country": {
 62    "geoname_id": 6252001,
 63    "is_in_european_union": true,
 64    "iso_code": "US",
 65    "names": {
 66      "de": "USA",
 67      "en": "United States",
 68      "es": "Estados Unidos",
 69      "fr": "États-Unis",
 70      "ja": "アメリカ合衆国",
 71      "pt-BR": "Estados Unidos",
 72      "ru": "США",
 73      "zh-CN": "美国"
 74    }
 75  },
 76  "represented_country": {
 77    "geoname_id": 6252001,
 78    "is_in_european_union": true,
 79    "iso_code": "US",
 80    "names": {
 81      "de": "USA",
 82      "en": "United States",
 83      "es": "Estados Unidos",
 84      "fr": "États-Unis",
 85      "ja": "アメリカ合衆国",
 86      "pt-BR": "Estados Unidos",
 87      "ru": "США",
 88      "zh-CN": "美国"
 89    },
 90    "type": "military"
 91  },
 92  "risk_reasons": [
 93    {
 94      "code": "ANONYMOUS_IP",
 95      "reason": "The IP address belongs to an anonymous network. See /ip_address/traits for more details."
 96    },
 97    {
 98      "code": "MINFRAUD_NETWORK_ACTIVITY",
 99      "reason": "Suspicious activity has been seen on this IP address across minFraud customers."
100    }
101  ],
102  "subdivisions": [
103    {
104      "confidence": 50,
105      "geoname_id": 5332921,
106      "iso_code": "CA",
107      "names": {
108        "de": "Kalifornien",
109        "en": "California",
110        "es": "California",
111        "fr": "Californie",
112        "ja": "カリフォルニア",
113        "ru": "Калифорния",
114        "zh-CN": "加州"
115      }
116    }
117  ],
118  "traits": {
119    "autonomous_system_number": 1239,
120    "autonomous_system_organization": "Linkem IR WiMax Network",
121    "connection_type": "Cable/DSL",
122    "domain": "example.com",
123    "ip_address": "1.2.3.4",
124    "is_anonymous": true,
125    "is_anonymous_proxy": true,
126    "is_anonymous_vpn": true,
127    "is_anycast": true,
128    "is_hosting_provider": true,
129    "is_public_proxy": true,
130    "is_residential_proxy": true,
131    "is_satellite_provider": true,
132    "is_tor_exit_node": true,
133    "isp": "Linkem spa",
134    "mobile_country_code": "310",
135    "mobile_network_code": "004",
136    "network": "1.2.3.0/24",
137    "organization": "Linkem IR WiMax Network",
138    "static_ip_score": 1.5,
139    "user_count": 1,
140    "user_type": "traveler"
141  }
142}

Key	Value Type	Description
`risk`	decimal	This field contains the risk associated with the IP address. The value ranges from 0.01 to 99. A higher score indicates a higher risk. Learn more about the IP risk score on our Knowledge Base. min: 0.01, max: 99 minFraud Score minFraud Insights minFraud Factors
`country`	object	This object contains country-level geolocation data associated with the IP address associated with the event. minFraud Score minFraud Insights minFraud Factors
`location`	object	This object contains city-level geolocation data associated with the IP address associated with the event. minFraud Score minFraud Insights minFraud Factors
`risk_reasons`	array	This array contains IP Address Risk Reason objects identifying the reasons why the IP address received the associated risk. Learn how to use IP risk reasons for risk analysis on our Knowledge Base. minFraud Score minFraud Insights minFraud Factors

IP Address > Country

This object contains country-level geolocation data associated with the IP address associated with the event

See the GeoIP2 Insights response body for more information.

 1{
 2  "confidence": 75,
 3  "geoname_id": 6252001,
 4  "is_in_european_union": true,
 5  "iso_code": "US",
 6  "names": {
 7    "de": "USA",
 8    "en": "United States",
 9    "es": "Estados Unidos",
10    "fr": "États-Unis",
11    "ja": "アメリカ合衆国",
12    "pt-BR": "Estados Unidos",
13    "ru": "США",
14    "zh-CN": "美国"
15  }
16}

IP Address > Location

This object contains city-level geolocation data associated with the IP address associated with the event.

See the GeoIP2 Insights response body for more information.

 1{
 2  "accuracy_radius": 20,
 3  "average_income": 50321,
 4  "latitude": 37.6293,
 5  "local_time": "2015-04-26T01:37:17-08:00",
 6  "longitude": -122.1163,
 7  "metro_code": 807,
 8  "population_density": 7122,
 9  "time_zone": "America/Los_Angeles"
10}

Key	Value Type	Description
`local_time`	string	The date and time of the transaction in the time zone associated with the IP address. The value is formatted according to RFC 3339. For instance, the local time in Boston might be returned as`2015-04-27T19:17:24-04:00`. max length: 255 minFraud Score minFraud Insights minFraud Factors

IP Address > Risk Reasons

This array contains IP Address Risk Reason objects identifying the reasons why the IP address received the associated risk.

 1[
 2  {
 3    "code": "ANONYMOUS_IP",
 4    "reason": "The IP address belongs to an anonymous network. See /ip_address/traits for more details."
 5  },
 6  {
 7    "code": "MINFRAUD_NETWORK_ACTIVITY",
 8    "reason": "Suspicious activity has been seen on this IP address across minFraud customers."
 9  }
10]

Key Value Type Description

code

string

This value is a machine-readable code identifying the reason. Although more codes may be added in the future, the current codes are:

Code	Explanation
`ANONYMOUS_IP`	The IP address belongs to an anonymous network. See the object at/ip_address/traits for more details.
`BILLING_POSTAL_VELOCITY`	Many different billing postal codes have been seen on this IP address.
`EMAIL_VELOCITY`	Many different email addresses have been seen on this IP address.
`HIGH_RISK_DEVICE`	A high risk device was seen on this IP address.
`HIGH_RISK_EMAIL`	A high risk email address was seen on this IP address in your past transactions.
`ISSUER_ID_NUMBER_VELOCITY`	Many different issuer ID numbers have been seen on this IP address.
`MINFRAUD_NETWORK_ACTIVITY`	Suspicious activity has been seen on this IP address across minFraud customers.

Learn how to use IP risk reasons for risk analysis on our Knowledge Base.

format: enum, max length: 255

minFraud Score minFraud Insights minFraud Factors

reason

string

This field provides an explanation of the reason, as seen in the table above. The explanation text may change at any time and should not be matched against.

Learn how to use IP risk reasons for risk analysis on our Knowledge Base.

minFraud Score minFraud Insights minFraud Factors

Credit Card

This object contains minFraud information related to the credit card. If an issuer ID number (IIN) was not provided in the request, this object will not be present in the response.

 1{
 2  "brand": "Visa",
 3  "country": "US",
 4  "is_business": true,
 5  "is_issued_in_billing_address_country": true,
 6  "is_prepaid": true,
 7  "is_virtual": true,
 8  "issuer": {
 9    "matches_provided_name": true,
10    "matches_provided_phone_number": true,
11    "name": "Bank of America",
12    "phone_number": "800-732-9194"
13  },
14  "type": "credit"
15}

Key	Value Type	Description
`issuer`	object	This field contains a JSON object with information relating to the credit card issuer. minFraud Score minFraud Insights minFraud Factors
`brand`	string	The card brand, such as “Visa”, “Discover”, “American Express”, etc. Learn how to use the credit card brand data for risk analysis on our Knowledge Base. max length: 255 minFraud Score minFraud Insights minFraud Factors
`country`	string	The two letter ISO 3166-1 alpha-2 country code associated with the location of the majority of customers using this credit card as determined by their billing address. In cases where the location of customers is highly mixed, this defaults to the country of the bank issuing the card. Learn how to use the credit card country data for risk analysis on our Knowledge Base. max length: 2 minFraud Score minFraud Insights minFraud Factors
`is_business`	boolean	This field is `true` if the issuer ID number is for a business card. It is`false` if the issuer ID number is for for a non-business card. The key is only present when a valid issuer ID number has been provided. minFraud Score minFraud Insights minFraud Factors
`is_issued_in_billing_address_country`	boolean	This field is `true` if the country of the billing address matches the country of the majority of customers using that IIN. It is `false` if both countries are available but do not match. If one or both of the countries are missing, the key will not be present. In cases where the location of customers is highly mixed, the match is to the country of the bank issuing the card. Learn how to use the billing address to credit card country matching for risk analysis on our Knowledge Base. minFraud Score minFraud Insights minFraud Factors
`is_prepaid`	boolean	This field is `true` if the issuer ID number is for a prepaid card. It is`false` if the issuer ID number is for for a non-prepaid card. The key is only present when a valid issuer ID number has been provided. Learn how to use prepaid card detection for risk analysis on our Knowledge Base. minFraud Score minFraud Insights minFraud Factors
`is_virtual`	boolean	This field is `true` if the issuer ID number is for a virtual card. It is`false` if the issuer ID number is for a non-virtual card. The key is only present when a valid issuer ID number has been provided. Learn how to use virtual card detection for risk analysis on our Knowledge Base. minFraud Score minFraud Insights minFraud Factors
`type`	string	The card’s type. The valid values are: `charge` – See Wikipedia for an explanation of the difference between charge and credit cards. `credit` `debit` format: enum minFraud Score minFraud Insights minFraud Factors

Credit Card > Issuer

This is a sub-object of credit_card that contains information related to the issuer of the card.

1{
2  "matches_provided_name": true,
3  "matches_provided_phone_number": true,
4  "name": "Bank of America",
5  "phone_number": "800-732-9194"
6}

Key	Value Type	Description
`name`	string	This field contains a JSON object with information relating to the credit card issuer. Learn how to use the credit card issuer name for risk analysis on our Knowledge Base. max length: 255 minFraud Score minFraud Insights minFraud Factors
`matches_provided_name`	boolean	This field is `true` if the name matches the name provided in the request for the card issuer. It is `false` if the name does not match. The field is not included if either no name or issuer ID number (IIN) is provided in the request or if MaxMind does not have a name associated with the IIN. minFraud Score minFraud Insights minFraud Factors
`phone_number`	string	The phone number of the bank which issued the credit card. In some cases the phone number we return may be out of date. max length: 255 minFraud Score minFraud Insights minFraud Factors
`matches_provided_phone_number`	boolean	This field is `true` if the phone number matches the number provided in the request for the card issuer. It is `false` if the number does not match. The field is not included if either no phone number or issuer ID number (IIN) is provided in the request or if MaxMind does not have a phone number associated with the IIN. minFraud Score minFraud Insights minFraud Factors

Device

This object contains information about the device that MaxMind believes is associated with the IP address passed in the request.

1{
2  "confidence": 99,
3  "id": "7835b099-d385-4e5b-969e-7df26181d73b",
4  "last_seen": "2016-06-08T14:16:38Z",
5  "local_time": "2018-01-02T10:40:11-08:00"
6}

Key	Value Type	Description
`confidence`	decimal	A number from 0.01 to 99 representing the confidence that the `/device/id`refers to a unique device as opposed to a cluster of similar devices. A confidence of 0.01 indicates very low confidence that the device is unique, whereas 99 indicates very high confidence. Learn how to use device confidence for risk analysis on our Knowledge Base. min: 0.01, max: 99 minFraud Score minFraud Insights minFraud Factors
`id`	string	A UUID that MaxMind uses for the device associated with this IP address. This is only available if you are using the Device Tracking Add-on. format: UUID minFraud Score minFraud Insights minFraud Factors
`last_seen`	string	The date and time of the last sighting of the device. The value is formatted according to RFC 3339. Learn how to use the last sighting data for risk analysis on our Knowledge Base. max length: 255 minFraud Score minFraud Insights minFraud Factors
`local_time`	string	The local date and time of the transaction in the time zone of the device. This is determined by using the UTC offset associated with the device. The value is formatted according to RFC 3339. Learn how to use local time data for risk analysis on our Knowledge Base. max length: 255 minFraud Score minFraud Insights minFraud Factors

Email

1{
2  "domain": {
3    "first_seen": "2015-01-20"
4  },
5  "first_seen": "2016-02-03",
6  "is_disposable": false,
7  "is_free": false,
8  "is_high_risk": true
9}

Key	Value Type	Description
`domain`	object	This field contains a JSON object with information relating to the domain. minFraud Score minFraud Insights minFraud Factors
`first_seen`	string	A date string (e.g. 2017-04-24) to identify the date an email address was first seen by MaxMind. This is expressed using the ISO 8601 date format YYYY-MM-DD. The earliest date that may be returned is January 1, 2008. Learn how to use email first seen data for risk analysis on our Knowledge Base. format: YYYY-MM-DD, max length: 10 minFraud Score minFraud Insights minFraud Factors
`is_disposable`	boolean	This field is `true` if MaxMind believes that the email address is from a disposable email provider. It is `false` if the address is not from a known disposable email provider. The key will only be present if a valid email address or email domain is provided. Learn how to use disposable email detection for risk analysis on our Knowledge Base. minFraud Score minFraud Insights minFraud Factors
`is_free`	boolean	This field is `true` if MaxMind believes that this email domain is for a free email provider such as Gmail or Yahoo! Mail. It is `false` if the domain is not for a known free email provider. The key will only be present if a valid email address or email domain is provided. Learn how to use free email detection for risk analysis on our Knowledge Base. minFraud Score minFraud Insights minFraud Factors
`is_high_risk`	boolean	This field is `true` if MaxMind believes that this email address is likely to be used for fraud. It is `false` if MaxMind does not believe the address is used for fraud. The key will only be present if a valid email address or email address hash is provided. Note that this is also factored into the overall `risk_score` in the response as well. Learn how to use our high risk email flag for risk analysis on our Knowledge Base. minFraud Score minFraud Insights minFraud Factors

Email > Domain

This is a sub-object of email that contains information related to the domain.

1{
2  "first_seen": "2015-01-20"
3}

Key	Value Type	Description
`first_seen`	string	A date string (e.g. 2019-01-01) to identify the date an email address domain was first seen by MaxMind. This is expressed using the ISO 8601 date format `YYYY-MM-DD`. The earliest date that may be returned is January 1, 2019. Learn how to use email first seen data for risk analysis on our Knowledge Base. format: YYYY-MM-DD, max length: 10 minFraud Score minFraud Insights minFraud Factors

Shipping Address

1{
2  "distance_to_billing_address": 22,
3  "distance_to_ip_location": 15,
4  "is_high_risk": true,
5  "is_in_ip_country": true,
6  "is_postal_in_city": true,
7  "latitude": 37.632,
8  "longitude": -122.313
9}

Key	Value Type	Description
`is_high_risk`	boolean	This field is `true` if the shipping address is an address associated with fraudulent transactions. The field is `false` when the address is not associated with increased risk. The key will only be present when a shipping address is provided. Learn more about the flag for high risk shipping addresses on our Knowledge Base. minFraud Score minFraud Insights minFraud Factors
`is_postal_in_city`	boolean	This field is `true` if the postal code provided with the address is in the city for the address. The field is `false` when the postal code is not in the city. The key will only be present when a billing postal code, city, and country have been provided. We use GeoNames data for the postal-city match, which uses the preferred place name for a US ZIP code. Alternative place names for US ZIP codes may not trigger a match for this field. Learn how to use the postal to city check for risk analysis on our Knowledge Base. minFraud Score minFraud Insights minFraud Factors
`latitude`	decimal	The approximate WGS84 latitude associated with the address. Latitude and longitude are not precise and should not be used to identify a particular street address or household. minFraud Score minFraud Insights minFraud Factors
`longitude`	decimal	The approximate WGS84 longitude associated with the address. Latitude and longitude are not precise and should not be used to identify a particular street address or household. minFraud Score minFraud Insights minFraud Factors
`distance_to_ip_location`	integer	The distance in kilometers from the address to the IP location. We fall back to country or subdivision information if we do not have postal or city information for an IP address, which may lead to inaccurate distance calculations. Learn how to use the IP geolocation to address distance for risk analysis on our Knowledge Base. minFraud Score minFraud Insights minFraud Factors
`distance_to_billing_address`	integer	The distance in kilometers from the shipping address to billing address. We fall back to country or subdivision information if we do not have postal or city information for an IP address, which may lead to inaccurate distance calculations. Learn how to use the shipping to billing address distance for risk analysis on our Knowledge Base. minFraud Score minFraud Insights minFraud Factors
`is_in_ip_country`	boolean	This field is `true` if the address is in the IP country. The field is`false` when the address is not in the IP country. If the IP address could not be geolocated or no billing address was provided, the field will not be included in the response. Learn how to use the IP location to country check for risk analysis on our Knowledge Base. minFraud Score minFraud Insights minFraud Factors

Shipping Phone

1{
2  "country": "CA",
3  "is_voip": true,
4  "network_operator": "Telus Mobility-SVR/2",
5  "number_type": "mobile"
6}

Key	Value Type	Description
`country`	string	A two-character ISO 3166-1 country code for the country associated with the shipping phone number. minFraud Score minFraud Insights minFraud Factors
`network_operator`	string	The name of the original network operator associated with the shipping phone number. This field does not reflect phone numbers that have been ported from the original operator to another, nor does it identify mobile virtual network operators. minFraud Score minFraud Insights minFraud Factors
`number_type`	string	One of the following values: `fixed` or `mobile`. Additional values may be added in the future. minFraud Score minFraud Insights minFraud Factors
`is_voip`	boolean	This is `true` if the shipping phone number is a Voice over Internet Protocol (VoIP) number allocated by a regulator. It is `false` if the shipping phone number is not a VoIP number allocated by a regulator. The key is only present when a valid shipping phone number has been provided and we have data for it. minFraud Score minFraud Insights minFraud Factors

Billing Address

1{
2  "distance_to_ip_location": 100,
3  "is_in_ip_country": true,
4  "is_postal_in_city": true,
5  "latitude": 37.545,
6  "longitude": -122.421
7}

Key	Value Type	Description
`is_postal_in_city`	boolean	This field is `true` if the postal code provided with the address is in the city for the address. The field is `false` when the postal code is not in the city. The key will only be present when a billing postal code, city, and country have been provided. We use GeoNames data for the postal-city match, which uses the preferred place name for a US ZIP code. Alternative place names for US ZIP codes may not trigger a match for this field. Learn how to use the postal to city check for risk analysis on our Knowledge Base. minFraud Score minFraud Insights minFraud Factors
`latitude`	decimal	The approximate WGS84 latitude associated with the address. Latitude and longitude are not precise and should not be used to identify a particular street address or household. minFraud Score minFraud Insights minFraud Factors
`longitude`	decimal	The approximate WGS84 longitude associated with the address. Latitude and longitude are not precise and should not be used to identify a particular street address or household. minFraud Score minFraud Insights minFraud Factors
`distance_to_ip_location`	integer	The distance in kilometers from the address to the IP location. We fall back to country or subdivision information if we do not have postal or city information for an IP address, which may lead to inaccurate distance calculations. Learn how to use the IP geolocation to address distance for risk analysis on our Knowledge Base. minFraud Score minFraud Insights minFraud Factors
`is_in_ip_country`	boolean	This field is `true` if the address is in the IP country. The field is`false` when the address is not in the IP country. If the IP address could not be geolocated or no billing address was provided, the field will not be included in the response. Learn how to use the IP location to country check for risk analysis on our Knowledge Base. minFraud Score minFraud Insights minFraud Factors

Billing Phone

1{
2  "country": "US",
3  "is_voip": true,
4  "network_operator": "Verizon/1",
5  "number_type": "fixed"
6}

Key	Value Type	Description
`country`	undefined	A two-character ISO 3166-1 country code for the country associated with the billing phone number. minFraud Score minFraud Insights minFraud Factors
`network_operator`	undefined	The name of the original network operator associated with the billing phone number. This field does not reflect phone numbers that have been ported from the original operator to another, nor does it identify mobile virtual network operators. minFraud Score minFraud Insights minFraud Factors
`number_type`	undefined	One of the following values: `fixed` or `mobile`. Additional values may be added in the future. minFraud Score minFraud Insights minFraud Factors
`is_voip`	boolean	This is `true` if the billing phone number is a Voice over Internet Protocol (VoIP) number allocated by a regulator. It is `false` if the billing phone number is not a VoIP number allocated by a regulator. The key is only present when a valid billing phone number has been provided and we have data for it. minFraud Score minFraud Insights minFraud Factors

Disposition

This object contains information about how a request was handled by the custom rules you have defined. If your account does not have any custom rules defined, then this object will not be present in the response.

Learn about custom rules and dispositions on our Knowledge Base.

1{
2  "action": "accept",
3  "reason": "default",
4  "rule_label": "my_custom_rule"
5}

Key Value Type Description

action

string

This describes how the request was handled. The valid values are:

Action	Explanation
`accept`	This is the default value that is used if none of your custom rules match the request.
`reject`
`manual_review`
`test`	This value can be used to test custom rules.

format: enum

minFraud Score minFraud Insights minFraud Factors

reason

string

This describes why the action was set to a particular value. The valid values are:

Reason	Explanation
`default`	No custom rules matched the request.
`custom_rule`	A custom rule was applied and set the action.

format: enum

minFraud Score minFraud Insights minFraud Factors

rule_label

string

The custom rule that was triggered. If you do not have custom rules set up, the triggered custom rule does not have a label, or no custom rule was triggered, the field will not be included in the response.

minFraud Score minFraud Insights minFraud Factors

Risk Score Reasons

The risk reasons output codes and reasons are currently in beta and are subject to change. These outputs are being actively developed and tested, and may undergo modifications that could impact their structure, format, and content. While we strive to maintain stability, we recommend that you use these beta outputs with caution and avoid relying on them for critical applications. Your feedback is valuable and will help us improve the final release.

This array contains risk score reason objects. Risk score reasons are usually only returned for medium to high risk transactions. If there were no significant changes to the risk score due to these reasons, then this array will not be present in the response.

 1[
 2  {
 3    "multiplier": 45,
 4    "reasons": [
 5      {
 6        "code": "ANONYMOUS_IP",
 7        "reason": "Risk due to IP being an Anonymous IP"
 8      }
 9    ]
10  },
11  {
12    "multiplier": 1.8,
13    "reasons": [
14      {
15        "code": "TIME_OF_DAY",
16        "reason": "Risk due to local time of day"
17      }
18    ]
19  },
20  {
21    "multiplier": 1.6,
22    "reasons": [
23      {
24        "reason": "Riskiness of newly-sighted email domain",
25        "code": "EMAIL_DOMAIN_NEW"
26      }
27    ]
28  },
29  {
30    "multiplier": 0.34,
31    "reasons": [
32      {
33        "code": "EMAIL_ADDRESS_NEW",
34        "reason": "Riskiness of newly-sighted email address"
35      }
36    ]
37  }
38]

Key Value Type Description

multiplier

Decimal

The factor by which the risk score is increased (if the value is greater than 1) or decreased (if the value is less than 1) for given risk reason(s). Multipliers greater than 1.5 and less than 0.66 are considered significant and lead to risk reason(s) being present.

min: 0.01, max: 100

minFraud Score minFraud Insights minFraud Factors

reasons

array

This array contains objects that describe one of the reasons for the multiplier.

minFraud Score minFraud Insights minFraud Factors

code

string

The machine-readable code for the risk reason. Although more codes may be added in the future, the current codes are:

Code	Reason
BROWSER_LANGUAGE	Riskiness of the browser user-agent and language associated with the request.
BUSINESS_ACTIVITY	Riskiness of business activity associated with the request.
COUNTRY	Riskiness of the country associated with the request.
CUSTOMER_ID	Riskiness of a customer’s activity.
EMAIL_DOMAIN	Riskiness of email domain.
EMAIL_DOMAIN_NEW	Riskiness of newly-sighted email domain.
EMAIL_ADDRESS_NEW	Riskiness of newly-sighted email address.
EMAIL_LOCAL_PART	Riskiness of the local part of the email address.
EMAIL_VELOCITY	Velocity on email - many requests on same email over short period of time.
ISSUER_ID_NUMBER_COUNTRY_MISMATCH	Riskiness of the country mismatch between IP, billing, shipping and IIN country.
ISSUER_ID_NUMBER_ON_SHOP_ID	Risk of Issuer ID Number for the shop ID.
ISSUER_ID_NUMBER_LAST_DIGITS_ACTIVITY	Riskiness of many recent requests and previous high-risk requests on the IIN and last digits of the credit card.
ISSUER_ID_NUMBER_SHOP_ID_VELOCITY	Risk of recent Issuer ID Number activity for the shop ID.
INTRACOUNTRY_DISTANCE	Risk of distance between IP, billing, and shipping location.
ANONYMOUS_IP	Risk due to IP being an Anonymous IP.
IP_BILLING_POSTAL_VELOCITY	Velocity of distinct billing postal code on IP address.
IP_EMAIL_VELOCITY	Velocity of distinct email address on IP address.
IP_HIGH_RISK_DEVICE	High-risk device sighted on IP address.
IP_ISSUER_ID_NUMBER_VELOCITY	Velocity of distinct IIN on IP address.
IP_ACTIVITY	Riskiness of IP based on minFraud network activity.
LANGUAGE	Riskiness of browser language.
MAX_RECENT_EMAIL	Riskiness of email address based on past minFraud risk scores on email.
MAX_RECENT_PHONE	Riskiness of phone number based on past minFraud risk scores on phone.
MAX_RECENT_SHIP	Riskiness of email address based on past minFraud risk scores on ship address.
MULTIPLE_CUSTOMER_ID_ON_EMAIL	Riskiness of email address having many customer IDs.
ORDER_AMOUNT	Riskiness of the order amount.
ORG_DISTANCE_RISK	Risk of ISP and distance between billing address and IP location.
PHONE	Riskiness of the phone number or related numbers.
CART	Riskiness of shopping cart contents.
TIME_OF_DAY	Risk due to local time of day.
TRANSACTION_REPORT_EMAIL	Risk due to transaction reports on the email address.
TRANSACTION_REPORT_IP	Risk due to transaction reports on the IP address.
TRANSACTION_REPORT_PHONE	Risk due to transaction reports on the phone number.
TRANSACTION_REPORT_SHIP	Risk due to transaction reports on the shipping address.
EMAIL_ACTIVITY	Riskiness of the email address based on minFraud network activity.
PHONE_ACTIVITY	Riskiness of the phone number based on minFraud network activity.
SHIP_ACTIVITY	Riskiness of ship address based on minFraud network activity.

format: enum, max length: 255

minFraud Score minFraud Insights minFraud Factors

reason

string

The human-readable description of the risk reason.

minFraud Score minFraud Insights minFraud Factors

Subscores

Risk factor scores are deprecated as of November 4, 2024. Please review risk score reasons for insight into why a risk score is high or low.

This object contains risk factor scores for many of the individual components that are used in calculating the risk_score. Learn more about risk factor scores on our Knowledge Base.

This object is only included with minFraud Factors. Learn more about the differences between the minFraud services on our Knowledge Base.

 1{
 2  "avs_result": 0.01,
 3  "billing_address": 0.02,
 4  "billing_address_distance_to_ip_location": 0.03,
 5  "browser": 0.04,
 6  "chargeback": 0.05,
 7  "country": 0.06,
 8  "country_mismatch": 0.07,
 9  "cvv_result": 0.08,
10  "device": 0.09,
11  "email_address": 0.1,
12  "email_domain": 0.11,
13  "email_local_part": 0.12,
14  "issuer_id_number": 0.13,
15  "order_amount": 0.14,
16  "phone_number": 0.15,
17  "shipping_address": 0.16,
18  "shipping_address_distance_to_ip_location": 0.17,
19  "time_of_day": 0.18
20}

Key	Value Type	Description
`avs_result`	decimal	This field has been deprecated. The risk associated with the AVS result. If present, this is a value in the range 0.01 to 99. min: 0.01, max: 99 minFraud Score minFraud Insights minFraud Factors
`billing_address`	decimal	This field has been deprecated. The risk associated with the billing address. If present, this is a value in the range 0.01 to 99. Learn how to use the billing address risk score for risk analysis on our Knowledge Base. min: 0.01, max: 99 minFraud Score minFraud Insights minFraud Factors
`billing_address_distance_to_ip_location`	decimal	This field has been deprecated. The risk associated with the distance between the billing address and the location for the given IP address. If present, this is a value in the range 0.01 to 99. Learn how to use the billing address distance risk score for risk analysis on our Knowledge Base. min: 0.01, max: 99 minFraud Score minFraud Insights minFraud Factors
`browser`	decimal	This field has been deprecated. The risk associated with the browser attributes such as the `User-Agent` and`Accept-Language`. If present, this is a value in the range 0.01 to 99. Learn how to use the browser risk score for risk analysis on our Knowledge Base. min: 0.01, max: 99 minFraud Score minFraud Insights minFraud Factors
`chargeback`	decimal	This field has been deprecated. Risk of IP address based on the number of chargebacks and high risk activity sighted on your account and shop ID from similar IP networks. This is only available to users sending chargeback data to MaxMind. If present, this is a value in the range 0.01 to 99. Learn how to use the chargeback risk score for risk analysis on our Knowledge Base. min: 0.01, max: 99 minFraud Score minFraud Insights minFraud Factors
`country`	decimal	This field has been deprecated. The risk associated with the country the transaction originated from. If present, this is a value in the range 0.01 to 99. Learn how to use the country risk score for risk analysis on our Knowledge Base. min: 0.01, max: 99 minFraud Score minFraud Insights minFraud Factors
`country_mismatch`	decimal	This field has been deprecated. The risk associated with the combination of IP country, card issuer country, billing country, and shipping country. If present, this is a value in the range 0.01 to 99. Learn how to use the country mismatch risk score for risk analysis on our Knowledge Base. min: 0.01, max: 99 minFraud Score minFraud Insights minFraud Factors
`cvv_result`	decimal	This field has been deprecated. The risk associated with the CVV result. If present, this is a value in the range 0.01 to 99. Learn how to use the CVV result risk score for risk analysis on our Knowledge Base. min: 0.01, max: 99 minFraud Score minFraud Insights minFraud Factors
`device`	decimal	This field has been deprecated. The risk associated with the device. If present, this is a value in the range 0.01 to 99. You must have device tracking enabled on your site to receive this risk factor score. Learn more about device tracking on our Knowledge Base. Learn how to use the device risk score for risk analysis on our Knowledge Base. min: 0.01, max: 99 minFraud Score minFraud Insights minFraud Factors
`email_address`	decimal	This field has been deprecated. The risk associated with the particular email address. If present, this is a value in the range 0.01 to 99. Learn how to use the email risk score for risk analysis on our Knowledge Base. min: 0.01, max: 99 minFraud Score minFraud Insights minFraud Factors
`email_domain`	decimal	This field has been deprecated. The general risk associated with the email domain. If present, this is a value in the range 0.01 to 99. Learn how to use the email domain risk score for risk analysis on our Knowledge Base. min: 0.01, max: 99 minFraud Score minFraud Insights minFraud Factors
`email_local_part`	decimal	This field has been deprecated. The risk associated with the email address local part (the part of the email address before the @ symbol). If present, this is a value in the range 0.01 to 99. Learn how to use the email local part risk score for risk analysis on our Knowledge Base. min: 0.01, max: 99 minFraud Score minFraud Insights minFraud Factors
`email_tenure`	undefined	This field has been deprecated. Please use the `email_address` risk factor score instead. min: 0.01, max: 99 minFraud Score minFraud Insights minFraud Factors
`ip_tenure`	undefined	This field has been deprecated. Please use `risk_score` instead. min: 0.01, max: 99 minFraud Score minFraud Insights minFraud Factors
`issuer_id_number`	decimal	This field has been deprecated. The risk associated with the particular issuer ID number (IIN) given the billing location and the history of usage of the IIN on your account and shop ID. If present, this is a value in the range 0.01 to 99. Learn how to use the IIN risk score for risk analysis on our Knowledge Base. min: 0.01, max: 99 minFraud Score minFraud Insights minFraud Factors
`order_amount`	decimal	This field has been deprecated. The risk associated with the particular order amount for your account and shop ID. If present, this is a value in the range 0.01 to 99. Learn how to use the order amount risk score for risk analysis on our Knowledge Base. min: 0.01, max: 99 minFraud Score minFraud Insights minFraud Factors
`phone_number`	decimal	This field has been deprecated. The risk associated with the particular phone number. If present, this is a value in the range 0.01 to 99. Learn how to use the phone number risk score for risk analysis on our Knowledge Base. min: 0.01, max: 99 minFraud Score minFraud Insights minFraud Factors
`shipping_address`	decimal	This field has been deprecated. The risk associated with the shipping address. If present, this is a value in the range 0.01 to 99. Learn how to use the shipping address risk score for risk analysis on our Knowledge Base. min: 0.01, max: 99 minFraud Score minFraud Insights minFraud Factors
`shipping_address_distance_to_ip_location`	decimal	This field has been deprecated. The risk associated with the distance between the shipping address and the location for the given IP address. If present, this is a value in the range 0.01 to 99. Learn how to use the shipping address distance risk score for risk analysis on our Knowledge Base. min: 0.01, max: 99 minFraud Score minFraud Insights minFraud Factors
`time_of_day`	decimal	This field has been deprecated. The risk associated with the local time of day of the transaction in the IP address location. If present, this is a value in the range 0.01 to 99. Learn how to use the time of day risk score for risk analysis on our Knowledge Base. min: 0.01, max: 99 minFraud Score minFraud Insights minFraud Factors

Warnings

This array contains warning objects detailing issues with the request that was sent such as invalid or unknown inputs. It is highly recommended that you check this array for issues when integrating the web service.

1[
2  {
3    "code": "INPUT_INVALID",
4    "input_pointer": "/shipping/city",
5    "warning": "Encountered value at /shipping/city that does not meet the required constraints"
6  }
7]

Key Value Type Description

code

string

This value is a machine-readable code identifying the warning. Although more codes may be added in the future, the current codes are:

Code	Description
`BILLING_CITY_NOT_FOUND`	The billing city could not be found in our database. This may impact our ability to provide accurate distance calculations.
`BILLING_COUNTRY_MISSING`	Billing address information was provided without providing a billing country. This may impact our ability to provide accurate distance calculations.
`BILLING_COUNTRY_NOT_FOUND`	The billing country could not be found in our database. This may impact our ability to provide accurate distance calculations.
`BILLING_POSTAL_NOT_FOUND`	The billing postal could not be found in our database. This may impact our ability to provide accurate distance calculations.
`BILLING_REGION_NOT_FOUND`	The billing region could not be found in our database. This may impact our ability to provide accurate distance calculations.
`EMAIL_ADDRESS_UNUSABLE`	The email address entered is likely incorrect due to an integration issue. To avoid false positives, it has not been used in scoring. Check how you are passing your email address inputs.
`INPUT_INVALID`	The value associated with the key does not meet the required constraints, e.g., “United States” in a field that requires a two-letter country code.
`INPUT_UNKNOWN`	An unknown key was encountered in the request body.
`IP_ADDRESS_INVALID`	The IP address supplied is not a valid IPv4 or IPv6 address.
`IP_ADDRESS_NOT_FOUND`	The IP address could not be geolocated.
`IP_ADDRESS_RESERVED`	The IP address supplied is in a reserved network.
`SHIPPING_CITY_NOT_FOUND`	The shipping city could not be found in our database. This may impact our ability to provide accurate distance calculations.
`SHIPPING_COUNTRY_MISSING`	Shipping address information was provided without providing a shipping country. This may impact our ability to provide accurate distance calculations.
`SHIPPING_COUNTRY_NOT_FOUND`	The shipping country could not be found in our database. This may impact our ability to provide accurate distance calculations.
`SHIPPING_POSTAL_NOT_FOUND`	The shipping postal could not be found in our database. This may impact our ability to provide accurate distance calculations.
`SHIPPING_REGION_NOT_FOUND`	The shipping region could not be found in our database. This may impact our ability to provide accurate distance calculations.

max length: 255

minFraud Score minFraud Insights minFraud Factors

warning

string

This field provides a human-readable explanation of the warning. The description may change at any time and should not be matched against.

max length: 255

minFraud Score minFraud Insights minFraud Factors

input_pointer

string

A JSON Pointer to the input field that the warning is associated with. For instance, if the warning was about the billing city, this would be /billing/city. If it was for the price in the second shopping cart item, it would be /shopping_cart/1/price

format: json pointer

minFraud Score minFraud Insights minFraud Factors

Example Response Bodies

Each service returns data as a JSON document. The document that is returned always consists of an object (aka map or hash). Below are full examples of the JSON body document for the minFraud Score, minFraud Insights, and minFraud Factors services, and a full example of the JSON body document for an error.

minFraud Score Body Example

 1{
 2  "disposition": {
 3    "action": "accept",
 4    "reason": "default",
 5    "rule_label": "my_custom_rule"
 6  },
 7  "funds_remaining": 25,
 8  "id": "5bc5d6c2-b2c8-40af-87f4-6d61af86b6ae",
 9  "ip_address": {
10    "risk": 0.01
11  },
12  "queries_remaining": 5000,
13  "risk_score": 0.01,
14  "warnings": [
15    {
16      "code": "INPUT_INVALID",
17      "input_pointer": "/shipping/city",
18      "warning": "Encountered value at /shipping/city that does not meet the required constraints"
19    }
20  ]
21}

minFraud Insights Body Example

  1{
  2  "disposition": {
  3    "action": "accept",
  4    "reason": "default",
  5    "rule_label": "my_custom_rule"
  6  },
  7  "funds_remaining": 25,
  8  "id": "5bc5d6c2-b2c8-40af-87f4-6d61af86b6ae",
  9  "ip_address": {
 10    "risk": 0.01,
 11    "city": {
 12      "confidence": 25,
 13      "geoname_id": 54321,
 14      "names": {
 15        "de": "Los Angeles",
 16        "en": "Los Angeles",
 17        "es": "Los Ángeles",
 18        "fr": "Los Angeles",
 19        "ja": "ロサンゼルス市",
 20        "pt-BR": "Los Angeles",
 21        "ru": "Лос-Анджелес",
 22        "zh-CN": "洛杉矶"
 23      }
 24    },
 25    "continent": {
 26      "code": "NA",
 27      "geoname_id": 123456,
 28      "names": {
 29        "de": "Nordamerika",
 30        "en": "North America",
 31        "es": "América del Norte",
 32        "fr": "Amérique du Nord",
 33        "ja": "北アメリカ",
 34        "pt-BR": "América do Norte",
 35        "ru": "Северная Америка",
 36        "zh-CN": "北美洲"
 37      }
 38    },
 39    "country": {
 40      "confidence": 75,
 41      "geoname_id": 6252001,
 42      "is_in_european_union": true,
 43      "iso_code": "US",
 44      "names": {
 45        "de": "USA",
 46        "en": "United States",
 47        "es": "Estados Unidos",
 48        "fr": "États-Unis",
 49        "ja": "アメリカ合衆国",
 50        "pt-BR": "Estados Unidos",
 51        "ru": "США",
 52        "zh-CN": "美国"
 53      }
 54    },
 55    "location": {
 56      "accuracy_radius": 20,
 57      "average_income": 50321,
 58      "latitude": 37.6293,
 59      "local_time": "2015-04-26T01:37:17-08:00",
 60      "longitude": -122.1163,
 61      "metro_code": 807,
 62      "population_density": 7122,
 63      "time_zone": "America/Los_Angeles"
 64    },
 65    "postal": {
 66      "code": "90001",
 67      "confidence": 10
 68    },
 69    "registered_country": {
 70      "geoname_id": 6252001,
 71      "is_in_european_union": true,
 72      "iso_code": "US",
 73      "names": {
 74        "de": "USA",
 75        "en": "United States",
 76        "es": "Estados Unidos",
 77        "fr": "États-Unis",
 78        "ja": "アメリカ合衆国",
 79        "pt-BR": "Estados Unidos",
 80        "ru": "США",
 81        "zh-CN": "美国"
 82      }
 83    },
 84    "represented_country": {
 85      "geoname_id": 6252001,
 86      "is_in_european_union": true,
 87      "iso_code": "US",
 88      "names": {
 89        "de": "USA",
 90        "en": "United States",
 91        "es": "Estados Unidos",
 92        "fr": "États-Unis",
 93        "ja": "アメリカ合衆国",
 94        "pt-BR": "Estados Unidos",
 95        "ru": "США",
 96        "zh-CN": "美国"
 97      },
 98      "type": "military"
 99    },
100    "risk_reasons": [
101      {
102        "code": "ANONYMOUS_IP",
103        "reason": "The IP address belongs to an anonymous network. See /ip_address/traits for more details."
104      },
105      {
106        "code": "MINFRAUD_NETWORK_ACTIVITY",
107        "reason": "Suspicious activity has been seen on this IP address across minFraud customers."
108      }
109    ],
110    "subdivisions": [
111      {
112        "confidence": 50,
113        "geoname_id": 5332921,
114        "iso_code": "CA",
115        "names": {
116          "de": "Kalifornien",
117          "en": "California",
118          "es": "California",
119          "fr": "Californie",
120          "ja": "カリフォルニア",
121          "ru": "Калифорния",
122          "zh-CN": "加州"
123        }
124      }
125    ],
126    "traits": {
127      "autonomous_system_number": 1239,
128      "autonomous_system_organization": "Linkem IR WiMax Network",
129      "connection_type": "Cable/DSL",
130      "domain": "example.com",
131      "ip_address": "1.2.3.4",
132      "is_anonymous": true,
133      "is_anonymous_proxy": true,
134      "is_anonymous_vpn": true,
135      "is_anycast": true,
136      "is_hosting_provider": true,
137      "is_public_proxy": true,
138      "is_residential_proxy": true,
139      "is_satellite_provider": true,
140      "is_tor_exit_node": true,
141      "isp": "Linkem spa",
142      "mobile_country_code": "310",
143      "mobile_network_code": "004",
144      "network": "1.2.3.0/24",
145      "organization": "Linkem IR WiMax Network",
146      "static_ip_score": 1.5,
147      "user_count": 1,
148      "user_type": "traveler"
149    }
150  },
151  "queries_remaining": 5000,
152  "risk_score": 0.01,
153  "warnings": [
154    {
155      "code": "INPUT_INVALID",
156      "input_pointer": "/shipping/city",
157      "warning": "Encountered value at /shipping/city that does not meet the required constraints"
158    }
159  ],
160  "billing_address": {
161    "distance_to_ip_location": 100,
162    "is_in_ip_country": true,
163    "is_postal_in_city": true,
164    "latitude": 37.545,
165    "longitude": -122.421
166  },
167  "billing_phone": {
168    "country": "US",
169    "is_voip": true,
170    "network_operator": "Verizon/1",
171    "number_type": "fixed"
172  },
173  "credit_card": {
174    "brand": "Visa",
175    "country": "US",
176    "is_business": true,
177    "is_issued_in_billing_address_country": true,
178    "is_prepaid": true,
179    "is_virtual": true,
180    "issuer": {
181      "matches_provided_name": true,
182      "matches_provided_phone_number": true,
183      "name": "Bank of America",
184      "phone_number": "800-732-9194"
185    },
186    "type": "credit"
187  },
188  "device": {
189    "confidence": 99,
190    "id": "7835b099-d385-4e5b-969e-7df26181d73b",
191    "last_seen": "2016-06-08T14:16:38Z",
192    "local_time": "2018-01-02T10:40:11-08:00"
193  },
194  "email": {
195    "domain": {
196      "first_seen": "2015-01-20"
197    },
198    "first_seen": "2016-02-03",
199    "is_disposable": false,
200    "is_free": false,
201    "is_high_risk": true
202  },
203  "shipping_address": {
204    "distance_to_billing_address": 22,
205    "distance_to_ip_location": 15,
206    "is_high_risk": true,
207    "is_in_ip_country": true,
208    "is_postal_in_city": true,
209    "latitude": 37.632,
210    "longitude": -122.313
211  },
212  "shipping_phone": {
213    "country": "CA",
214    "is_voip": true,
215    "network_operator": "Telus Mobility-SVR/2",
216    "number_type": "mobile"
217  }
218}

minFraud Factors Body Example

  1{
  2  "disposition": {
  3    "action": "accept",
  4    "reason": "default",
  5    "rule_label": "my_custom_rule"
  6  },
  7  "funds_remaining": 25,
  8  "id": "5bc5d6c2-b2c8-40af-87f4-6d61af86b6ae",
  9  "ip_address": {
 10    "risk": 0.01,
 11    "city": {
 12      "confidence": 25,
 13      "geoname_id": 54321,
 14      "names": {
 15        "de": "Los Angeles",
 16        "en": "Los Angeles",
 17        "es": "Los Ángeles",
 18        "fr": "Los Angeles",
 19        "ja": "ロサンゼルス市",
 20        "pt-BR": "Los Angeles",
 21        "ru": "Лос-Анджелес",
 22        "zh-CN": "洛杉矶"
 23      }
 24    },
 25    "continent": {
 26      "code": "NA",
 27      "geoname_id": 123456,
 28      "names": {
 29        "de": "Nordamerika",
 30        "en": "North America",
 31        "es": "América del Norte",
 32        "fr": "Amérique du Nord",
 33        "ja": "北アメリカ",
 34        "pt-BR": "América do Norte",
 35        "ru": "Северная Америка",
 36        "zh-CN": "北美洲"
 37      }
 38    },
 39    "country": {
 40      "confidence": 75,
 41      "geoname_id": 6252001,
 42      "is_in_european_union": true,
 43      "iso_code": "US",
 44      "names": {
 45        "de": "USA",
 46        "en": "United States",
 47        "es": "Estados Unidos",
 48        "fr": "États-Unis",
 49        "ja": "アメリカ合衆国",
 50        "pt-BR": "Estados Unidos",
 51        "ru": "США",
 52        "zh-CN": "美国"
 53      }
 54    },
 55    "location": {
 56      "accuracy_radius": 20,
 57      "average_income": 50321,
 58      "latitude": 37.6293,
 59      "local_time": "2015-04-26T01:37:17-08:00",
 60      "longitude": -122.1163,
 61      "metro_code": 807,
 62      "population_density": 7122,
 63      "time_zone": "America/Los_Angeles"
 64    },
 65    "postal": {
 66      "code": "90001",
 67      "confidence": 10
 68    },
 69    "registered_country": {
 70      "geoname_id": 6252001,
 71      "is_in_european_union": true,
 72      "iso_code": "US",
 73      "names": {
 74        "de": "USA",
 75        "en": "United States",
 76        "es": "Estados Unidos",
 77        "fr": "États-Unis",
 78        "ja": "アメリカ合衆国",
 79        "pt-BR": "Estados Unidos",
 80        "ru": "США",
 81        "zh-CN": "美国"
 82      }
 83    },
 84    "represented_country": {
 85      "geoname_id": 6252001,
 86      "is_in_european_union": true,
 87      "iso_code": "US",
 88      "names": {
 89        "de": "USA",
 90        "en": "United States",
 91        "es": "Estados Unidos",
 92        "fr": "États-Unis",
 93        "ja": "アメリカ合衆国",
 94        "pt-BR": "Estados Unidos",
 95        "ru": "США",
 96        "zh-CN": "美国"
 97      },
 98      "type": "military"
 99    },
100    "risk_reasons": [
101      {
102        "code": "ANONYMOUS_IP",
103        "reason": "The IP address belongs to an anonymous network. See /ip_address/traits for more details."
104      },
105      {
106        "code": "MINFRAUD_NETWORK_ACTIVITY",
107        "reason": "Suspicious activity has been seen on this IP address across minFraud customers."
108      }
109    ],
110    "subdivisions": [
111      {
112        "confidence": 50,
113        "geoname_id": 5332921,
114        "iso_code": "CA",
115        "names": {
116          "de": "Kalifornien",
117          "en": "California",
118          "es": "California",
119          "fr": "Californie",
120          "ja": "カリフォルニア",
121          "ru": "Калифорния",
122          "zh-CN": "加州"
123        }
124      }
125    ],
126    "traits": {
127      "autonomous_system_number": 1239,
128      "autonomous_system_organization": "Linkem IR WiMax Network",
129      "connection_type": "Cable/DSL",
130      "domain": "example.com",
131      "ip_address": "1.2.3.4",
132      "is_anonymous": true,
133      "is_anonymous_proxy": true,
134      "is_anonymous_vpn": true,
135      "is_anycast": true,
136      "is_hosting_provider": true,
137      "is_public_proxy": true,
138      "is_residential_proxy": true,
139      "is_satellite_provider": true,
140      "is_tor_exit_node": true,
141      "isp": "Linkem spa",
142      "mobile_country_code": "310",
143      "mobile_network_code": "004",
144      "network": "1.2.3.0/24",
145      "organization": "Linkem IR WiMax Network",
146      "static_ip_score": 1.5,
147      "user_count": 1,
148      "user_type": "traveler"
149    }
150  },
151  "queries_remaining": 5000,
152  "risk_score": 0.01,
153  "warnings": [
154    {
155      "code": "INPUT_INVALID",
156      "input_pointer": "/shipping/city",
157      "warning": "Encountered value at /shipping/city that does not meet the required constraints"
158    }
159  ],
160  "billing_address": {
161    "distance_to_ip_location": 100,
162    "is_in_ip_country": true,
163    "is_postal_in_city": true,
164    "latitude": 37.545,
165    "longitude": -122.421
166  },
167  "billing_phone": {
168    "country": "US",
169    "is_voip": true,
170    "network_operator": "Verizon/1",
171    "number_type": "fixed"
172  },
173  "credit_card": {
174    "brand": "Visa",
175    "country": "US",
176    "is_business": true,
177    "is_issued_in_billing_address_country": true,
178    "is_prepaid": true,
179    "is_virtual": true,
180    "issuer": {
181      "matches_provided_name": true,
182      "matches_provided_phone_number": true,
183      "name": "Bank of America",
184      "phone_number": "800-732-9194"
185    },
186    "type": "credit"
187  },
188  "device": {
189    "confidence": 99,
190    "id": "7835b099-d385-4e5b-969e-7df26181d73b",
191    "last_seen": "2016-06-08T14:16:38Z",
192    "local_time": "2018-01-02T10:40:11-08:00"
193  },
194  "email": {
195    "domain": {
196      "first_seen": "2015-01-20"
197    },
198    "first_seen": "2016-02-03",
199    "is_disposable": false,
200    "is_free": false,
201    "is_high_risk": true
202  },
203  "shipping_address": {
204    "distance_to_billing_address": 22,
205    "distance_to_ip_location": 15,
206    "is_high_risk": true,
207    "is_in_ip_country": true,
208    "is_postal_in_city": true,
209    "latitude": 37.632,
210    "longitude": -122.313
211  },
212  "shipping_phone": {
213    "country": "CA",
214    "is_voip": true,
215    "network_operator": "Telus Mobility-SVR/2",
216    "number_type": "mobile"
217  },
218  "risk_score_reasons": [
219    {
220      "multiplier": 45,
221      "reasons": [
222        {
223          "code": "ANONYMOUS_IP",
224          "reason": "Risk due to IP being an Anonymous IP"
225        }
226      ]
227    },
228    {
229      "multiplier": 1.8,
230      "reasons": [
231        {
232          "code": "TIME_OF_DAY",
233          "reason": "Risk due to local time of day"
234        }
235      ]
236    },
237    {
238      "multiplier": 1.6,
239      "reasons": [
240        {
241          "reason": "Riskiness of newly-sighted email domain",
242          "code": "EMAIL_DOMAIN_NEW"
243        }
244      ]
245    },
246    {
247      "multiplier": 0.34,
248      "reasons": [
249        {
250          "code": "EMAIL_ADDRESS_NEW",
251          "reason": "Riskiness of newly-sighted email address"
252        }
253      ]
254    }
255  ],
256  "subscores": {
257    "avs_result": 0.01,
258    "billing_address": 0.02,
259    "billing_address_distance_to_ip_location": 0.03,
260    "browser": 0.04,
261    "chargeback": 0.05,
262    "country": 0.06,
263    "country_mismatch": 0.07,
264    "cvv_result": 0.08,
265    "device": 0.09,
266    "email_address": 0.1,
267    "email_domain": 0.11,
268    "email_local_part": 0.12,
269    "issuer_id_number": 0.13,
270    "order_amount": 0.14,
271    "phone_number": 0.15,
272    "shipping_address": 0.16,
273    "shipping_address_distance_to_ip_location": 0.17,
274    "time_of_day": 0.18
275  }
276}

Error Body Example

1{
2  "code": "INSUFFICIENT_FUNDS",
3  "error": "You do not have sufficient funds to use this service."
4}

minFraud API Responses

On this page