Our most powerful API
Welcome to the Platform API. It’s MX’s newest and best way to connect with our powerful financial data platform (hence the name). The Platform API is intended to improve and replace the Atrium API (and eventually, all MX APIs). You’ll get the same features that Atrium had to offer, plus access to a lot more. And we’re adding functionality all the time.
If you’re reading this guide, you probably know all that, which is why you’d like to upgrade. Fortunately, Atrium and Platform are very similar, so the upgrade should be easy. In fact, there are just a few differences that will require you to make changes to your code. The rest of the differences come in the form of either behind-the-scenes improvements or new functionality.
What's in this guide
Below you’ll find a table that maps between the two APIs: For instance, old base URL -> new base URL, old Accept header -> new Accept header, etc. This mapping only includes things that exist in both APIs but differ slightly. So for instance, both APIs have a list accounts endpoint, but the route for each is the same (GET /users/{user_guid}/accounts
); hence, this isn’t included in the table. On the other hand, both APIs have a Connect widget endpoint, but the routes are different (POST /users/{user_guid}/connect_widget_url
in Atrium and POST /users/{user_guid}/widget_urls
in Platform); hence, this is included in the table.
If you can’t find what you’re looking for in the table, it’s safe to assume that the feature or function is identical in both APIs, or it simply doesn’t exist on one of them.
Let’s get started by explaining the biggest differences in their own sections. After that, you’ll find the mapping table.
Important differences
Authentication
One important change in the Platform API is how authentication works. In Atrium, you used the MX-API-Key
and MX-Client-ID
in separate headers. In Platform, you send the URL-safe Base64 encoding of both these values combined in a single Authorization
header.
In other words, CLIENT-1234:API-KEY-4567
encodes to Q0xJRU5ULTEyMzQ6QVBJLUtFWS00NTY3
, so the header and value would be Authorization: Basic Q0xJRU5ULTEyMzQ6QVBJLUtFWS00NTY3
.
Here are a couple example requests to make it more clear.
Atrium
1
2
3
4
5
6
7
8
9
10
11
$ curl -i -X POST 'https://vestibule.mx.com/users' \
-H 'Accept: application/vnd.mx.atrium.v1+json' \
-H 'Content-Type: application/json' \
-H 'MX-API-Key: {mx_api_key}' \
-H 'MX-Client-ID: {mx_client_id}' \
-d '{
"user": {
"identifier": "unique_id",
"metadata": "{\"first_name\": \"Steven\"}"
}
}'
Platform
1
2
3
4
5
6
7
8
9
10
11
12
curl -i -X POST 'https://int-api.mx.com/users' \
-u 'client_id:api_key' \
-H 'Accept: application/vnd.mx.api.v1+json' \
-H 'Content-Type: application/json' \
-d '{
"user": {
"id": "partner-2345",
"is_disabled": false,
"email": "totally.fake.email@notreal.com",
"metadata": "Yada yada yada"
}
}'
Fields and field naming
While Atrium and Platform don’t return the same set of fields for every resource (e.g., there are different member
fields in Atrium than in Platform), fields that appear in both will have the same name and definition.
There is one important exception to this: The identifier
field is called id
in Platform. The definition for both is identical and the values you’ve assigned to it for various resources haven’t changed; we simply shortened the key.
Upgrade mappings
Atrium | Platform | |
---|---|---|
Accept header | application/vnd.mx.atrium.v1+json |
application/vnd.mx.api.v1+json |
Authentication headers | MX-API-Key: {api_key} MX-Client-ID: {client_id} |
Authorization: Basic {token} where token = Base64 encoding of {client_id}:{api_key} |
Base URLs | Development:https://vestibule.mx.com |
Development:https://int-api.mx.com |
Production:https://atrium.mx.com |
Produciton:https://api.mx.com |
|
Endpoint routes and request bodies | Aggregate member account balances:POST /users/{user_guid}/members/{member_guid}/balance |
Check balances:POST /users/{user_guid}/members/{member_guid}/check_balance |
Categorize transactions:POST /transactions/cleanse_and_categorize |
Enhance transactions:POST /transactions/enhance |
|
Get a Connect widget URL:POST /users/{user_guid}/connect_widget_url |
Get a Connect widget URL:POST /users/{user_guid}/widget_urls This also requires a different, rooted request body specifying the Connect widget. |
|
Identify a member: The route is the same, but the request body is unrooted. |
Identify a member: The route is the same, but the request body is rooted in a member . |
|
Verify a member: The route is the same, but the request body is unrooted. |
Verify a member: The route is the same, but the request body is rooted in a member . |
|
Field names/keys | identifier This appears on multiple resources, e.g., users and members. |
id This appears on even more resources, e.g., users, members, accounts, and transactions. |