Fetch Account and Transaction Data with Connect

LEGACY GUIDEThis guide is for Platform API v2011101. For guidance on the newest version, see 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.

Prerequisites

Before you follow the steps in this guide make sure that you have:

Signed up for the Platform API and received your development API Keys.
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 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 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.

INFONone 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.

Request
Response

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

{
"user": {
"email": "totally.fake.email@notreal.com",
"guid": "USR-11141024-90b3-1bce-cac9-c06ced52ab4c",
"id": "partner-2345",
"is_disabled": false,
"metadata": "Yada yada yada"
}
}

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.

Request
Response

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

{
  "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

INFOIf 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.

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 from the Connect Widget:

member status updated which gives you the member GUID and the current connection_status.
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 with a dedicated API endpoint.

Request
Response

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'

{
"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.

Request
Response

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'

{
"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
}
}

INFOThere 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.

Request
Response

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'

{
"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
}
}

INFOThere are multiple endpoints for listing transactions provided for code convenience. The others are:GET /users/{user_guid}/accounts/{account_guid}/transactionsGET /users/{user_guid}/transactionsYou may also wish to read the details of a specific account:GET /users/{user_guid}/transactions/{transaction_guid}

Legacy Connectivity Guides

Fetch Account and Transaction Data with Connect

Prerequisites

1. Create a User

2. Request a Connect Widget URL

3. Load the URL and Let the End User Interact

4. List Account Data

5. List Transaction Data

​Prerequisites

​1. Create a User

​2. Request a Connect Widget URL

​3. Load the URL and Let the End User Interact

​4. List Account Data

​5. List Transaction Data

Prerequisites

1. Create a User

2. Request a Connect Widget URL

3. Load the URL and Let the End User Interact

4. List Account Data

5. List Transaction Data