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
Create a new connection
POST https://{domain}.biapi.pro/2.0/users/{userId}/connections
Request body: ConnectionRequest object
Path Parameters
userId*
Interger or "me"
ID of the related user.
Response body: Connection object
List connections
GET https://{domain}.biapi.pro/2.0/users/{userId}/connections
Path Parameters
userId*
Interger or "me"
ID of the related user.
Response body: ConnectionsList object
Get a connection
GET https://{domain}.biapi.pro/2.0/users/{userId}/connections/{connectionId}
Get a single connection by ID.
Path Parameters
userId*
Interger or "me"
ID of the related user.
connectionId*
Integer
ID of the connection.
Response body: Connection object
Update a connection
POST https://{domain}.biapi.pro/2.0/users/{userId}/connections/{connectionId}
Update a single connection by ID.
Request body: ConnectionUpdateRequest object
Path Parameters
userId*
Interger or "me"
ID of the related user.
connectionId*
Integer
ID of the connection.
Query Parameters
background
Boolean
Flag to make the request asynchronous (i.e. the API will respond immediately and process the synchronization with the bank in background). When using this option, you must implement polling on the connection to monitor the state.
Response body: Connection object
Sync a connection
PUT https://{domain}.biapi.pro/2.0/users/{userId}/connections/{connectionId}
Request synchronization of a single connection by ID.
Path Parameters
userId*
Interger or "me"
ID of the related user.
connectionId*
Integer
ID of the connection.
Query Parameters
psu_requested
Boolean
Flag to indicate whether the refresh of the connection was asked by the final user. If set to true (the default) the process might trigger an SCA. If you wish to force synchronization when the PSU is not in your application you must set it to false for compliance reasons.
Response body: Connection object
Delete a connection
DELETE https://{domain}.biapi.pro/2.0/users/{userId}/connections/{connectionId}
This operation deletes the connection and all its related data (accounts, transactions, subscriptions, documents, identities...). This is a hard delete and cannot be reversed: the data (including full history) is permanently erased from Powens' databases. This operation meets GDPR requirements related to the deletion of personal data.
Path Parameters
userId*
Interger or "me"
ID of the related user.
connectionId*
Integer
ID of the connection.
Response body: Connection object
Web authorization
Construct a connection URL for web authorization
GET https://{domain}.biapi.pro/2.0/webauth-url
Constructs a connection URL for connectors (and sources) using the webauth auth mechanism. The same service can be used for both establishing a new connection and resuming an existing connection that requires an update for SCA or consent renewal (i.e. in the SCARequired state).
The returned URL should be presented on the device of the PSU using the most appropriate front-end components, taking full advantage of URL-handling behaviors to enable app-to-app experiences when available.
Query Parameters
client_id*
Integer
The client ID of your client application.
redirect_uri*
String
The final redirect URL to be redirected to after the flow has completed. This URL must not contain query parameters. Make sure to properly encode it.
id_connector
Integer
To add a new connection only, the ID of the connector. The connector must have webauth as its auth_mechanism.
id_connection
Integer
To recover or resume a connection only, the ID of the connection.
source
String
The specific source (designated by its name) to add or reset when interacting with bank connectors.
state
String
An optional opaque string that will be returned 'as is' with the redirect URL.
Response body: WebauthURL object
Redirect to a URL for web authorization
GET https://{domain}.biapi.pro/2.0/webauth
The /webauth-url endpoint provides an alternate (recommended) way to obtain the redirection URL in order to optimize app-to-app experiences.
This endpoint is a special redirection service to help presenting the auth webview from a connector (e.g. using OAuth2 protocol). This service is not an API endpoint, the URL must be navigated to in a browser.
Query Parameters
client_id*
Integer
The client ID of your client application.
redirect_uri*
String
The final redirect URL to be redirected to after the flow has completed. This URL must not contain query parameters. Make sure to properly encode it.
id_connector
Integer
To add a new connection only, the ID of the connector. The connector must have webauth as its auth_mechanism.
id_connection
Integer
To recover or resume a connection only, the ID of the connection.
source
String
The specific source (designated by its name) to add or reset when interacting with bank connectors.
state
String
An optional opaque string that will be returned 'as is' with the redirect URL.
Response body: WebauthURL object
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
id_connection
Integer
The ID of the connection that was created or updated during the webauth flow.
Error callback parameters
error
String
This parameter is added if an error occurred.
error_description
String
The description of the error, if available.
Connection sources management
List sources of a connection
GET https://{domain}.biapi.pro/2.0/users/{userId}/connections/{connectionId}/sources
By default, disabled sources are omitted in the response. Add the all query parameter to include them.
Path Parameters
userId*
Interger or "me"
ID of the related user.
connectionId*
Integer
ID of the connection.
Query Parameters
all
Value-less
Flag to include disabled sources.
Response body: ConnectionSourcesList object
Get a connection source
GET https://{domain}.biapi.pro/2.0/users/{userId}/connections/{connectionId}/sources/{sourceId}
Path Parameters
userId*
Interger or "me"
ID of the related user.
connectionId*
Integer
ID of the connection.
sourceId*
Integer
ID of the source.
Query Parameters
all
Value-less
Flag to enable access to a disabled source.
Response body: ConnectionSource object
Update a connection source
POST https://{domain}.biapi.pro/2.0/users/{userId}/connections/{connectionId}/sources/{sourceId}
Request body: ConnectionSourceUpdateRequest object
Path Parameters
userId*
Interger or "me"
ID of the related user.
connectionId*
Integer
ID of the connection.
sourceId*
Integer
ID of the source.
Query Parameters
all
Value-less
Flag to enable access to a disabled source.
Response body: ConnectionSource object
Connection logs
List synchronization logs
GET https://{domain}.biapi.pro/2.0/users/{userId}/connections/{connectionId}/logs
List synchronization logs of a connection by ID.
Path Parameters
userId*
Interger or "me"
ID of the related user.
connectionId*
Integer
ID of the connection.
Query Parameters
limit
Integer
Maximum number of results.
offset
Integer
First result offset.
min_date
Date
Minimum date.
max_date
Date
Maximum date.
id_source
Integer
ID of a connection source.
Response body: ConnectionSourcesList object
Webhooks
Connection synced
A CONNECTION_SYNCED webhook is emitted after a connection has been synced.
Webhook request:
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[].market_orders
Array of MarketOrder objects
On each account item, the new market orders 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
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
Connection object
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:
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.
ConnectionState values
Instructions for presenting and processing the various error states are available in our dedicated integration guide.
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
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
ConnectionSource object
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
disabled
Boolean
No
Whether the source should be disabled or not.
WebauthURL object
url
String
The URL to display.
Last updated
Was this helpful?