> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mx.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Fetch Account and Transaction Data with the API
**LEGACY GUIDE**
This guide is for Platform API v2011101. For guidance on the newest version, see [Connectivity Integration Guides](/products/connectivity/overview/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](https://dashboard.mx.com).
* Retrieve your `client_id` and `api_key` as 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.
1. Create a `user`.
2. Create a `member` using the correct institution code and credentials required by that institution. When a member is created, an Account Aggregation is automatically started.
3. Call the `aggregate` endpoint.
4. Poll the member's connection status.
5. Answer multifactor authentication, if necessary.
6. List account data.
7. List transaction data.
## 1. Create a User
A user represents your end user in the MX Platform. Make a request to the [Create User](/api-reference/platform-api/reference/create-user) endpoint (`POST /users`).
We recommend that you include a unique [`id`](/api-reference/platform-api/overview/formats-requirements#identifiers-and-metadata) 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.
**INFO**
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.
```shell theme={null}
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": "example@example.com",
"metadata": "Some metadata"
}
}'
```
```json theme={null}
{
"user": {
"email": "totally.fake.email@notreal.com",
"guid": "USR-11141024-90b3-1bce-cac9-c06ced52ab4c",
"id": "partner-2345",
"is_disabled": false,
"metadata": "Yada yada yada"
}
}
```
## 2. 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:
1. Search for an institution
2. Get the institution-required credentials
3. 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](/api-reference/platform-api/reference/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](/api-reference/platform-api/reference/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.
```shell theme={null}
curl -X GET https://int-api.mx.com/institutions/mxbank/credentials \
-H 'Accept: application/vnd.mx.api.v1+json' \
-u 'client_id:api_key'
```
```json theme={null}
{
"credentials": [
{
"display_order": 1,
"field_name": "LOGIN",
"field_type": "LOGIN",
"guid": "CRD-9f61fb4c-912c-bd1e-b175-ccc7f0275cc1",
"label": "Username"
},
{
"display_order": 2,
"field_name": "PASSWORD",
"field_type": "PASSWORD",
"guid": "CRD-e3d7ea81-aac7-05e9-fbdd-4b493c6e474d",
"label": "Password"
}
]
}
```
### 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](/api-reference/platform-api/reference/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.
**WARNING**
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.
```shell theme={null}
curl -i -X POST 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/members' \
-u 'client_id:api_key' \
-H 'Accept: application/vnd.mx.api.v1+json' \
-H 'Content-Type: application/json' \
-d '{
"member": {
"credentials": [
{
"guid": "CRD-1ec152cd-e628-e81a-e852-d1e7104624da",
"value": "mxuser"
},
{
"guid": "CRD-1ec152cd-e628-e81a-e852-d1e7104624da",
"value": "password"
}
],
"institution_code": "mxbank"
}
}'
```
```json theme={null}
{
"member": {
"aggregated_at": null,
"connection_status": "CREATED",
"background_aggregation_is_disabled": false,
"guid": "MBR-3bdc7d6b-efd4-1497-a0af-b23501cf9bd0",
"id": null,
"institution_code": "mxbank",
"is_being_aggregated": true,
"metadata": null,
"name": "MX Bank",
"successfully_aggregated_at": null,
"user_guid": "USR-11141024-90b3-1bce-cac9-c06ced52ab4c"
}
}
```
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.
* `CREATED`
* `CONNECTED`
* `DEGRADED`
* `DISCONNECTED`
* `EXPIRED`
* `FAILED`
* `IMPEDED`
* `RECONNECTED`
* `UPDATED`
**INFO**
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](/resources/webhooks).
## 3. 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.
```shell theme={null}
curl -i 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/members/MBR-3bdc7d6b-efd4-1497-a0af-b23501cf9bd0/status' \
-H 'Accept: application/vnd.mx.api.v1+json' \
-u 'client_id:api_key'
```
```json theme={null}
{
"member": {
"aggregated_at": "2020-05-07T22:01:00Z",
"connection_status": "CONNECTED",
"guid": "MBR-3bdc7d6b-efd4-1497-a0af-b23501cf9bd0",
"is_authenticated": true,
"is_being_aggregated": false,
"successfully_aggregated_at": "2020-05-07T22:01:25Z"
}
}
```
## 4. Aggregate the Member
After you've determined that aggregation is possible, make a POST request to the [aggregate member](/api-reference/platform-api/reference/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.
```shell theme={null}
curl -i -X POST 'https://int-api.mx.com/users/USR-3a17a2b1-acbc-48d1-8098-1b8ae8939ab2/members/MBR-7c6f361b-e582-15b6-60c0-358f12466b4b/aggregate' \
-H 'Accept: application/vnd.mx.api.v1+json' \
-H 'Content-Type: application/json' \
-u 'client_id:api_key'
```
```json theme={null}
{
"member": {
"aggregated_at": "2016-10-13T18:07:57.000Z",
"connection_status": "CONNECTED",
"guid": "MBR-3bdc7d6b-efd4-1497-a0af-b23501cf9bd",
"id": "unique_id",
"institution_code": "chase",
"is_being_aggregated": true,
"is_managed_by_user": false,
"is_oauth": false,
"metadata": "\"credentials_last_refreshed_at\": \"2015-10-15\"",
"name": "Chase Bank",
"oauth_window_uri": "https://mxbank.mx.com/oauth/authorize?client_id=b8OikQ4Ep3NuSUrQ13DdvFuwpNx-qqoAsJDVAQCyLkQ&redirect_uri=https%3A%2F%2Fint-app.moneydesktop.com%2Foauth%2Fredirect_from&response_type=code&scope=openid&state=d745bd4ee6f0f9c184757f574bcc2df2",
"successfully_aggregated_at": "2016-05-07T17:57:38.000Z",
"user_guid": "USR-fa7537f3-48aa-a683-a02a-b18940482f54",
"user_id": "user123"
}
}
```
## 5. Check the Member's Status Again
Make another GET request to the [read member status](/api-reference/platform-api/reference/read-member-status) endpoint.
```shell theme={null}
curl -i 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/members/MBR-3bdc7d6b-efd4-1497-a0af-b23501cf9bd0/status' \
-H 'Accept: application/vnd.mx.api.v1+json' \
-u 'client_id:api_key'
```
```json theme={null}
{
"member": {
"aggregated_at": "2020-05-07T22:01:00Z",
"connection_status": "CONNECTED",
"guid": "MBR-3bdc7d6b-efd4-1497-a0af-b23501cf9bd0",
"is_authenticated": true,
"is_being_aggregated": false,
"successfully_aggregated_at": "2020-05-07T22:01:25Z"
}
}
```
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.
```json theme={null}
{
"member": {
"aggregated_at": "2020-09-18T16:29:15Z",
"connection_status": "CONNECTED",
"guid": "MBR-3bdc7d6b-efd4-1497-a0af-b23501cf9bd",
"is_authenticated": true,
"is_being_aggregated": false,
"successfully_aggregated_at": "2020-09-18T16:29:52Z"
}
}
```
## 6. List Account Data
Get a list of all the account data associated with your user by making a GET request to the [list accounts](/api-reference/platform-api/reference/list-user-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.
```shell theme={null}
curl -i 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/accounts' \
-u 'client_id:api_key' \
-H 'Accept: application/vnd.mx.api.v1+json'
```
```json theme={null}
{
"accounts": [
{
"account_number": "708191771",
"apr": null,
"apy": null,
"available_balance": 1000,
"available_credit": null,
"balance": 1000,
"cash_balance": null,
"cash_surrender_value": null,
"created_at": "2020-09-21T19:43:44Z",
"credit_limit": null,
"currency_code": null,
"day_payment_is_due": null,
"death_benefit": null,
"guid": "ACT-8e6f92c8-1491-42ce-8bf6-c309e9531530",
"holdings_value": null,
"id": "act-223434333",
"institution_code": "mxbank",
"interest_rate": null,
"is_closed": false,
"is_hidden": false,
"last_payment": null,
"last_payment_at": null,
"loan_amount": null,
"matures_on": null,
"member_guid": "MBR-84ca0882-ad6c-4f10-817f-c8c0de7424fa",
"minimum_balance": null,
"minimum_payment": null,
"name": "Checking",
"original_balance": null,
"payment_due_at": null,
"payoff_balance": null,
"started_on": null,
"subtype": null,
"total_account_value": null,
"type": "CHECKING",
"updated_at": "2020-09-21T19:52:04Z",
"user_guid": "USR-11141024-90b3-1bce-cac9-c06ced52ab4c"
}
],
"pagination": {
"current_page": 1,
"per_page": 25,
"total_entries": 21,
"total_pages": 1
}
}
```
## 7. List Transaction Data
With the account `GUID` you found in the last step, make a request to the [list transaction by account](/api-reference/platform-api/reference/list-transactions-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.
```shell theme={null}
curl -i 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/accounts/ACT-8e6f92c8-1491-42ce-8bf6-c309e9531530/transactions' \
-u 'client_id:api_key' \
-H 'Accept: application/vnd.mx.api.v1+json'
```
```json theme={null}
{
"transactions": [
{
"category": "Gas",
"category_guid": "CAT-b6d63a19-30a7-e852-2703-bdfb4072289e",
"created_at": "2020-09-21T19:43:48Z",
"date": "2020-09-21",
"posted_at": "2020-09-22T12:00:00Z",
"status": "POSTED",
"top_level_category": "Auto & Transport",
"transacted_at": "2020-09-21T12:00:00Z",
"type": "DEBIT",
"updated_at": "2020-09-21T19:43:51Z",
"account_guid": "ACT-8e6f92c8-1491-42ce-8bf6-c309e9531530",
"amount": 7.29,
"check_number_string": null,
"currency_code": "USD",
"description": "ExxonMobil",
"guid": "TRN-822b443e-972c-431e-8dcf-c2b08de21136",
"is_bill_pay": false,
"is_direct_deposit": false,
"is_expense": true,
"is_fee": false,
"is_income": false,
"is_international": null,
"is_overdraft_fee": false,
"is_payroll_advance": false,
"latitude": null,
"localized_description": null,
"localized_memo": null,
"longitude": null,
"member_guid": "MBR-84ca0882-ad6c-4f10-817f-c8c0de7424fa",
"memo": null,
"merchant_category_code": 0,
"merchant_guid": "MCH-dcd9bbcd-11bb-076a-60c4-90f1101b3372",
"original_description": "ExxonMobil",
"user_guid": "USR-11141024-90b3-1bce-cac9-c06ced52ab4c"
}
],
"pagination": {
"current_page": 1,
"per_page": 25,
"total_entries": 176,
"total_pages": 8
}
}
```
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.
```shell theme={null}
curl -i 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/accounts/ACT-8e6f92c8-1491-42ce-8bf6-c309e9531530/transactions?records_per_page=100&page=2' \
-u 'client_id:api_key' \
-H 'Accept: application/vnd.mx.api.v1+json'
```
```json theme={null}
{
"transactions": [
{
"category": "Paycheck",
"category_guid": "CAT-982ea9e6-3f0e-0c5b-611b-6657a10ba819",
"created_at": "2020-09-21T19:43:48Z",
"date": "2020-07-31",
"posted_at": "2020-08-01T12:00:00Z",
"status": "POSTED",
"top_level_category": "Income",
"transacted_at": "2020-07-31T12:00:00Z",
"type": "CREDIT",
"updated_at": "2020-09-21T19:43:51Z",
"account_guid": "ACT-8e6f92c8-1491-42ce-8bf6-c309e9531530",
"amount": 23.57,
"check_number_string": null,
"currency_code": "USD",
"description": "Paycheck",
"guid": "TRN-27b176b7-5941-42a4-8085-cfa6657f6dff",
"is_bill_pay": false,
"is_direct_deposit": false,
"is_expense": false,
"is_fee": false,
"is_income": true,
"is_international": null,
"is_overdraft_fee": false,
"is_payroll_advance": false,
"latitude": null,
"localized_description": null,
"localized_memo": null,
"longitude": null,
"member_guid": "MBR-84ca0882-ad6c-4f10-817f-c8c0de7424fa",
"memo": null,
"merchant_category_code": 0,
"merchant_guid": null,
"original_description": "Payroll",
"user_guid": "USR-11141024-90b3-1bce-cac9-c06ced52ab4c"
}
],
"pagination": {
"current_page": 2,
"per_page": 100,
"total_entries": 176,
"total_pages": 2
}
}
```