Accounts

Business Account Insight

Receive fully automated transaction data on your bank account.

Technical

Open API Specification

  • To download the OAS 3.0 Business Account Insight API in .YAML format, click here.
  • To view the reference content and understand the full semantics of this service, open the .YAML file in a tool such as Swagger Editor.

Business Account Insight v1.0.0-beta

This is the first publication.

Environments

Note: This product is in closed beta.

Access token

The Business Account Insight API uses the OAuth 2.0 Client Credentials Flow for authorization. For more information see Client credentials. To use the API, you must obtain an access token from the Authentication API with the one or more of the following scopes:

Operation Scope Description
Details account:details:read Fetches account details.
Balances account:balance:read Reads the balance of the account.
Transactions account:transaction:read Retrieves transactions of the account.
Funds account:funds:read Checks if sufficient funds are available for amount.

GET details

GET /v1/accounts/{accountNumber}/details

This operation retrieves the details of the account, like currency and account holder name.

Request attributes
Name Type In Required Description
Authorization String Header true Access token to be passed as a Bearer token.
API-Key String Header true API Key for your application in the Developer Portal.
accountNumber String Path true IBAN of the account that you want to retrieve information on.
Response attributes
Name Type In Required Description
accountNumber String Body true IBAN of the request account.
currency String Body true Currency of the account, 3 characters, ISO 4217 currency code (EUR or USD)
accountHolderName String Body true Name of the account holder for consumers, or trade name for commercial clients.

GET balances

GET /v1/accounts/{accountNumber}/balances

This operation retrieves the details of the account, such as balance of the account, and currency.

Request attributes
Name Type In Required Description
Authorization String Header true Access token to be passed as a Bearer token.
API-Key String Header true API Key for your application in the Developer Portal.
accountNumber String Path true IBAN of the account that you want to retrieve the balance on.
Response attributes
Name Type In Required Description
accountNumber String Body true IBAN of the account on which the balance was retrieved.
balanceType String Body true Indicator of the type of balance that was retrieved.
currency String Body true Currency of the account, 3 characters, ISO 4217 currency code ( EUR or USD)
amount Number Body true Balance of the account. This can be negative when there is a debit balance.

GET transactions

GET /v1/accounts/{accountNumber}/transactions

This operation fetches available transaction details for an account. It can provide both real-time bookings for current date and also bookings for past book dates. By default, the response from the API returns transactions that are available on the account in reversed chronological order.

  • If no transactions are available, a blank response is returned.
  • If more than 50 transactions are available on the account, a next page key is returned that can be used to retrieve the next 50 transactions in a new call.

Filtering for specific book-dates can be done using the from and to date. Transactions history can be retrieved for up to a period of 18 months.

Request attributes
Name Type In Required Description
Authorization String Header true Access token to be passed as a Bearer token.
API-Key String Header true The API Key for your application in the Developer Portal.
accountNumber String Path true IBAN for which the transactions are to be retrieved.
bookDateFrom String Query false Retrieves transactions after this date (Format: yyyy-mm-dd). If field or date is omitted, the last 50 transactions are retrieved.
bookDateTo String Query false Retrieves transactions before this date (Format: yyyy-mm-dd).
nextPageKey String Query false Key parameter for fetching the next set of transactions. Use the value that is returned in the body of the previous request.
Response attributes
Name Type In Required Description
transactions Array Body true Transaction details
mutationCode String transactions true Indicates the type of transaction.
transactionTimestamp String transactions true Timestamp of the transaction execution in format yyyy-mm-dd-hh:mm:ss.000. Only used for NL.
descriptionLines Array transactions true Unformatted text entered by the user during the transaction. String array of up to nine lines of each 0 to 32 characters.
bookDate String transactions true Book date of the mutation.
balanceAfterMutation String transactions true Account book-balance after the payment transaction. Minus in case of negative balance.
counterPartyAccountNumber String transactions true Counter account number. Will be empty if no counter account is found for the transaction, for example, an ATM withdrawal.
counterPartyName String transactions true Name associated with the counter account number.
amount String transactions true Transaction amount including minus in case of transactions deducted from the account.
currency String transactions true Currency of the mutation, 3 characters alphabetic, ISO currency code (EUR or USD).
transactionId String transactions true Unique transaction identification number generated for every payment request. For ATM transactions, no transactionId is generated.
status String transactions true Status of the transaction. Possible values are: EXECUTED, or blank.
accountNumber String Body true IBAN of the request for which the transactions were retrieved.
nextPageKey String Body true Reference key of the last retrieved transaction. This can be used as Query parameter in the next call, to fetch the next set of transactions. This key is provided if more than 50 transactions are present.

