The WFM model

Workforce management (WFM) answers four questions every contact center asks every day: how much work is coming in, when should each agent work, did they do what the schedule said, and how do we rebalance when reality drifts from the plan. Orbit mounts the whole surface under /api/v1/wfm as one coherent model — not a grab-bag of endpoints — and this page explains that model once so the operator workflows and API reference stay thin. WFM splits into two halves. Planning is everything that happens before the day: forecast demand, build shift templates, generate schedules, publish assignments. Adherence measurement is everything that happens during and after the day: compare what the schedule said against what agents actually did in the ACD (their aux states — online, on a call, on break, in training, logged out) and score the difference. The first half is worthless if the second never runs; the second has nothing to score without the first. The model is also two-sided by design. Managers (owner/admin) build forecasts and schedules, publish coverage, approve or deny submissions, and read the rollups. Agents self-serve: file exception requests, bid on open shifts, claim overtime or voluntary time off, and see the schedule that comes back — scoped to their own records. Every endpoint sits on one of those two sides.

1. The six WFM domains

The /wfm prefix groups its endpoints into six domains. Each domain answers one question and owns one cluster of endpoints; the domains chain together into the planning → adherence loop.

Domain 1 — Forecasts: how much work is coming in

Forecasting turns historical traffic into projected demand per channel and interval. The surface:

GET/POST /wfm/forecasts — create and read forecast rows (required agents per channel per interval).
POST /wfm/forecasts/recompute — rebuild a forecast from current history.
GET /wfm/forecasts/accuracy — measure forecast-vs-actual so you know how much to trust the next recompute.
POST /wfm/forecasts/what-if — scenario a demand change before you commit a schedule to it.

A forecast is the input every downstream domain consumes; schedules generated without one are guesswork with timestamps.

Domain 2 — Schedules and shifts: when each agent should work

A shift is a reusable time template; shift activities are the segments inside it (work, break, training); a generated schedule maps agents onto shift windows for a period. The surface:

GET/POST /wfm/shifts, GET/PATCH/DELETE /wfm/shifts/:id — shift template CRUD.
GET/POST /wfm/shifts/:shiftId/activities — the activity segments inside a shift.
POST /wfm/schedules/generate then POST /wfm/schedules/generate/commit — draft schedules against a forecast, then publish. The two-step split means generation is a proposal until a manager commits it.

Domain 3 — Assignments: the published roster

An assignment is the committed line that says “agent X works shift Y on date Z.” It is the roster entry adherence scoring compares reality against:

GET/POST /wfm/assignments, GET/PATCH/DELETE /wfm/assignments/:id — assignment CRUD.
POST /wfm/assignments/bulk — build a full roster in one call (typical after a schedule commit).

Domain 4 — Staffing and capacity: am I covered, what coverage costs

Given the published roster, staffing answers “do I have enough people, where, and when” — and capacity planning asks the longer-horizon question “how much coverage should the week/month carry, accounting for shrinkage” (time lost to leave, holidays, training, no-shows):

GET /wfm/intraday/staffing — required vs. scheduled agents per interval, today.
POST /wfm/staffing/optimize — the optimization pass that suggests roster changes.
GET /wfm/capacity/plan — capacity against shrinkage-adjusted availability.
GET /wfm/shrinkage, POST /wfm/shrinkage/recompute — shrinkage measurement and rebuild.
POST /wfm/rebalancing/recommend and POST /wfm/rebalancing/apply — propose coverage fixes, then apply them (extend/trim assignments for the drift the staffing read found).

Holiday calendars sit in this domain: the forecaster and the scheduler both treat holiday dates as reduced-capacity days, so a public-holiday week does not come out over-staffed by accident.

Domain 5 — Adherence and timekeeping: did the day go as planned

Adherence compares the published assignments against the live agent-state feed from the ACD and scores the divergence; timekeeping records the payable time on agents’ timesheets:

GET /wfm/adherence/intraday — today’s per-agent adherence score; GET /wfm/adherence/conformance — schedule-conformance detail; GET /wfm/adherence/team — the team rollup.
GET /wfm/rta/stream — the server-sent-events wallboard supervisors watch live; GET /wfm/rta/breaches — the currently-open adherence breaches without a stream.
GET /wfm/timesheets — timekeeping records per agent.

