List Balances

Retrieves a history of account balances associated with a consent, with optional filtering. For the most recent balance only, please check the accounts/list endpoint.

Consent status: If the consent is expired, revoked, deactivated, failed, or suspended, this endpoint returns 400 with code consent_not_active.

Important Notes

At least one normalized balance type (available) is always provided per account
The amount field is always a positive number - use credit_debit_indicator to determine the actual sign
For overdraft/negative balances, credit_debit_indicator will be debit

Normalized Balance Types

These types are commonly available across banks:

Type

Description

available	Available balance calculated in the course of the business day, at the time specified, subject to further changes. Calculated on booked credit/debit items.
closing	Closing balance of cleared amount. Only provided when bank explicitly provides ClosingCleared/Booked balance.

Additional Bank-Specific Balance Types

Type

Description

closing_available	Closing balance at account owner's disposal on the date specified
closing_booked	Balance at end of pre-agreed account reporting period (sum of opening booked + all entries during period)
closing_cleared	Closing balance of cleared amount on date specified
expected	Balance of booked entries and pending items, projecting end-of-day balance if everything is booked
forward_available	Forward available balance at disposal on date specified
information	Balance for informational purposes
interim_available	Available balance in course of business day, subject to changes
interim_booked	Balance calculated in course of business day, subject to changes
interim_cleared	Cleared balance in course of business day, subject to changes
opening_available	Opening balance at account owner's disposal on date specified
opening_booked	Book balance at beginning of reporting period (equals previous closing book balance)
opening_cleared	Opening balance of cleared amount on date specified
previouslyclosedbooked	Balance at previously closed reporting period

Balance Interpretation Guide

The meaning of a balance depends on the combination of type, credit_limit_included, and credit_debit_indicator:

Available Balance

credit_limit_included

credit_debit_indicator

Meaning

false	credit	Account balance representing the amount of money which can be spent
false	debit	Borrowed funds from the account's associated overdraft
true	credit	Total balance = account balance + overdraft value

Closing Balance

credit_limit_included

credit_debit_indicator

Meaning

false	credit	Account balance at the official banking day closing
false	debit	Borrowed funds from overdraft at banking day closing
true	credit	Remaining unused overdraft amount at day closing

Body Parameters

client_idstring Required

API client identifier

Max length

128

client_secretstring

API client secret for authentication. Required for internal (non-OAuth2) authentication mode (e.g., test-only). Not required when using OAuth2 (Bearer token) authentication.

Max length

128

consent_idstring Required

filterobject

Filter criteria for listing balances. All filters are optional and combined with AND logic.

Show child attributes

paginationobject

Pagination parameters for list endpoints using keyset-based pagination. Keyset pagination provides stable, efficient pagination that works well with large datasets and concurrent updates.

Show child attributes

Response

200

Object

Balances retrieved successfully

Response Attributes

api_client_appstring

Name of the API client application

client_idstring

API client identifier

request_idstring

Unique identifier for the API request

consent_idstring

ID of the consent these balances belong to

balancesarray

List of balances matching the filter criteria

Show child attributes

paginationobject

Pagination metadata included in list responses

Show child attributes

latest_completed_jobobject | null

Slim summary of the most recently successfully completed AIS data refresh job (full or light) for the consent referenced by the request. null when no job has ever completed for the consent.

Show child attributes

400

Object

Validation error or invalid request

Response Attributes

error_idstring Required

Unique identifier for this error instance

request_idstring Required

Request identifier for tracking and correlation

codestring Required

Machine-readable error code for 400 errors:

bad_request: Generic validation or request error
validation_error: Request payload validation failed
invalid_input: Invalid input data provided
internal_error: AIS-side unexpected internal error
external_api_unavailable: External provider HTTP failure (timeout, connection refused, DNS, etc.). Surfaced as HTTP 400 instead of a gateway 504.
external_api_error: External provider returned a structured error during the AIS ...

Enum values:

bad_requestvalidation_errorinvalid_inputinternal_errorexternal_api_unavailableexternal_api_errorcooldown_failedconsent_not_activejob_in_progressmethod_selection_error

... 2 other enums

messagestring Required

Human-readable error message

401

Object

Authentication failed

Response Attributes

error_idstring Required

Unique identifier for this error instance

request_idstring Required

Request identifier for tracking and correlation

codestring Required

Machine-readable error code for 401 errors:

unauthorized: Authentication failed or insufficient permissions

Enum values:

unauthorized

messagestring Required

Human-readable error message

404

Object

Resource not found

Response Attributes

error_idstring Required

Unique identifier for this error instance

request_idstring Required

Request identifier for tracking and correlation

codestring Required

Machine-readable error code for 404 errors:

not_found: Generic resource not found
consent_not_found: Specified consent does not exist
job_not_found: Specified job does not exist or outside accessible date range

Enum values:

not_foundconsent_not_foundjob_not_found

messagestring Required

Human-readable error message

Sections

List Balances

Important Notes

Normalized Balance Types

Additional Bank-Specific Balance Types

Balance Interpretation Guide

Available Balance

Closing Balance

Body ParametersExpand all

ResponseExpand all

Response Attributes

Response Attributes

... 2 other enums

Response Attributes

Response Attributes

Response

Ask an AI

Code with AI

Body Parameters

Response