Connections
Connections materialize the individual link between a user and a connector. They act as a parent for business data and hold metadata about the synchronization state, the PSU credentials and consents.
post
https://{domain}.biapi.pro/2.0
/users/{userId}/connections
Create a new connection
get
https://{domain}.biapi.pro/2.0
/users/{userId}/connections
List connections
get
https://{domain}.biapi.pro/2.0
/users/{userId}/connections/{connectionId}
Get a connection
post
https://{domain}.biapi.pro/2.0
/users/{userId}/connections/{connectionId}
Update a connection
put
https://{domain}.biapi.pro/2.0
/users/{userId}/connections/{connectionId}
Sync a connection
delete
https://{domain}.biapi.pro/2.0
/users/{userId}/connections/{connectionId}
Delete a connection
get
https://{domain}.biapi.pro/2.0
/webauth-url
Construct a connection URL for web authorization
get
https://{domain}.biapi.pro/2.0
/webauth
Redirect to a URL for web authorization
To optimize user experience, the URL should be opened in a fully-capable browser. From a website or webapp, perform a full-page redirect. In a native Android app, prefer opening the default browser or relying on Chrome Custom Tabs. In a native iOS app, prefer using a SFSafariViewController.
After the flow has terminated, a redirection will be performed to the provided
redirect_uri
, with additional query parameters:Parameter | Type | Description |
---|---|---|
id_connection | Integer | The ID of the connection that was created or updated during the webauth flow. |
Parameter | Type | Description |
---|---|---|
error | String | This parameter is added if an error occurred. |
error_description | String | The description of the error, if available. |
get
https://{domain}.biapi.pro/2.0
/users/{userId}/connections/{connectionId}/sources
List sources of a connection
get
https://{domain}.biapi.pro/2.0
/users/{userId}/connections/{connectionId}/sources/{sourceId}
Get a connection source
post
https://{domain}.biapi.pro/2.0
/users/{userId}/connections/{connectionId}/sources/{sourceId}
Update a connection source
get
https://{domain}.biapi.pro/2.0
/users/{userId}/connections/{connectionId}/logs
List synchronization logs
A
CONNECTION_SYNCED
webhook is emitted after a connection has been synced.Webhook request:
Property | Type | Description |
---|---|---|
user | The user related to the sync. | |
connection | The connection details. | |
connection.connector | The connector associated with the connection. | |
connection.sources | The activated connection sources that were synced. | |
connection.accounts | The activated bank accounts sources that were synced. | |
connection.accounts[].investments | On each account item, the new investments that were found. | |
connection.accounts[].investments[].pockets | On each investment item, the new pockets that were found. | |
connection.accounts[].recipients | (Deprecated) On each account item, the new recipients that were found (for transfer usage). | |
connection.accounts[].transactions | On each account item, the new transactions that were found. | |
connection.accounts[].transfers | (Deprecated) On each account item, the new transfers that were made. | |
connection.subscriptions | The activated subscriptions sources that were synced. | |
connection.subscriptions[].documents | On each subscription item, the new documents that were found. |
A
CONNECTION_DELETED
webhook is emitted after a connection has been deleted.Name | Type | Required | Description |
---|---|---|---|
id_connector | Integer | No | ID of the connector. Required if connector_uuid is not provided. |
connector_uuid | String | No | UUID of the connector. Required if id_connector is not provided. |
source | String | No | The specific source (designated by its name ) to add when interacting with bank connectors. |
To add a connection to a connector/source using the
credentials
AuthMechanism, you must also include in the request values from the connector fields
definition.Property | Type | Description |
---|---|---|
connections | List of connections. |
Property | Type | Description |
---|---|---|
id | Integer | ID of the connection. |
id_user | Integer or null | ID of the related user. |
id_connector | Integer | ID of the related connector. |
id_provider | Integer | (Deprecated) ID of the provider. |
id_bank | Integer | (Deprecated) ID of the bank. |
state | If the last update failed, the state code. The null value indicates a successful sync. | |
error | (Deprecated) If the last update failed, the state code. The null value indicates a successful sync. | |
error_message | String or null | If the last update failed, an optional message from the institution to guide the user into recovering from the error. |
fields | For connections in an error state, an optional list of connector fields that must be prompted to the end-user. | |
last_update | DateTime or null | Last successful update. |
created | DateTime or null | Creation date of the connection. |
active | Boolean | Whether this connection is active and will be automatically synced. |
last_push | DateTime or null | Last successful push. |
expire | DateTime or null | Highest value among expiration dates of connection sources. |
connector_uuid | String | UUID of the related connector. |
next_try | DateTime or null | Scheduled date of next synchronization. |
Available expands
Property | Type | Description |
---|---|---|
connector | The connector associated with this connection. | |
accounts | The list of activated bank accounts associated with the connection (disabled accounts are omitted). | |
all_accounts | The list of all bank accounts associated with the connection, including disabled ones. | |
subscriptions | The list of activated subscriptions associated with the connection (disabled subscriptions are omitted). | |
all_subscriptions | The list of all subscriptions associated with the connection, including disabled ones. | |
sources | The details of the sources configured for the connection. |
Instructions for presenting and processing the various error states are available in our dedicated integration guide.
Value | Description |
---|---|
SCARequired | An SCA process must be performed to resume the synchronization process. |
webauthRequired | |
additionalInformationNeeded | Additional information is needed to resume synchronization, such as an OTP. Connections in this state have a fields property. |
decoupled | User validation is required on a third-party app or device (ex: digital key). |
validating | User validation is being processed on our side. This state is temporary. |
actionNeeded | An action is needed on the website by the user, synchronization is blocked. |
passwordExpired | The password has expired and needs to be changed by the user before the synchronization can be retried. |
wrongpass | The authentication on website has failed and new credentials must be obtained from the user. Connections in this state have a fields property. |
rateLimiting | The target website or API is temporarily blocking synchronizations due to rate limiting. |
websiteUnavailable | The connector website or API is unavailable. |
bug | An internal error has occurred during the synchronization. |
notSupported | The source is not supported on the connector. |
Forward compatibility requirement: additional states may be added in the future. When implementing state handling, always fallback to a non-resolvable generic case for unknown values.
Property | Type | Required | Description |
---|---|---|---|
source | String | No | The specific source (designated by its name ) to add or update when interacting with bank connectors. |
active | Boolean | No | Whether the connection synchronization is active. |
expire | DateTime | No | Set expiration of the connection to this date. |
resume | Boolean | No | Resume a connection in the decoupled state. |
refresh_auth | Boolean | No | For PSD2 connections, renew the PSU's authorization before its automatic expiration. This process will trigger an SCA. This flag is only effective for the openapi source, if any. |
To edit a connection source using the
credentials
AuthMechanism, you can also include in the request new values from the connector fields
.Property | Type | Description |
---|---|---|
sources | Sources of the connection. |
Property | Type | Description |
---|---|---|
id | Integer | ID of the connection source. |
id_connection | Integer | ID of the related connection. |
id_connector_source | Integer | ID of the related connector source. |
name | String | Name of the connection source. |
last_update | DateTime or null | Last successful update of the source. |
disabled | DateTime or null | If set, this source is ignored on synchronizing the connection. |
created | DateTime | Creation date of the connection source. |
state | If the last update has failed, the state code. The null value indicates a successful sync. | |
access_expire | DateTime or null | Expiration date of the access, if known. |
expire | DateTime or null | Expiration of the connection source. Used to purge the connection in case completion was not finished. |
next_try | DateTime or null | Scheduled date of next synchronization. |
Property | Type | Required | Description |
---|---|---|---|
disabled | Boolean | No | Whether the source should be disabled or not. |
Property | Type | Description |
---|---|---|
url | String | The URL to display. |
Last modified 1mo ago