With minFraud Interactive, customers can create Custom Rules that are used to
assign a disposition to every transaction received in a minFraud request.
Custom Rules can set a transaction’s disposition to
manual_review. For more information on Custom Rules and Dispositions, see the
documentation on our knowledge base.
After transactions are received, customers can use the account portal to review
all transactions dispositioned as
manual_review. Transactions can then either
rejected, and/or have a note added. Learn how to use the
account portal to do manual review on our knowledge
In order for these manual updates made in the account portal to be useful, they
need to find their way back into customers’ systems. The Dispositions API allows
customers to get a list of the manual updates and notes made to their
You only need to implement the Dispositions API if you (1) use the account portal to make manual changes to dispositions, and (2) require those changes to propagate to your own system.
To make a disposition request, you need the request URI and parameters, and your MaxMind account ID and license key.
API calls should be made with HTTP GET request to
We require a URL parameter called
updates_after with an RFC 3339 timestamp
value. This value is an exclusive lower bound for the updates; only updates
made after this time will be returned.
For example, to get updates after March 15, 2021 at 9 AM UTC, your request
would look like:
Accept header for a request is entirely optional. If you do include one,
you must accept one of the following:
application/vnd.maxmind.com-disposition-updates+json; charset=UTF-8; version=1.0
If you set the
Accept-Charset header in your client code, you must accept the
UTF-8 character set. If you don't you will receive a
406 Not Acceptable
Content-Type header for a successful response is
application/vnd.maxmind.com-disposition-updates+json; charset=UTF-8; version=1.0.
Content-Length header will be provided.
Data will be returned as a JSON document in UTF-8 encoding. The document will
include two keys:
last_update_timestamp value provides the relevant timestamp the last
returned transaction was sorted by, in RFC 3339 format (NB: this value is not
necessarily the earlier of the
*_last_updated keys of the last included
transaction; this is why it’s being provided explicitly).
updates value provides an array of transactions for
which the disposition and/or note have been manually updated, or, the
transaction’s manual review period has expired. The transactions will be sorted
from least recently updated to most recently updated, using the earliest
updated timestamp (either the disposition or note) after the
time for each transaction.
At most, 1000 updated transactions will be returned for any single request.
These will be the earliest updated transactions after the provided
updates_after timestamp, not the most recent. For each repeated request, the
updates_after request value should be replaced with the
value returned from the previous request.
Each transaction in the updates array will contain the following keys:
|UUID||The transaction’s unique identifier.|
|String||The most recent transaction disposition action. In addition to |
|Timestamp||The date and time the disposition action was last updated, in RFC 3339 format with microsecond precision.|
|String||The most recent transaction note. Limited to 500 characters. Will be |
|Timestamp||The date and time the note was last updated, in RFC 3339 format with microsecond precision. If a note has never been set, this will be |
As a note to implementers, we are considering adding additional keys to this object in future versions of this API.
Content-Type header for an unsuccessful response is
application/vnd.maxmind.com-error+json; charset=UTF-8; version=1.0.
Content-Length header will be provided.
In the event an error occurs (the response indicates a 4xx or 5xx HTTP status),
the response may include a JSON document in the body. An error in content
negotiation will not include a body, nor will many 5xx errors, which typically
happen outside of our web service handling code. Before attempting to decode
the body as JSON, you should verify that the
Content-Type of the error
If the JSON document is included in the response body, it will be a single
object with the keys
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.
In addition to the errors documented below, client code should also be prepared to handle any valid HTTP 4xx or 5xx status code.
|UPDATES_AFTER_REQUIRED||400 Bad Request||You have not supplied the |
|TIMESTAMP_INVALID||400 Bad Request||The |
|PARAMETER_UNKNOWN||400 Bad Request||You have supplied one or more parameters which are not used by this endpoint.|
|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.|
|PERMISSION_REQUIRED||403 Forbidden||You do not have permission to use the service. Please contact email@example.com for more information.|
|(none)||406 Not Acceptable||Your request included an |
|(none)||415 Unsupported Media Type||Your request included an |
|(none)||503 Service Not Available||There is a problem with the web service server. You can try this request again later.|
This page was last updated on September 29, 2022.