> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Workforce Management API

> Forecast contact volume, build agent schedules, publish open shifts, and track adherence for your contact center.

# 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](/api-reference/error-codes).

## Forecasts

Project contact volume and average handle time, run what-if scenarios, and score past forecasts against actuals.

| Method | Path                              | Purpose                                      |
| ------ | --------------------------------- | -------------------------------------------- |
| `GET`  | `/api/v1/wfm/forecasts`           | List forecasts                               |
| `POST` | `/api/v1/wfm/forecasts/recompute` | Recompute a forecast from historical data    |
| `POST` | `/api/v1/wfm/forecasts/what-if`   | Run a what-if scenario without persisting it |
| `GET`  | `/api/v1/wfm/forecasts/accuracy`  | Compare a past forecast 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.

| Method | Path                            | Purpose                                                  |
| ------ | ------------------------------- | -------------------------------------------------------- |
| `POST` | `/api/v1/wfm/staffing/optimize` | Optimize staffing across channels (dedicated vs blended) |

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.

| Method   | Path                      | Purpose        |
| -------- | ------------------------- | -------------- |
| `POST`   | `/api/v1/wfm/shifts`      | Create a shift |
| `GET`    | `/api/v1/wfm/shifts`      | List shifts    |
| `GET`    | `/api/v1/wfm/shifts/{id}` | Get a shift    |
| `PATCH`  | `/api/v1/wfm/shifts/{id}` | Update a shift |
| `DELETE` | `/api/v1/wfm/shifts/{id}` | Delete a shift |

## Schedule generation

Generate a draft schedule from a forecast and staffing rules, then commit it once you have reviewed the preview.

| Method | Path                                    | Purpose                             |
| ------ | --------------------------------------- | ----------------------------------- |
| `POST` | `/api/v1/wfm/schedules/generate`        | Generate a draft schedule (preview) |
| `POST` | `/api/v1/wfm/schedules/generate/commit` | Commit a generated schedule         |

## Assignments

Assign agents to shifts and adjust a published schedule.

| Method   | Path                           | Purpose                                 |
| -------- | ------------------------------ | --------------------------------------- |
| `POST`   | `/api/v1/wfm/assignments`      | Assign an agent to a shift              |
| `POST`   | `/api/v1/wfm/assignments/bulk` | Create multiple assignments in one call |
| `GET`    | `/api/v1/wfm/assignments`      | List assignments                        |
| `GET`    | `/api/v1/wfm/assignments/{id}` | Get an assignment                       |
| `PATCH`  | `/api/v1/wfm/assignments/{id}` | Update an assignment                    |
| `DELETE` | `/api/v1/wfm/assignments/{id}` | Remove an assignment                    |

## Open shifts

Publish unassigned shifts for agents to bid on, then award them.

| Method | Path                                                 | Purpose                         |
| ------ | ---------------------------------------------------- | ------------------------------- |
| `POST` | `/api/v1/wfm/open-shifts`                            | Publish an open shift           |
| `GET`  | `/api/v1/wfm/open-shifts`                            | List open shifts                |
| `GET`  | `/api/v1/wfm/open-shifts/{id}`                       | Get an open shift               |
| `POST` | `/api/v1/wfm/open-shifts/{id}/cancel`                | Cancel an open shift            |
| `POST` | `/api/v1/wfm/open-shifts/{id}/bids`                  | Place a bid on an open shift    |
| `GET`  | `/api/v1/wfm/open-shifts/{id}/bids`                  | List bids on an open shift      |
| `POST` | `/api/v1/wfm/open-shifts/{id}/bids/{bidId}/withdraw` | Withdraw a bid                  |
| `POST` | `/api/v1/wfm/open-shifts/{id}/award`                 | Award an open shift to a bidder |

## Requests

Handle agent time-off, shift-swap, and preference requests through an approval workflow.

| Method | Path                                    | Purpose                                                |
| ------ | --------------------------------------- | ------------------------------------------------------ |
| `POST` | `/api/v1/wfm/requests`                  | Submit a time-off, shift-swap, or preference request   |
| `GET`  | `/api/v1/wfm/requests`                  | List requests (filter by `agent_id`, `status`, `type`) |
| `GET`  | `/api/v1/wfm/requests/{id}`             | Get a request                                          |
| `POST` | `/api/v1/wfm/requests/{id}/accept-swap` | Counterparty accepts a shift-swap request              |
| `POST` | `/api/v1/wfm/requests/{id}/approve`     | Approve a request                                      |
| `POST` | `/api/v1/wfm/requests/{id}/deny`        | Deny a request                                         |
| `POST` | `/api/v1/wfm/requests/{id}/cancel`      | Cancel a request                                       |

## Adherence

Measure how closely agents follow their scheduled activities, per agent, per team, and intraday.

| Method | Path                             | Purpose                     |
| ------ | -------------------------------- | --------------------------- |
| `GET`  | `/api/v1/wfm/adherence`          | Adherence scores by agent   |
| `GET`  | `/api/v1/wfm/adherence/team`     | Adherence rolled up by team |
| `GET`  | `/api/v1/wfm/adherence/intraday` | Intraday adherence timeline |

### Adherence exceptions

Record and review exceptions that should not count against an agent's adherence.

| Method | Path                                            | Purpose                    |
| ------ | ----------------------------------------------- | -------------------------- |
| `POST` | `/api/v1/wfm/adherence-exceptions`              | Create an exception        |
| `GET`  | `/api/v1/wfm/adherence-exceptions`              | List exceptions            |
| `GET`  | `/api/v1/wfm/adherence-exceptions/trends`       | Exception trends over time |
| `POST` | `/api/v1/wfm/adherence-exceptions/{id}/approve` | Approve an exception       |
| `POST` | `/api/v1/wfm/adherence-exceptions/{id}/deny`    | Deny an exception          |
| `POST` | `/api/v1/wfm/adherence-exceptions/{id}/cancel`  | Cancel an exception        |

### Real-time adherence

Stream live adherence events and read current breaches.

| Method | Path                       | Purpose                                                 |
| ------ | -------------------------- | ------------------------------------------------------- |
| `GET`  | `/api/v1/wfm/rta/stream`   | Server-sent event stream of real-time adherence updates |
| `GET`  | `/api/v1/wfm/rta/breaches` | List current adherence breaches                         |

## Shrinkage

Compute and read shrinkage (the share of paid time agents are not handling contacts).

| Method | Path                              | Purpose               |
| ------ | --------------------------------- | --------------------- |
| `POST` | `/api/v1/wfm/shrinkage/recompute` | Recompute shrinkage   |
| `GET`  | `/api/v1/wfm/shrinkage`           | Get shrinkage figures |

## Agent insights

Surface wellness and attrition signals to support staffing decisions.

| Method | Path                            | Purpose                              |
| ------ | ------------------------------- | ------------------------------------ |
| `GET`  | `/api/v1/wfm/agent-wellness`    | Agent wellness signals               |
| `GET`  | `/api/v1/wfm/agent-flight-risk` | Agent flight-risk (attrition) scores |

<Note>
  `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.
</Note>

## See also

* [Agents API](/api-reference/agents)
* [Analytics API](/api-reference/analytics)
* [Error codes](/api-reference/error-codes)