Overview
An overview on the Connection object
A connection links one user to a financial institution through their consent. A user can have multiple connections; each connection can contain multiple accounts and their transactions.
For bank information, the PSD2 connection mode starts the provider's open banking consent process. Start with Creating your first connection.
Connection states
Read the latest connection with GET /connections/{connectionId}. The REST response uses id and status; connection webhooks use connectionId and connectionStatus.
Your integration should read and synchronize account data only in ACTIVE or COMPLETED, using a token for the connection owner's userId. These are the normal successful-collection states; check the additional-approval and freshness caveat below before replacing local data.
| Status | Meaning and next action |
|---|---|
INACTIVE | Created and awaiting user action. Open the returned connectUrl. |
CONNECTED | Consent connected; collection proceeds asynchronously. Check collection progress. |
FETCHING | Collection is in progress. Keep the integration in a pending state. |
PARTIALLY_AUTHORIZED | Additional account-owner approvals are required. Wait for the provider's consent process. |
COMPLETED | Normal successful collection result with refreshData=false. Read the data and its freshness. |
ACTIVE | Normal successful collection result with refreshData=true, but can also precede initial collection after additional approvals. Check freshness and data. |
ERROR, CREDENTIALS_ERROR | Connection or authentication failed. Inspect error before deciding whether the user must reconnect. |
FETCHING_ERROR | Collection encountered an error. Inspect error; available data may be incomplete. |
REJECTED | Consent was rejected. Explain the outcome to the user before offering a new consent journey. |
EXPIRED, REVOKED | Consent ended. A new consent is needed to regain access. |
REPLACED | Another connection replaced this one. Use the replacement connection. |
SUSPENDED_BY_PROVIDER | The provider suspended consent. Check with the provider or Open Finance before retrying. |
TERMINATED_BY_USER | Deleted through the connection API, including deletion by your application. This connection is no longer usable. |
Check data separately from consentBrowser return and
ACTIVEalone do not establish data readiness. Check collection timestamps and the data endpoints. An old timestamp does not confirm a new refresh has completed, andFETCHING_ERRORmay leave partial data.
Consent duration, additional-approval timing and automatic refresh behavior depend on the provider and configuration. COMPLETED does not itself guarantee that no later collection will occur. See Reading account data for pagination and freshness, or Deleting a connection for disconnection.
Updated 25 days ago