Cashflow Report

GET /api/v1/reports/cashflow

Returns cashflow data grouped by transaction type (income, expense, asset, liability, transfer, unknown) and time period. This endpoint provides the same data as the Cashflow Report in the web UI, allowing you to analyze cash movements by transaction type over time.

Query Parameters

Parameter	Type	Required	Default	Description
date_from	string	Yes	-	Start date (YYYY-MM-DD)
date_to	string	Yes	-	End date (YYYY-MM-DD)
group_by	string	No	month	Grouping period (day/week/month/year)
accounts	string	No	all	Comma-separated account IDs to filter
particulars	string	No	-	Filter by particulars (partial match)
entity	string	No	-	Filter by entity (partial match, use 'empty' for null)
category	string	No	-	Filter by category (partial match, use 'empty' for null)

Example Request

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

Response

{
  "data": {
    "period": {
      "date_from": "2024-01-01",
      "date_to": "2024-12-31",
      "group_by": "month"
    },
    "data": [
      {
        "period": "2024-01",
        "income": {
          "inflow": 15000.00,
          "outflow": 0,
          "net": 15000.00,
          "transaction_count": 5
        },
        "expense": {
          "inflow": 0,
          "outflow": 8500.00,
          "net": -8500.00,
          "transaction_count": 12
        },
        "asset": {
          "inflow": 2000.00,
          "outflow": 500.00,
          "net": 1500.00,
          "transaction_count": 3
        },
        "liability": {
          "inflow": 1000.00,
          "outflow": 500.00,
          "net": 500.00,
          "transaction_count": 2
        },
        "transfer": {
          "inflow": 3000.00,
          "outflow": 3000.00,
          "net": 0,
          "transaction_count": 4
        }
      },
      {
        "period": "2024-02",
        "income": {
          "inflow": 18000.00,
          "outflow": 0,
          "net": 18000.00,
          "transaction_count": 6
        },
        "expense": {
          "inflow": 0,
          "outflow": 9200.00,
          "net": -9200.00,
          "transaction_count": 15
        }
      }
    ],
    "accounts": [
      {
        "id": "acc123",
        "name": "Main Business Account",
        "category": "bank"
      },
      {
        "id": "acc456",
        "name": "Business Credit Card",
        "category": "credit_card"
      }
    ]
  }
}

Response Fields

period

Field	Type	Description
date_from	string	Start date of the report
date_to	string	End date of the report
group_by	string	Grouping period used (day/week/month/year)

data

Array of period objects, each containing:

Field	Type	Description
period	string	Period identifier (format depends on group_by: YYYY-MM-DD for day, YYYY-Www for week, YYYY-MM for month, YYYY for year)
income	object	Income transactions for this period (optional, only present if data exists)
expense	object	Expense transactions for this period (optional, only present if data exists)
asset	object	Asset transactions for this period (optional, only present if data exists)
liability	object	Liability transactions for this period (optional, only present if data exists)
transfer	object	Transfer transactions for this period (optional, only present if data exists)
unknown	object	Unknown type transactions for this period (optional, only present if data exists)

Transaction Type Object

Each transaction type (income, expense, etc.) contains:

Field	Type	Description
inflow	number	Total inflows for this type in the period
outflow	number	Total outflows for this type in the period
net	number	Net amount (inflow - outflow)
transaction_count	number	Total number of transactions (inflow + outflow)

accounts

Array of account objects available for filtering:

Field	Type	Description
id	string	Account ID
name	string	Account name
category	string	Account category (bank/credit_card)

Grouping Period Formats

The period field format varies based on the group_by parameter:

day: YYYY-MM-DD (e.g., "2024-01-15")
week: YYYY-Www (e.g., "2024-W03")
month: YYYY-MM (e.g., "2024-01")
year: YYYY (e.g., "2024")

Use Cases

Cashflow Analysis: Track how different transaction types contribute to overall cashflow
Income vs Expense: Compare income and expense patterns over time
Budget Tracking: Monitor spending patterns across different periods
Financial Planning: Identify seasonal patterns in income and expenses
Asset/Liability Management: Track changes in assets and liabilities over time

Filtering

Use the optional filters to narrow down the analysis:

accounts: Focus on specific bank accounts or credit cards
particulars: Find transactions with specific descriptions
entity: Filter by vendor, customer, or entity name
category: Analyze specific expense or income categories

Errors

Code	Description
400	Missing required parameters (date_from, date_to)
400	Invalid date format (must be YYYY-MM-DD)
400	date_from is after date_to
400	Invalid group_by value (must be day, week, month, or year)
401	Invalid or missing API credentials
403	API key lacks `reports:read` permission