Engagements
Engagements represent active client work — retainers, projects, and contracts. Each engagement tracks revenue, headcount, team members, and deliverables.
Routes
GET /api/engagements
List engagements.
Auth: Required
Query params:
| Param | Type | Description |
|---|---|---|
status | string | active, paused, completed, cancelled |
company_id | string | Filter by company |
product | string | Filter by product |
limit | number | Default: 50 |
Response includes: All engagement fields + company_name from join.
GET /api/engagements/:id
Get a single engagement with company name.
Auth: Required
POST /api/engagements
Create an engagement.
Auth: Required
Request body:
| Field | Type | Required | Description |
|---|---|---|---|
company_id | string | yes | Associated company |
name | string | yes | Engagement name |
engagement_type | string | no | retainer, project, consulting. Default: retainer |
product | string | no | Default: studios |
status | string | no | Default: active |
start_date | string | no | ISO date |
end_date | string | no | ISO date |
monthly_revenue | number | no | MRR |
total_value | number | no | TCV |
headcount | number | no | Team size |
cogs | number | no | Cost of goods sold |
margin_pct | number | no | Margin percentage |
team_members | array | no | [{ role, hours, rate }] |
tools | array | no | ["Jira", "GitHub"] |
deliverables | string | no | Deliverables description |
notes | string | no | Internal notes |
PATCH /api/engagements/:id
Update engagement fields.
Auth: Required
Updatable fields: name, engagement_type, product, status, start_date, end_date, monthly_revenue, total_value, headcount, cogs, margin_pct, team_members, tools, deliverables, jira_board_url, notes, plain_status, jira_project_key, contract_renewal_date
Invoices
GET /api/invoices
List invoices.
Auth: Required
Query params: company_id, status (draft, sent, paid, overdue), limit
Response: Includes company_name from join.
POST /api/invoices
Create an invoice.
Auth: Required
Request body:
| Field | Type | Required | Description |
|---|---|---|---|
company_id | string | yes | Associated company |
amount | number | yes | Total amount |
engagement_id | string | no | Associated engagement |
invoice_number | string | no | Invoice number |
currency | string | no | Default: USD |
status | string | no | Default: draft |
issued_date | string | no | ISO date |
due_date | string | no | ISO date |
subtotal | number | no | Pre-tax amount |
tax | number | no | Tax amount |
discount | number | no | Discount amount |
margin_pct | number | no | Margin % |
cogs | number | no | Cost of goods sold |
profit | number | no | Profit amount |
line_items | array | no | Line items array |
notes | string | no | Notes |
source | string | no | manual, stripe, quickbooks. Default: manual |