Get Financial Overview (v1)

Method & Path

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

Description

Get financial overview with charts data including income, expenses, and profit breakdowns for the specified period.

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
period	string	No	Time period (daily, weekly, monthly, yearly, custom). Default: monthly
startDate	string	No	Start date for custom period (YYYY-MM-DD format). Required when period is custom
endDate	string	No	End date for custom period (YYYY-MM-DD format). Required when period is custom

Response 200 OK

{
  "period": "monthly",
  "startDate": "2025-01-01",
  "endDate": "2025-01-31",
  "expenses": {
    "total": 3000.00,
    "count": 10,
    "chartData": [
      { "date": "2025-01-01", "amount": 500.00 },
      { "date": "2025-01-08", "amount": 800.00 },
      { "date": "2025-01-15", "amount": 600.00 },
      { "date": "2025-01-22", "amount": 700.00 },
      { "date": "2025-01-29", "amount": 400.00 }
    ]
  },
  "income": {
    "total": 10000.00,
    "count": 25,
    "chartData": [
      { "date": "2025-01-01", "amount": 2000.00 },
      { "date": "2025-01-08", "amount": 2500.00 },
      { "date": "2025-01-15", "amount": 2000.00 },
      { "date": "2025-01-22", "amount": 2000.00 },
      { "date": "2025-01-29", "amount": 1500.00 }
    ]
  },
  "profit": {
    "total": 7000.00,
    "chartData": [
      { "date": "2025-01-01", "amount": 1500.00 },
      { "date": "2025-01-08", "amount": 1700.00 },
      { "date": "2025-01-15", "amount": 1400.00 },
      { "date": "2025-01-22", "amount": 1300.00 },
      { "date": "2025-01-29", "amount": 1100.00 }
    ]
  }
}

Response Fields

• period (string): The time period used for the overview
• startDate (string): Start date of the period (YYYY-MM-DD format)
• endDate (string): End date of the period (YYYY-MM-DD format)
• expenses (object): Expense data
  • total (number): Total expenses for the period
  • count (number): Number of expense records
  • chartData (array): Array of data points for chart visualization
    • date (string): Date in YYYY-MM-DD format
    • amount (number): Expense amount for that date
• income (object): Income data
  • total (number): Total income for the period
  • count (number): Number of income records
  • chartData (array): Array of data points for chart visualization
    • date (string): Date in YYYY-MM-DD format
    • amount (number): Income amount for that date
• profit (object): Profit data (income - expenses)
  • total (number): Total profit for the period
  • chartData (array): Array of data points for chart visualization
    • date (string): Date in YYYY-MM-DD format
    • amount (number): Profit amount for that date

Common Errors

400 Bad Request:

• Invalid workspace ID format
• Invalid period value
• Missing startDate or endDate when period is custom
• 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 analytics

404 Not Found: Workspace not found

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

Notes

• Date calculations use the workspace's configured timezone
• Chart data points are aggregated based on the selected period:
  • daily: One data point per day
  • weekly: One data point per week (starting from Sunday)
  • monthly: One data point per month
  • yearly: One data point per year
  • custom: Data points based on the date range
• Profit is calculated as income minus expenses for each period
• Workspace subscription status is checked before processing the request