Bank accounts

The Bank product lets you retrieve bank accounts of end users. Bank accounts are associated with a connection, and a connector (a bank).

API endpoints

Authentication: endpoints listed in this page require header authentication with a user token.

List bank accounts

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

Path Parameters

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

Query Parameters

Name	Type	Description
all	Value-less	Flag to access disabled accounts.

200: OK List of bank accounts

Response body: BankAccountsList object

Filtering route alias:

/users/{userId}/connections/{connectionId}/accounts

Get a bank account

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

Get a single bank account by ID.

Path Parameters

Name	Type	Description
accountId*	Integer	ID of the bank account.
userId*	Integer or "me"	ID of the related user.

200: OK Bank account details

Response body: BankAccount object

Bank account ressources partially support an update operation to handle activation/deactivation, or to override some display-related properties of accounts:

Update a bank account

POST https://{domain}.biapi/pro/2.0/users/{userId}/accounts/{accountId}

Update a single bank account by ID.

Request body: BankAccountUpdateRequest object

Path Parameters

Name	Type	Description
accountId*	Integer	ID of the bank account.
userId*	Integer	ID of the related user.

Query Parameters

Name	Type	Description
all	Value-less	Add this flag to access a disabled bank accounts.

200: OK Bank account updated

Response body: BankAccount object

Life cycle

Activation

Bank accounts can be in a disabled or enabled state.

For legal compliance, accounts are disabled by default. Also, disabling account will result in the deletion of account child resources (transactions, investments, market orders, balances).

Querying

Disabled accounts will only appear when passing the all parameter:

GET /users/{userId}/accounts/{id}?all
GET /users/{userId}/connections/{connectionId}/accounts/{id}?all

Enabling

To enable one such account, it is necessary to perform a POST request on that account, with the all parameter and { "disabled": false }.

Please note that this action represents the PSU's consent.

Webhooks

Accounts fetched

An ACCOUNTS_FETCHED webhook is emitted during a sync after bank accounts have been synchronized, but before the transactions are processed.

Webhook request :

Property	Type	Description
user	User object	The user related to the sync.
connection	Connection object	Connection.
connection .connector	Connector object	The connector associated with the connection.
connection .sources	Array of ConnectionSource objects	The activated connections sources that were synced.
connection .accounts	Array of BankAccount objects	The activated bank accounts sources that were synced.

Accounts synced

An ACCOUNT_SYNCED webhook is emitted during a sync after a bank account was processed, including new transactions. Webhook request: BankAccount object with the following additional properties:

Property	Type	Description
investments	Array of Investment objects	The new investments that were found.
investments[] .pockets	Array of Pocket objects	On each investment item, the new pockets that were found.
recipients	Array of Recipient objects	(Deprecated) The new recipients that were found (for transfer usage).
transactions	Array of Transaction objects	The new transactions that were found.
transfers	Array of Transfer objects	(Deprecated) The new transfers that were found.

Account disabled

An ACCOUNT_DISABLED webhook is emitted after a bank account was disabled. The disabled property in the request contains the deactivation date.

Webhook request: BankAccount object

Account enabled

An ACCOUNT_ENABLED webhook is emitted after a bank account was enabled. The disabled property in the request will be null.

Webhook request: BankAccount object

Account found

An ACCOUNT_FOUND webhook is emitted after a new bank account was discovered. The account is disabled by default.

Webhook request:

Property	Type	Description
id	Integer	ID of the bank account.
id_user	Integer	ID of the related user.
id_connection	Integer	ID of the related connection.
disabled	DateTime	New accounts are disabled by default, so the property is set to the discovery date.
type	AccountTypeName string	Technical code of the account type.

Data model

BankAccountsList object

Property	Type	Description
accounts	Array of BankAccount objects	List of bank accounts.
balances	Object	Associative map of ISO currency codes to the total balance (decimal number) of accounts in the given currency.

BankAccount object

Property	Type	Description
id	Integer	ID of the bank account.
id_connection	Integer or null	ID of the related connection.
id_user	Integer or null	ID of the related user.
id_source	Integer or null	ID of the related connection source.
id_parent	Integer or null	ID of the parent account.
number	String or null	Account number.
original_name	String	Original name of the account, as seen on the bank.
balance	Decimal or null	Balance of the account.
coming	Decimal or null	Amount of coming operations not yet debited.
display	Boolean	Whether the bank account should be presented.
last_update	DateTime or null	Last successful update of the account.
deleted	DateTime or null	If set, this account is not found on the website anymore.
disabled	DateTime or null	If set, this account has been disabled by user and will not be synchronized anymore.
iban	String or null	Account IBAN.
currency	Currency object or null	Account currency.
type	AccountType object	Technical code of the account type.
id_type	Integer	ID of the account type.
bookmarked	Integer	This account has been bookmarked by user.
name	String	The name of the account.
error	String or null	If the last update has failed, the error code.
usage	BankAccountUsage string	Account usage. If not overridden, the value of original_usage is returned.
ownership	BankAccountOwnership string or null	(Deprecated) Relationship between the credentials owner and the account.
company_name	String or null	Name of the company holding the employee savings of the account.
loan	Loan object or null	For loan accounts, the loan details.

Available expands

The following parameters can be used for response properties expansion:

Property	Type	Description
connection	Connection object	The connection associated with this bank account.

BankAccountUsage values

Value	Description
PRIV	Private account.
ORGA	Professional account.

Forward compatibility requirement: additional usages may be added in the future. When implementing usage handling, always fallback to a generic case for unknown values.

BankAccountOwnership values (deprecated)

Value	Description
owner	Account holder.
co-owner	Holder on a joint account.
attorney	Account authorized agent.

Forward compatibility requirement: additional ownership values may be added in the future. When implementing ownership handling, always fallback to a generic case for unknown values.

Loan object

Property	Type	Description
total_amount	Decimal or null	Total amount of the loan.
available_amount	Decimal or null	Amount of the loan not yet released and still available.
used_amount	Decimal or null	Amount of the load already used.
subscription_date	Date or null	Subscription date of the loan.
maturity_date	Date or null	Estimated end date of the loan.
start_repayment_date	Date or null	When starts the repayment of the loan. In case of deferred loans, some fees could be payed by the borrower before the first repayment term planned at this start_repayment_date.
deferred	Boolean or null	(beta) True if loan repayment has not yet begun.
next_payment_amount	Decimal or null	Amount of the next payment.
next_payment_date	Date or null	Date of the next payment.
rate	Decimal or null	Rate of the loan.
nb_payments_left	Integer or null	Number of payments still due.
nb_payments_done	Integer or null	Number of payments done.
nb_payments_total	Integer or null	Total number of payments.
last_payment_amount	Decimal or null	Amount of the last payment.
last_payment_date	Date or null	Date of the last payment.
account_label	String or null	Name of the debited account.
insurance_label	String or null	Label of the insurance.
insurance_amount	Decimal or null	Amount of the loan's insurance.
insurance_rate	Decimal or null	Rate of the insurance (between 0 and 1).
duration	Integer or null	Duration of the loan, in months.
type	String	Type of the loan: mortgage, consumercredit, revolvingcredit or loan (by default).

BankAccountUpdateRequest object

Name	Type	Required	Description
display	Boolean	No	Whether the bank account should be displayed and included in aggregated metrics.
name	String	No	Display name of the account.
disabled	Boolean	No	Whether the bank account should be synchronized.
bookmarked	Boolean	No	Whether the bank account is bookmarked.
usage	BankAccountUsage string	No	Account usage.