Appearance
Workflows
All endpoints use an integration bearer token. There are two different IDs: a workflow template ID selects a workflow to assign, while an assignment ID identifies one employee's assigned workflow.
Workflow catalog
GET /api/v1/workflows
Returns HTTP 200 with { data: [...] }, containing the latest non-archived version per workflow template. Entries have id, name, version, status (draft or published), and updated_at. The catalog is not paginated. Draft entries may be discoverable, but only published, non-archived workflows can be assigned.
bash
curl -H 'Authorization: Bearer YOUR_INTEGRATION_TOKEN' \
'https://YOUR-INSTANCE/api/v1/workflows'Workflow requirements
GET /api/v1/workflows/{workflowId}
Use a template ID from the catalog. Returns HTTP 200 with:
workflow: catalog summary.parameters:{ key, label, type, required, defaultValue? }entries. Types aredate,text,user,email, orenum.roles:{ roleId, roleKey, roleName, required, allowedTypes, default }entries. Defaults are an internal user, an external email, or null.
startDate is required. offerDate is required when the workflow uses an offer-accepted anchor. Other keys match workflow placeholders. An unknown template returns 404.
bash
curl -H 'Authorization: Bearer YOUR_INTEGRATION_TOKEN' \
'https://YOUR-INSTANCE/api/v1/workflows/WORKFLOW_TEMPLATE_ID'Assign a workflow
POST /api/v1/employees/{employeeId}/workflows
Use an existing employee ID and a published workflow template ID. Send Content-Type: application/json:
json
{
"workflowId": "WORKFLOW_TEMPLATE_ID",
"parameters": {"startDate": "2026-11-02", "offerDate": "2026-10-20"},
"assignees": {
"role_id:ROLE_ID": {"type": "internalUser", "userId": "USER_ID"}
}
}bash
curl -X POST -H 'Authorization: Bearer YOUR_INTEGRATION_TOKEN' \
-H 'Content-Type: application/json' \
-d '{"workflowId":"WORKFLOW_TEMPLATE_ID","parameters":{"startDate":"2026-11-02"}}' \
'https://YOUR-INSTANCE/api/v1/employees/EMPLOYEE_ID/workflows'assignees is optional when valid defaults satisfy every required role. Keys can be role_id:{roleId} or the returned roleKey. Values are { "type": "internalUser", "userId": "..." } or { "type": "externalEmail", "email": "..." }, subject to each role's allowedTypes. Internal user IDs must belong to the organisation.
Use real calendar dates in YYYY-MM-DD form. Supply required custom placeholder values and avoid unknown keys. offerDate cannot be after startDate.
Success is HTTP 201:
json
{"assignment":{"id":"ASSIGNMENT_ID","workflowId":"WORKFLOW_TEMPLATE_ID","workflowVersion":1,"employeeId":"EMPLOYEE_ID","status":"IN_PROGRESS"}}The status is the stored assignment status; do not hard-code it from this illustrative example. Validation failures return HTTP 400:
json
{"error":"Validation failed.","code":"VALIDATION_FAILED","fields":{"parameters.startDate":["startDate is required."]}}A duplicate active assignment returns HTTP 409 with code: "DUPLICATE_ACTIVE_ASSIGNMENT". Missing employees or templates return 404. This endpoint does not support an idempotency key; inspect existing assignments before retrying an ambiguous submission.
Assigned workflows
GET /api/v1/employees/{employeeId}/workflows
Returns HTTP 200 with { data: [...] }. Each entry has workflowId (assignment ID), name, stepsCompleted, stepsTotal, status, offerAcceptedDate, startDate, progressPercent, workflowAssignees, steps, and isArchived.
Steps contain title, assigneeRole, assignee, status, assignedAt, completedAt, dueAt, and dayDelta. Dates can be null; a step with no due date has dueAt: null. Skipped steps do not count toward progress.
bash
curl -H 'Authorization: Bearer YOUR_INTEGRATION_TOKEN' \
'https://YOUR-INSTANCE/api/v1/employees/EMPLOYEE_ID/workflows?includeArchived=true'Assigned workflow detail
GET /api/v1/employees/{employeeId}/workflows/{assignmentId}
Returns one assigned workflow object with the same fields as the list entries, without a data wrapper. Use an assignment ID returned by the list or assignment-creation response. Despite the route's historical workflowId parameter name, a template ID will not identify the employee's assignment. Accepts includeArchived=true; returns 404 when the assignment is unavailable for this employee.
bash
curl -H 'Authorization: Bearer YOUR_INTEGRATION_TOKEN' \
'https://YOUR-INSTANCE/api/v1/employees/EMPLOYEE_ID/workflows/ASSIGNMENT_ID'