Workforce Management API
Plan and run a contact-center workforce: forecast volume, optimize staffing across every channel, generate and edit schedules, let agents bid on open shifts, route time-off and swap requests, and measure schedule adherence in real time. Base path:/api/v1/wfm
Authentication: API key (X-API-Key) or session JWT.
Roles: read endpoints are available to the owner, admin, developer, and viewer roles.
Management write endpoints — publishing and cancelling open shifts, awarding a bid, approving or denying requests, and recomputing forecasts or shrinkage — require the owner or admin role.
Agent self-serve write actions are available to all four roles, since agents act on their own records: submitting a time-off, shift-swap, or preference request (POST /wfm/requests), accepting a shift-swap as the counterparty (POST /wfm/requests/{id}/accept-swap), and placing or withdrawing a bid on an open shift (POST /wfm/open-shifts/{id}/bids, POST /wfm/open-shifts/{id}/bids/{bidId}/withdraw). These actions are scoped by agent_id, so a caller can only act on their own request or bid regardless of role.
All data is scoped to the calling tenant. Validation failures return 422 with a VALIDATION_ERROR body; see Error codes.
Forecasts
Project contact volume and average handle time, run what-if scenarios, and score past forecasts against actuals.Staffing optimizer
Turn per-channel demand into a cross-channel staffing plan, and see the headcount you save by blending channels into shared agent pools instead of dedicating agents to one channel each.
Give it per-channel demand —
arrival_rate_per_second, expected_aht_seconds, concurrency (how many contacts one agent handles at once), and an optional service_level_target / service_level_target_seconds — or omit those and it reads the latest stored forecast for each channel (pass interval_start to target a specific interval). Define blended pools with pools; omit them and every channel forms one blended pool.
The response returns two views — channels (the agents each channel needs on its own) and pools (the agents needed when channels share a pool, with each pool’s combined demand solved together and per-channel concurrency factored in) — plus dedicated_agents_total, blended_agents_total, agents_saved, and pooling_efficiency_pct. Each pool honours the strictest service-level target among its channels, so blending never quietly relaxes an SLA. This is a read-style compute endpoint available to the owner, admin, developer, and viewer roles; it persists nothing.
Shifts
Manage the individual shift definitions that schedules are built from.Schedule generation
Generate a draft schedule from a forecast and staffing rules, then commit it once you have reviewed the preview.Assignments
Assign agents to shifts and adjust a published schedule.Open shifts
Publish unassigned shifts for agents to bid on, then award them.Requests
Handle agent time-off, shift-swap, and preference requests through an approval workflow.Adherence
Measure how closely agents follow their scheduled activities, per agent, per team, and intraday.Adherence exceptions
Record and review exceptions that should not count against an agent’s adherence.Real-time adherence
Stream live adherence events and read current breaches.Shrinkage
Compute and read shrinkage (the share of paid time agents are not handling contacts).Agent insights
Surface wellness and attrition signals to support staffing decisions.GET /wfm/agent-flight-risk is an exception to the read policy above: it is restricted to the owner and admin roles. A developer or viewer caller receives 403 INSUFFICIENT_PERMISSIONS. GET /wfm/agent-wellness follows the standard read policy and is available to all four roles.