Fetch Account and Transaction Data with the API
This guide is for Platform API v2011101. For guidance on the newest version, see Connectivity Integration Guides.
The following guide starts at the beginning and shows you how to navigate the Platform API to get up to 90 days of account and transaction data for an end user.
Before following the steps in this guide, you'll need to:
- Sign up for access to the Platform API and get your development API keys.
- Retrieve your
client_idandapi_keyas you’ll need them to pass requests. - Whitelist your IP addresses.
- Ensure all requests are using HTTPS with TLSv1.2 encryption or higher or else they will fail.
Workflow
You’ll use this workflow with the Platform API.
- Create a
user. - Create a
memberusing the correct institution code and credentials required by that institution. When a member is created, an Account Aggregation is automatically started. - Call the
aggregateendpoint. - Poll the member’s connection status.
- Answer multifactor authentication, if necessary.
- List account data.
- List transaction data.
Create a user
A user represents your end user in the MX Platform. Make a request to the Create User endpoint (POST /users).
We recommend that you include a unique id of your choice with the request. You may also include metadata, such as the date the user was created or the end user's name. Don't include any sensitive information here, such as credentials.
None of these parameters are required, but the user object can't be empty. We recommend that you always set the id parameter when creating a user.
In the response, the API gives each new user an MX-defined guid (or user_guid when appearing outside the user object). Between your id and the guid, you can map between your system and ours. You'll need the user guid for nearly every request on the MX API, at least when using basic authorization.
Create a Member
Next, create a member. A member represents the relationship between a user and an institution, and creating one is how you connect one to the other. Multiple members may be attached to a single user (for example, one member for their bank, another for their mortgage provider, another for their credit card provider, etc.).
To create a member:
- Search for an institution
- Get the institution-required credentials
- Make a request to the create member endpoint
a. Search for an Institution
First, you need to know what financial institution the member should be connected to and what type of credentials the institution expects to get.
Search for an institution by making a GET request using query parameters on the list institutions endpoint
The example that follows searches for MX Bank, which is MX’s institution for testing and development.
The response returns a paginated list of institutions that match the string you send in the name query parameter. Make a note of the code you find in the example response; you’ll need this for the next step.
b. Get the Institution-Required Credentials
Each institution requires different types of credentials. Some require an email and a password, some require a username and a password, and some may require other types of credentials.
Make a GET request to the list institution credentials endpoint.
Include the institution code retrieved from the previous step in the request URL. This endpoint returns the guid for each credential returned, which is used to match the credentials the end user provides to the required credential type in the next step.
c. Create the Member
After you have the user_guid, an institution_code, and a guid for each credential required by the institution, create a new member. For this step, you need the values provided by the end user for each necessary credential.
Make a POST request to the create member endpoint. There are several parameters that you can pass in this request which are included in the following table.
| Parameter | Data Type | Description | Required? |
|---|---|---|---|
background_aggregation_is_disabled | Boolean | When set to true, background aggregation will be disabled for this member. | No |
credentials | Array | The credentials endpoint for the requested institution will give you a list of all the credentials required to create a member for a given institution. Each required credential will need to be included within this array. | Yes |
id | String | The unique partner-defined identifier for the member. | No |
institution_code | String | The unique code for the institution to which the member will connect. Defined by MX. | Yes |
metadata | String | Additional information you can store on this member. | No |
The following example uses MX Bank and requires a username and a password. It sets the username to mxuser and the password to password which are the credentials for the test user for MX Bank. For real institutions, these values must be the end user’s correct login information.
Note: Do not add multiple members that connect to the same institution using the same credentials on the same user. This will result in a 409 Conflict error.
If the request is successful, the response returns with the newly created member and indicates that the connection process has started. The connection_status should be CREATED and the is_being_aggregated field should be true.
The connection_status must be one of the following in order to continue with account aggregation. For this guide, we just created a member so the connection_status is still CREATED and we can move forward, but if you've already connected a member for a different reason, validate that the status is one of the following. Also, validate that is_being_aggregated: false because you cannot initiate aggregation for a member if a connection already in process.
CREATEDCONNECTEDDEGRADEDDISCONNECTEDEXPIREDFAILEDIMPEDEDRECONNECTEDUPDATED
We suggest you add a Connection Status Webhook in the Client Dashboard. We provide webhooks that send HTTPS POST callback requests to the URL of your choice. This webhook notifies you whenever a member’s connection_status field enters into an end-user-actionable state. For more information on webhooks, see our complete reference page.
Check the Member's Status
Check the member’s connection_status to see whether aggregation is either necessary or even possible. Make a GET request to the read member status endpoint.
Notice the various fields you see. The request that follows shows a member that was successfully authenticated and aggregated previously in May 2020 but is not currently being aggregated. You see a connection_status of CONNECTED, which was the final state of the member in May. All this means we can proceed to the next step and request a new aggregation.
Aggregate the Member
After you've determined that aggregation is possible, make a POST request to the aggregate member endpoint.
Notice in the following example response that the member still has a connection_status of CONNECTED and successfully_aggregated_at is still the date in May.
However, the aggregated_at field has updated to the time the request was made, and the is_being_aggregated boolean is now true. This shows that the aggregation process is active and ongoing. The connection_status hasn’t changed from what it was back in May because this process has not run into any errors or obstacles. However, it may change at any time in the process, so continue to check the status.
Check the Member's Status Again
Make another GET request to the read member status endpoint.
The connection_status is still CONNECTED, is_being_aggregated is still true, and the successfully_aggregated_at field is still the same May date. This means the aggregation is still proceeding normally and no errors or obstacles have been encountered.
Continue to check the status until an end state is reached. In this last example response, the connection_status is still CONNECTED, but the successfully_aggregated_at field is now just a few seconds after the initial aggregation request, and the is_being_aggregated field is now false. This shows that the aggregation is complete, and there were no problems.
_10{_10 "member": {_10 "aggregated_at": "2020-09-18T16:29:15Z",_10 "connection_status": "CONNECTED",_10 "guid": "MBR-3bdc7d6b-efd4-1497-a0af-b23501cf9bd",_10 "is_authenticated": true,_10 "is_being_aggregated": false,_10 "successfully_aggregated_at": "2020-09-18T16:29:52Z"_10 }_10}
List Account Data
Get a list of all the account data associated with your user by making a GET request to the list accounts endpoint.
You can see in the following example that the user has 21 accounts associated with it. If you look at the type field, there is a checking account, a savings account, a credit card account, and several others. Also, there is information on the balance of each account, such as APY for credit accounts or payment due days. You won’t always get values for every field; that depends on the data provider and the information available from the financial institution in question.
Make a note of the account GUID for the checking account associated with our test member: ACT-8e6f92c8-1491-42ce-8bf6-c309e9531530. We’ll need this to list all the transactions associated with the account.
List Transaction Data
With the account GUID you found in the last step, make a request to the list transaction by account endpoint. Notice from the pagination object in the response that there are 176 transactions in this account and that the endpoint returned the first 25 of these.
There are several other endpoints that can give you access to transaction data: list transactions by user and [list transactions by member]. These work in the same way as the list transactions by account endpoint.
You can access the rest of these transactions by making another request and specifying the number of records you want to access (valid values range between 10 and 100) and specifying the page you’d like to see. You can pass these parameters in the request URL to the same endpoint as demonstrated in the following example. The pagination object in the response now shows 100 records per page and a current page of 2.