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