Introduction

Aggregating account and transaction data is one of the most important features of the MX API. Seeing when, where, and how much people are spending is core not only to personal financial management, but also to hundreds of fintechs, banks, credit unions, and financial companies who seek to learn from and improve the financial lives of their customers.

It can also be a somewhat complicated process, especially when dealing with issues like multi-factor authentication (MFA). This guide will walk you through the process step-by-step so that you can see the potential pitfalls and avoid them.

In general, it involves:

  1. Making a request to the aggregate member endpoint;
  2. Repeatedly check the member for changes in the state of the aggregation using the read member connection status endpoint and looking at fields such as connection_status, is_being_aggregated, is_authenticated, has_processed_accounts, etc.;
  • Using the Connect widget provided by MX greatly simplifies and automates steps 2 and 3;
  1. If necessary, answering MFA challenges using the resume aggregation endpoint;
  2. Reading aggregated data using the list accounts and list transactions endpoints.

Before we get to the real step-by-step, though, there’s some things you should know that will make your development easier. However, keep in mind that we are leaving a lot of very important information out of this guide just so you can focus on the happy path and get a feel for the API. If you want to see more complete information, check out our advanced aggregation guide which deals with MFA.

There are multiple aggregation-type processes in the MX API

One important thing to point out up front is that there are multiple processes in the API that follow the same general steps and workflows. This guide will help you with all of them, but we’ll focus on standard aggregation in the examples here.

Aggregation-type processes include:

  • Standard aggregation
  • Account verification
  • Identification
  • Fetching an extended transaction history
  • Fetching account statements
  • Fetching account balances
  • Fetching account rewards information

Important fields and states: connection_status, is_being_aggregated, and more

There are multiple fields on each member that give you all the information you need to determine what state it is in and how to resolve that state into a successful aggregation — as well as when resolution is not possible. These all need to be weighed together in order to make an aggregation successful.

The connection_status field indicates the current state of an aggregation in a general way. For instance, a value of CREATED indicates that the member has just been created. A value of CHALLENGED means the aggregation has run into MFA. FAILED means that the aggregation was unsuccessful. Below, you’ll see exact definitions and next steps for each of the 21 connection statuses.

Another important field is the boolean is_being_aggregated. This indicates whether an aggregation process is currently taking place on the MX platform.

These fields should be used in conjunction with several other member fields to determine future actions. These include aggregated_at, successfully_aggregated_at, and is_authenticated.

But we’ll get into more detail about all these various fields and values in future guides. For right now, we’ll focus on the happy path.

Member fields to pay attention to

Field Name Data Type Description
aggregated_at String The date and time the member the last aggregation was initiated, represented in ISO 8601 format with timestamp (e.g., 2015-04-13T12:01:23-06:00).
connection_status String This field indicates the state of a member’s aggregation, provided as a string. See member connection statuses for more information on possible values.
is_being_aggregated Boolean This field will be true if the member is being aggregated at the time of the request. Otherwise, this field will be false.
successfully_aggregated_at String The date and time the account was last successfully aggregated, represented in ISO 8601 format with timestamp (e.g., 2015-04-13T12:01:23-06:00).

1. Check the member's connection status

Now that you’ve got all that important information above, we can take you through the actual aggregation process step by step. We’re showing the happy path here, i.e., a successful aggregation with no errors and no MFA. Situations with MFA or other errors will be covered in other guides.

The first step is to check the member’s connection_status to see whether aggregation is either necessary or even possible. Each status indicates something different; some connection statuses mean that an aggregation will fail if attempted or that an aggregation is already in progress. Again, we’ll focus on an easy case where aggregation proceeds successfully for this example, but here’s some important information on what these statuses mean anyway.

In general, aggregation can be attempted for a member with the following connection statuses:

  • CREATED
  • CONNECTED
  • DEGRADED
  • DISCONNECTED
  • EXPIRED
  • FAILED
  • IMPEDED
  • RECONNECTED
  • UPDATED

Endpoint:

GET /users/{user_guid}/members/{member_guid}/status

Example request

1
2
3
curl -L -X GET 'https://int-api.mx.com/users/USR-5274d346-f173-41af-a041-45594080970c/members/MBR-2fa3d216-5bf7-498a-97b7-528c41df9c6f/status' \
-H 'Accept: application/vnd.mx.api.v1+json' \
-H 'Authorization: Basic {token}'