Adherence only reads truth when agents set their aux state (online / break / training / wrap) in the dialer or inbox — the comparison input is the state feed, not login time.

Domain 6 — Wellness, risk, and the labor market

Two maintenance surfaces keep the roster healthy and keep gaps filled between planning cycles:

Wellness and risk — GET /wfm/agent-wellness (burnout/strain indicators from adherence and overtime patterns) and GET /wfm/agent-flight-risk (churn-risk scoring per agent). Output feeds into coaching and capacity decisions.
The labor market — the gap-filling surfaces: /wfm/open-shifts (publish unowned shifts, agents bid), /wfm/overtime-offers (add hours on already-scheduled agents), /wfm/vto-offers (release hours on a slow day), /wfm/leave-policies + /wfm/leave-balances (+ /adjust) (leave types and per-agent balances), and /wfm/agent-skills (the skill tags the other domains filter coverage by).

2. Planning domain samples

Every sample below runs as written — base https://api.orbit.devotel.io/api/v1, X-API-Key on every call, and the { data, meta } envelope back (envelope shapes). The reads are scoped by wfm:read; the writes need wfm:read + wfm:write, and every endpoint named here is inventoried in the WFM API reference.

Forecasts — POST `/wfm/forecasts/recompute`

Recompute rebuilds the forecast rows for one channel (or all seven when you omit channel) from the tenant’s live traffic history. The call is synchronous: a 200 carries the per-channel outcome, and partial: true plus an outcome of partial_timeout or partial_error tells you which channels to re-trigger — a 25 s wall-clock budget keeps the request under the ingress timeout instead of dying mid-write.

Node.js
Python
Go

const res = await fetch(
  "https://api.orbit.devotel.io/api/v1/wfm/forecasts/recompute",
  {
    method: "POST",
    headers: {
      "X-API-Key": process.env.ORBIT_API_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ channel: "voice" }),
  },
);
const { data } = await res.json();
console.log(data.outcome, data.upserted, data.channels);

import os, requests

res = requests.post(
    "https://api.orbit.devotel.io/api/v1/wfm/forecasts/recompute",
    headers={"X-API-Key": os.environ["ORBIT_API_KEY"]},
    json={"channel": "voice"},
)
data = res.json()["data"]
print(data["outcome"], data["upserted"], data["channels"])

body, _ := json.Marshal(map[string]string{"channel": "voice"})
req, _ := http.NewRequest("POST",
  "https://api.orbit.devotel.io/api/v1/wfm/forecasts/recompute", bytes.NewReader(body))
req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
req.Header.Set("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()

type envelope struct {
  Data map[string]any `json:"data"`
}
var env envelope
json.NewDecoder(res.Body).Decode(&env)
fmt.Println(env.Data["outcome"], env.Data["upserted"])

Response — 200 (all channels completed)

{
  "data": {
    "correlation_id": "wfmRecompute_2f8c1a",
    "partial": false,
    "outcome": "completed",
    "channels_completed": 1,
    "channels_total": 1,
    "upserted": 336,
    "duration_ms": 1240,
    "holiday_calendar_id": null,
    "holiday_overrides": 0,
    "channels": [
      { "channel": "voice", "status": "completed", "upserted": 336, "duration_ms": 1240 }
    ]
  },
  "meta": { "request_id": "req_9d21bc", "timestamp": "2026-10-09T14:02:11.004Z" }
}

What to read out of the row: channels[] is the per-channel ledger — anything not status: "completed" is a channel to re-run (a skipped_timeout row means the 25 s budget elapsed before that channel started; an error row carries its error string). upserted counts the forecast intervals written, and correlation_id is the log-grep token when a slow pass needs investigation.

Schedules — POST `/wfm/schedules/generate` then `/wfm/schedules/generate/commit`

Generation is a proposal until you commit it. /generate runs the coverage optimizer against the stored forecasts and returns the proposed assignment list plus a coverage summary — nothing is persisted on that first call. /commit persists the proposal rows (idempotently: an already-booked (agent_id, shift_id, scheduled_date) triple is skipped, never duplicated) and comes back 201 with inserted / skipped counters.

cURL — generate (proposal only)
cURL — commit (persist the proposal)

curl -X POST https://api.orbit.devotel.io/api/v1/wfm/schedules/generate \
  -H "X-API-Key: dv_live_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from_date": "2026-10-12",
    "to_date": "2026-10-18",
    "channels": ["voice"],
    "constraints": {
      "max_weekly_hours": 40,
      "min_rest_hours": 11,
      "max_consecutive_days": 6
    }
  }'

