API Reference
DocumentationChangelogConsoleWebsite
  • API Guides
  • Overview
    • API design
    • Errors
    • Webview
    • Fair usage policy
    • Authentication
  • USER CONNECTIONS
    • Users
    • Connectors
    • Connections
  • PRODUCTS
    • DATA AGGREGATION
      • Bank accounts
      • Bank transactions
      • Transactions attachments
      • Categorization
      • Bank account types
      • Balances
      • Currencies
      • Account Ownerships
      • Identities (obsolete)
      • Categories (obsolete)
      • Invoices
      • Credit notes
      • Advisory (obsolete)
      • Indicators
    • WEALTH AGGREGATION
      • Investments
      • Market orders
      • Pockets
      • Loan amortizations
    • DOCUMENTS AGGREGATION
      • Subscriptions
      • Documents
      • Document types
      • Connection Identity
    • PAYMENTS
      • Payments
      • Payment Links
      • Transfers (obsolete)
  • API SETUP
    • Configuration
    • Client applications
Powered by GitBook
On this page
  • API endpoints
  • Connections management
  • Create a new connection
  • List connections
  • Get a connection
  • Update a connection
  • Sync a connection
  • Delete a connection
  • Web authorization
  • Construct a connection URL for web authorization
  • Redirect to a URL for web authorization
  • Connection sources management
  • List sources of a connection
  • Get a connection source
  • Update a connection source
  • Connection logs
  • List synchronization logs
  • Webhooks
  • Connection synced
  • Connection deleted
  • Data model
  • ConnectionRequest object
  • ConnectionsList object
  • Connection object
  • ConnectionState values
  • ConnectionUpdateRequest object
  • ConnectionSourcesList object
  • ConnectionSource object
  • ConnectionSourceUpdateRequest object
  • WebauthURL object

Was this helpful?

  1. USER CONNECTIONS

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.

PreviousConnectorsNextDATA AGGREGATION

Last updated 8 months ago

Was this helpful?

API endpoints

Authentication: endpoints listed in this page require 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.

Response body: Connection object

Response body: 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.

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.

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

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

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.

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.

Response body: Connection object

Web authorization

Construct a connection URL for web authorization

GET https://{domain}.biapi.pro/2.0/webauth-url

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.

Response body: WebauthURL object

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

Redirect to a URL for web authorization

GET https://{domain}.biapi.pro/2.0/webauth

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

Response body: WebauthURL object

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.

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.

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.

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.

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

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.

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.

ConnectionsList object

Property
Type
Description

connections

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

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

Property
Type
Description

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.

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

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.

ConnectionSourcesList object

Property
Type
Description

sources

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

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.

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

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

Response body: with invalidValue code

The provides an alternate (recommended) way to obtain the redirection URL in order to optimize app-to-app experiences.

A temporary to secure the call.

To optimize user experience, the URL should be opened in a fully-capable browser. From a website or webapp, perform a . In a native Android app, prefer opening the default browser or relying on . In a native iOS app, prefer using a .

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

To add a connection to a connector/source using the credentials , you must also include in the request values from the definition.

Array of objects

string or null

string or null

Array of objects or null

The following parameters can be used for :

object

Array of objects

Array of objects

Array of objects

Array of objects

Array of objects

A web-based authentication process is required using .

To edit a connection source using the credentials , you can also include in the request new values from the connector fields.

Array of objects

string or null

SCARequired state
full-page redirect
Chrome Custom Tabs
SFSafariViewController
/webauth-url endpoint
polling on the connection
Connection
ConnectionSource
Connection
ConnectionState
ConnectionState
ConnectionSource
the /webauth endpoint
ConnectionSource
ConnectionState
response properties expansion
header authentication
Investment
authorization code
User
Pocket
Document
Error object
Error object
Error object
MarketOrder
AuthMechanism
connector fields
AuthMechanism
Connector
ConnectorField
Connector
BankAccount
BankAccount
BankAccount
Transaction
Subscription
Subscription
Subscription
Recipient
Transfer