​

Hold and pause reason codes

• Hold reason codes attach to a live call. The catalog is fixed by the platform; agents pick from it but you cannot add entries.
• Pause reason codes attach to an agent’s availability state. The catalog ships platform defaults, and owners and admins can add their own codes to match their operation.

​

Hold reason codes: why the caller is on hold

​

Attaching a hold reason

POST /api/v1/voice/calls/call_01HZK…/hold
Content-Type: application/json

{
  "reason_code": "consulting"
}

• The reason is stored on the call record itself — hold_reason and its resolved hold_reason_label land in the call’s metadata alongside the hold start timestamp. No catalog row to reference, no schema change to deploy.
• Releasing the hold clears the tag. When the agent resumes the call, the current hold’s reason slate resets; the pattern is “what is the current hold for,” not a standing flag.
• The reason is optional. POST .../hold with no body works exactly as before — long-standing integrations that never send a reason_code keep working unchanged.

​

Pause (aux) reason codes: why the agent is away

• Defaults — lunch, bio, training, break, coaching. These are always available to every tenant and cannot be shadowed by a tenant row.
• Tenant additions — domain-specific reasons like team_standup, qa_review, or a shift supervisor’s one_on_one. Tenant codes carry a display label, an optional per-reason duration ceiling, and an active flag they can flip to retire a code without orphaning history.

• On the wallboard — the away tile renders the label next to the away duration, so a glance tells “three on lunch, two in training” from “two missing agents.”
• In the agent activity feed — every state change is recorded with the reason code, so a day-review can reconstruct when each agent went away and for what.
• In WFM adherence — the reason an agent set is read against their scheduled activity, so an unscheduled meeting reads differently from a scheduled training deviation. See Workforce-management workflows for how adherence consumes the feed.

​

Reporting: what the tags buy you

• After-call reporting — a call that spent 4 minutes on hold now reports 4 minutes — Consulting a colleague instead of an unexplained block. Hold mix (how much of handle time is hold, broken down by reason) becomes a coaching input instead of an anecdote.
• Supervisor hold-time alert — when a caller sits on hold past the threshold (60 seconds by default), the wallboard emits a long-hold alert. The reason tag is alongside the duration, so the supervisor triaging “who needs a hand” sees Awaiting supervisor and acts on it instead of walking to the agent’s desk to ask.
• Pause reporting — adherence exceptions, shrinkage, and break-overrun alerts all segment by reason. “Away 12% of staffed hours” is a very different problem when most of that 12% is approved training versus when it is a miscellany of uncoded absences.

​

API examples

​

List the hold-reason catalog

curl "https://api.orbit.devotel.io/api/v1/voice/hold-reason-codes" \
  -H "X-API-Key: dv_live_sk_your_key_here"

{
  "data": {
    "items": [
      { "code": "verifying_info", "display_label": "Verifying information" },
      { "code": "checking_system", "display_label": "Checking system" },
      { "code": "consulting", "display_label": "Consulting a colleague" },
      { "code": "researching", "display_label": "Researching the request" },
      { "code": "supervisor_review", "display_label": "Awaiting supervisor" },
      { "code": "processing", "display_label": "Processing the request" },
      { "code": "other", "display_label": "Other" }
    ]
  }
}

​

Hold a call with a reason, then release it

# Place the caller on hold, tagged with a reason
curl -X POST "https://api.orbit.devotel.io/api/v1/voice/calls/call_01HZK…/hold" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "reason_code": "consulting" }'

# Resume the call — the reason tag clears
curl -X POST "https://api.orbit.devotel.io/api/v1/voice/calls/call_01HZK…/unhold" \
  -H "X-API-Key: dv_live_sk_your_key_here"

​

Read hold history for a call

curl "https://api.orbit.devotel.io/api/v1/voice/calls/call_01HZK…" \
  -H "X-API-Key: dv_live_sk_your_key_here"

​

List the pause-reason catalog (defaults + tenant codes)

curl "https://api.orbit.devotel.io/api/v1/voice/agents/pause-reason-codes" \
  -H "X-API-Key: dv_live_sk_your_key_here"

​

Add a tenant pause reason (owner or admin)

curl -X POST "https://api.orbit.devotel.io/api/v1/voice/agents/pause-reason-codes" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "team_standup",
    "display_label": "Team standup",
    "max_seconds": 900
  }'

​

Update or retire a tenant pause reason (owner or admin)

# Change the label or the ceiling — code slug is immutable
curl -X PATCH "https://api.orbit.devotel.io/api/v1/voice/agents/pause-reason-codes/prc_abc123" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "display_label": "Daily standup", "max_seconds": 1200 }'

# Soft-delete — historical uses keep the label
curl -X DELETE "https://api.orbit.devotel.io/api/v1/voice/agents/pause-reason-codes/prc_abc123" \
  -H "X-API-Key: dv_live_sk_your_key_here"

​

Set an agent’s away state with a reason

curl -X POST "https://api.orbit.devotel.io/api/v1/voice/agents/agent_12/status" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "status": "away", "reason_code": "team_standup" }'

​

Edge notes

• Reasons are optional everywhere. A hold posted with no body, or a status flip with no reason_code, behaves exactly as before the catalogs existed — no breaking change for integrations built before this.
• Hold catalog slugs are stable across releases. The seven platform codes never change name; report queries keyed on code are safe to persist.
• Tenant additions only apply to pause codes. There is no tenant extension point for hold reasons — that is a deliberate parity choice, not an oversight, since a per-call picker should never need domain training.
• Pause code slugs are immutable once created. Retire (soft-delete) and recreate to rename; a hard rename would orphan the audit and adherence records that carry the slug.
• Codes normalise. Consulting, consulting, and consulting are the same tag; keep your integration storing the canonical lowercase slug.
• The catalogs are tenant-scoped for pause, global for hold. One tenant’s added pause reasons are invisible to others; the hold catalog is identical for everyone.

​

Related references

• Workforce-management workflows — how adherence consumes pause reasons for exceptions and scoring
• Wallboard — where supervisors see live hold and away durations with their reason labels
• Wrap-up codes — the end-of-call disposition catalog, a separate reporting axis from hold and away reasons
• Voice API reference — full endpoint inventory