curl -X POST https://api.orbit.devotel.io/api/v1/wfm/schedules/generate/commit \
  -H "X-API-Key: dv_live_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "assignments": [
      { "agent_id": "usr_7f3a9c", "shift_id": "wfmShift_d88",
        "scheduled_date": "2026-10-12" },
      { "agent_id": "usr_7f3a9c", "shift_id": "wfmShift_d88",
        "scheduled_date": "2026-10-13" }
    ]
  }'

Response — 200 from /generate (trimmed to one proposal row)

{
  "data": {
    "from_date": "2026-10-12",
    "to_date": "2026-10-18",
    "channels": ["voice"],
    "calendar_id": null,
    "holiday_dates": [],
    "assignments": [
      { "agent_id": "usr_7f3a9c", "shift_id": "wfmShift_d88",
        "scheduled_date": "2026-10-12" }
    ],
    "coverage": [
      { "interval_start": "2026-10-12T09:00:00Z", "channel": "voice",
        "required_agents": 12.4, "scheduled_agents": 12,
        "delta": -0.4, "under_covered": false }
    ],
    "summary": {
      "intervals": 336,
      "under_covered_intervals": 24,
      "total_required": 4120.6,
      "total_scheduled": 4096,
      "proposed_assignments": 1,
      "agents_considered": 38,
      "eligible_supply_exhausted": false
    }
  },
  "meta": { "request_id": "req_31cc07", "timestamp": "2026-10-09T14:05:44.118Z" }
}

Response — 201 from /commit

{
  "data": {
    "requested": 2,
    "inserted": 2,
    "skipped": 0,
    "status": "scheduled"
  },
  "meta": { "request_id": "req_77e210", "timestamp": "2026-10-09T14:06:02.730Z" }
}

What to read out of the row: from /generate, the assignments array is exactly the payload you hand back to /commit after a manager reviews it — and summary.under_covered_intervals is the number that decides whether you regenerate with a wider agent pool before committing. From /commit, skipped > 0 means some dates were already booked and the insert deliberately did nothing for them; status is always scheduled so the rows feed adherence scoring unchanged.

Intraday staffing — GET `/wfm/intraday/staffing`

The variance read a supervisor polls during the day: required vs. scheduled agents per channel per interval against the tenant’s operating date (or a ?date= override). A variance inside the sub-agent rounding band floors to zero — a 0.001-agent residual is neither under- nor over-staffed.

Node.js
Python
Go

const res = await fetch(
  "https://api.orbit.devotel.io/api/v1/wfm/intraday/staffing",
  { headers: { "X-API-Key": process.env.ORBIT_API_KEY! } },
);
const { data } = await res.json();
console.log(data.understaffed_interval_count, data.intervals[0]);

import os, requests

res = requests.get(
    "https://api.orbit.devotel.io/api/v1/wfm/intraday/staffing",
    headers={"X-API-Key": os.environ["ORBIT_API_KEY"]},
)
data = res.json()["data"]
print(data["understaffed_interval_count"], data["intervals"][0])

req, _ := http.NewRequest("GET",
  "https://api.orbit.devotel.io/api/v1/wfm/intraday/staffing", nil)
req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()

type envelope struct {
  Data struct {
    UnderstaffedIntervalCount int `json:"understaffed_interval_count"`
  } `json:"data"`
}
var env envelope
json.NewDecoder(res.Body).Decode(&env)
fmt.Println(env.Data.UnderstaffedIntervalCount)

Response — 200 (one interval shown)

