Guides

On-demand refreshes

Partners can request an on-demand refresh of a user’s Open Banking data to retrieve updated account information and transactions.

This feature is available for partners integrating with the direct connection journey. It applies only to users sourced through that journey and is not supported for marketplace-sourced users.

Triggering a refresh

To trigger an on-demand refresh for a user’s connected accounts, call:

POST /v1/users/{userId}/accounts-refresh

See the Refresh User accounts API reference for request and response schemas.

The response acknowledges the request, whilst refresh processing continues asynchronously.

The response includes every connected account for the user in metadata.accounts, each with an outcome of either:

  • TRIGGERED - refresh will begin for the account
  • SKIPPED - no refresh was started for the account

Skipped accounts also include a reason field:

  • ACCOUNT_EXPIRED - the account no longer has valid Open Banking consent
  • RATE_LIMITED - the account is within the refresh interval described below

The overall HTTP response is:

  • 201 Created when at least one account is TRIGGERED
  • 200 OK when all accounts are SKIPPED and no refresh job is created

Each refresh request that responds with a 201 Created is assigned a jobId, a unique identifier that enables partners to correlate the API response with subsequent webhook notifications. The same jobId is included in the payload of each v1.account_transactions.on_demand_refresh.succeeded event for that request.

When refresh completes

Refreshed data is available per account once processing finishes for that account. Partners can determine when data is ready in two ways.

Subscribe to the:

v1.account_transactions.on_demand_refresh.succeeded

webhook event to receive a notification when refreshed data for an account is ready for consumption. This is the recommended approach.

See the webhooks guide for further details.

Alternatively, poll the accounts endpoint and check whether lastTransactionRefreshDate has been updated for the accounts that were triggered. Once updated, partners can retrieve the latest account and transaction payloads using the standard API endpoints.

Refresh behaviour

D•One evaluates refresh eligibility per account before refresh processing begins.

Accounts without valid Open Banking consent are not refreshed. These accounts are returned as SKIPPED with the reason ACCOUNT_EXPIRED.

For eligible accounts, D•One applies a twenty-minute refresh interval based on the account’s lastTransactionRefreshDate from the accounts API.

That timestamp is updated whenever refreshed transaction data has been successfully ingested for the account, including after:

  • scheduled refreshes
  • the initial connection fetch
  • earlier successful on-demand refreshes

The refresh interval is evaluated when the refresh request is validated.

If at least one eligible account has not been refreshed within the previous twenty minutes, all eligible accounts are marked TRIGGERED and sent for refresh.

If all eligible accounts were refreshed within the previous twenty minutes, they are marked SKIPPED with the reason RATE_LIMITED.

Updated 6 days ago