Skip to main content
Aggregation gathers a member’s data from its financial institution. MX aggregates members automatically in the background, and you can also start aggregation yourself while the end user is present.

​
Aggregation timing and status fields

The member fields that report aggregation timing and status depend on the API version: This page uses “last successful aggregation” and “connection status” to refer to these fields in every version.

​
Background aggregation

MX automatically aggregates each member about every 24 hours, keeping end user data current. If a member’s last successful aggregation was within the last 24 hours, you can skip foreground aggregation and read the member’s account and transaction data directly. Background aggregation runs only when:
  • The institution supports background aggregation. Most do.
  • The member hasn’t been aggregated in the last 20 hours.
  • The member’s connection status is CONNECTED, UPDATED, or CREATED.
To turn off background aggregation:
  • For all members: Contact MX.
  • For one member: Set background_aggregation_is_disabled to true when you create or update the member.
  • In the Connect Widget: Set the disable_background_agg widget option.
Background aggregation is off by default for members created for account verification. To turn it on, set disable_background_agg to false. This affects new members only. MX may pause background aggregation for a member after several failed attempts in a row. Foreground aggregation is still available for those members.

​
Foreground aggregation

Start foreground aggregation when the end user is present. The end user must be available to respond to multi-factor authentication (MFA) challenges, update credentials, accept terms, or respond to other prompts from the institution. Aggregation isn’t available for disabled users. Re-enable the user before you aggregate.

​
Aggregation limits

​
Standard aggregation throttling

A standard aggregation brings in a member’s latest account and transaction data. Background aggregation is a standard aggregation, and you start one yourself with Aggregate Transactions (POST /users/{user_identifier}/members/{member_identifier}/transactions). Other job types, such as account verification or statements, aren’t standard aggregations. After a standard aggregation, you can’t start another standard aggregation for the same member until the throttle period ends. The default throttle period is three hours (10,800 seconds), but it can vary by institution. This applies to both foreground and background aggregation.
  • Throttled requests don’t return an error. The response is 202 Accepted and includes the member’s current connection status.
  • Premium jobs aren’t throttled and don’t start the throttle period. Premium jobs are extended transaction history, identity verification, account verification, statements, and balance checks. You can run one right after a standard aggregation.
  • Members with credential errors aren’t throttled. This applies when the connection status is REJECTED, PREVENTED, or UPDATED.
  • MX Bank isn’t throttled. There’s no throttling of any kind when you use the MX Bank test institution.
Balance checks are limited to 5 per member every 2 hours. Additional balance checks in that window return 429 Too Many Requests. Test institutions are exempt. Spread aggregation requests out by user over each three-hour window instead of aggregating your whole platform at once. While you develop your integration, watch the last successful aggregation time to see when a member was aggregated. For request rate limits, see Rate Limits.

​
Data availability

Aggregation isn’t guaranteed to return every data point for a resource. Institutions don’t always provide every field, so a resource may include some fields and return null for others. Expect this for every resource and every type of aggregation.