minFraud API Responses
Headers
The Content-Type for a successful response varies based on the service as
outlined below:
Service | Content-Type |
|---|---|
Score |
|
Insights |
|
Factors |
|
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 |
|---|---|---|
| 400 Bad Request | We cannot decode the body as a JSON object. |
| 400 Bad Request | The request body is valid JSON but contains no valid input values. |
| 401 Unauthorized | You have supplied an invalid MaxMind account ID and/or license key in the Authorization header. |
| 401 Unauthorized | You have not supplied a MaxMind license key in the Authorization header. |
| 401 Unauthorized | You have not supplied a MaxMind account ID in the Authorization header. |
| 402 Payment Required | The license key you have provided does not have sufficient funds to use this service. Please purchase more service credits. |
| 403 Forbidden | 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 |
(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_cardkey or value.
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.
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.
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.
The approximate US dollar value of the funds remaining on your MaxMind account.
The approximate number of queries remaining for the service before your account runs out of funds.
This object contains a risk score and (for minFraud Insights and Factors requests) risk data for the IP address associated with the event.
This object contains information about the device that MaxMind believes is associated with the IP address passed in the request.
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.
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.
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.
This object contains risk factor scores for many of the individual
components that are used in calculating the risk_score.
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.
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:
riskhas been added directly to theip_addressobjectlocal_timehas been added to thelocationsub-objectThe
maxmindobject is not present. See below for descriptions.minFraud Insights and Factors return the following anonymous IP outputs:
is_anonymousis_anonymous_vpnis_hosting_provideris_public_proxyis_residential_proxyis_tor_exit_node
See the GeoIP2 Insights response body for more information.
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.
This object contains country-level geolocation data associated with the IP address associated with the event.
This object contains city-level geolocation data associated with the IP address associated with the event.
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.
This object contains country-level geolocation data associated with the IP address associated with the event
This object contains city-level geolocation data associated with the IP address associated with the event.
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.
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.
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 |
|---|---|
| The IP address belongs to an anonymous network. See the object at
|
| Many different billing postal codes have been seen on this IP address. |
| Many different email addresses have been seen on this IP address. |
| A high risk device was seen on this IP address. |
| A high risk email address was seen on this IP address in your past transactions. |
| Many different issuer ID numbers have been seen on this IP address. |
| 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.
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.
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.
This field contains a JSON object with information relating to the credit card issuer.
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.
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.
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.
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.
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.
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.
This is a sub-object of credit_card that contains information related to the
issuer of the card.
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.
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.
The phone number of the bank which issued the credit card. In some cases the phone number we return may be out of date.
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.
This object contains information about the device that MaxMind believes is associated with the IP address passed in the request.
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.
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.
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.
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.
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.
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.
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.
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.
This is a sub-object of email that contains information related to the
domain.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
This describes how the request was handled. The valid values are:
Action | Explanation |
|---|---|
| This is the default value that is used if none of your custom rules match the request. |
| |
| |
| This value can be used to test custom rules. |
This describes why the action was set to a particular value. The valid
values are:
Reason | Explanation |
|---|---|
| No custom rules matched the request. |
| A custom rule was applied and set the action. |
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.
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.
The risk associated with the AVS result. If present, this is a value in the range 0.01 to 99.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
This field has been deprecated. Please use the email_address risk
factor score instead.
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.
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.
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.
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.
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.
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.
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.
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 |
|---|---|
| The billing city could not be found in our database. This may impact our ability to provide accurate distance calculations. |
| Billing address information was provided without providing a billing country. This may impact our ability to provide accurate distance calculations. |
| The billing country could not be found in our database. This may impact our ability to provide accurate distance calculations. |
| The billing postal could not be found in our database. This may impact our ability to provide accurate distance calculations. |
| The billing region could not be found in our database. This may impact our ability to provide accurate distance calculations. |
| 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. |
| 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. |
| An unknown key was encountered in the request body. |
| The IP address supplied is not a valid IPv4 or IPv6 address. |
| The IP address could not be geolocated. |
| The IP address supplied is in a reserved network. |
| The shipping city could not be found in our database. This may impact our ability to provide accurate distance calculations. |
| Shipping address information was provided without providing a shipping country. This may impact our ability to provide accurate distance calculations. |
| The shipping country could not be found in our database. This may impact our ability to provide accurate distance calculations. |
| The shipping postal could not be found in our database. This may impact our ability to provide accurate distance calculations. |
| The shipping region could not be found in our database. This may impact our ability to provide accurate distance calculations. |
This field provides a human-readable explanation of the warning. The description may change at any time and should not be matched against.
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
This page was last updated on June 6, 2023.