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.

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. For detailed explanations of each property within the response body, please refer to the object reference section below.

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

402 Payment Required

You do not have permission to use the service. Please contact support@maxmind.com 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.

Object Reference

Each schema definition contains a description of an object, along with a list of properties that belong to the object. The following information is listed for each object property:

  • name
  • type (array<type>, boolean, number, integer, object, string)
  • description
  • example
  • formatting
  • constraints
  • supported services (Score, Factors, Insights)

Additionally, for object properties, a link is provided to view a schema definition that further describes that specific object.

  • Keys with undefined or empty values will not be included in the returned in the response object.

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

  • 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.

Responseobject

The following is an example of a complete minFraud Factors response, including all available outputs. In practice, fewer outputs may be returned based on the minFraud service you query and the inputs provided.

Example
idstring

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.

Example
Format: UUID
ScoreInsightsFactors
risk_scorenumber

This field contains the 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.

Example
Format: decimalMin: 0.01Max: 99
ScoreInsightsFactors
funds_remainingnumber

The approximate US dollar value of the funds remaining on your MaxMind account.

Example
Format: decimalMin: 0
ScoreInsightsFactors
queries_remaininginteger

The approximate number of queries remaining for the service before your account runs out of funds.

Example
Min: 0
ScoreInsightsFactors
ip_addressobject

This object contains a risk score and (for minFraud Insights and Factors requests) risk data for the IP address associated with the event.

Example
ScoreInsightsFactors
credit_cardobject

This object contains minFraud information related to the credit card.

Example
ScoreInsightsFactors
deviceobject

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

Example
ScoreInsightsFactors
emailobject

This object contains information about the email address passed in the request.

Example
ScoreInsightsFactors
shipping_addressobject

This object contains minFraud response data associated with the shipping address. If the shipping address was not provided in the request or could not be parsed, this object will not be present in the response.

Example
ScoreInsightsFactors
billing_addressobject

This object contains minFraud response data associated with the billing address. If the billing address was not provided in the request or could not be parsed, this object will not be present in the response.

Example
ScoreInsightsFactors
dispositionobject

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.

Example
ScoreInsightsFactors
subscoresobject

This object contains subscores for many of the individual components that are used in calculating the risk_score.

Example
ScoreInsightsFactors
warningsarray

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.

Example
ScoreInsightsFactors

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:

  1. risk has been added directly to the ip_address object
  2. local_time has been added to the location sub-object
  3. The maxmind object is not present. See below for descriptions.
  4. 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.

Example
risknumber

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.

Example
Format: DecimalMin: 0.01Max: 99
ScoreInsightsFactors
countryobject

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

Example
ScoreInsightsFactors
locationobject

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

Example
ScoreInsightsFactors
risk_reasonsarray

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

Example
ScoreInsightsFactors

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

Example
is_high_riskbooleandeprecated

This field has been deprecated.

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

Example
local_timestring

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.

Example
Max Length: 255
ScoreInsightsFactors
Example

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

Example
codestring

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.

Example
EnumMax Length: 255
ScoreInsightsFactors
reasonstring

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.

Example
ScoreInsightsFactors

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.

Example
issuerobject

This field contains a JSON object with information relating to the credit card issuer.

Example
ScoreInsightsFactors
brandstring

The card brand, such as "Visa", "Discover", "American Express", etc.

Example
Max Length: 255
ScoreInsightsFactors
countrystring

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.

Example
Max Length: 2
ScoreInsightsFactors
is_businessboolean

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.

Example
ScoreInsightsFactors
is_issued_in_billing_address_countryboolean

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.

Example
ScoreInsightsFactors
is_prepaidboolean

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.

Example
ScoreInsightsFactors
is_virtualboolean

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.

Example
ScoreInsightsFactors
typestring

The card’s type. The valid values are:

  • charge – See Wikipedia for an explanation of the difference between charge and credit cards.
  • credit
  • debit
Example
Enum
ScoreInsightsFactors

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

Example
namestring

This field contains a JSON object with information relating to the credit card issuer.

Example
Max Length: 255
ScoreInsightsFactors
matches_provided_nameboolean

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.

Example
ScoreInsightsFactors
phone_numberstring

The phone number of the bank which issued the credit card. In some cases the phone number we return may be out of date.

Example
Max Length: 255
ScoreInsightsFactors
matches_provided_phone_numberboolean

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.

Example
ScoreInsightsFactors

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

Example
confidencenumber

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.

Example
Format: DecimalMin: 0.01Max: 99
ScoreInsightsFactors
idstring

A UUID that MaxMind uses for the device associated with this IP address. Note that many devices cannot be uniquely identified because they are too common (for example, all iPhones of a given model and OS release). In these cases, the minFraud service will simply not return a UUID for that device. This is only available if you are using the Device Tracking Add-on.

Example
Format: UUID
ScoreInsightsFactors
last_seenstring

The date and time of the last sighting of the device. The value is formatted according to RFC 3339.

