Balance Report

GET /api/v1/reports/balance

Returns daily cash position data for accounts over a date range. This endpoint provides the same data as the Balance Report in the web UI.

Query Parameters

Parameter	Type	Required	Default	Description
date_from	string	No	60 days ago	Start date (YYYY-MM-DD)
date_to	string	No	today	End date (YYYY-MM-DD)
accounts	string	No	all	Comma-separated account IDs to filter

Example Request

curl -X GET "https://statements.finopsbricks.com/api/v1/reports/balance?date_from=2024-01-01&date_to=2024-12-31&accounts=acc123,acc456" \
  -H "api-key: fob_stm_xxxxxxxxxxxx" \
  -H "api-secret: xxxxxxxxxxxxxxxx"

Response

{
  "data": {
    "period": {
      "date_from": "2024-01-01",
      "date_to": "2024-12-31"
    },
    "accounts": [
      {
        "id": "acc123",
        "name": "Main Business Account",
        "category": "bank",
        "opening_balance": 10000.00,
        "opening_balance_date": "2024-01-01"
      }
    ],
    "opening_balances": [
      {
        "account_id": "acc123",
        "account_name": "Main Business Account",
        "balance_at_period_start": 10000.00,
        "total_inflow_before_period": 0,
        "total_outflow_before_period": 0
      }
    ],
    "daily_aggregates": [
      {
        "account_id": "acc123",
        "date": "2024-01-01",
        "daily_inflow": 5000.00,
        "daily_outflow": 2000.00,
        "transaction_count": 12
      },
      {
        "account_id": "acc123",
        "date": "2024-01-02",
        "daily_inflow": 3000.00,
        "daily_outflow": 1500.00,
        "transaction_count": 8
      }
    ]
  }
}

Response Fields

period

Field	Type	Description
date_from	string	Start date of the report
date_to	string	End date of the report

accounts

Array of account objects included in the report.

Field	Type	Description
id	string	Account ID
name	string	Account name
category	string	Account category (`bank` or `credit_card`)
opening_balance	number\|null	Account's configured opening balance
opening_balance_date	string\|null	Date of the opening balance

opening_balances

Balance at the start of the report period for each account.

Field	Type	Description
account_id	string	Account ID
account_name	string	Account name
balance_at_period_start	number\|null	Computed balance at start of `date_from`
total_inflow_before_period	number\|null	Sum of inflows before the period
total_outflow_before_period	number\|null	Sum of outflows before the period

daily_aggregates

Daily transaction summaries for each account. Only dates with transactions are included.

Field	Type	Description
account_id	string	Account ID
date	string	Transaction date
daily_inflow	number	Total inflows for the day
daily_outflow	number	Total outflows for the day
transaction_count	number	Number of transactions

Computing Daily Balances

To compute the end-of-day balance for any date:

EOD Balance = balance_at_period_start + cumulative_inflows - cumulative_outflows

Where cumulative values are the sum of daily_aggregates from date_from up to and including the target date.

Errors

Code	Description
400	Invalid date format (must be YYYY-MM-DD)
400	`date_from` is after `date_to`
401	Invalid or missing API credentials
403	API key lacks `reports:read` permission