Income Report

GET /api/v1/reports/income

Returns income transaction data grouped by category or entity over time periods. This endpoint provides the same data as the Income Report pages in the web UI (both "by category" and "by entity" views).

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)
group_by_field	string	No	category	Grouping field (category/entity)
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, or "empty" for null values)
category	string	No	-	Filter by category (partial match, or "empty" for null values)

Example Request

Grouped by Category

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

Grouped by Entity

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

With Filters

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

Response

Grouped by Category

{
  "data": {
    "period": {
      "date_from": "2024-01-01",
      "date_to": "2024-12-31",
      "group_by": "month",
      "group_by_field": "category"
    },
    "data": [
      {
        "category": "Sales",
        "2024-01": {
          "inflow": 50000.00,
          "outflow": 0.00,
          "net": 50000.00,
          "transaction_count": 15
        },
        "2024-02": {
          "inflow": 65000.00,
          "outflow": 0.00,
          "net": 65000.00,
          "transaction_count": 18
        }
      },
      {
        "category": "Services",
        "2024-01": {
          "inflow": 20000.00,
          "outflow": 0.00,
          "net": 20000.00,
          "transaction_count": 5
        }
      }
    ],
    "accounts": [
      {
        "id": "acc123",
        "name": "Main Business Account",
        "category": "bank"
      }
    ]
  }
}

Grouped by Entity

{
  "data": {
    "period": {
      "date_from": "2024-01-01",
      "date_to": "2024-12-31",
      "group_by": "month",
      "group_by_field": "entity"
    },
    "data": [
      {
        "entity": "Client A",
        "2024-01": {
          "inflow": 30000.00,
          "outflow": 0.00,
          "net": 30000.00,
          "transaction_count": 8
        }
      },
      {
        "entity": "Client B",
        "2024-01": {
          "inflow": 40000.00,
          "outflow": 0.00,
          "net": 40000.00,
          "transaction_count": 10
        }
      }
    ],
    "accounts": [
      {
        "id": "acc123",
        "name": "Main Business Account",
        "category": "bank"
      }
    ]
  }
}

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)
group_by_field	string	Grouping field used (category/entity)

data

Array of income data objects. Each object contains:

Field	Type	Description
category	string	Category name (when `group_by_field=category`)
entity	string	Entity name (when `group_by_field=entity`)
[period]	object	Income data for each time period (e.g., "2024-01", "2024-02")

[period] (time period data)

Field	Type	Description
inflow	number	Total income inflow for the period (in base currency units)
outflow	number	Total income outflow for the period (in base currency units)
net	number	Net income (inflow - outflow) for the period
transaction_count	number	Total number of transactions (inflows + outflows)

accounts

Array of account objects available for filtering.

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

Understanding Income Report Data

Income Transactions

Income transactions represent money coming into the organization, typically from:

Sales revenue
Service fees
Investment income
Grants and donations
Other revenue sources

Grouping Options

By Category: Groups income by transaction category (e.g., "Sales", "Services", "Interest")

Use when analyzing different revenue streams
Default grouping when group_by_field is not specified

By Entity: Groups income by the entity field (e.g., "Client A", "Partner B")

Use when analyzing income sources by customer or partner
Helps identify top revenue contributors

Time Period Aggregation

The group_by parameter controls how dates are aggregated:

day: Daily income totals
week: Weekly income totals
month: Monthly income totals (default)
year: Yearly income totals

Filtering

Multiple filters can be combined:

accounts: Limit to specific bank accounts
particulars: Search transaction descriptions (e.g., "invoice")
entity: Filter by customer/partner name
category: Filter by income category
Use "empty" for entity or category to find uncategorized transactions

Use Cases

Revenue Analysis

# Monthly sales revenue for 2024
GET /api/v1/reports/income?date_from=2024-01-01&date_to=2024-12-31&group_by=month&category=Sales

Client Revenue Tracking

# Income by client for Q1 2024
GET /api/v1/reports/income?date_from=2024-01-01&date_to=2024-03-31&group_by=month&group_by_field=entity

Uncategorized Income Review

# Find uncategorized income transactions
GET /api/v1/reports/income?date_from=2024-01-01&date_to=2024-12-31&category=empty

Errors

Code	Description
400	Missing required parameters (`date_from` and `date_to` are required)
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/year)
400	Invalid `group_by_field` value (must be category/entity)
401	Invalid or missing API credentials
403	API key lacks `reports:read` permission

Notes

All monetary values are in base currency units (not cents/paise)
Income transactions have type="income" in the database
Dates must be in YYYY-MM-DD format
Period keys in the response match the group_by format:
- day: "2024-01-15"
- week: "2024-W03"
- month: "2024-01"
- year: "2024"
Empty/null categories or entities are returned as "empty" in the data
The net field is calculated as inflow - outflow (typically positive for income)