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.

API endpoints
Authentication: endpoints listed in this page require header authentication with a user token.
Connections management
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
Web authorization
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:
Success callback parameters
Parameter
Type
Description
id_connection
Integer
The ID of the connection that was created or updated during the webauth flow.
Error callback parameters
Parameter
Type
Description
error
String
This parameter is added if an error occurred.
error_description
String
The description of the error, if available.
Connection sources management
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
Connection logs
get
https://{domain}.biapi.pro/2.0
/users/{userId}/connections/{connectionId}/logs
List synchronization logs
Webhooks
Connection synced
A CONNECTION_SYNCED webhook is emitted after a connection has been synced.
Webhook request:
Property
Type
Description
user
​User object
The user related to the sync.
connection
​Connection object
The connection details.
connection.connector
​Connector object
The connector associated with the connection.
connection.sources
Array of ConnectionSource objects
The activated connection sources that were synced.
connection.accounts
Array of BankAccount objects
The activated bank accounts sources that were synced.
connection.accounts[].investments
Array of Investment objects
On each account item, the new investments that were found.
connection.accounts[].investments[].pockets
Array of Pocket objects
On each investment item, the new pockets that were found.
connection.accounts[].recipients
Array of Recipient objects
(Deprecated) On each account item, the new recipients that were found (for transfer usage).
connection.accounts[].transactions
Array of Transaction objects
On each account item, the new transactions that were found.
connection.accounts[].transfers
Array of Transfer objects
(Deprecated) On each account item, the new transfers that were made.
connection.subscriptions
Array of Subscription objects
The activated subscriptions sources that were synced.
connection.subscriptions[].documents
Array of Document objects
On each subscription item, the new documents that were found.
Connection deleted
A CONNECTION_DELETED webhook is emitted after a connection has been deleted.
Webhook request: Connection object​
Data model
ConnectionRequest object
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.
ConnectionsList object
Property
Type
Description
connections
Array of Connection objects
List of connections.
Connection object
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
​ConnectionState string or null
If the last update failed, the state code. The null value indicates a successful sync.
error
​ConnectionState string or null
(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
Array of ConnectorField objects or null
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
The following parameters can be used for response properties expansion:
Property
Type
Description
connector
​Connector object
The connector associated with this connection.
accounts
Array of BankAccount objects
The list of activated bank accounts associated with the connection (disabled accounts are omitted).
all_accounts
Array of BankAccount objects
The list of all bank accounts associated with the connection, including disabled ones.
subscriptions
Array of Subscription objects
The list of activated subscriptions associated with the connection (disabled subscriptions are omitted).
all_subscriptions
Array of Subscription objects
The list of all subscriptions associated with the connection, including disabled ones.
sources
Array of ConnectionSource objects
The details of the sources configured for the connection.
ConnectionState values
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
A web-based authentication process is required using the /webauth endpoint.
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.
ConnectionUpdateRequest object
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.
ConnectionSourcesList object
Property
Type
Description
sources
Array of ConnectionSource objects
Sources of the connection.
ConnectionSource object
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
​ConnectionState string or null
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.
ConnectionSourceUpdateRequest object
Property
Type
Required
Description
disabled
Boolean
No
Whether the source should be disabled or not.
WebauthURL object
Property
Type
Description
url
String
The URL to display.

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.

Property	Type	Description
`user`	User object	The user related to the sync.
`connection`	Connection object	The connection details.
`connection.connector`	Connector object	The connector associated with the connection.
`connection.sources`	Array of ConnectionSource objects	The activated connection sources that were synced.
`connection.accounts`	Array of BankAccount objects	The activated bank accounts sources that were synced.
`connection.accounts[].investments`	Array of Investment objects	On each `account` item, the new investments that were found.
`connection.accounts[].investments[].pockets`	Array of Pocket objects	On each `investment` item, the new pockets that were found.
`connection.accounts[].recipients`	Array of Recipient objects	(Deprecated) On each `account` item, the new recipients that were found (for transfer usage).
`connection.accounts[].transactions`	Array of Transaction objects	On each `account` item, the new transactions that were found.
`connection.accounts[].transfers`	Array of Transfer objects	(Deprecated) On each `account` item, the new transfers that were made.
`connection.subscriptions`	Array of Subscription objects	The activated subscriptions sources that were synced.
`connection.subscriptions[].documents`	Array of Document objects	On each `subscription` item, the new documents that were found.

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.

Property	Type	Description
`connections`	Array of Connection objects	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`	ConnectionState string or null	If the last update failed, the state code. The `null` value indicates a successful sync.
`error`	ConnectionState string or null	(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`	Array of ConnectorField objects or null	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.

Property	Type	Description
`connector`	Connector object	The connector associated with this connection.
`accounts`	Array of BankAccount objects	The list of activated bank accounts associated with the connection (disabled accounts are omitted).
`all_accounts`	Array of BankAccount objects	The list of all bank accounts associated with the connection, including disabled ones.
`subscriptions`	Array of Subscription objects	The list of activated subscriptions associated with the connection (disabled subscriptions are omitted).
`all_subscriptions`	Array of Subscription objects	The list of all subscriptions associated with the connection, including disabled ones.
`sources`	Array of ConnectionSource objects	The details of the sources configured for the connection.

Value	Description
`SCARequired`	An SCA process must be performed to resume the synchronization process.
`webauthRequired`	A web-based authentication process is required using the /webauth endpoint.
`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.

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.

Property	Type	Description
`sources`	Array of ConnectionSource objects	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`	ConnectionState string or null	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.

USER CONNECTIONS - Previous

Connectors

Next - PRODUCTS

DATA AGGREGATION

Last modified 1mo ago