Client Onboarding API
All endpoints require authentication and clients tool permissions. Routes are mounted under /api/clients.
Get Onboarding Progress
Section titled “Get Onboarding Progress”GET /api/clients/:companyId/onboardingReturns the client’s assigned onboarding template with all stages, milestones, and completion progress.
Permission: clients:view
Path parameters:
| Param | Type | Description |
|---|---|---|
companyId | string | Company ID |
Response: { template, stages, current_stage_type, total_milestones, completed_milestones, completion_percentage }
Each stage includes a nested milestones array with:
| Field | Type | Description |
|---|---|---|
completed | boolean | Whether the milestone is complete |
completed_at | string|null | Completion timestamp |
completed_by | string|null | User ID who completed it |
completed_by_name | string|null | User name who completed it |
source | string|null | Completion source (manual or auto) |
notes | string|null | Completion notes |
Each stage also includes completed_count and total_count summary fields.
Returns { template: null, stages: [], current_stage_type: null } if no template is assigned.
Assign Onboarding Template
Section titled “Assign Onboarding Template”POST /api/clients/:companyId/onboarding/assignAssigns an onboarding template to a client. Creates progress rows for all milestones and auto-completes milestones whose conditions are already met (e.g. deal already won, project already created, invoice already exists).
Permission: clients:update
Path parameters:
| Param | Type | Description |
|---|---|---|
companyId | string | Company ID |
Body:
| Field | Type | Required | Description |
|---|---|---|---|
template_id | string | Yes | Onboarding template ID |
force | boolean | No | Force re-assignment if a different template is already assigned |
Response: { ok: true }
Error responses:
400—template_idmissing404— Template not found/inactive or client profile not found409— Different template already assigned (useforce: trueto override). Returns{ requires_confirmation: true }
Toggle Milestone
Section titled “Toggle Milestone”PATCH /api/clients/:companyId/onboarding/milestones/:milestoneIdMarks a milestone as completed or uncompleted. Recomputes the client’s current_stage_type after toggling.
Permission: clients:update
Path parameters:
| Param | Type | Description |
|---|---|---|
companyId | string | Company ID |
milestoneId | string | Milestone ID |
Body:
| Field | Type | Required | Description |
|---|---|---|---|
completed | boolean | Yes | Whether the milestone is complete |
notes | string | No | Optional notes |
Response: { ok: true }
Error responses:
400— No onboarding template assigned404— Milestone not found in the assigned template
Stuck Clients
Section titled “Stuck Clients”GET /api/clients/onboarding/stuckDashboard widget endpoint. Returns up to 5 clients whose onboarding has stalled (no milestone activity in 14+ days, onboarding not yet completed).
Permission: clients:view
Response: { clients }
Each client includes:
| Field | Type | Description |
|---|---|---|
id | string | Company ID |
name | string | Company name |
logo_url | string|null | Company logo |
current_stage_type | string|null | Current onboarding stage type |
completed_count | number | Milestones completed |
total_count | number | Total milestones |
last_activity | string|null | Last milestone completion date |
days_since_activity | number|null | Days since last activity |