Overview

This guide explains how to aggregate using a standard workflow and begins directly after you have created a member. This guide does not address multifactor authentication or OAuth but instead focuses on a standard aggregation that results in a successful connection.

In general, standard aggregation begins after you create a member and use the following steps:

1. Make 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 to look at fields such as connection_status, is_being_aggregated, is_authenticated, has_processed_accounts, etc.;
3. If necessary, answer MFA challenges using the resume aggregation endpoint;
4. Read aggregated data using the list accounts and list transactions endpoints.

1. Check the Member's Status

The first step is to check the member’s connection_status to see whether aggregation is either necessary or even possible. Make a GET request to the read member status endpoint.

Endpoint:

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

1
2
3
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'

1
2
3
4
5
6
7
8
9
10
{
  "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"
  }
}

Each status indicates something different; some connection statuses mean that an aggregation will fail if attempted or that an aggregation is already in progress. This guide demonstrates a happy path by showing a successful aggregation with no MFA or OAuth.
You may attempt aggregation if the member’s connection_status is one of the following:

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

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

2. Use the Aggregate Endpoint

Make a POST request to the aggregate member endpoint.

Endpoint:

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

Notice in the following 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.

1
2
3
4
curl -i -X POST 'https://int-api.mx.com/users/USR-3a17a2b1-acbc-48d1-8098-1b8ae8939ab2/members/MBR-7c6f361b-e582-15b6-60c0-358f12466b4b/aggregate' \
  -H 'Accept: application/vnd.mx.api.v1+json' \
  -H 'Content-Type: application/json' \
  -u 'client_id:api_key'

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{
  "member": {
    "aggregated_at": "2016-10-13T18:07:57.000Z",
    "connection_status": "CONNECTED",
    "guid": "MBR-3bdc7d6b-efd4-1497-a0af-b23501cf9bd",
    "id": "unique_id",
    "institution_code": "chase",
    "is_being_aggregated": false,
    "is_managed_by_user": false,
    "is_oauth": false,
    "metadata": "\"credentials_last_refreshed_at\": \"2015-10-15\"",
    "name": "Chase Bank",
    "oauth_window_uri": "https://mxbank.mx.com/oauth/authorize?client_id=b8OikQ4Ep3NuSUrQ13DdvFuwpNx-qqoAsJDVAQCyLkQ&redirect_uri=https%3A%2F%2Fint-app.moneydesktop.com%2Foauth%2Fredirect_from&response_type=code&scope=openid&state=d745bd4ee6f0f9c184757f574bcc2df2",
    "successfully_aggregated_at": "2016-10-13T17:57:38.000Z",
    "user_guid": "USR-fa7537f3-48aa-a683-a02a-b18940482f54",
    "user_id": "user123"
  }
}

3. Check the Member's Status Again

Make another GET request to the read member status endpoint.

Endpoint:

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

1
2
3
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'

1
2
3
4
5
6
7
8
9
10
{
  "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"
  }
}

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 aggregation is still proceeding normally and no errors or obstacles have been encountered.

Check the status again, perhaps several more times, until an end state is reached. 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.

1
2
3
4
5
6
7
8
9
10
{
  "member": {
    "aggregated_at": "2020-09-18T16:29:15Z",
    "connection_status": "CONNECTED",
    "guid": "MBR-3bdc7d6b-efd4-1497-a0af-b23501cf9bd",
    "is_authenticated": true,
    "is_being_aggregated": false,
    "successfully_aggregated_at": "2020-09-18T16:29:52Z"
  }
}