Dispositions API

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 accept, reject, or manual_review.

After transactions are received, customers can use the minFraud Interactive interface to review all transactions dispositioned as manual_review. Transactions can then either be accepted or rejected, and/or have a note added. In order for these manual updates made in minFraud Interactive 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 transactions.

Release Notes

Changes to the minFraud web services (including the Dispositions API) are documented in our release notes.

The Request

Request URI

API calls should be made with HTTP GET request to https://minfraud.maxmind.com/minfraud/disposition/v1.0/updates

Request Headers

The Accept header for a request is entirely optional. If you do include one, you must accept one of the following:

• application/json
• application/vnd.maxmind.com-disposition-updates+json
• 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 response, because this data is only available in UTF-8.

Request Authorization

The HTTP Authorization header is required for authorization. The username is your MaxMind account ID. The password is your MaxMind license key. You must request a demo or subscribe to one of our web services in order to receive an account ID and license key. The authorization realm is `minfraud`.

We use basic HTTP authentication. The APIs which require authentication are only available via HTTPS. The credentials are never transmitted unencrypted. If you attempt to access this service via HTTP, you will receive a 403 Forbidden HTTP response.

Request Parameters

The request must consist of a single URL parameter:

Key	Value Type	Description
updates_after	Timestamp	An exclusive lower bound for the updates in RFC 3339 format. Only updates made after this time will be returned.

Example Request Parameters

?updates_after=2017-03-16T00:00:00.04353Z

The Response

Response Headers

The Content-Type header will vary based on whether the request was successful or not, and is detailed further in each of the two Response Body sections below.

The response will always include a Content-Length header.

Response Body (for successful requests)

The Content-Type header for a successful response will be application/vnd.maxmind.com-disposition-updates+json; charset=UTF-8; version=1.0

Data will be returned as a JSON document in UTF-8 encoding. The document will include two keys: last_update_timestamp and updates. The 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). The 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 updates_after 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 last_update_timestamp value returned from the previous request.

Each transaction in the updates array will contain the following keys:

Key	Value Type	Description
minfraud_id	UUID	The transaction’s unique identifier.
action	String	The most recent transaction disposition action. In addition to the actions described in the minFraud documentation, you may also see `expired_review`, which indicates the manual review period (1 week) expired before the transaction was reviewed.
action_last_updated	Timestamp	The date and time the disposition action was last updated, in RFC 3339 format with microsecond precision.
note	String	The most recent transaction note. Limited to 500 characters.
note_last_updated	Timestamp	The date and time the note was last updated, in RFC 3339 format with microsecond precision.

In the event a transaction’s note isn’t currently set, the note field will be null. In the event a transaction’s note has never been set, the note_last_updated will also be null. As a note to implementers, we’re considering adding additional keys to this object in future versions of this API.

Example Response (for a successful request)

{
    "last_update_timestamp": "2017-03-15T22:06:56.848123Z",
    "updates": [
        {
            "minfraud_id": "deadbeef-0000-0000-0000-00000000",
            "action": "accept",
            "action_last_updated": "2017-03-14T22:04:01.04425Z",
            "note": null,
            "note_last_updated": null
        },
        {
            "minfraud_id": "deadbeef-0000-0000-0000-00000002",
            "action": "reject",
            "action_last_updated": "2017-03-14T21:39:57.854300Z",
            "note": null,
            "note_last_updated": "2017-03-15T11:37:42.83235Z"
        },
        {
            "minfraud_id": "deadbeef-0000-0000-0000-00000003",
            "action": "manual_review",
            "action_last_updated": "2017-03-04T20:14:42.757200Z",
            "note": null,
            "note_last_updated": "2017-03-05T16:52:31.995250Z"
        },
        {
            "minfraud_id": "deadbeef-0000-0000-0000-00000020",
            "action": "manual_review",
            "action_last_updated": "2017-03-15T22:04:11.044250Z",
            "note": "Ndapanda, can you check this out?",
            "note_last_updated": "2017-03-15T22:04:25.828250Z"
        },
        {
            "minfraud_id": "deadbeef-0000-0000-0000-00000030",
            "action": "accept",
            "action_last_updated": "2017-03-15T22:05:42.954231Z",
            "note": "Customer was travelling abroad.",
            "note_last_updated": "2017-03-15T22:05:58.132423Z"
        },
        {
            "minfraud_id": "deadbeef-0000-0000-0000-00000050",
            "action": "expired_review",
            "action_last_updated": "2017-03-15T22:06:22.492945Z",
            "note": "Customer didn't answer several phone calls.",
            "note_last_updated": "2017-03-15T22:06:56.848123Z"
        }
    ]
}

Response Body (for unsuccessful requests)

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 response is application/vnd.maxmind.com-error+json; charset=UTF-8; version=1.0.

If the JSON document is included in the response body, it will be 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 any 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.

Code	HTTP Status	Error
UPDATES_AFTER_REQUIRED	400 Bad Request	You have not supplied the updates_after URI parameter.
TIMESTAMP_INVALID	400 Bad Request	The updates_after field must be in RFC 3339 format.
PARAMETER_UNKNOWN	400 Bad Request	You have supplied one or more parameters which are not used by this endpoint.
AUTHORIZATION_INVALID	401 Unauthorized	Your account ID or license key could not be authenticated.
LICENSE_KEY_REQUIRED	401 Unauthorized	An account ID and license key are required to use this service.
USER_ID_REQUIRED	401 Unauthorized	An account ID and license key are required to use this service.
PERMISSION_REQUIRED	403 Forbidden	You do not have permission to use the service. Please contact support@maxmind.com for more information.
(none)	406 Not Acceptable	Your request included an Accept-Charset header that is not supported. UTF-8 is the only acceptable character set.
(none)	415 Unsupported Media Type	Your request included an Accept header that is not supported. The web service cannot return content of that type.
(none)	503 Service Not Available	There is a problem with the web service server. You can try this request again later.

Example Response (for an unsuccessful request)

{
    "code": "USER_ID_REQUIRED",
    "error": "You have not supplied a MaxMind account ID in the Authorization header"
}