{
  "data": {
    "date": "2026-10-09",
    "generated_at": "2026-10-09T14:10:03.552Z",
    "intervals": [
      {
        "interval_start": "2026-10-09T13:30:00Z",
        "channel": "voice",
        "required_agents": 12.48,
        "scheduled_agents": 11,
        "net_variance": -1.48,
        "is_understaffed": true,
        "is_overstaffed": false
      }
    ],
    "understaffed_interval_count": 7,
    "overstaffed_interval_count": 2,
    "net_required_agent_minutes": 241.3,
    "net_scheduled_agent_minutes": 229.0,
    "net_variance_agent_minutes": -12.3
  },
  "meta": { "request_id": "req_55f8ab", "timestamp": "2026-10-09T14:10:03.552Z" }
}

What to read out of the row: negative net_variance with is_understaffed: true is the gap the rebalancing loop below repairs; the day-span totals (net_*_agent_minutes) are the KPI chips the dashboard renders — the required/scheduled agent values sit on the same average-headcount scale the forecast rows carry, so comparison is apples-to-apples.

3. One aggregate read — `GET /wfm/summary`

The WFM dashboard home assembles its top-of-page cards from one request instead of fanning out six: GET /wfm/summary returns the day’s forecast coverage, staffing totals, pending self-serve requests, open shifts, and pending bids for the tenant’s local operating date (or a date override). It resolves the same operating date as /wfm/adherence/intraday and /wfm/intraday/staffing, so the summary cards and their drill-down panels always agree on which calendar day they show.

4. Execution domain samples — the roster write + the drift repair

Two writes sit in the execution half of the loop: publishing the roster itself, and repairing that roster when intraday variance says it’s drifting. Every endpoint named here is inventoried in the WFM API reference.

Assignments — POST `/wfm/assignments/bulk`

The bulk-create fills one agent onto one shift over an inclusive date range in a single call — the typical follow-up right after a schedule commit, and the shape manual roster builders use directly. An optional ISO weekdays filter (1=Mon…7=Sun) narrows which days land; omit it and the shift template’s own declared weekdays apply. The insert is idempotent on the natural key, so a retry never double-books.

cURL
Node.js

curl -X POST https://api.orbit.devotel.io/api/v1/wfm/assignments/bulk \
  -H "X-API-Key: dv_live_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "usr_7f3a9c",
    "shift_id": "wfmShift_d88",
    "from_date": "2026-10-12",
    "to_date": "2026-10-23",
    "weekdays": [1, 2, 3, 4, 5]
  }'

const res = await fetch(
  "https://api.orbit.devotel.io/api/v1/wfm/assignments/bulk",
  {
    method: "POST",
    headers: {
      "X-API-Key": process.env.ORBIT_API_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      agent_id: "usr_7f3a9c",
      shift_id: "wfmShift_d88",
      from_date: "2026-10-12",
      to_date: "2026-10-23",
      weekdays: [1, 2, 3, 4, 5],
    }),
  },
);
const { data } = await res.json();
console.log(data.inserted, data.dates);

Response — 201 (Mon–Fri over the two-week range; one date already booked)

{
  "data": {
    "shift_id": "wfmShift_d88",
    "agent_id": "usr_7f3a9c",
    "requested_dates": 10,
    "inserted": 9,
    "skipped_dates": ["2026-10-19"]
  },
  "meta": { "request_id": "req_20c4d1", "timestamp": "2026-10-09T14:22:18.490Z" }
}

What to read out of the row: requested_dates is the count the range + weekday filter expanded into — verify it before you fan a bulk call across hundreds of agents, because a weekday filter hitting the wrong ISO numbers multiplies across the whole roster. inserted counts the rows that landed; every date in skipped_dates[] was already booked for that (agent, shift, date) triple and the insert deliberately did nothing — retry-proof. The two-step drift repair mirrors the schedule two-step: /recommend is pure compute that turns a remaining-day staffing snapshot (or the stored forecast when you omit required_agents per cell) into an ordered MOVE / ADD / RELEASE list, and /apply turns that list into floor action — short channels with a shift_by_channel mapping get their deficit posted as open shifts; channels without a mapping come back as non-writing advisories. The apply call honours dry_run: true so a supervisor (or an auto-apply caller) previews exactly what would post before anything writes.

cURL — recommend (compute only)
cURL — apply (move + publish, hint shift templates)