Example response

1
2
3
4
5
6
7
8
9
10
{
  "member": {
    "aggregated_at": "2020-04-29T20:39:45Z",
    "connection_status": "CONNECTED",
    "guid": "MBR-2fa3d216-5bf7-498a-97b7-528c41df9c6f",
    "is_authenticated": true,
    "is_being_aggregated": false,
    "successfully_aggregated_at": "2020-04-29T20:40:07Z"
  }
}

Notice the various fields you see. This shows a member that was successfully authenticated and aggregated in April 2020, but is not currently being aggregated. You see a connection_status of CONNECTED, which was the final state of the member back in April. All this means we can proceed to the next step and actually request a new aggregation.


2. Call the aggregate member endpoint

Go ahead and make a request to the aggregate member endpoint.

Endpoint:

POST /users/{user_guid}/members/{member_guid}/aggregate

Example request

1
2
3
4
curl -L -X POST 'https://int-api.mx.com/users/USR-5274d346-f173-41af-a041-45594080970c/members/MBR-2fa3d216-5bf7-498a-97b7-528c41df9c6f/aggregate' \
-H 'Authorization: Basic {token}' \
-H 'Accept: application/vnd.mx.api.v1+json' \
-H 'Content-Type: application/json'

Example response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
  "member": {
    "aggregated_at": "2020-09-18T16:29:15Z",
    "connection_status": "CONNECTED",
    "guid": "MBR-86f19f4f-217e-4af4-aaa2-1f9a6864f43b",
    "id": null,
    "institution_code": "mxbank",
    "is_being_aggregated": true,
    "metadata": null,
    "name": "MX Bank",
    "successfully_aggregated_at": "2020-04-29T20:40:07Z",
    "user_guid": "USR-5274d346-f173-41af-a041-45594080970c"
  }
}

Notice in the example response that the member still has a connection_status of CONNECTED and successfully_aggregated_at is still the date in April.

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. The connection_status hasn’t changed from what it was back in April because this process has not run into any errors or obstacles. However, it may change at any time in the process, so we need to check the status again.


3. Check the member status again (and again) until an end state is reached

Make another status request.

Endpoint:

GET /users/{user_guid}/members/{member_guid}/status

Example request

1
2
3
curl -L -X GET 'https://int-api.mx.com/users/USR-5274d346-f173-41af-a041-45594080970c/members/MBR-2fa3d216-5bf7-498a-97b7-528c41df9c6f/status' \
-H 'Accept: application/vnd.mx.api.v1+json' \
-H 'Authorization: Basic {token}'

Example response

1
2
3
4
5
6
7
8
9
10
{
  "member": {
    "aggregated_at": "2020-09-18T16:29:15Z",
    "connection_status": "CONNECTED",
    "guid": "MBR-2fa3d216-5bf7-498a-97b7-528c41df9c6f",
    "is_authenticated": true,
    "is_being_aggregated": true,
    "successfully_aggregated_at": "2020-04-29T20:40:07Z"
  }
}

The connection_status is still CONNECTED, is_being_aggregated is still true, and the successfully_aggregated_at field is still the same April date. This means the aggregations is still proceeding normally and no errors or obstacles have been encountered.

You’ll need to check the status again, perhaps several more times, until an end state is reached.

Successful aggregation end state

1
2
3
4
5
6
7
8
9
10
{
  "member": {
    "aggregated_at": "2020-09-18T16:29:15Z",
    "connection_status": "CONNECTED",
    "guid": "MBR-2fa3d216-5bf7-498a-97b7-528c41df9c6f",
    "is_authenticated": true,
    "is_being_aggregated": false,
    "successfully_aggregated_at": "2020-09-18T16:29:52Z"
  }
}

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.

Next Steps

Advanced aggregation: Dealing with MFA

In our next guide, we’ll take a look at dealing with MFA when running an aggregation-type process. This guide has more comprehensive information about the process including connection statuses, what they all mean, and more.

However, you’ve also just performed a successful aggregation, so if you wanted, you could read the account and transaction data that was gathered. This is relatively simple to do.