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.
Last updated
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.
Last updated
Authentication: endpoints listed in this page require header authentication with a user token.
POST https://{domain}.biapi.pro/2.0/users/{userId}/connections
Request body: ConnectionRequest object
userId*
Interger or "me"
ID of the related user.
Response body: Connection object
GET https://{domain}.biapi.pro/2.0/users/{userId}/connections
userId*
Interger or "me"
ID of the related user.
Response body: ConnectionsList object
GET https://{domain}.biapi.pro/2.0/users/{userId}/connections/{connectionId}
Get a single connection by ID.
userId*
Interger or "me"
ID of the related user.
connectionId*
Integer
ID of the connection.
Response body: Connection object
POST https://{domain}.biapi.pro/2.0/users/{userId}/connections/{connectionId}
Update a single connection by ID.
Request body: ConnectionUpdateRequest object
userId*
Interger or "me"
ID of the related user.
connectionId*
Integer
ID of the connection.
background
Boolean
Response body: Connection object
PUT https://{domain}.biapi.pro/2.0/users/{userId}/connections/{connectionId}
Request synchronization of a single connection by ID.
userId*
Interger or "me"
ID of the related user.
connectionId*
Integer
ID of the connection.
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 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.
userId*
Interger or "me"
ID of the related user.
connectionId*
Integer
ID of the connection.
Response body: Connection object
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.
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
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.
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.
token
String
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:
id_connection
Integer
The ID of the connection that was created or updated during the webauth flow.
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
By default, disabled sources are omitted in the response. Add the all query parameter to include them.
userId*
Interger or "me"
ID of the related user.
connectionId*
Integer
ID of the connection.
all
Value-less
Flag to include disabled sources.
Response body: ConnectionSourcesList object
GET https://{domain}.biapi.pro/2.0/users/{userId}/connections/{connectionId}/sources/{sourceId}
userId*
Interger or "me"
ID of the related user.
connectionId*
Integer
ID of the connection.
sourceId*
Integer
ID of the source.
all
Value-less
Flag to enable access to a disabled source.
Response body: ConnectionSource object
POST https://{domain}.biapi.pro/2.0/users/{userId}/connections/{connectionId}/sources/{sourceId}
Request body: ConnectionSourceUpdateRequest object
userId*
Interger or "me"
ID of the related user.
connectionId*
Integer
ID of the connection.
sourceId*
Integer
ID of the source.
all
Value-less
Flag to enable access to a disabled source.
Response body: ConnectionSource object
GET https://{domain}.biapi.pro/2.0/users/{userId}/connections/{connectionId}/logs
List synchronization logs of a connection by ID.
userId*
Interger or "me"
ID of the related user.
connectionId*
Integer
ID of the connection.
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
A CONNECTION_SYNCED webhook is emitted after a connection has been synced.
Webhook request:
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[].market_orders
On each account item, the new market orders 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.
Webhook request: Connection 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.
connections
List of connections.
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
The following parameters can be used for response properties expansion:
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.
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.
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.
sources
Sources of the connection.
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.
disabled
Boolean
No
Whether the source should be disabled or not.
url
String
The URL to display.
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 to monitor the state.
Response body: with wrongPass code
Response body: with invalidValue code
A temporary to secure the call.
object
object
object
Array of objects
Array of objects
Array of objects
Array of objects
Array of objects
Array of objects
Array of objects
Array of objects
Array of objects
Array of objects
Array of objects
string or null
string or null
Array of objects or null
object
Array of objects
Array of objects
Array of objects
Array of objects
Array of objects
A web-based authentication process is required using .
Array of objects
string or null