Overview Report

GET /api/v1/reports/overview

Returns aggregated transaction data showing inflow/outflow sums and counts grouped by time period. This endpoint provides the same data as the Overview/Heatmap Report in the web UI, which visualizes transaction activity over time.

Query Parameters

Example Request

curl -X GET "https://statements.finopsbricks.com/api/v1/reports/overview?date_from=2024-01-01&date_to=2024-01-31&group_by=day" \
  -H "api-key: fob_stm_xxxxxxxxxxxx" \
  -H "api-secret: xxxxxxxxxxxxxxxx"

Response

{
  "data": {
    "period": {
      "date_from": "2024-01-01",
      "date_to": "2024-01-31",
      "group_by": "day"
    },
    "accounts": [
      {
        "id": "acc123",
        "name": "Business Checking",
        "category": "bank"
      },
      {
        "id": "acc456",
        "name": "Credit Card",
        "category": "credit_card"
      }
    ],
    "data": [
      {
        "period": "2024-01-01",
        "inflow": 15000.00,
        "outflow": 8500.00,
        "net": 6500.00,
        "inflow_count": 12,
        "outflow_count": 8,
        "total_count": 20
      },
      {
        "period": "2024-01-02",
        "inflow": 22000.00,
        "outflow": 12000.00,
        "net": 10000.00,
        "inflow_count": 18,
        "outflow_count": 15,
        "total_count": 33
      }
    ]
  }
}

Response Fields

period

accounts

Array of account objects included in the report (non-archived accounts).

data

Array of overview data objects grouped by period.

Period Format

The period field format depends on the group_by parameter:

• day: YYYY-MM-DD (e.g., "2024-01-15")
• week: ISO 8601 timestamp of week start (e.g., "2024-01-08T00:00:00.000Z")
• month: ISO 8601 timestamp of month start (e.g., "2024-01-01T00:00:00.000Z")
• year: ISO 8601 timestamp of year start (e.g., "2024-01-01T00:00:00.000Z")

Understanding Overview Reports

Overview reports provide a high-level view of transaction activity patterns:

• Transaction Density: Identify periods with high or low transaction volumes
• Cash Flow Patterns: Visualize inflow vs outflow trends over time
• Activity Heatmap: Spot unusual transaction activity or gaps in data
• Period Comparison: Compare activity across different time periods

This report is particularly useful for:

• Identifying data coverage gaps (days with zero transactions)
• Spotting anomalies in transaction patterns
• Understanding seasonal cash flow trends
• Verifying data completeness

Filtering Options

Special Values

• entity='empty': Filters for transactions with null or empty entity field
• category='empty': Filters for transactions with null or empty category field
• comments='empty': Filters for transactions with null or empty comments field

Partial Matching

The particulars, entity, category, and comments filters use case-insensitive partial matching:

• particulars=salary matches "Salary Payment", "SALARY", "Monthly Salary"
• entity=vendor matches "Vendor ABC", "VENDOR XYZ", "Main Vendor"
• category=expense matches "Office Expense", "EXPENSE", "Travel Expenses"

Account Filtering

Pass comma-separated account IDs to filter transactions:

• accounts=acc123 - Single account
• accounts=acc123,acc456,acc789 - Multiple accounts

Combining Filters

All filters can be combined to narrow down results:

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

Use Cases

Daily Activity Monitoring

# Get daily transaction activity for current month
curl -X GET "https://statements.finopsbricks.com/api/v1/reports/overview?\
date_from=2024-01-01&\
date_to=2024-01-31&\
group_by=day" \
  -H "api-key: fob_stm_xxxxxxxxxxxx" \
  -H "api-secret: xxxxxxxxxxxxxxxx"

Monthly Cash Flow Overview

# Get monthly overview for the year
curl -X GET "https://statements.finopsbricks.com/api/v1/reports/overview?\
date_from=2024-01-01&\
date_to=2024-12-31&\
group_by=month" \
  -H "api-key: fob_stm_xxxxxxxxxxxx" \
  -H "api-secret: xxxxxxxxxxxxxxxx"

Account-Specific Activity

# Get activity for specific accounts
curl -X GET "https://statements.finopsbricks.com/api/v1/reports/overview?\
date_from=2024-01-01&\
date_to=2024-12-31&\
group_by=week&\
accounts=acc123,acc456" \
  -H "api-key: fob_stm_xxxxxxxxxxxx" \
  -H "api-secret: xxxxxxxxxxxxxxxx"

Errors