Aggregation Methods

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.

There are multiple ways to achieve aggregation with the MX Platform API depending on your integration. You can aggregate data in one of the following ways:

• Using the MXconnect widget: A widget that can be embedded in your application to aggregate user’s account data by prompting end users to connect to their financial institutions using their credentials. This is the preferred method of aggregation. MXconnect currently only supports standard aggregation and account verification.
• Using API endpoints: Requires you to make multiple calls to several endpoints to create unique identifiers using an end user’s personal information that can be used to retrieve account information.

Background Aggregation

MX aggregates each member every 24 hours automatically. 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 (i.e., 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.

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.

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.

Automatic Aggregation

Automatic aggregation is a bit different. Every time a new member is successfully created or an existing member is successfully updated, an aggregation process will start automatically, without having to manually call the aggregate member endpoint. You will, however, need to follow up on the rest of the aggregation process, like looking for changes in the connection status, answering MFA, etc.

If your workflow requires that there not be any automatic aggregation, you can easily prevent it by including the skip_aggregation body parameter and setting it to true in either a [create member] or update member request.

Important Fields and States

There are multiple fields on each member that help you determine what state aggregation 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 to make an aggregation successful.

connection_status

The connection_status field indicates the current state of an aggregation. For instance:

• CREATED means the member has just been created.
• CHALLENGED means the aggregation has run into MFA.
• FAILED means the aggregation was unsuccessful.

The connection statuses CREATED, UPDATED, DELAYED, and RESUMED represent transient states for different points in the aggregation process and generally do not require a specific action or end-user input. They may, however, require you to keep making read requests on the member until an actionable status or an end state shows up.

The connection statuses PREVENTED, DENIED, IMPEDED, IMPAIRED, REJECTED, EXPIRED, LOCKED, IMPORTED, DISABLED, DISCONTINUED, and CLOSED represent end states that require a new aggregation, and possibly end-user input, for future success.

For exact definitions and next steps for each of the 21 connection statuses visit the API Reference.

is_being_aggregated

The is_being_aggregated indicates whether an aggregation process is currently taking place on the MX platform.

The connection_status and is_being_aggregated 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.

For example, when the connection_status is CONNECTED and the is_being_aggregated field is false, this means the latest aggregation attempt has finished and data for accounts and transactions can be read. You can use the field successfully_aggregated_at to determine when the last successful aggregation occurred.

Member fields to pay attention to

Connection Status

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

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

In general, you must update credentials before aggregating a member with the following connection statuses:

• PREVENTED
• DENIED
• IMPAIRED
• IMPORTED

The following connection statuses represent a transitory state in an ongoing aggregation process:

• CHALLENGED
• DELAYED
• REJECTED
• RESUMED

You should not attempt aggregation on a member with the following connection statuses:

• CLOSED
• DISABLED
• DISCONTINUED