Workspace Financial Endpoints (v1)

This section documents all workspace financial management endpoints including income, expenses, and financial analytics.

Income Management

• List Incomes - Get list of workspace incomes with filters
• Get Income - Get income by ID
• Create Income - Create a new income record
• Update Income - Update an existing income record
• Delete Income - Delete an income record
• Get Income Stats - Get income statistics
• Upload Income Receipt - Upload receipt image for income

Expenses Management

• List Expenses - Get list of workspace expenses with filters
• Get Expense - Get expense by ID
• Create Expense - Create a new expense record
• Update Expense - Update an existing expense record
• Delete Expense - Delete an expense record
• Get Expense Stats - Get expense statistics
• Upload Expense Receipt - Upload receipt image for expense

Workspace-Defined Lists (Income Sources, Expense Categories, Payment Methods)

• List Income Sources - List workspace income sources for filtering and forms
• List Expense Categories - List workspace expense categories for filtering and forms
• List Payment Methods - List workspace payment methods for forms

Financial Analytics

• Get Financial Overview - Get financial overview with charts data (supports sourceId and categoryId filters)
• Get Revenue Analytics - Get revenue analytics (supports sourceId and categoryId filters)
• Get Financial Summary - Get financial summary

Recurring Expenses Management

Note: Recurring expenses endpoints are documented in the API changelog. The system allows workspace owners to create rules for recurring expenses and automatically generate expense occurrences.

Recurring Expense Rules

• POST /api/v1/client/workspace/:workspaceId/recurring-expense-rules - Create a new recurring expense rule
• GET /api/v1/client/workspace/:workspaceId/recurring-expense-rules - List recurring expense rules with filtering
• GET /api/v1/client/workspace/:workspaceId/recurring-expense-rules/:ruleId - Get a recurring expense rule by ID
• PATCH /api/v1/client/workspace/:workspaceId/recurring-expense-rules/:ruleId - Update a recurring expense rule
• POST /api/v1/client/workspace/:workspaceId/recurring-expense-rules/:ruleId/pause - Pause a recurring expense rule
• POST /api/v1/client/workspace/:workspaceId/recurring-expense-rules/:ruleId/resume - Resume a paused recurring expense rule
• DELETE /api/v1/client/workspace/:workspaceId/recurring-expense-rules/:ruleId - Delete a recurring expense rule

Recurring Expense Occurrences

• GET /api/v1/client/workspace/:workspaceId/recurring-expense-occurrences - List recurring expense occurrences with filtering
• GET /api/v1/client/workspace/:workspaceId/recurring-expense-occurrences/stats - Get occurrence statistics
• GET /api/v1/client/workspace/:workspaceId/recurring-expense-occurrences/:occurrenceId - Get an occurrence by ID
• POST /api/v1/client/workspace/:workspaceId/recurring-expense-occurrences/:occurrenceId/post - Post an occurrence (create expense and mark as posted)
• POST /api/v1/client/workspace/:workspaceId/recurring-expense-occurrences/:occurrenceId/skip - Skip an occurrence

For detailed documentation, see API Changelog - Recurring Expenses.

Authentication

All endpoints require workspace authentication. Users must be authenticated as either:

• Workspace Owner: Full access to all financial data
• Staff with Financial Permissions: Access based on role permissions

Base Path

All endpoints use the base path:

/api/v1/client/workspace/:workspaceId

Common Features

• Date Filtering: All list endpoints support date range filtering
• Pagination: List endpoints support pagination with configurable page size
• Receipt Images: Income and expense records can have receipt images attached
• Statistics: Separate endpoints provide aggregated statistics
• Subscription Check: All endpoints verify workspace subscription status