Appearance
WeekOne API reference
Use WeekOne APIs to read employee onboarding progress, discover workflow templates, assign workflows, and receive task updates from external systems. Replace https://YOUR-INSTANCE in examples with your WeekOne deployment origin.
Authentication
| API | Credential |
|---|---|
Public /api/v1 employee, team, learning-path and workflow endpoints | Integration token from Settings → API Access |
| Task status callback | Execution-scoped callback key inserted into the outgoing API task body |
/api/v1/tokens management | Signed-in admin or owner browser session; writes also require a same-origin Origin or Referer header |
Legacy /api?action=employee-track | Organisation API key, supplied by your organisation owner |
Send integration tokens and callback keys as Authorization: Bearer YOUR_TOKEN. A callback key grants access to one task execution; it does not grant access to reporting APIs. Store credentials securely and never put them in URLs.
Create an integration token in API Access settings, copy its secret when shown, and use it from your server:
bash
curl -H 'Authorization: Bearer YOUR_INTEGRATION_TOKEN' \
'https://YOUR-INSTANCE/api/v1/employees?page=1&pageSize=50'Public v1 endpoints enforce organisation isolation and active subscription status. Tokens can be revoked in settings. Optional employee fields are hidden unless enabled in the token's field allowlist. Passwords are never exposed.
Endpoint directory
| Method | Path | Reference |
|---|---|---|
| GET | /api/v1/employees | Employees |
| GET | /api/v1/employees/{employeeId} | Employee overview |
| GET | /api/v1/employees/{employeeId}/workflows | Assigned workflows |
| GET | /api/v1/employees/{employeeId}/workflows/{assignmentId} | Assigned workflow detail |
| GET | /api/v1/employees/{employeeId}/learning-paths | Assigned learning paths |
| GET | /api/v1/employees/{employeeId}/learning-paths/{learningPathId} | Assigned learning path detail |
| GET | /api/v1/workflows | Workflow catalog |
| GET | /api/v1/workflows/{workflowId} | Workflow requirements |
| POST | /api/v1/employees/{employeeId}/workflows | Assign a workflow |
| GET | /api/v1/teams | Teams |
| GET | /api/v1/learning-paths | Learning path catalog |
| POST | /api/callbacks/tasks/{taskId}/status | Task callbacks |
| GET, POST | /api/v1/tokens | Token management |
| POST | /api/v1/tokens/{tokenId}/revoke | Revoke a token |
| POST | /api?action=employee-track | Legacy employee track |
| POST | /api/callbacks/tasks/{taskId}/complete | Legacy completion callback |
Application endpoints for the flow designer, connection administration, test requests, execution history and recovery use browser authentication. They are internal application APIs rather than integration contracts.
Pagination and filtering
GET /employees, /teams and /learning-paths accept page (default 1) and pageSize (default 50, maximum 200). Responses contain data and pagination:
json
{"data":[],"pagination":{"page":1,"pageSize":50,"total":0,"hasNext":false}}Employee lists and employee detail/nested assignment endpoints accept includeArchived=true (also 1). This includes archived employees and assignments where supported. Employee lists normally include EMPLOYEE and HIRING_MANAGER users; includePrivileged=true also includes ADMIN and OWNER users. Direct employee-ID lookups and workflow assignment creation accept all four roles without that flag. The team and learning-path catalogs exclude deleted records.
Errors and rate limits
V1 failures generally return {"error":"message"}. Workflow assignment validation also provides code and fields; callback failures return a stable translation key in error.
| Status | Meaning |
|---|---|
| 400 | Invalid JSON, missing parameters, or invalid input |
| 401 | Missing, invalid or revoked credential |
| 403 | Inactive subscription, insufficient role, invalid browser origin, or plan restriction |
| 404 | Resource not found within the authenticated organisation |
| 405 | Unsupported method |
| 409 | Duplicate active assignment or incompatible task/execution state |
| 413 | Callback payload exceeds 64 KiB |
| 415 | Callback request is not JSON |
| 422 | Callback outputs or profile mappings are invalid, or input contains credentials |
| 429 | V1 integration token rate limit exceeded |
V1 integration tokens allow 100 requests per 60-second window per token. A 429 response includes Retry-After (seconds) and X-RateLimit-Reset (ISO timestamp). Back off until the indicated time. Task callbacks and browser token management do not use this v1 token rate limit. Do not blindly retry workflow assignment POST requests: check existing assignments after an ambiguous network result.