curl -X POST https://api.orbit.devotel.io/api/v1/wfm/rebalancing/recommend \
  -H "X-API-Key: dv_live_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "demand": [
      { "channel": "voice", "interval_start": "2026-10-09T14:30:00Z",
        "scheduled_agents": 11 },
      { "channel": "chat",  "interval_start": "2026-10-09T14:30:00Z",
        "scheduled_agents": 6 }
    ],
    "pools": [["voice", "chat"]],
    "min_gap": 1
  }'

curl -X POST https://api.orbit.devotel.io/api/v1/wfm/rebalancing/apply \
  -H "X-API-Key: dv_live_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "demand": [
      { "channel": "voice", "interval_start": "2026-10-09T14:30:00Z",
        "scheduled_agents": 11 }
    ],
    "scheduled_date": "2026-10-09",
    "shift_by_channel": { "voice": "wfmShift_d88" },
    "dry_run": false
  }'

Response — 200 from /recommend

{
  "data": {
    "min_gap": 1,
    "pools": [["voice", "chat"]],
    "recommendations": [
      {
        "action": "ADD",
        "interval_start": "2026-10-09T14:30:00Z",
        "interval_seconds": 1800,
        "channel": "voice",
        "to_channel": null,
        "agents": 2,
        "pool": ["voice", "chat"],
        "rationale": "voice is 2 agents under forecast"
      }
    ],
    "intervals": [
      {
        "interval_start": "2026-10-09T14:30:00Z",
        "interval_seconds": 1800,
        "required_agents": 13,
        "scheduled_agents": 11,
        "moves": [],
        "net_deficit": 2,
        "net_surplus": 0
      }
    ],
    "total_deficit": 2,
    "total_surplus": 0,
    "total_moved_agents": 2,
    "move_count": 1
  },
  "meta": { "request_id": "req_4a91e0", "timestamp": "2026-10-09T14:26:55.102Z" }
}

Response — 200 from /apply (publish path taken)

{
  "data": {
    "scheduled_date": "2026-10-09",
    "dry_run": false,
    "recommendations": [
      { "action": "ADD", "interval_start": "2026-10-09T14:30:00Z",
        "interval_seconds": 1800, "channel": "voice", "to_channel": null,
        "agents": 2, "pool": null, "rationale": "voice is 2 agents under forecast" }
    ],
    "plan": {
      "publishes": [
        { "channel": "voice", "shift_id": "wfmShift_d88",
          "slots": 2, "rationale": "closes the forecast deficit for voice" }
      ],
      "advisories": []
    },
    "applied": {
      "open_shifts_published": ["wfmOpenShift_bb12"],
      "open_shifts_skipped": [],
      "published_count": 1,
      "skipped_count": 0
    },
    "adherence": {
      "recommended_add_agents": 2,
      "planned_add_agents": 2,
      "applied_add_agents": 2,
      "apply_ratio": 1
    }
  },
  "meta": { "request_id": "req_87f3da", "timestamp": "2026-10-09T14:27:40.901Z" }
}

What to read out of the row: on /recommend, the intervals[] ledger is where the dead-band (min_gap) already netted out sub-agent noise — only cells still actionable reached recommendations[]. On /apply, plan.publishes[] vs plan.advisories[] is the split between “will write an open shift” and “advisory only” decided by shift_by_channel, and the adherence block’s apply_ratio tracks how much of the recommended headcount actually got posted — the floor’s signal for partial apply.

5. Adherence + health reads

Three reads close the loop: the team rollup for the executive’s summary number, the live intraday preview for the supervisor’s mid-shift call, and the capacity plan for the longer-horizon “are we hiring the right shape” question. All three are inventoried in the WFM API reference.

Team rollup — GET `/wfm/adherence/team`

The roster-wide adherence snapshot for one operating date — the same per-agent scores the intraday read computes, aggregated tenant-wide (or queue-scoped with an optional ?queue_id=). Approved exceptions are already netted into these numbers; do not re-adjust on top.

curl "https://api.orbit.devotel.io/api/v1/wfm/adherence/team?date=2026-10-09" \
  -H "X-API-Key: dv_live_sk_YOUR_KEY"

Response — 200 (one agent row shown; agents sort worst-first)

