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 accept
ed or reject
ed, 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.
Authorization/Security
The HTTP Authorization header is required for authorization. The username is your MaxMind account ID. The password is your MaxMind license key. You must be approved for a trial or purchase credit for use with 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.
We require TLS 1.2 or greater for all requests to our servers to keep your data secure.
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. |
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 code
s 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"
}