Links

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 connector 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.