{
  "data": {
    "date": "2026-10-09",
    "queue_id": null,
    "agents_evaluated": 34,
    "agents": [
      {
        "agent_id": "usr_7f3a9c",
        "scheduled_seconds": 28800,
        "in_adherent_state_seconds": 26130,
        "adherence_ratio": 0.9073,
        "adherence_percent": 91,
        "excused_seconds": 1800,
        "adjusted_in_adherent_state_seconds": 27930,
        "adjusted_adherence_ratio": 0.9698,
        "adjusted_adherence_percent": 97
      }
    ]
  },
  "meta": { "request_id": "req_02b7ce", "timestamp": "2026-10-09T18:41:12.307Z" }
}

What to read out of the row: agents_evaluated is the denominator the executive card quotes — a 0 here means the date resolution picked a day with nobody scheduled (a UTC-day mismatch the server-side resolution now handles), not an empty roster. Per agent, the raw and adjusted (excused_seconds carve-outs applied) pairs both come back so an audit can see which approved exceptions moved the number; sort is worst-first by the adjusted figure.

Coverage-drift preview — GET `/wfm/adherence/intraday`

The supervisor’s mid-shift read: each agent’s partial-window adherence against today’s schedule, with an is_out_of_adherence flag the wallboard renders red. The query accepts a ?threshold= override on the default out-of-adherence threshold, and an optional ?date= / ?queue_id= filter.

curl "https://api.orbit.devotel.io/api/v1/wfm/adherence/intraday" \
  -H "X-API-Key: dv_live_sk_YOUR_KEY"

Response — 200 (one flagged agent shown)

{
  "data": {
    "date": "2026-10-09",
    "threshold": 0.85,
    "generated_at": "2026-10-09T15:02:44.812Z",
    "agents_evaluated": 34,
    "out_of_adherence_count": 3,
    "agents": [
      {
        "agent_id": "usr_7f3a9c",
        "scheduled_seconds": 14400,
        "elapsed_seconds": 8100,
        "in_adherent_state_seconds": 6410,
        "adherence_ratio": 0.7913,
        "adherence_percent": 79,
        "is_out_of_adherence": true,
        "current_state": "break",
        "current_state_started_at": "2026-10-09T14:31:02Z"
      }
    ]
  },
  "meta": { "request_id": "req_b4c218", "timestamp": "2026-10-09T16:32:10.331Z" }
}

What to read out of the row: is_out_of_adherence: true on a partial window is the exact signal the SSE wallboard banner pushes — poll this endpoint when you want the same list without holding a stream open. adherence_ratio / adherence_percent carry identical information (pick one), and current_state + current_state_started_at reads the live aux the dialer reported — the drift to coach on. threshold echoes back whichever override governed the flag.

Capacity plan — POST `/wfm/capacity/plan`

The longer-horizon read: given per-period forecast volumes, planned headcount, and shrinkage (with AHT/occupancy defaults the call fills when you omit them), the endpoint computes the FTE requirement per period against occupancy and shrinkage buffers — the “how under- or over-hired are we” answer.

curl -X POST https://api.orbit.devotel.io/api/v1/wfm/capacity/plan \
  -H "X-API-Key: dv_live_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "periods": [
      { "period": "2026-11", "forecast_volume": 402000, "planned_headcount": 98 },
      { "period": "2026-12", "forecast_volume": 519000, "planned_headcount": 98 }
    ],
    "productive_hours_per_fte": 144
  }'

Response — 200 (plan computed)

