> ## 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 Extended Transaction Data
**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/).
Extended Transaction History (ETH) extends the Account Aggregation product from 90 days to up to 24 months, depending on the financial institution.
This guide walks through the Extended Transaction History process using API endpoints. Extended transaction data cannot be retrieved using the Connect Widget.
## API Workflow
The workflow is as follows:
1. Create a user.
2. Search for an institution.
3. Get the credentials required by the institution.
4. Create a member.
5. Poll the member's connection status.
6. Request extended transaction history.
7. Poll the member’s connection status again until it reaches an end state.
* You may need to deal with Multifactor Authentication.
* A successful end state is when the `connection_status` is `CONNECTED` and the `is_aggregating` field changes from true to false.
8. List the member's account information or read a particular account's information.
9. List the member's transaction information or read a particular transaction's information.
## 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. Search for an Institution
To create a member, you need to know what financial institution the member should be connected to and what type of credentials the institution expects to get.
First, search for an institution using query parameters on the list institutions endpoint, GET `/institutions?name={string}&supports_transaction_history=true`.
The example searches for MX Bank, which is [MX's institution for testing and development](/resources/test-platform). It also limits results to institutions that support ETH.
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.
```shell theme={null}
curl -i 'https://int-api.mx.com/institutions?name=mx&supports_transaction_history=true' \
-u 'client_id:api_key' \
-H 'Accept: application/vnd.mx.api.v1+json'
```
```json theme={null}
{
"institutions": [
{
"code": "mxbank",
"forgot_password_url": null,
"forgot_username_url": null,
"instructional_text": null,
"medium_logo_url": "https://content.moneydesktop.com/storage/MD_Assets/Ipad%20Logos/100x100/INS-1572a04c-912b-59bf-5841-332c7dfafaef_100x100.png",
"name": "MX Bank",
"small_logo_url": "https://content.moneydesktop.com/storage/MD_Assets/Ipad%20Logos/50x50/INS-1572a04c-912b-59bf-5841-332c7dfafaef_50x50.png",
"supports_account_identification": true,
"supports_account_statement": false,
"supports_account_verification": true,
"supports_oauth": false,
"supports_tax_document": false,
"supports_transaction_history": true,
"trouble_signing_in_url": null,
"url": "https://www.mx.com"
},
{
"code": "bank_of_mx_oauth",
"forgot_password_url": null,
"forgot_username_url": null,
"instructional_text": null,
"medium_logo_url": "https://content.moneydesktop.com/storage/MD_Assets/Ipad%20Logos/100x100/default_100x100.png",
"name": "Bank of MX (OAuth)",
"small_logo_url": "https://content.moneydesktop.com/storage/MD_Assets/Ipad%20Logos/50x50/default_50x50.png",
"supports_account_identification": true,
"supports_account_statement": false,
"supports_account_verification": true,
"supports_oauth": false,
"supports_tax_document": false,
"supports_transaction_history": true,
"trouble_signing_in_url": null,
"url": "https://banksy.kube.int.internal.mx"
}
],
"pagination": {
"current_page": 1,
"per_page": 25,
"total_entries": 2,
"total_pages": 1
}
}
```
## 3. Get the Institution's 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 request to the [List Institution Credentials endpoint](/api-reference/platform-api/reference/list-institution-credentials) (`GET /institutions/{institution_code}/credentials`). Include the institution code retrieved from the previous step in the request path.
This endpoint returns the `GUID` for each required credential, which is used to match the credentials the end user provides to the required credential type when creating a member.
```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"
}
]
}
```
## 4. Create a Member
For this step, you need to have already gathered from the end user the values needed for each credential. The following example uses the MX Bank institution and therefore 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.
Make a POST request to the `/users/{user_guid}/members` endpoint. The response includes the newly created `member`.
* Put the `user_guid` in the path.
* In the body, include the credential GUIDs and their values in the `credentials` array.
* In the body, set the `skip_aggregation` parameter to `true`.
* Standard aggregation begins automatically when a member is created unless you explicitly prevent it by using `skip_aggregation`. Because you are going to aggregate data using the Extended Transaction History product, you don't need to start standard aggregation.
* In the body, set the `id` and `metadata` fields as you see fit. This is not required, but is strongly encouraged.
* Optionally, you can disable background aggregation with the `background_aggregation_is_disabled` parameter. It defaults to `false`. In other words, background aggregation is enabled by default.
We encourage that you also poll the member using the Check Status endpoint as shown in [Step 5](#5-poll-the-member-to-check-for-connection-status) to be sure you can aggregate the member. For more information on Connection Status, view our [Reference](/api-reference/platform-api/v20111101/reference/members).
**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"
}
],
"id": "member-9876",
"institution_code": "mxbank",
"metadata": "some metadata",
"skip_aggregation": true
}
}'
```
```json theme={null}
{
"member": {
"aggregated_at": null,
"background_aggregation_is_disabled": false,
"connection_status": "CREATED",
"guid": "MBR-3bdc7d6b-efd4-1497-a0af-b23501cf9bd0",
"id": "member-9876",
"institution_code": "mxbank",
"is_being_aggregated": false,
"is_managed_by_user": true,
"is_oauth": false,
"metadata": "some metadata",
"name": "MX Bank",
"successfully_aggregated_at": null,
"user_guid": "USR-11141024-90b3-1bce-cac9-c06ced52ab4c",
"user_id": "partner-2345"
}
}
```
## 5. Poll the Member's Connection Status
Check the connection status of the member to get information on the state of the aggregation. Important fields include `connection_status`, `is_being_aggregated`, and `successfully_aggregated_at`. The `is_being_aggregated` field will tell you whether the aggregation is ongoing or complete.
When you see `"connection_status": "CONNECTED"` and `"is_being_aggregated": false` at the same time, the aggregation is done and you can move on to the next step.
You may need to check the connection status several times until an end state is reached.
Make a request to the [Read Member Status endpoint](/api-reference/platform-api/reference/read-member-status) (`GET /users/{user_guid}/members/{member_guid}/status`).
```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"
}
}
```
## 6. Request Extended Transaction History
Make a POST request to the `/users/{user_guid}/members/{member_guid}/extend_history` endpoint. This request only starts the process; actually reading the aggregated data comes later. The response will be a `member` object with information about the state of the process you just started.
```shell theme={null}
curl -i -X POST 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/members/MBR-3bdc7d6b-efd4-1497-a0af-b23501cf9bd0/extend_history' \
-H 'Accept: application/vnd.mx.api.v1+json' \
-H 'Content-Type: application/json' \
-u 'client_id:api_key'
```
```json theme={null}
{
"member": {
"aggregated_at": "2023-04-10T08:50:10Z",
"background_aggregation_is_disabled": false,
"connection_status": "CREATED",
"guid": "MBR-3bdc7d6b-efd4-1497-a0af-b23501cf9bd0",
"id": "member-9876",
"institution_code": "mxbank",
"is_being_aggregated": true,
"is_managed_by_user": true,
"is_oauth": false,
"metadata": "some metadata",
"name": "MX Bank",
"successfully_aggregated_at": null,
"user_guid": "USR-11141024-90b3-1bce-cac9-c06ced52ab4c",
"user_id": "partner-2345"
}
}
```
## 7. Poll the Member to Check for Connection Status Again
Check the connection status of the member to get information on the state of the ETH aggregation. Important fields include `connection_status`, `is_being_aggregated`, and `successfully_aggregated_at`. The `is_being_aggregated` field will tell you whether the ETH aggregation is ongoing or complete.
When you see `"connection_status": "CONNECTED"` and `"is_being_aggregated": false` at the same time, the ETH aggregation is done and you can move on to the next step.
You may need to check the connection status several times until an end state is reached.
Make a request to the [Read Member Status endpoint](/api-reference/platform-api/reference/read-member-status) (`GET /users/{user_guid}/members/{member_guid}/status`).
```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"
}
}
```
### Deal with Multifactor Authentication
ETH may trigger multifactor authentication (MFA) from the institution associated with the member. This is indicated by `connection_status: CHALLENGED`.
Please see the detailed section on [answering MFA challenges](/products/connectivity/overview/mfa) for more information. For this part of the guide, we'll assume there was no MFA and move on to the next step.
## 8. List Account Data
The ETH process was successful and you can now read account information.
Make a `GET` request to the `/users/{user_guid}/members/{member_guid}/accounts` endpoint. The response will include all the accounts belonging to the member.
```shell theme={null}
curl -i -X GET 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/members/MBR-3bdc7d6b-efd4-1497-a0af-b23501cf9bd0/accounts' \
-H 'Accept: application/vnd.mx.api.v1+json' \
-u 'client_id:api_key'
```
```json theme={null}
{
"accounts": [
{
"account_number": "5366",
"apr": 1.0,
"apy": 1.0,
"available_balance": 1000.0,
"available_credit": 1000.0,
"balance": 1000.0,
"cash_balance": 1000.0,
"cash_surrender_value": 1000.0,
"created_at": "2016-10-13T17:57:37.000Z",
"credit_limit": 100.0,
"currency_code": "USD",
"day_payment_is_due": 20,
"death_benefit": 1000,
"guid": "ACT-06d7f44b-caae-0f6e-1384-01f52e75dcb1",
"holdings_value": 1000.0,
"id": "1040434698",
"imported_at": "2015-10-13T17:57:37.000Z",
"institution_code": "chase",
"insured_name": "Frodo Baggins",
"interest_rate": 1.0,
"is_closed": false,
"is_hidden": false,
"last_payment": 100.0,
"last_payment_at": "2015-10-13T17:57:37.000Z",
"loan_amount": 1000.0,
"matures_on": "2015-10-13T17:57:37.000Z",
"member_guid": "MBR-3bdc7d6b-efd4-1497-a0af-b23501cf9bd0",
"member_id": "member-9876",
"member_is_managed_by_user": false,
"metadata": "some metadata",
"minimum_balance": 100.0,
"minimum_payment": 10.0,
"name": "Test account 2",
"nickname": "My Checking",
"original_balance": 10.0,
"pay_out_amount": 10.0,
"payment_due_at": "2015-10-13T17:57:37.000Z",
"payoff_balance": 10.0,
"premium_amount": 1.0,
"routing_number": "68899990000000",
"started_on": "2015-10-13T17:57:37.000Z",
"subtype": "NONE",
"total_account_value": 1.0,
"type": "SAVINGS",
"updated_at": "2016-10-13T18:08:00.000Z",
"user_guid": "USR-11141024-90b3-1bce-cac9-c06ced52ab4c",
"user_id": "partner-2345"
}
],
"pagination": {
"current_page": 1,
"per_page": 25,
"total_entries": 1,
"total_pages": 1
}
}
```
**INFO**
There is another endpoint for listing accounts which may be more suitable for your use case: `GET /users/{user_guid}/accounts`.
You may also consider reading the attributes of a specific account. There are two endpoints for this which return the same information, provided for code convenience:
`GET /users/{user_guid}/members/{member_guid}/accounts/{account_guid}`
`GET /users/{user_guid}/accounts/{account_guid}`
## 9. List Transaction Data
With the account `GUID` from the last step, make a request to the [list transaction by account](/api-reference/platform-api/reference/list-transactions-by-account) endpoint. To retrieve transaction history older than 90 days, set `from_date` to a date more than 90 days before the request. If you do not set a `from_date` older than 90 days, the response will include at most 90 days of transaction data available through the [Account Aggregation](/products/connectivity/account-aggregation) product.
```shell theme={null}
curl -i -X GET 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/members/BR-3bdc7d6b-efd4-1497-a0af-b23501cf9bd0/transactions?from_date=2020-09-20&page=1&records_per_page=10&to_date=2023-10-20' \
-H 'Accept: application/vnd.mx.api.v1+json' \
-u 'client_id:api_key'
```
```json theme={null}
{
"pagination": {
"current_page": 1,
"per_page": 10,
"total_entries": 243,
"total_pages": 25
},
"transactions": [
{
"account_guid": "ACT-06d7f44b-caae-0f6e-1384-01f52e75dcb1",
"account_id": "account123",
"amount": 61.11,
"category": "Groceries",
"category_guid": "CAT-9588eaad-90a4-bb5c-66c8-1812503d0db8",
"check_number_string": "6812",
"created_at": "2016-10-06T09:43:42.000Z",
"currency_code": "USD",
"date": "2013-09-23T00:00:00.000Z",
"description": "Whole foods",
"extended_transaction_type": "partner_transaction_type",
"guid": "TRN-265abee9-889b-af6a-c69b-25157db2bdd9",
"id": "transaction-265abee9-889b-af6a-c69b-25157db2bdd9",
"is_bill_pay": false,
"is_direct_deposit": false,
"is_expense": true,
"is_fee": false,
"is_income": false,
"is_international": false,
"is_overdraft_fee": false,
"is_payroll_advance": false,
"is_recurring": false,
"is_subscription": false,
"latitude": -43.2075,
"localized_description": "This is a localized_description",
"localized_memo": "This is a localized_memo",
"longitude": 139.691706,
"member_guid": "MBR-3bdc7d6b-efd4-1497-a0af-b23501cf9bd0",
"member_is_managed_by_user": false,
"memo": "This is a memo",
"merchant_category_code": 5411,
"merchant_guid": "MCH-7ed79542-884d-2b1b-dd74-501c5cc9d25b",
"merchant_location_guid": "MCL-00024e59-18b5-4d79-b879-2a7896726fea",
"metadata": "some metadata",
"original_description": "WHOLEFDS TSQ 102",
"posted_at": "2016-10-07T06:00:00.000Z",
"status": "POSTED",
"top_level_category": "Food & Dining",
"transacted_at": "2016-10-06T13:00:00.000Z",
"type": "DEBIT",
"updated_at": "2016-10-07T05:49:12.000Z",
"user_guid": "USR-11141024-90b3-1bce-cac9-c06ced52ab4c",
"user_id": "partner-2345"
}
]
}
```
Keep in mind that all list endpoints are paginated. To get the full list of transactions, you'll need to pay attention to the `pagination` object and make multiple requests specifying the page and the `records_per_page` in order to see all the available data.
Notice from the `pagination` object in the response that there are 243 transactions in this account and that the endpoint returned the first 10 of these.
There are several other endpoints that can give you access to transaction data: [list transactions by user](/api-reference/platform-api/reference/list-transactions) and [list transactions by member](/api-reference/platform-api/reference/list-transactions-by-member). These work in the same way as the list transactions by account endpoint.