Example
Max Length: 255
ScoreInsightsFactors
local_timestring

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.

Example
Max Length: 255
ScoreInsightsFactors
Example
domainobject

This field contains a JSON object with information relating to the domain.

Example
ScoreInsightsFactors
first_seenstring

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.

Example
Format: YYYY-MM-DDMax Length: 10
ScoreInsightsFactors
is_disposableboolean

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.

Example
ScoreInsightsFactors
is_freeboolean

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.

Example
ScoreInsightsFactors
is_high_riskboolean

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.

Example
ScoreInsightsFactors

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

Example
first_seenstring

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.

Example
Format: YYYY-MM-DDMax Length: 10
Example
is_high_riskboolean

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.

Example
ScoreInsightsFactors
is_postal_in_cityboolean

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.

Example
ScoreInsightsFactors
latitudenumber

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.

Example
Format: Decimal
ScoreInsightsFactors
longitudenumber

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.

Example
Format: Decimal
ScoreInsightsFactors
distance_to_ip_locationinteger

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.

Example
ScoreInsightsFactors
distance_to_billing_addressinteger

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.

Example
ScoreInsightsFactors
is_in_ip_countryboolean

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.

Example
ScoreInsightsFactors
Example
is_postal_in_cityboolean

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.

Example
ScoreInsightsFactors
latitudenumber

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.

Example
Format: Decimal
ScoreInsightsFactors
longitudenumber

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.

Example
Format: Decimal
ScoreInsightsFactors
distance_to_ip_locationinteger

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.

Example
ScoreInsightsFactors
is_in_ip_countryboolean

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.

Example
ScoreInsightsFactors

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.

Example
actionstring

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.

Example
Enum
ScoreInsightsFactors
reasonstring

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.

Example
Enum
ScoreInsightsFactors
rule_labelstring

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.

Example
ScoreInsightsFactors

This object contains subscores for many of the individual components that are used in calculating the risk_score.

This object is only included with minFraud Factors.

Example
billing_addressnumber

The risk associated with the billing address. If present, this is a value in the range 0.01 to 99.

Example
Format: DecimalMin: 0.01Max: 99
ScoreInsightsFactors
billing_address_distance_to_ip_locationnumber

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.

Example
Format: DecimalMin: 0.01Max: 99
ScoreInsightsFactors
browsernumber

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.

Example
Format: DecimalMin: 0.01Max: 99
ScoreInsightsFactors
chargebacknumber

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.

Example
Format: DecimalMin: 0.01Max: 99
ScoreInsightsFactors
countrynumber

The risk associated with the country the transaction originated from. If present, this is a value in the range 0.01 to 99.

Example
Format: DecimalMin: 0.01Max: 99
ScoreInsightsFactors
country_mismatchnumber

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.

Example
Format: DecimalMin: 0.01Max: 99
ScoreInsightsFactors
cvv_resultnumber

The risk associated with the CVV result. If present, this is a value in the range 0.01 to 99.

Example
Format: DecimalMin: 0.01Max: 99
ScoreInsightsFactors
devicenumber

The risk associated with the device. If present, this is a value in the range 0.01 to 99.

Example
Format: DecimalMin: 0.01Max: 99
ScoreInsightsFactors
email_addressnumber

The risk associated with the particular email address. If present, this is a value in the range 0.01 to 99.

Example
Format: DecimalMin: 0.01Max: 99
ScoreInsightsFactors
email_domainnumber

The general risk associated with the email domain. If present, this is a value in the range 0.01 to 99.

Example
Format: DecimalMin: 0.01Max: 99
ScoreInsightsFactors
email_local_partnumber

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.

Example
Format: DecimalMin: 0.01Max: 99
ScoreInsightsFactors
email_tenuredeprecated

This field has been deprecated. Please use email_address subscore instead.

ip_tenuredeprecated

This field has been deprecated. Please use risk_score subscore instead.

issuer_id_numbernumber

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.

Example
Format: DecimalMin: 0.01Max: 99
ScoreInsightsFactors
order_amountnumber

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.

Example
Format: DecimalMin: 0.01Max: 99
ScoreInsightsFactors
phone_numbernumber

The risk associated with the particular phone number. If present, this is a value in the range 0.01 to 99.

Example
Format: DecimalMin: 0.01Max: 99
ScoreInsightsFactors
shipping_addressnumber

The risk associated with the shipping address. If present, this is a value in the range 0.01 to 99.

Example
Format: DecimalMin: 0.01Max: 99
ScoreInsightsFactors
shipping_address_distance_to_ip_locationnumber

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.

Example
Format: DecimalMin: 0.01Max: 99
ScoreInsightsFactors
time_of_daynumber

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.

Example
Format: DecimalMin: 0.01Max: 99
ScoreInsightsFactors
Example

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.

Example
codestring

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.

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.

Example
Max Length: 255
warningstring

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

Example
Max Length: 255
input_pointerstring

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

Example
JSON Pointer

This page was last updated on October 13, 2021.