{
  "data": {
    "productive_hours_per_fte": 144,
    "max_occupancy": 0.85,
    "horizon_periods": 2,
    "total_recommended_hires": 7,
    "total_expected_attrition": 1.2,
    "peak_required_fte": 104.6,
    "peak_gap": 6.6,
    "periods_understaffed": 1,
    "periods_overstaffed": 1,
    "periods": [
      {
        "period": "2026-11",
        "forecast_volume": 402000,
        "avg_handle_time_seconds": 300,
        "shrinkage": 0.3,
        "workload_hours": 14357.1,
        "required_fte": 86.4,
        "required_headcount": 123.5,
        "planned_headcount": 128,
        "gap": 4.5,
        "attrition_rate": 0,
        "expected_attrition": 0,
        "net_available_headcount": 96.7,
        "recommended_hires": 0,
        "status": "surplus"
      },
      {
        "period": "2026-12",
        "forecast_volume": 519000,
        "avg_handle_time_seconds": 300,
        "shrinkage": 0.3,
        "workload_hours": 18535.7,
        "required_fte": 104.6,
        "required_headcount": 135,
        "planned_headcount": 128,
        "gap": -7,
        "attrition_rate": 0,
        "expected_attrition": 1.2,
        "net_available_headcount": 91.4,
        "recommended_hires": 7,
        "status": "hire"
      }
    ]
  },
  "meta": { "request_id": "req_6ff0a2", "timestamp": "2026-10-09T15:19:33.271Z" }
}

What to read out of the row: per period, status collapses the whole computation to hire (planned headcount can’t cover the shrinkage-adjusted requirement), surplus (headroom exists), or balanced; recommended_hires is the count that closes the gap this period, and the top-level peak_gap names the worst shortfall across the horizon. The defaults the call filled (max_occupancy 0.85, AHT 300 s, shrinkage 0.30) echo back, so two planners reading one payload see the same figure.

6. The request/approval loop

Every drift between plan and reality converges on the same state machine: pending → approved | denied (with cancel available while still pending). This holds across the whole surface:

/wfm/requests — the agent self-serve queue (time off, swap offers, shift-change requests). An agent files in pending; a manager approves or denies; the requester (or a manager) can cancel a still-pending row; an offered swap is accepted with /accept-swap.
/wfm/adherence-exceptions — carve-outs that excuse deviation minutes (a system outage, an all-hands meeting). Same loop: pending → approve (deviation excused) | deny (it still counts).
/wfm/open-shifts — publish → agents bid → manager awards one bidder.
/wfm/overtime-offers and /wfm/vto-offers — publish → eligible agents claim → manager awards (OT can award several claimants; VTO awards to release hours).

Two rules make the loop safe to automate around: only pending rows can be decided (a second decision returns 409), and every approve/deny/award accepts a note or reason that persists with the row — the audit trail, not an implementation detail.

6. Data roles: management vs. self-serve

Role split across the whole prefix is consistent:

Surface	Owner/admin	Agent (non-manager)
Reads and rollups (`/wfm/summary`, adherence reads, lists)	tenant-wide	scoped to their own records
Publish (open shifts, overtime, VTO)	yes	no
Decide (approve/deny/award/cancel offers)	yes	only cancel their own pending rows
File (requests, exceptions, bids, claims)	yes, on behalf of agents	yes, as themselves
Schedule/shift/assignment writes	yes	no

Non-manager callers listing exceptions, requests, or bids only ever see their own rows — the same scope rule as the rest of the tenant-isolated API. API keys carry wfm:read for reporting surfaces and wfm:read + wfm:write for anything that publishes, awards, approves, or denies.

7. How adherence scores roll up — and how exceptions carve minutes out

The scorer walks an agent’s scheduled windows for the operating day and compares each interval’s expected state from the assignment against the actual aux states the agent reported. The result is a per-agent intraday score plus a breach record for each window where reality diverged beyond the allowed threshold — breaches are what GET /wfm/rta/breaches lists and what the /wfm/rta/stream wallboard pushes live. Approved adherence exceptions rewrite that math. While an exception is approved, its time window is excluded from the deviation base — the minutes stopped being “missed schedule” the moment a manager confirmed the agent was not at fault (a dialer outage is not agent behavior). This is why the exception queue is an operations queue and not just paperwork: approving or denying it directly moves team adherence numbers, and GET /wfm/adherence-exceptions/trends exposes that movement grouped by exception type and status. Team rollups (GET /wfm/adherence/team) aggregate the same per-agent scores managers just adjusted, so the team number an executive reads already has approved carve-outs netted out — do not re-adjust on top.

8. Where the workflow guide and API reference live

This page is the concept map — plan before you operate. The procedures (file an exception, post an open shift, award a bid, close the loop) live on the Workforce-management workflows guide, and the full endpoint inventory with request/response shapes lives on the WFM API reference. Two sibling concept pages complete the picture of what the schedule adheres to: the ACD queue model (the dispatch state adherence compares against) and agent presence lifecycle (the aux-state feed adherence consumes).

