Upgrade to the Platform API from Atrium

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 of example requests to make it more clear.

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\"}"
        }
      }'

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`	Production: `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.

​What’s In This Guide

​Important Differences

​Authentication

​Fields and Field Naming

​Upgrade Mappings

What’s In This Guide

Important Differences

Authentication

Fields and Field Naming

Upgrade Mappings