Account Aggregation
Get account and transaction data by connecting end users' financial accounts
See the Connectivity Overview to learn about our Connectivity products and integration options.
With Account Aggregation, connect to end users' financial institutions and retrieve 90 days of data for their accounts and transactions. Use this data for any number of solutions such as personal financial management or risk analysis. Data is available for accounts ranging from checking and savings to mortgages and credit cards — and everything in between. We cleanse this data to make it understandable to end users, and we automatically put it into more than 100 predefined categories. We also add enhanced information such as which merchant was involved in a transaction and whether it represents a direct deposit, bill pay, or subscription.
Aggregation
Aggregation is an important feature of the MX Platform API. Aggregating data enables people to see when, where, and how much they are spending. This helps you build solutions that can improve the financial lives of your organization’s customers.
The best way to aggregate data is with the Connect Widget, MX's ready-made UI that can be embedded in your application to aggregate users' account data by prompting end users to connect to their financial institutions using their credentials. This is the preferred method of aggregation.
Background Aggregation
MX automatically aggregates each member approximately every 24 hours. This process is called background aggregation. It ensures that end users' data is always up to date. This is beneficial because, if a background aggregation is successful (for example, the successfully_aggregated_at field indicates a time within the last 24 hours), you can choose to skip foreground aggregation and jump right to reading account and transaction data, which can help you load things faster in your product.
This background aggregation can be disabled by default for all members. Please reach out to MX to have this setting configured.
Background aggregation can be disabled or enabled for individual members by setting the background_aggregation_is_disabled field when creating or updating a member (or the disable_background_agg configuration option when using the Connect Widget).
Background aggregation is also disabled for members created when using the Connect Widget in verification mode. You can override this behavior by setting the disable_background_agg widget option to false. Note that this only affects newly created members.
There are a few other general rules related to background aggregation:
- The data source must allow background aggregation. Most sources do, but there are cases in which the data source does not.
- The member must not have been aggregated in the last 20 hours.
- The member must be in a
CONNECTED,UPDATED, orCREATEDstate.
Foreground Aggregation
If an end user is present, you can choose to manually run a foreground aggregation. End users must be present during foreground aggregations because they may run into MFA, credential update requests, terms and conditions agreements, or other situations requiring end-user input. Just keep in mind that you cannot run a new aggregation within three hours of a successful aggregation, whether foreground or background. Thus, attention must be paid to the aggregated_at and successfully_aggregated_at member fields while you're developing your product with the Platform API.
Both foreground and background aggregation may be prevented by disabling a user. A user must be re-enabled before any aggregation can be attempted. We may suspend background aggregation on a particular member in some circumstances, such as when several consecutive aggregation attempts fail. However, you can always attempt a foreground aggregation on a suspended member.
Quick Links
Account Sample Data
This sample response shows the data you can expect to get for financial accounts.
_59{_59 "accounts": [_59 {_59 "account_number": "5366",_59 "apr": 1.0,_59 "apy": 1.0,_59 "available_balance": 1000.0,_59 "available_credit": 1000.0,_59 "balance": 1000.0,_59 "cash_balance": 1000.0,_59 "cash_surrender_value": 1000.0,_59 "created_at": "2016-10-13T17:57:37.000Z",_59 "credit_limit": 100.0,_59 "currency_code": "USD",_59 "day_payment_is_due": 20,_59 "death_benefit": 1000,_59 "guid": "ACT-06d7f44b-caae-0f6e-1384-01f52e75dcb1",_59 "holdings_value": 1000.0,_59 "id": "1040434698",_59 "imported_at": "2015-10-13T17:57:37.000Z",_59 "institution_code": "chase",_59 "insured_name": "Frodo Baggins",_59 "interest_rate": 1.0,_59 "is_closed": false,_59 "is_hidden": false,_59 "last_payment": 100.0,_59 "last_payment_at": "2015-10-13T17:57:37.000Z",_59 "loan_amount": 1000.0,_59 "matures_on": "2015-10-13T17:57:37.000Z",_59 "member_guid": "MBR-3bdc7d6b-efd4-1497-a0af-b23501cf9bd0",_59 "member_id": "member-9876",_59 "member_is_managed_by_user": false,_59 "metadata": "some metadata",_59 "minimum_balance": 100.0,_59 "minimum_payment": 10.0,_59 "name": "Test account 2",_59 "nickname": "My Checking",_59 "original_balance": 10.0,_59 "pay_out_amount": 10.0,_59 "payment_due_at": "2015-10-13T17:57:37.000Z",_59 "payoff_balance": 10.0,_59 "premium_amount": 1.0,_59 "routing_number": "68899990000000",_59 "started_on": "2015-10-13T17:57:37.000Z",_59 "subtype": "NONE",_59 "total_account_value": 1.0,_59 "type": "SAVINGS",_59 "updated_at": "2016-10-13T18:08:00.000Z",_59 "user_guid": "USR-11141024-90b3-1bce-cac9-c06ced52ab4c",_59 "user_id": "partner-2345"_59 }_59 ],_59 "pagination": {_59 "current_page": 1,_59 "per_page": 25,_59 "total_entries": 1,_59 "total_pages": 1_59 }_59}
Transaction Sample Data
This sample response shows the data you can expect to get for transactions.
_56{_56 "transactions": [_56 {_56 "account_guid": "ACT-06d7f44b-caae-0f6e-1384-01f52e75dcb1",_56 "account_id": "account123",_56 "amount": 61.11,_56 "category": "Groceries",_56 "category_guid": "CAT-9588eaad-90a4-bb5c-66c8-1812503d0db8",_56 "check_number_string": "6812",_56 "created_at": "2016-10-06T09:43:42.000Z",_56 "currency_code": "USD",_56 "date": "2013-09-23T00:00:00.000Z",_56 "description": "Whole foods",_56 "extended_transaction_type": "partner_transaction_type",_56 "guid": "TRN-265abee9-889b-af6a-c69b-25157db2bdd9",_56 "id": "transaction-265abee9-889b-af6a-c69b-25157db2bdd9",_56 "is_bill_pay": false,_56 "is_direct_deposit": false,_56 "is_expense": true,_56 "is_fee": false,_56 "is_income": false,_56 "is_international": false,_56 "is_overdraft_fee": false,_56 "is_payroll_advance": false,_56 "is_recurring": false,_56 "is_subscription": false,_56 "latitude": -43.2075,_56 "localized_description": "This is a localized_description",_56 "localized_memo": "This is a localized_memo",_56 "longitude": 139.691706,_56 "member_guid": "MBR-3bdc7d6b-efd4-1497-a0af-b23501cf9bd0",_56 "member_is_managed_by_user": false,_56 "memo": "This is a memo",_56 "merchant_category_code": 5411,_56 "merchant_guid": "MCH-7ed79542-884d-2b1b-dd74-501c5cc9d25b",_56 "merchant_location_guid": "MCL-00024e59-18b5-4d79-b879-2a7896726fea",_56 "metadata": "some metadata",_56 "original_description": "WHOLEFDS TSQ 102",_56 "posted_at": "2016-10-07T06:00:00.000Z",_56 "status": "POSTED",_56 "top_level_category": "Food & Dining",_56 "transacted_at": "2016-10-06T13:00:00.000Z",_56 "type": "DEBIT",_56 "updated_at": "2016-10-07T05:49:12.000Z",_56 "user_guid": "USR-11141024-90b3-1bce-cac9-c06ced52ab4c",_56 "user_id": "partner-2345"_56 },_56 // •••_56 ],_56 "pagination": {_56 "current_page": 1,_56 "per_page": 10,_56 "total_entries": 243,_56 "total_pages": 25_56 }_56}