Getting Started

Channels

Channels (Voice)

AI Agents

Campaigns

Flows

Numbers & Verify

Concepts

Features

Billing

Webhooks

Security & SSO

Compliance

Legal

Brand & press

Changelog

The WFM model: forecasting, scheduling, adherence, and the labor market

The WFM model

1. The six WFM domains

Domain 1 — Forecasts: how much work is coming in

Domain 2 — Schedules and shifts: when each agent should work

Domain 3 — Assignments: the published roster

Domain 4 — Staffing and capacity: am I covered, what coverage costs

Domain 5 — Adherence and timekeeping: did the day go as planned

Domain 6 — Wellness, risk, and the labor market

2. Planning domain samples

Forecasts — POST `/wfm/forecasts/recompute`

Schedules — POST `/wfm/schedules/generate` then `/wfm/schedules/generate/commit`

Intraday staffing — GET `/wfm/intraday/staffing`

3. One aggregate read — `GET /wfm/summary`

4. Execution domain samples — the roster write + the drift repair

Assignments — POST `/wfm/assignments/bulk`

5. Adherence + health reads

Team rollup — GET `/wfm/adherence/team`

Coverage-drift preview — GET `/wfm/adherence/intraday`

Capacity plan — POST `/wfm/capacity/plan`

6. The request/approval loop

6. Data roles: management vs. self-serve

7. How adherence scores roll up — and how exceptions carve minutes out

8. Where the workflow guide and API reference live

​The WFM model

​1. The six WFM domains

​Domain 1 — Forecasts: how much work is coming in

​Domain 2 — Schedules and shifts: when each agent should work

​Domain 3 — Assignments: the published roster

​Domain 4 — Staffing and capacity: am I covered, what coverage costs

​Domain 5 — Adherence and timekeeping: did the day go as planned

​Domain 6 — Wellness, risk, and the labor market

​2. Planning domain samples

​Forecasts — POST /wfm/forecasts/recompute

​Schedules — POST /wfm/schedules/generate then /wfm/schedules/generate/commit

​Intraday staffing — GET /wfm/intraday/staffing

​3. One aggregate read — GET /wfm/summary

​4. Execution domain samples — the roster write + the drift repair

​Assignments — POST /wfm/assignments/bulk

​Rebalance — POST /wfm/rebalancing/recommend then /wfm/rebalancing/apply

​5. Adherence + health reads

​Team rollup — GET /wfm/adherence/team

​Coverage-drift preview — GET /wfm/adherence/intraday

​Capacity plan — POST /wfm/capacity/plan

​6. The request/approval loop

​6. Data roles: management vs. self-serve

​7. How adherence scores roll up — and how exceptions carve minutes out

​8. Where the workflow guide and API reference live

The WFM model

1. The six WFM domains

Domain 1 — Forecasts: how much work is coming in

Domain 2 — Schedules and shifts: when each agent should work

Domain 3 — Assignments: the published roster

Domain 4 — Staffing and capacity: am I covered, what coverage costs

Domain 5 — Adherence and timekeeping: did the day go as planned

Domain 6 — Wellness, risk, and the labor market

2. Planning domain samples

Forecasts — POST `/wfm/forecasts/recompute`

Schedules — POST `/wfm/schedules/generate` then `/wfm/schedules/generate/commit`

Intraday staffing — GET `/wfm/intraday/staffing`

3. One aggregate read — `GET /wfm/summary`

4. Execution domain samples — the roster write + the drift repair

Assignments — POST `/wfm/assignments/bulk`

Rebalance — POST `/wfm/rebalancing/recommend` then `/wfm/rebalancing/apply`

5. Adherence + health reads

Team rollup — GET `/wfm/adherence/team`

Coverage-drift preview — GET `/wfm/adherence/intraday`

Capacity plan — POST `/wfm/capacity/plan`

6. The request/approval loop

6. Data roles: management vs. self-serve

7. How adherence scores roll up — and how exceptions carve minutes out

8. Where the workflow guide and API reference live