Get Balance History
Returns an array of dated balance snapshots for a given financial account over a specified time period. This endpoint is useful for generating account statements, auditing balance trends, and powering reporting dashboards. Each entry in the response pairs a timestamp with the account balance recorded at that point in time.
Endpoint
GET /Report/balance
Authentication
Bearer token required. Obtain via:
POST https://api.banking.netevia.dev/api/auth/v2Include 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 audit historical balance changes for a specific financial account over a defined period. It is commonly used to build balance trend charts, generate periodic account statements, or verify that scheduled transfers and transactions have resulted in expected balance movements.
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| period | string (date-time) | No | The point in time (ISO 8601 date-time) up to which balance history is retrieved. |
| profileId | integer (int32) | No | The unique identifier of the customer profile whose account balance history is being requested. |
| financialAccountId | string | No | The unique identifier of the financial account for which balance history is retrieved. |
Response
200 OK
Returns an array of datebalance objects, each representing a balance snapshot at a specific date and time.
| Field | Type | Description |
|---|---|---|
| date | string (date-time) | The date and time at which the balance snapshot was recorded, in ISO 8601 format. |
| balance | integer (int64) | The account balance at the recorded date, expressed in the smallest currency unit (e.g., cents). |
[
{
"date": "2024-01-01T00:00:00Z",
"balance": 150000
},
{
"date": "2024-01-15T00:00:00Z",
"balance": 143500
},
{
"date": "2024-02-01T00:00:00Z",
"balance": 162000
}
]Error Codes
| Code | When it happens |
|---|---|
| 400 | Missing required fields or validation error |
| 401 | Token missing, expired, or invalid |
| 403 | Insufficient permissions |
| 404 | Resource not found |
| 500 | Internal server error |
Common Mistakes
- Providing a
periodvalue that is not a valid ISO 8601 date-time string, which will result in a 400 validation error. - Omitting
financialAccountIdwhen querying a profile that has multiple financial accounts, which may return balance history across unintended accounts or an empty result. - Using a
profileIdthat does not belong to the authenticated partner, which will result in a 403 forbidden error. - Forgetting that
balancevalues are expressed in the smallest currency unit (cents), so a value of150000represents $1,500.00.
Related Endpoints
GET /Report/transactions— Retrieve transaction history for a financial account over a specified period.GET /Report/statement— Generate a formal account statement for a given financial account and date range.
Example
curl -X GET "https://api.banking.netevia.dev/Report/balance?period=2024-02-01T00%3A00%3A00Z&profileId=98765&financialAccountId=XXXXXXXXXX" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json"