GET funds

GET /v1/accounts/{accountNumber}/funds

This operation checks if the amount specified in the request is available on the account at that time, including any credit line.

Request attributes
Name Type In Required Description
Authorization String Header true Access token to be passed as a Bearer token.
API-Key String Header true API Key for your application in the developer portal.
accountNumber String Resource true IBAN for which the details are to be retrieved.
amount Number Query true Amount, decimal always a positive number, and no more than 3 decimals (fractional digits).
currency String Query false Currency of the amount, 3 characters alphabetic, ISO-4217 currency code (EUR or USD). If no currency is provided, EUR is assumed.
Response attributes
Name Type In Required Description
accountNumber String Body true IBAN of the request for which the details were retrieved.
amount Number Body true Amount as specified in the request, decimal, always a positive number and no more than 3 decimals (fractional digits).
currency String Body true Currency of the amount, 3 characters alphabetic, ISO currency code ( EUR or USD) as per ISO-4217.
available Boolean Body true Boolean indication if the requested amount is available.

GET /v1/consentinfo

This operation describes the type of authorization an access token provides on a resource. The access token represents the authorization to an account or resource. The information returned contains information about the granted scopes, account number, or transaction ID.

Request attributes
Name Type In Required Description
Authorization String Header true Access token to be passed as a Bearer token.
API-Key String Header true API Key for your application in the developer portal.
Response attributes
Name Type In Required Description
iban String Body false IBAN of the account associated with the access token.
transactionId String Body false Transaction identification number associated with the access token for registered payments. This is "null" if an access token is not used for payment.
scopes String Body false Scopes associated with the access token.
valid Number Body true Time that the token is valid, in Unix epoch format.

Error response and codes

This section describes the error response and the codes that are sent by the API.

Error response attributes
Name Type In Required Description
code String Body true Code of the error.
message String Body true Human readable error message.
reference String Body true Reference of where to find more information on error.
Trace-Id String Body true Unique identification number generated for every request.
status String Body true HTTPS error code, 4xx or 5xx.
category String Body true Category of error. Possible values are: 'BAD_REQUEST', 'FORBIDDEN', 'INTERNAL_SERVER_ERROR', 'BACKEND_ERROR'. For more generic errors, see Error handling.
Error codes

This section lists the errors that are particular for this API. If your error is not listed here, or you want to know which general errors can occur, see Error handling.

HTTP status code Error Code Error Description
400 MESSAGE_RST560_0001 Account number empty or null
400 MESSAGE_RST560_0007 IBAN is invalid
400 MESSAGE_RST560_0008 To date is invalid
400 MESSAGE_RST560_0009 From date is invalid
400 MESSAGE_RST560_0010 Account number too long
400 MESSAGE_RST560_0011 From date is greater than to date
400 MESSAGE_RST560_0012 To date is greater than current date
400 MESSAGE_RST560_0013 From date is greater than current date
400 MESSAGE_RST560_0014 Amount is invalid
400 MESSAGE_RST560_0015 Currency is invalid
400 MESSAGE_RST560_0018 Amount is blank
400 MESSAGE_RST560_0022 Invalid book date
400 MESSAGE_RST560_0023 Book date is in future
400 MESSAGE_BAI560_0029 From date is more than 18 months in the past
403 MESSAGE_RST560_0016 No access to account. Contact the account holder for details
500 MESSAGE_BAI560_0005 Report download service failure. No data exists for the request. For example, no bookings are available yet or no payments were processed on the provided bookdate. Solution is to try later or choose another date
5xx MESSAGE_xxxxxxxxxxx For any other 500 error, use the Contact form if the problem persists

Additional information

  • If a POST operation fails, retry at a later point in time. The service may be down temporarily and will succeed when the service is available again.
  • When reposting, to avoid rate limiting scenarios, do not use short retry periods.