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

Name	Type	Description
userId*	Interger or "me"	ID of the related user.

201: Created Connection created

Response body: Connection object

400: Bad Request Invalid credentials

Response body: Error object with wrongPass code

List connections

GET https://{domain}.biapi.pro/2.0/users/{userId}/connections

Path Parameters

Name	Type	Description
userId*	Interger or "me"	ID of the related user.

200: OK List of connections

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

Name	Type	Description
userId*	Interger or "me"	ID of the related user.
connectionId*	Integer	ID of the connection.

200: OK Connection details

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

Name	Type	Description
userId*	Interger or "me"	ID of the related user.
connectionId*	Integer	ID of the connection.

Query Parameters

Name	Type	Description
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.

200: OK Connection updated

Response body: Connection object

400: Bad Request Invalid credentials

Response body: Error object with wrongPass code

Sync a connection

PUT https://{domain}.biapi.pro/2.0/users/{userId}/connections/{connectionId}

Request synchronization of a single connection by ID.

Path Parameters

Name	Type	Description
userId*	Interger or "me"	ID of the related user.
connectionId*	Integer	ID of the connection.

Query Parameters

Name	Type	Description
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.

200: OK Connection details

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

Name	Type	Description
userId*	Interger or "me"	ID of the related user.
connectionId*	Integer	ID of the connection.

204: No Content Connection details

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

Name	Type	Description
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.

200: OK URL created

Response body: WebauthURL object

409: Conflict Invalid connection state

The connection is already up to date and a connection URL cannot be provided.

Response body: Error object with invalidValue code

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

Name	Type	Description
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	A temporary authorization code to secure the call.

307: Temporary Redirect Redirection to the connector 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

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

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

Name	Type	Description
userId*	Interger or "me"	ID of the related user.
connectionId*	Integer	ID of the connection.

Query Parameters

Name	Type	Description
all	Value-less	Flag to include disabled sources.

200: OK List of connection sources

Response body: ConnectionSourcesList object

Get a connection source

GET https://{domain}.biapi.pro/2.0/users/{userId}/connections/{connectionId}/sources/{sourceId}

Path Parameters

Name	Type	Description
userId*	Interger or "me"	ID of the related user.
connectionId*	Integer	ID of the connection.
sourceId*	Integer	ID of the source.

Query Parameters

Name	Type	Description
all	Value-less	Flag to enable access to a disabled source.

200: OK Connection source details

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

Name	Type	Description
userId*	Interger or "me"	ID of the related user.
connectionId*	Integer	ID of the connection.
sourceId*	Integer	ID of the source.

Query Parameters

Name	Type	Description
all	Value-less	Flag to enable access to a disabled source.

200: OK Connection source details

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

Name	Type	Description
userId*	Interger or "me"	ID of the related user.
connectionId*	Integer	ID of the connection.

Query Parameters

Name	Type	Description
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.

200: OK List of connection sources

Response body: ConnectionSourcesList object

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[].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

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.