Get Financial Summary (v1)

Method & Path

GET /api/v1/client/workspace/:workspaceId/financial/summary

Description

Get a financial summary with total income, expenses, net profit, and record counts for the specified date range.

Authentication

Required: Workspace authentication. User must be authenticated as Workspace Owner or Staff with financial permissions.

Headers

Authorization: Bearer <workspace_token>
Content-Type: application/json

Path Parameters

Parameter	Type	Required	Description
workspaceId	string	Yes	Workspace identifier

Query Parameters

Parameter	Type	Required	Description
startDate	string	No	Start date for the summary (YYYY-MM-DD format). If not provided, includes all records
endDate	string	No	End date for the summary (YYYY-MM-DD format). If not provided, includes all records

Response 200 OK

{
  "period": "custom",
  "startDate": "2025-01-01",
  "endDate": "2025-01-31",
  "totalIncome": 10000.00,
  "totalExpenses": 3000.00,
  "netProfit": 7000.00,
  "incomeCount": 25,
  "expenseCount": 10
}

Response Fields

• period (string): Always custom for this endpoint
• startDate (string | null): Start date of the summary period (YYYY-MM-DD format), or null if not specified
• endDate (string | null): End date of the summary period (YYYY-MM-DD format), or null if not specified
• totalIncome (number): Total income amount for the period
• totalExpenses (number): Total expense amount for the period
• netProfit (number): Net profit (totalIncome - totalExpenses)
• incomeCount (number): Number of income records in the period
• expenseCount (number): Number of expense records in the period

Common Errors

400 Bad Request:

• Invalid workspace ID format
• Invalid date format (must be YYYY-MM-DD)
• startDate is after endDate

401 Unauthorized: Missing or invalid authentication token

403 Forbidden: User does not have permission to view financial summary

404 Not Found: Workspace not found

500 Internal Server Error: Server error occurred while processing the request

Notes

• If neither startDate nor endDate is provided, the summary includes all income and expense records
• If only startDate is provided, the summary includes records from that date onwards
• If only endDate is provided, the summary includes records up to that date
• Date calculations use UTC timezone
• Net profit is calculated as total income minus total expenses
• Workspace subscription status is checked before processing the request