Get Financial Account Balances

The Get Financial Account Balances endpoint retrieves current balance data for all financial accounts associated with a user. It supports optional filtering by a specific financial account or by a point-in-time period, making it suitable for both real-time balance checks and historical balance lookups. This endpoint is essential for dashboards, account management screens, and financial reporting workflows.

Endpoint

GET /api/financialAccounts/balance

Authentication

Bearer token required. Obtain via:

POST https://api.banking.netevia.dev/api/auth/v2

Include in header: Authorization: Bearer {token}
Token lifetime: 10 minutes. Refresh via POST /api/auth/refresh.

When to use

Use this endpoint when you need to display up-to-date account balances to a customer, populate a financial dashboard, or verify available funds before initiating a transfer or payment. You can scope the result to a single account by passing financialAccountId, or retrieve balances as of a specific date and time using the period parameter.

Query Parameters

Response

200 OK

Returns an array of balance objects. Each object contains a date and the corresponding balance in cents (integer).

[
  {
    "date": "2024-06-08T00:00:00Z",
    "balance": 524750
  },
  {
    "date": "2024-06-07T00:00:00Z",
    "balance": 498200
  }
]

Error Codes

Common Mistakes

• Passing a period value in a non-ISO 8601 format (e.g., 06/08/2024) will result in a 400 error; always use the date-time format such as 2024-06-08T00:00:00Z.
• The balance field is returned as an integer in the smallest currency unit (cents). Divide by 100 to display a dollar amount — do not treat the raw value as a dollar figure.
• Omitting financialAccountId returns balances for all accounts linked to the token's user; if you only need one account's balance, pass the ID to avoid processing unnecessary data.
• A customer may have up to 5 active financial accounts by default. Ensure your integration handles an array response rather than expecting a single object.

Related Endpoints

• GET /api/financialAccounts — Retrieve the list of all financial accounts for the authenticated user, including account IDs needed for the financialAccountId parameter
• GET /api/financialAccounts/{financialAccountId} — Retrieve detailed information for a single financial account
• GET /api/financialAccounts/transactions — Retrieve transaction history for financial accounts

Example

curl -X GET "https://api.banking.netevia.dev/api/financialAccounts/balance?financialAccountId=fa_XXXXXXXXXX&period=2024-06-08T00%3A00%3A00Z" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json"