Welcome
The MX Platform API provides a wide range of features that allow banks, fintechs, and other financial institutions to give end users an exceptional experience. These include:
- Account and transaction data aggregation from tens of thousands of institutions.
- For some institutions, up to 24 months of transaction data can be gathered in a single request.
- Held data can be managed entirely on your own while still maintaining access to the other features of the API.
- Industry-leading data enhancement out of the box, including automatic transaction categorization and classification, custom categorization by end users, and description cleansing.
- Enhancement for non-aggregated data provided directly from your own systems.
- Account verification (often eliminating the need for cumbersome microdeposits) as well as owner identification.
- Personalization including transaction rules, custom tags, custom categories, and more.
- MX’s award-wining personal financial management widgets, including Connect, which automates aggregation and account verification.
- Pulse, our personalized, predictive financial management tool, either through our beautiful, pre-build user interface or through standard API resources.
- Merchant data for thousands of businesses and vendors.
New features are continually being added. Be on the lookout for access to credit card rewards data, automated and custom budgets, daily change files for all resources, end-user goals, and much more.
What should you do first?
Once you have your client ID and API key, you can start making test requests and creating resources right away. In the guides below and our full API reference, we provide easy-to-use code examples that you can copy into any terminal. Or you can download our Postman collection to get going even more quickly.
You must also log on to our client dashboard and whitelist any IP addresses that requests will originate from. If you don’t, you’ll run into 403 Forbidden
errors.
You should read through the important things you need to know shown below. You can also take a look at our guides on creating users and members, aggregating data, dealing with multi-factor authentication when aggregating, and reading account and transaction data.
As with all APIs, there are several requirements, standards, and conventions to keep in mind as you’re getting started.
You could skip a lot of this and dive right in to the step-by-step guides given below (especially if you’re already familiar with one or more of the older MX APIs) as long as you promise to come back to this important information soon. But it would definitely be worth looking at least at the sections on authentication and headers or you’ll run into errors very quickly.
API architecture and resource structure
The MX Platform API has many different resources and features, but once you break it down, it is centered around five major resource types. Virtually all the others are connected in one way or another with the resources described below.
Resource | Description |
---|---|
institution |
An institution represents a financial institution (FI) like Chase or Wells Fargo. It’s important to point out that many real-world FI will actually have several different institution objects within the MX Platform API. This is because, for example, the mortgage division of Wells Fargo might use a separate system than its everyday banking division, which is different from its credit card division, etc. |
user |
A user represents an end-user accessing the MX Platform API via your application, be it a mobile app, web app, desktop app, etc. |
member |
A member represents the relationship between a user and an institution . A user may have multiple members, one each for their bank, their mortgage broker, their credit card provider, etc. Aggregation, verification, and many other processes are centered around a member , meaning this is probably the most important type of object you’ll be working with. |
account |
An account represents a financial account held by an FI, e.g., a user’s checking or savings account. A member may have more than one account associated with it. For instance, a user may have both a checking and savings account associated with one Chase login and would therefore have two accounts associated with that member . |
transaction |
A transaction represents any instance in which money moves into or out of an account , such as a purchase at a business, a payroll deposit, a transfer from one account to another, an ATM withdrawal, etc. Each transaction belongs to only one account . |
Authentication and security
MX Platform API requests must be HTTPS with encryption TLSv1.2 or higher or else they will fail.
Requests are authorized with a Basic
token which requires the use of a client_id
and an api_key
.
The Basic
token is the URL-safe Base64 encoding of a string which contains both your client_id
and your api_key
separated by a colon. For example, where your client ID is CLIENT-1234
and your API key is API-KEY-4567
, your Basic
authorization token would be Q0xJRU5ULTEyMzQ6QVBJLUtFWS00NTY3
. See the example below.
The client_id
and api_key
for both the development and production environments are available in the client dashboard.
Because the values described above may grant access to some or all of your data, you must keep them secret and keep them safe. Do not share them in public areas, use them in client-side code, or otherwise use them in a way that may compromise their security.
In some instances, requests that require authentication will return 404 Not Found
, instead of 401 Unauthorized
. This is to prevent leaking private information.
Authorization header
Authorization: Basic {token}
Basic authorization token
Base64 encoding of:
{client_id}:{api_key}
Example
CLIENT-1234:API-KEY-4567 -> Q0xJRU5ULTEyMzQ6QVBJLUtFWS00NTY3
Base URL
MX uses separate base URLs for its development and production environments. All examples given use the development base URL.
Development URL
https://int-api.mx.com
Production URL
https://api.mx.com
Caching
Certain API resources are subject to change at any time; for instance, institutions. For this reason, we discourage you from caching lists of resources. If caching is necessary, we recommend refreshing a cached list at least daily.
Character encoding
Requests to the API must use characters encoded with the UTF-8 standard.
Data format
JSON structured data is expected in all requests and returned in all responses, including some errors.
Dates and times
Dates and times are always given in ISO 8601 format.
Fields which end in _on
are given without a timestamp: 2018-07-18
Fields which end in _at
are given with a timestamp: 2015-04-13T12:01:23-06:00
.
Errors
The MX Platform API uses conventional HTTP response codes to indicate the success or failure of a request, with supplementary error messaging as needed within response bodies.
Status codes
Status | Explanation |
---|---|
2xx Success | |
200 OK |
Everything worked as expected with content returned. |
202 Accepted |
1. Everything worked and MX’s system is processing the request. 2. When attempting an aggregation on a member , an aggregation of the same type is already running; e.g., calling aggregate member while a previous aggregation is still running, or calling verify member while a previous verification is still running. |
204 No Content |
Everything worked as expected without content returned. |
4xx Requester error | |
400 Bad Request |
Often, this means a required parameter was missing. |
401 Unauthorized |
Invalid MX-API-Key or MX-Client-ID provided. |
403 Forbidden |
The request was made from a non-whitelisted address. |
404 Not Found |
Invalid item/id/URL requested. |
405 Method Not Allowed |
A constraint on the requested endpoint wasn’t met. |
406 Not Acceptable |
The request didn’t specify a valid API version. |
409 Conflict |
1. An object with the given attributes already exists. 2. When attempting an aggregation on a member , the member already has an an aggregation of a different type running; e.g., calling the verify endpoint while a standard aggregation is already running, or calling fetch statements while an identification aggregation is already running. |
422 Unprocessable Entity |
The data provided cannot be processed. |
5xx Responder error — which are rare | |
500, 502, 504 Server errors |
Something went wrong with MX’s servers. |
503 Service Unavailable |
The MX Platform is being updated. |
Example error message
1
2
3
4
5
{
"error": {
"message": "Unrecognized institution.",
}
}
Headers
In addition to the required Authorization
header, each request also requires an Accept
header. POST and PUT requests also require a Content-Type
header. These are as follows:
'Content-Type: application/json'
'Accept: application/vnd.mx.api.v1+json'
Identifiers and metadata
All updateable resources created with the API support an optional metadata
field. You can use the metadata
field to store structured (key-value) data about a resource. For example, you could store a user’s username for your system, their sign-up date, the date and time of their last logon in your system, or all of these. Metadata is not used by MX.
Do not store sensitive information as metadata.
Updateable resources also contain an id
field. For instance, you may need to make certain that some resources are created only once or may need to sync data on the MX platform with data on your own platform. In these situations, you can give a unique id
to resources created with the MX Platform API. The API will return a 409 Conflict
error if a resource is created with an id
that already exists.
Limits on the API
User and member limits
The development environment limits developers to 100 users and access to the top 15 financial institutions.
No user
may have more than 25 members in either the development or production environments.
Aggregation limits
The default minimum time between aggregation-type events (which includes account verification, balance requests, extended transaction requests, identity verification, and statement requests) is 10,800 seconds (3 hours), though this limit can vary by institution.
Aggregating within this limit will not return an error, however; the response will have a status of 202 Accepted
and contain the current state of the member
, including the latest connection_status
. Certain codepaths may bypass this limit.
The MX Bank test institution has no aggregation limits.
Data availability
Be aware that aggregation is not guaranteed to return all relevant information or even every data point on a given resource. For instance, aggregation may return the balance
of an account, but return a null
value for the apr
and apy
fields. This is to be expected in all resources and all aggregations.
Pagination
All endpoints which return lists are paginated. These endpoints also support two query parameters which specify the number of records per page and the page to be returned.
Each response will include a pagination
object specifying information on the total number of entries and the current page.
Example pagination object
1
2
3
4
5
6
"pagination": {
"current_page": 1,
"per_page": 25,
"total_entries": 2,
"total_pages": 1
}
Query parameters
Parameter | Definition |
---|---|
page |
This specifies the page to be returned. Defaults to 1 . |
records_per_page |
This specifies the number of records to be returned on each page. Defaults to 25 . The valid range is from 10 to 100 . |
Pagination fields
Field | Definition |
---|---|
current_page |
The page delivered by the current response. |
per_page |
The number of records delivered with each page. |
total_entries |
The total number of records available. |
total_pages |
The total number of pages available. |
Versioning
We always try to make API changes backwards-compatible. However, when we make breaking changes to the MX Platform API, we’ll increment the version number. The current version is v1
. Versions are specified in a request’s Accept
header. All requests will access the current version unless a different version is specified with the request, so it’s best to always specify the API version. The current Accept header is application/vnd.mx.api.v1+json
.