# Data Refresh
source: https://developer.mastercard.com/open-finance-us/documentation/products/manage/account-aggregation/data-refresh/index.md

Mastercard automatically updates the data from accounts added by customers during our nightly batch aggregation. As long as those accounts have an active `aggregationStatusCode` equal to 0, indicating the account is ready for aggregation, Mastercard continues updating the account details to stay current with the host financial institution. The `aggregationSuccessDate` field indicates the timestamp of the last successful aggregation of the account.

When there is a specific business case, account data may also be refreshed on demand by using the Account Refresh Service. Discuss with your Account Manager and Solution Engineer for further clarification.

Client applications are not permitted to automate calls to the data refresh service. As many financial institutions only post transactions once per day, calling the data refresh service repeatedly is usually a waste of resources and could have an adverse impact on your integration.

## Asynchronous Data Refresh Endpoints {#asynchronous-data-refresh-endpoints}

The asynchronous Data Refresh endpoints enable you to trigger an asynchronous
refresh of transaction data for a customer's accounts. We recommend using these
endpoints for new integrations instead of the [legacy endpoints](https://developer.mastercard.com/open-finance-us/documentation/products/manage/account-aggregation/data-refresh/index.md#legacy-refresh-endpoints) described below.

You can choose to refresh specific
accounts, or all accounts linked to a provided institution login ID. You can also choose the date range
of transactions to refresh.

1. Call **Trigger Customer Account Refresh** with a request body specifying either
   an `institutionLoginId` or a list of `accountIds`. If both are provided,
   `accountIds` takes priority. Use the `mode` parameter to specify
   the date range for the refresh (refer to [Refresh Modes](https://developer.mastercard.com/open-finance-us/documentation/products/manage/account-aggregation/data-refresh/index.md#refresh-modes) on this page).


   API Reference: `POST /aggregation/customers/{customerId}/transactions/refreshes`

2. The endpoint returns a `202 Accepted` response containing a `refreshId`, a `createdAt` value (an ISO 8601 date-time value
   with timezone describing when the refresh request was created)
   and an initial `status` of `NEW`.

Note: Identical **Trigger Customer Account Refresh** requests within 5 minutes of each other are treated as duplicates: the same `refreshId` is returned and no new refresh is triggered. If more than 5 minutes have passed since the last identical request, a new refresh is triggered.

3. Either:

   * Poll **Get Customer Account Refresh Status** with the `refreshId` until the status is `COMPLETED` or `FAILED` (refer to [Refresh Status Values](https://developer.mastercard.com/open-finance-us/documentation/products/manage/account-aggregation/data-refresh/index.md#refresh-status-values) on this page for details).


   API Reference: `GET /aggregation/customers/{customerId}/transactions/refreshes/{refreshId}`

   * Subscribe to the `data-refresh.transaction.status-changed` webhook event through [OBWMS](https://developer.mastercard.com/open-finance-us/documentation/webhooks/obwms/index.md) to receive the same data provided by the Get Customer Account Refresh Status response when processing completes.

   <br />

   The response always returns all fields shown in the `TransactionRefreshStatusDetails` object except
   `aggregationStatusCode` and `aggregationSuccessDate`, which are optional.

Tip: A `COMPLETED` status does not mean every account refreshed successfully. The response includes `totalCount`, `successCount`, and `failedCount` fields, along with per-account `aggregationStatusCode` values. Check these to confirm which accounts were refreshed and which encountered errors.

4. Retrieve the refreshed transaction data using the standard transaction endpoints, for example:
   * [Get All Customer Transactions](https://developer.mastercard.com/open-finance-us/documentation/api-reference/index.md#GetAllCustomerTransactions)
   * [Get Customer Account Transactions](https://developer.mastercard.com/open-finance-us/documentation/api-reference/index.md#GetCustomerAccountTransactions)

### Refresh Modes {#refresh-modes}

|    Mode    |        Description         |                                                                                  Date range                                                                                   |                                                                                      Billing                                                                                      |
|------------|----------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `standard` | Standard refresh (default) | Last 6 months (`fromDate` and `toDate` are ignored)                                                                                                                           | Non-billable                                                                                                                                                                      |
| `historic` | Extended historical load   | Last 2 years (`fromDate` and `toDate` are ignored)                                                                                                                            | Billable (uses [Load Historic Transactions](https://developer.mastercard.com/open-finance-us/documentation/products/manage/transaction-data/index.md#load-historic-transactions)) |
| `custom`   | Custom date range          | `fromDate` is required `fromDate` cannot be more than 2 years in the past; values before 2 years ago return a 400 error `toDate` defaults to the current date if not provided | Billable if `fromDate` is more than 6 months in the past                                                                                                                          |

Note: For `custom` mode, `fromDate` and `toDate` use ISO 8601 date-time format with timezone, for example `2022-03-10T06:06:20.042Z`. This differs from most other Open Finance endpoints, which use Unix epoch timestamps.

### Refresh Status Values {#refresh-status-values}

|    Status     |                                            Description                                             |
|---------------|----------------------------------------------------------------------------------------------------|
| `NEW`         | Refresh request received                                                                           |
| `IN_PROGRESS` | Refresh is running                                                                                 |
| `COMPLETED`   | The overall operation has finished; check `successCount` and `failedCount` for per-account results |
| `FAILED`      | The refresh failed for all accounts                                                                |

<br />

## Legacy Refresh Endpoints {#legacy-refresh-endpoints}

There are two sets of legacy synchronous refresh endpoints.
Note: You must use the correct pair of endpoints depending on whether you use Data Access Tiers or Standalone services:

* If you are using Data Access Tiers (ASD, AFD, or ATD), you must use the V2 Refresh endpoints.
* If you are using the standalone Account Limited Aggregation (ALA) and Transaction Access (TAU), you must use the V1 Refresh endpoints.

See [Data Access Tiers](https://developer.mastercard.com/open-finance-us/documentation/products/manage/data-access-tiers/index.md) for more information about the different tiers.

The recommended timeout setting for this request is 180 seconds in order to receive a response. However, a terminated call prior to a response does not terminate the refresh. Evidence of a refresh request can be found in the `aggregationAttemptDate` field, and data can be retrieved through the Account Aggregation and Transaction Aggregation services.

### Refresh Endpoints for Data Access Tiers (V2) {#refresh-endpoints-for-data-access-tiers-v2}

If you are using Data Access Tiers (ASD, AFD, ATD), use the V2 endpoints in this section.

Refresh customer account data for all accounts:

API Reference: `POST /aggregation/v2/customers/{customerId}/accounts`

Refresh customer account data for all accounts associated with a given financial institution:

API Reference: `POST /aggregation/v2/customers/{customerId}/institutionLogins/{institutionLoginId}/accounts`

<br />

### Refresh Endpoints for Standalone Services (V1) {#refresh-endpoints-for-standalone-services-v1}

If you are using the standalone Account Limited Access (ALA) service and not using Data Access Tiers, use the V1 endpoints in this section.

Note these are not suitable if you are using any of the Data Access Tiers products (ASD, AFD, ATD).

Refresh customer account data for all accounts:

API Reference: `POST /aggregation/v1/customers/{customerId}/accounts`

Refresh customer account data for all accounts associated with a given institution login ID with a connection to the institution:

API Reference: `POST /aggregation/v1/customers/{customerId}/institutionLogins/{institutionLoginId}/accounts`