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 portal 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.

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 our development environment are available on the client portal. Please contact MX to get an api_key and client_id for the production environment. In the near future, these will also be available through the MX client portal.

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

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

Pagination fields

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.