> ## 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 Connect
**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/).
This guide assumes you are following MX's recommendation to use the Connect Widget. If your use case requires you to use API endpoints only, see our [separate guide on this type of integration](/other/legacy-connectivity-guides/fetch-account-transaction-data-api).
## Prerequisites
Before you follow the steps in this guide make sure that you have:
1. Signed up for the Platform API and [received your development API Keys](https://dashboard.mx.com).
2. Integrated the Connect Widget into your application or website. The best way to do this is to use one of the widget SDKs mentioned in [Integration Guides](/connect/guides/) that MX has created for this purpose.
## 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. Request a Connect Widget URL
There are many configuration options for the Connect Widget for performing various tasks. Default configuration values are set with account aggregation in mind, so little configuration is required for simple aggregation. Nevertheless, you should carefully read the documentation on configuration options as they may be important for your particular use case.
Make a POST request to the `/users/{user_guid}/widget_urls` endpoint.
* In the body, set the `widget_type` parameter to `connect_widget`.
* In the path, set the `user_guid` to the value for the user you created in step 1.
The response will contain a URL to Connect Widget which you will load in the next step.
```shell theme={null}
curl -i -X POST 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/widget_urls' \
-u '{client_id}:{api_key}' \
-H 'Accept: application/vnd.mx.api.v1+json' \
-H 'Content-Type: application/json' \
-d '{
"widget_url": {
"widget_type": "connect_widget",
"color_scheme": "dark"
}
}'
```
```json theme={null}
{
"widget_url": {
"type": "connect_widget",
"url": "https://int-widgets.moneydesktop.com/md/connect/yxcdk7f1nb99jwApp34lA24m0AZ8rzprgmw17gm8z8h2AzjyAnd1rj42qfv42r3xnn07Amfwlg3j09hwp8bkq8tc5z21j33xjggmp2qtlpkz2v4gywfhfn31l44tx2w91bfc2thc58j4syqp0hgxcyvA4g7754hk7gjc56kt7tc36s45mmkdz2jqqqydspytmtr3dAb9jh6fkb24f3zkfpdjj0v77f0vmrtzvzxkmxz7dklsq8gd0gstkbhlw5bgpgc3m9mAtpAcr2w15gwy5xc4blgxppl42Avnm63291z3cyp0wm3lqgmvgzdAddct423gAdqxdlfx5d4mvc0ck2gt7ktqgks4vxq1pAy5",
"user_id": "partner-2345"
}
}
```
## 3. Load the URL and Let the End User Interact
**INFO**
If you're following this guide for testing purposes, you must search for the test institution in the widget and enter the credentials mentioned in one of our [testing guides](/resources/test-platform/).
Load the URL in your application or website. At this point the end user will interact with the Connect Widget. The widget handles the creation of a `member` as well as the aggregation process and any MFA that may be encountered. It automatically asks end users to search for an institution, give their credentials, or authenticate with OAuth. It also deals with any errors along the way.
You'll need to listen for a couple important [event messages](/connect/widget-events) from the Connect Widget:
* [member status updated](/connect/widget-events#member-status-update) which gives you the member GUID and the current `connection_status`.
* [member connected](/connect/widget-events#member-connected) tells you that the member has been successfully connected and you can move on to the next steps.
Alternatively, if the end user closes the Connect Widget early or some other problem occurs before you see a `CONNECTED` status, you can use the `member_guid` to immediately [check the member's connection status](/api-reference/platform-api/reference/read-member-status) with a dedicated API 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"
}
}
```
## 4. List Account Data
The aggregation 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}`
## 5. List Transaction Data
You can now read all the transaction data that has been gathered. Keep in mind that all list endpoints in the Platform API 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. You can also limit results to a specific time frame using `from_date` and `to_date`.
```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=2022-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}
{
"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"
},
// •••
],
"pagination": {
"current_page": 1,
"per_page": 10,
"total_entries": 243,
"total_pages": 25
}
}
```
**INFO**
There are multiple endpoints for listing transactions provided for code convenience. The others are:
GET `/users/{user_guid}/accounts/{account_guid}/transactions`
GET `/users/{user_guid}/transactions`
You may also wish to read the details of a specific account:
GET `/users/{user_guid}/transactions/{transaction_guid}`