Worked voice samples

These four flows walk an outbound call from creation to completed-recording retrieval, including the two error shapes you must handle on the way. All requests use your API key (X-API-Key) against https://api.orbit.devotel.io.

1. Place an outbound call

POST /voice/calls initiates an outbound call and returns the new call id and its initial status. 202 is not returned here — a successful initiation responds 201.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/voice/calls" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+14155552671",
    "from": "+18005551234",
    "record": true
  }'

201 Created

{
  "data": {
    "call_id": "call_7b3e9c2d",
    "status": "initiated",
    "direction": "outbound"
  },
  "meta": {
    "request_id": "req_8c3f…",
    "timestamp": "2026-08-27T09:14:03Z"
  }
}

status starts as initiated; the lifecycle progresses through the terminal state completed/no-answer/failed (see hangup_reason on the webhook, or GET /voice/calls/{id} below). Poll the status endpoint or listen for the webhook — don’t assume the call is still ringing.

2. Poll the call status

GET /voice/calls/{id} returns the call row with the fields updated as the call progresses.

cURL

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

200 OK

{
  "data": {
    "id": "call_7b3e9c2d",
    "direction": "outbound",
    "from": "+18005551234",
    "to": "+14155552671",
    "status": "completed",
    "duration_seconds": 142,
    "billing_seconds": 142,
    "recording_url": "/recordings/rec_a51e2c94/download",
    "cost": "0.024",
    "currency": "USD",
    "started_at": "2026-08-27T09:14:03Z",
    "answered_at": "2026-08-27T09:14:15Z",
    "ended_at": "2026-08-27T09:17:37Z"
  },
  "meta": {
    "request_id": "req_9d4e…",
    "timestamp": "2026-08-27T09:17:38Z"
  }
}

3. Webhook — `call.completed`

Register a webhook endpoint (POST /webhooks) subscribed to call.completed so your server receives the terminal status the moment it happens, instead of polling.

POST to your endpoint

{
  "type": "call.completed",
  "data": {
    "call_id": "call_7b3e9c2d",
    "provider": "jambonz",
    "provider_call_sid": "CA-…",
    "direction": "outbound",
    "from": "+18005551234",
    "to": "+14155552671",
    "status": "completed",
    "duration_seconds": 142,
    "hangup_reason": "normal_clearing",
    "sip_response_code": 200,
    "sip_reason": "OK",
    "timestamp": "2026-08-27T09:17:37Z"
  }
}

The full event list and endpoint-management API live at Webhook events. Field-level definitions (the same payload every webhook carries) are pinned against call.initiated and call.completed there.

4. Retrieve the recording

Once a call shows a recording, GET /voice/calls/{id}/recording returns a signed, time-limited playback URL plus the duration/format and any chapter markers. The url is pre-signed and expires after the expires_at epoch-ms timestamp.

cURL

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

200 OK

{
  "data": {
    "url": "https://storage.googleapis.com/orbit-rec…/call_7b3e9c2d.wav?X-Signed-…",
    "duration_seconds": 142,
    "format": "wav",
    "expires_at": 1787899680000,
    "recording_id": "rec_a51e2c94",
    "chapters": []
  },
  "meta": {
    "request_id": "req_a4f1…",
    "timestamp": "2026-08-27T09:17:50Z"
  }
}

When structured chaptering is enabled, chapters carries [{ start_ms, end_ms, title, summary }] markers; when it is off, it is []. A call that was never recorded returns 404 NOT_FOUND.

Error — unverified caller-id

When the caller-id in from is neither a platform/tenant number you own nor a verified external caller-id, the request is rejected before dispatch.

422 Unprocessable Entity

{
  "error": {
    "code": "UNVERIFIED_CALLER_ID",
    "message": "Caller-id `from` is not a number owned by this organization and has not been verified as an outbound caller-id. Either pick one of your active platform/tenant numbers, or enrol the number via POST /voice/caller-ids/verify and confirm the OTP first.",
    "status": 422,
    "details": {
      "from": "+14155559999",
      "docs_url": "https://docs.orbit.devotel.io/voice/verified-caller-ids"
    }
  },
  "meta": {
    "request_id": "req_7b2c…",
    "timestamp": "2026-08-27T09:13:58Z"
  }
}

Fix it by enrolling the number through the verified-caller-id flow (POST /voice/caller-ids/verify + OTP confirm) and retrying, or by picking a number already active on your account.

Beyond the call lifecycle: six more operations, worked

The generator renders the four call-lifecycle flows above with full bodies, but six more voice operations resolve to an empty placeholder envelope — the bare "data": {} shape the sample guard bans — because their OpenAPI 2xx response carries no JSON schema. Each section below replaces that placeholder with the worked { data, meta } envelope the operation actually returns. The Node SDK does not wrap the voice namespace yet, so every TypeScript tab goes through the SDK’s orbit.request escape hatch (the same convention the API recipes guide uses for uncovered resources) — you get the SDK’s auth, retries, and envelope unwrapping against the raw REST path. Python tabs mirror through its SDK’s client.request raw-request method, no requests packaging needed. Use a sandbox key (dv_test_sk_YOUR_KEY) until the flow reads clean, then swap in your live key. Every envelope here follows the four shapes in How to read a worked sample — success carries { data, meta }, failure carries { error, meta } with a stable error.code.

5. Read the affinity-routing strategy

GET /voice/affinity-routing returns your organization’s behavioral-affinity routing config — the pairing objective that routes an inbound contact to the agent best matched to them (customer-segment ↔ agent-affinity fit), not merely the globally best-scoring agent. The response is normalized: a tenant that never configured it gets the disabled default shape (not a 404), so you can render the empty state straight off the response.

cURL

curl "https://api.orbit.devotel.io/api/v1/voice/affinity-routing" \
  -H "X-API-Key: dv_test_sk_YOUR_KEY"

Node.js — SDK escape hatch

const res = await orbit.request("GET", "/api/v1/voice/affinity-routing");
// res.data.enabled — false until you PUT a config (see the next section)

Python — client.request raw-request

from orbit_sdk import OrbitClient

client = OrbitClient.from_api_key("dv_test_sk_YOUR_KEY")
res = client.request("GET", "/voice/affinity-routing")
# res["data"]["profile_count"] — how many agent profiles carry affinity tags

{
  "data": {
    "enabled": true,
    "treatment_percent": 100,
    "affinity_weight": 0.75,
    "headroom_weight": 0.25,
    "agent_profiles": {
      "user_9f3ac2d1": ["segment:enterprise", "style:analytical"]
    },
    "profile_count": 1
  },
  "meta": {
    "request_id": "req_voice_affinity_get",
    "timestamp": "2026-09-27T08:12:04Z"
  }
}

agent_profiles maps an agent’s user id to the affinity tags that agent pairs well with (segment, style, value). An untouched tenant reads { "enabled": false, "treatment_percent": 0, …, "agent_profiles": {} } with profile_count: 0 — still a clean 200.

6. Replace the affinity-routing strategy

PUT /voice/affinity-routing replaces the whole config. Only the affinity-routing sub-object is rewritten — every other tenant setting is untouched, and the stored blob is the resolved (clamped, weight-renormalized, tag-normalized) config. The write is audited; the response echoes the canonical shape the router will actually apply, so read it back rather than assuming your input survived as-is.

cURL

curl -X PUT "https://api.orbit.devotel.io/api/v1/voice/affinity-routing" \
  -H "X-API-Key: dv_test_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "treatment_percent": 100,
    "affinity_weight": 0.75,
    "headroom_weight": 0.25,
    "agent_profiles": {
      "user_9f3ac2d1": ["segment:enterprise", "style:analytical"]
    }
  }'

Node.js — SDK escape hatch

const res = await orbit.request("PUT", "/api/v1/voice/affinity-routing", {
  enabled: true,
  treatment_percent: 100,
  affinity_weight: 0.75,
  headroom_weight: 0.25,
  agent_profiles: { user_9f3ac2d1: ["segment:enterprise", "style:analytical"] },
});
// res.data — the canonical stored shape, weights renormalized if needed

Python — client.request raw-request

res = client.request("PUT", "/voice/affinity-routing", json={
    "enabled": True,
    "treatment_percent": 100,
    "affinity_weight": 0.75,
    "headroom_weight": 0.25,
    "agent_profiles": {"user_9f3ac2d1": ["segment:enterprise", "style:analytical"]},
})

{
  "data": {
    "enabled": true,
    "treatment_percent": 100,
    "affinity_weight": 0.75,
    "headroom_weight": 0.25,
    "agent_profiles": {
      "user_9f3ac2d1": ["segment:enterprise", "style:analytical"]
    },
    "profile_count": 1
  },
  "meta": {
    "request_id": "req_voice_affinity_put",
    "timestamp": "2026-09-27T08:12:09Z"
  }
}

To turn the affinity arm off, PUT {"enabled": false} — the config stays stored but the router stops consulting it. Body schema violations (a weight outside 0…1, treatment_percent outside 0…100, an unknown key on the strict body) return 422 VALIDATION_ERROR with error.details per field, exactly as pinned in the placeholder-eliminator pinned test for this op. Per-op error shapes:

Status	`error.code`	Why it fires	What to do
401	`INVALID_API_KEY`	the key is missing, revoked, or wrong-prefix	rotate or re-mint the key, then retry
403	`FORBIDDEN`	affinity-routing reads and writes are admin-only	use an owner/admin key or widen the API-key scopes
422	`VALIDATION_ERROR`	the PUT body failed the schema (`error.details` names the field)	fix the field and resend — never blind-retry
429	`RATE_LIMITED`	the read/write window quota is exhausted	retry after `error.details.retry_after` (or the `Retry-After` header) with the same body

A 404 cannot fire on this pair — an unset config reads as the disabled default shape, and the PUT creates it on first write.

7. Read a call’s deferred AMD decision

GET /voice/calls/{id}/amd returns the Answering Machine Detection decision for a call you placed with amd: true on POST /voice/calls. AMD resolves as live speech, a machine greeting, or unknown; a call placed without the flag has no decision row to read.

cURL

curl "https://api.orbit.devotel.io/api/v1/voice/calls/call_7b3e9c2d/amd" \
  -H "X-API-Key: dv_test_sk_YOUR_KEY"

Node.js — SDK escape hatch

const res = await orbit.request("GET", "/api/v1/voice/calls/call_7b3e9c2d/amd");
// res.data.result === "machine" → your greeting flow should hang up first

Python — client.request raw-request

res = client.request("GET", "/voice/calls/call_7b3e9c2d/amd")
# res["data"]["status"] — "completed" once the decision is final

{
  "data": {
    "call_id": "call_7b3e9c2d",
    "requested": true,
    "result": "machine",
    "confidence": 0.93,
    "status": "completed",
    "decided_at": "2026-08-27T09:14:09Z"
  },
  "meta": {
    "request_id": "req_voice_amd_get",
    "timestamp": "2026-08-27T09:14:10Z"
  }
}

While the decision is still open, status reads pending with result: null — poll or take the webhook rather than treating pending as an error. Per-op error shapes:

Status	`error.code`	Why it fires	What to do
401	`INVALID_API_KEY`	the key is missing, revoked, or wrong-prefix	rotate or re-mint the key, then retry
403	`FORBIDDEN`	the key lacks the read scope	widen the API-key scopes
404	`NOT_FOUND`	the call id is unknown to your tenant	re-list calls and branch — a stale id never resolves
422	`VALIDATION_ERROR`	the call id segment failed the id schema	fix the path id and resend
429	`RATE_LIMITED`	the polling window quota is exhausted	retry after `error.details.retry_after`, or move to the webhook

8. Read a call’s audit annotations

A call’s free-form account / cost-center annotation (PUT /voice/calls/{id}/account-code) lives on the audit row, not the call row itself. GET /voice/calls/{id}/account-code reads the current annotation so your billing-reconciliation loop can assert what the last write left behind — annotation and audit only; no outbound signalling.

cURL

curl "https://api.orbit.devotel.io/api/v1/voice/calls/call_7b3e9c2d/account-code" \
  -H "X-API-Key: dv_test_sk_YOUR_KEY"

Node.js — SDK escape hatch

const res = await orbit.request(
  "GET",
  "/api/v1/voice/calls/call_7b3e9c2d/account-code",
);
// res.data.value — the chargeback code your last PUT stored

Python — client.request raw-request

res = client.request("GET", "/voice/calls/call_7b3e9c2d/account-code")

{
  "data": {
    "call_id": "call_7b3e9c2d",
    "value": "CC-4100-SUPPORT",
    "set_by": "user_4ac1f9d0",
    "set_at": "2026-08-27T10:02:41Z"
  },
  "meta": {
    "request_id": "req_voice_audit_get",
    "timestamp": "2026-08-27T10:05:12Z"
  }
}

A call with no annotation yet returns the same envelope with value: null (and set_by/set_at null) — a clean 200, so branch on value, not on the status code. Per-op error shapes:

Status	`error.code`	Why it fires	What to do
401	`INVALID_API_KEY`	the key is missing, revoked, or wrong-prefix	rotate or re-mint the key, then retry
403	`FORBIDDEN`	the key lacks the read scope	widen the API-key scopes
404	`NOT_FOUND`	the call does not exist in the caller’s tenant	re-list calls and branch
422	`VALIDATION_ERROR`	the call id segment failed the id schema	fix the path id and resend
429	`RATE_LIMITED`	the read window quota is exhausted	retry after `error.details.retry_after`

9. Read the calls stream page

GET /voice/calls/stream returns one page of the tenant’s call feed for feed-style dashboards. The page is cursor-paginated: keep issuing the same request with the returned cursor until has_more flips false, and treat an empty items array as the end of the feed, never as a failure.

cURL

curl "https://api.orbit.devotel.io/api/v1/voice/calls/stream?limit=50" \
  -H "X-API-Key: dv_test_sk_YOUR_KEY"

Node.js — SDK escape hatch

const res = await orbit.request(
  "GET",
  "/api/v1/voice/calls/stream?limit=50",
);
// res.data.has_more → loop again with ?cursor=…

Python — client.request raw-request

res = client.request("GET", "/voice/calls/stream?limit=50")
# res["data"]["items"] — up to `limit` call rows, a cursor when more remain

{
  "data": {
    "items": [
      {
        "id": "call_7b3e9c2d",
        "direction": "outbound",
        "from": "+18005551234",
        "to": "+14155552671",
        "status": "completed",
        "duration_seconds": 142,
        "started_at": "2026-08-27T09:14:03Z"
      }
    ],
    "has_more": true,
    "cursor": "cur_0f5a9c41e2"
  },
  "meta": {
    "request_id": "req_voice_stream_get",
    "timestamp": "2026-08-27T09:20:01Z"
  }
}

Per-op error shapes:

Status	`error.code`	Why it fires	What to do
401	`INVALID_API_KEY`	the key is missing, revoked, or wrong-prefix	rotate or re-mint the key, then retry
403	`FORBIDDEN`	the key lacks the read scope	widen the API-key scopes
422	`VALIDATION_ERROR`	`limit` out of range or a malformed cursor	fix the query and resend
429	`RATE_LIMITED`	the polling window quota is exhausted	retry after `error.details.retry_after`

A 404 cannot fire on this read — the feed is tenant-scoped, so an unknown page cursor is the only empty-list condition beyond the end of the feed.

10. List queue callbacks (scheduled dials)

GET /voice/callbacks lists the contact-center callbacks the queue has promised — the scheduled dials an agent or the queue will place — with an analytics summary in the same envelope. Filter by queue_id or status, and cancel a pending one with DELETE /voice/callbacks/{id} (idempotent: already-terminal rows answer 204, unknown ids 404).

cURL

curl "https://api.orbit.devotel.io/api/v1/voice/callbacks?status=pending&limit=50" \
  -H "X-API-Key: dv_test_sk_YOUR_KEY"

Node.js — SDK escape hatch

const res = await orbit.request(
  "GET",
  "/api/v1/voice/callbacks?status=pending&limit=50",
);
// res.data.summary.pending — the scheduled-dial backlog for the queue

Python — client.request raw-request

res = client.request("GET", "/voice/callbacks?status=pending&limit=50")
# res["data"]["items"] — callback rows with the caller's number masked

{
  "data": {
    "items": [
      {
        "id": "cbk_2e41a9f7",
        "queue_id": "que_9c31d5b2",
        "caller_id_masked": "+14155****671",
        "status": "pending",
        "scheduled_at": "2026-08-27T14:30:00Z",
        "created_at": "2026-08-27T11:58:22Z"
      }
    ],
    "summary": {
      "total": 37,
      "successful": 21,
      "failed": 3,
      "pending": 13,
      "avg_wait_seconds": 641
    },
    "has_more": false,
    "cursor": null
  },
  "meta": {
    "request_id": "req_voice_scheduled_dial_list",
    "timestamp": "2026-08-27T12:04:45Z"
  }
}

Phone numbers are masked on every read (+14155****567 shape), so the list is safe to render in operator UIs and logs. Per-op error shapes:

Status	`error.code`	Why it fires	What to do
401	`INVALID_API_KEY`	the key is missing, revoked, or wrong-prefix	rotate or re-mint the key, then retry
403	`FORBIDDEN`	the key lacks the read scope	widen the API-key scopes
404	`NOT_FOUND`	the `DELETE` addressed a callback id that is gone	re-list and branch — a stale id never resolves
422	`VALIDATION_ERROR`	a query filter failed the schema (`status`, `limit`, cursor)	fix the query and resend
429	`RATE_LIMITED`	the polling window quota is exhausted	retry after `error.details.retry_after`

Queue & agent state round-trips, worked

The generated voice page still renders { "data": {} } for every queue/agent- state round-trip — the CCaaS operator daily path. Twelve of the most-hit queue and agent-state read routes get their worked envelope below. Each shape matches its handler in queue.controller.ts / aux-codes.controller.ts / pause-reason-codes.controller.ts / agent-state-history.controller.ts / conference.controller.ts / voicemail.controller.ts.

11. List the queues

GET /voice/queues returns your org’s queue list with the routing-strategy and live-member snapshot the operator page needs. The summary block totals over the org’s queues so the dashboard’s cross-queue SLA chip stays one call.

{
  "data": {
    "items": [
      {
        "queue_id": "que_9c31d5b2",
        "name": "Support",
        "routing_strategy": "skill-weighted",
        "rna_timeout_seconds": 30,
        "max_participants": 250,
        "skill_priorities": { "segment:enterprise": 3 },
        "member_count": 18,
        "active_member_count": 9
      }
    ],
    "summary": {
      "total_queues": 37,
      "active_queues": 12,
      "sla_compliance_percent": 98.2
    }
  },
  "meta": {
    "request_id": "req_voice_queues_list",
    "timestamp": "2026-09-27T10:03:11Z"
  }
}

POST /voice/queues creates queues; the config editors route through POST /voice/queues + PATCH /voice/queues/{id} writes before GET hydrates.

12. Get the queue detail

GET /voice/queues/{id} returns the queue’s synthesis — config + live member list from the Redis agent registry. The supervisor page reads this when it re-hydrates after the operator clicks a dial pad.

{
  "data": {
    "queue_id": "que_9c31d5b2",
    "name": "Support",
    "routing_strategy": "skill-weighted",
    "rna_timeout_seconds": 30,
    "sla_breach_policy": "degrade-first",
    "members": [
      {
        "agent_id": "user_9f3ac2d1",
        "display_name": "Fatima Q.",
        "status": "on_call",
        "skills": ["segment:enterprise", "style:analytical"],
        "last_answered_at": "2026-09-27T10:02:47Z"
      }
    ],
    "live_count": 1,
    "summary": {
      "queue_in_line": 41,
      "service_level": 97.8
    }
  },
  "meta": {
    "request_id": "req_voice_queue_get",
    "timestamp": "2026-09-27T10:03:12Z"
  }
}

PATCH /voice/queues/{id} mutates the queue config (routing strategy, RNA timeout, SLA policy). The response mirrors the stored shape so the detail page renders from the PATCH round-trip without an extra GET.

13. List queue members

GET /voice/queues/{id}/members enumerates the agent workspace — with total + has_more cursor so the page never re-pulls every agent on a tab re-open.

{
  "data": {
    "items": [
      {
        "agent_id": "user_9f3ac2d1",
        "display_name": "Fatima Q.",
        "status": "on_call",
        "skills": ["segment:enterprise", "style:analytical"],
        "skill_levels": { "segment:enterprise": 3, "style:analytical": 4 },
        "queue_weights": { "que_9c31d5b2": 62, "que_81eac8f0": 38 }
      }
    ],
    "total": 2,
    "has_more": false
  },
  "meta": {
    "request_id": "req_voice_queue_members_list",
    "timestamp": "2026-09-27T10:03:14Z"
  }
}

POST /voice/queues/{id}/members adds a member; PATCH /voice/queues/{id}/members/{memberId} flips status offline — the member editor round-trips on the returned skill_levels/queue_weights snapshots, not a full page refresh.

14. Read the per-queue routing weights

GET /voice/agents/{id}/queue-weights returns the agent’s cross-queue routing weights ({queueId: 1-100} from the Redis registry, or { } when the agent has never pushed). The queue-config editor stays visible on the empty case and the operator fills it inline.

{
  "data": {
    "agent_id": "user_9f3ac2d1",
    "queue_weights": {
      "que_81eac8f0": 62,
      "que_97d0c3e9": 38
    }
  },
  "meta": {
    "request_id": "req_voice_queue_weights_get",
    "timestamp": "2026-09-27T10:03:16Z"
  }
}

PATCH /voice/agents/{id}/queue-weights MERGES a per-queue delta and returns the same envelope — the editor renders what actually persisted, not the optimistic delta.

15. Read the skill-proficiency map

GET /voice/agents/{id}/skill-proficiency returns the agent’s skill×level matrix from acd_queue_members.skill_levels (levels 1…5). The editor renders this as the live state.

{
  "data": {
    "agent_id": "user_9f3ac2d1",
    "skills": {
      "segment:enterprise": 3,
      "style:analytical": 4,
      "technical": 5
    }
  },
  "meta": {
    "request_id": "req_voice_skill_levels_get",
    "timestamp": "2026-09-27T10:03:18Z"
  }
}

PATCH /voice/agents/{id}/skill-proficiency REPLACES the map — the route echoes the replaced shape on the response, so the editor finalises the save against the wire payload, not the patch operator.

16. Read the state-history timeline

GET /voice/agents/{id}/state-history returns the per-agent transition timeline, ordered changed_at DESC (newest first), windowed by from / to / limit. HR-audit and supervisor pages paginate this.

{
  "data": {
    "agent_id": "user_9f3ac2d1",
    "from": "2026-09-01T00:00:00Z",
    "to": "2026-09-28T00:00:00Z",
    "rows": [
      {
        "id": "ash-0148",
        "agent_id": "user_9f3ac2d1",
        "from_state": "break",
        "to_state": "available",
        "reason": "end-of-break",
        "changed_at": "2026-09-27T09:58:59Z"
      },
      {
        "id": "ash-0122",
        "agent_id": "user_9f3ac2d1",
        "from_state": "available",
        "to_state": "on_call",
        "reason": "call.answered",
        "changed_at": "2026-09-27T10:02:47Z"
      }
    ]
  },
  "meta": {
    "request_id": "req_voice_agent_state_history",
    "timestamp": "2026-09-27T09:58:34Z"
  }
}

The audit row’s reason carries the pause reason code. The supervisor and the agent browser both anchor to from/to (HR quarters, supervisor 24-h panel) — paginate with limit (default 500, max 5000).

17. List the pause-reason catalog

GET /voice/agents/pause-reason-codes returns the tenant’s ACD pause-reason codes + the defaults set the FE must not have to synthesize.

{
  "data": {
    "items": [
      {
        "id": "prc_2b735a1561",
        "code": "lunch",
        "display_label": "Lunch Break",
        "max_seconds": 3600,
        "active": true,
        "created_at": "2026-08-15T11:20:41Z",
        "updated_at": "2026-09-21T09:33:29Z"
      },
      {
        "id": "prc_ae9b27c192",
        "code": "coaching-1:1",
        "display_label": "1:1 Coaching",
        "max_seconds": 1800,
        "active": true,
        "created_at": "2026-09-02T10:22:10Z",
        "updated_at": "2026-09-02T10:22:10Z"
      }
    ],
    "defaults": ["lunch", "break", "training", "coaching-1:1"],
    "limit": 100,
    "offset": 0
  },
  "meta": {
    "request_id": "req_voice_pause_reason_list",
    "timestamp": "2026-09-27T10:03:21Z"
  }
}

POST /voice/agents/pause-reason-codes adds; PATCH /voice/agents/pause-reason-codes/{id} mutates active / display_label / max_seconds — and the audit created_at stays stable so replays stay deterministic.

18. List the AUX codes

GET /voice/aux-codes returns the tenant’s AUX-code taxonomy the agent- softphone away-state picker must render. page + pageSize are server- side so the picker never re-pulls the archive on accident.

{
  "data": {
    "items": [
      {
        "id": "aux_0abc",
        "code": "lunch",
        "label": "Lunch Break",
        "adherenceState": "lunch",
        "paidFlag": true,
        "sortOrder": 100,
        "isActive": true,
        "createdAt": "2026-08-15T11:20:41Z",
        "updatedAt": "2026-09-21T09:33:29Z"
      },
      {
        "id": "aux_2def",
        "code": "coaching-1:1",
        "label": "1:1 Coaching",
        "adherenceState": "coaching-1:1",
        "paidFlag": false,
        "sortOrder": 100,
        "isActive": true,
        "createdAt": "2026-09-02T10:22:10Z",
        "updatedAt": "2026-09-02T10:22:10Z"
      }
    ],
    "total": 2,
    "page": 1,
    "pageSize": 100
  },
  "meta": {
    "request_id": "req_voice_aux_codes_list",
    "timestamp": "2026-09-27T10:03:23Z"
  }
}

POST /voice/aux-codes adds; PATCH /voice/aux-codes/{id} mutates. Absent tenants degrade to items: [] + total: 0, never a 404, so the picker always has a pageable page.

19. List conferences

GET /voice/conferences lists the tenant’s conferences (oldest-first if you pass a sort param). The operator board keeps a soft-deleted filter so a deleted conference never sits stale.

{
  "data": {
    "items": [
      {
        "conference_id": "conf_17b3e9c2d",
        "name": "Lunch Sync",
        "status": "in-progress",
        "caller_id": "+18005551234",
        "participant_count": 1,
        "max_participants": 32,
        "expires_at": "2026-09-27T14:00:00Z",
        "started_at": "2026-09-27T09:59:00Z",
        "created_at": "2026-09-27T09:48:12Z",
        "updated_at": "2026-09-27T10:01:00Z"
      }
    ],
    "total": 1,
    "has_more": false,
    "cursor": null
  },
  "meta": {
    "request_id": "req_voice_conference_list",
    "timestamp": "2026-09-27T10:02:34Z"
  }
}

POST /voice/conferences seeds; DELETE /voice/conferences/{id} terminates.

20. Get the conference detail

GET /voice/conferences/{id} returns the conference’s join plus the live participants — the operator view renders this straight off one read.

{
  "data": {
    "conference_id": "conf_17b3e9c2d",
    "name": "Lunch Sync",
    "status": "in-progress",
    "caller_id": "+18005551234",
    "max_participants": 32,
    "pin": "4821",
    "expires_at": "2026-09-27T14:00:00Z",
    "started_at": "2026-09-27T09:59:00Z",
    "participants": [
      {
        "id": "prt_3b41e2",
        "conference_id": "conf_17b3e9c2d",
        "phone_number": "+14155552671",
        "display_name": "Fatima Q.",
        "status": "connected",
        "is_host": false,
        "recording_consent_state": "granted",
        "dial_attempt": 1,
        "joined_at": "2026-09-27T09:59:38Z",
        "left_at": null
      }
    ],
    "participant_count": 1
  },
  "meta": {
    "request_id": "req_voice_conference_detail",
    "timestamp": "2026-09-27T10:03:30Z"
  }
}

POST /voice/conferences/{id}/participants adds a leg; DELETE /voice/conferences/{id} ends the parent.

21. Page conference participants

GET /voice/conferences/{id}/participants enumerates the per-leg dial list — the dashboard timeline renders each leg straight off this page.

{
  "data": {
    "items": [
      {
        "id": "prt_3b41e2",
        "conference_id": "conf_17b3e9c2d",
        "leg_call_sid": "jam-…-sid",
        "phone_number": "+14155552671",
        "display_name": "Fatima Q.",
        "status": "connected",
        "sip_response_code": 200,
        "failure_reason": null,
        "error_code": null,
        "is_host": false,
        "recording_consent_state": "granted",
        "dial_attempt": 1,
        "joined_at": "2026-09-27T09:59:38Z",
        "left_at": null
      }
    ],
    "has_more": false,
    "cursor": null
  },
  "meta": {
    "request_id": "req_voice_conference_participant_page",
    "timestamp": "2026-09-27T10:03:33Z"
  }
}

The per-leg failure_reason / error_code mirror the audit row — the conference reconciliation must assert the same code when the operator’s manager mirrors back.

22. List voicemail greetings

GET /voice/voicemail/greeting returns the tenant’s greeting catalog the admin page renders.

{
  "data": {
    "items": [
      {
        "greeting_id": "vgm_4b735a1561",
        "kind": "wav",
        "is_default": false,
        "is_tts_enabled": false,
        "uploaded_at": "2026-09-15T10:12:00Z",
        "updated_at": "2026-09-21T10:12:00Z",
        "duration_seconds": 30,
        "size_bytes": 320012
      }
    ],
    "defaults": ["client-default.wav"],
    "limit": 100,
    "offset": 0
  },
  "meta": {
    "request_id": "req_voice_voicemail_greeting_list",
    "timestamp": "2026-09-27T10:03:36Z"
  }
}

POST /voice/voicemail/greeting adds; POST /voice/voicemail/greeting/tts synthesizes TTS. Untouched tenants render items: [] with defaults: [] — defaults stay safe before the first upload.

Queue appointment booking, worked

The queue-booking pair is public — a hosted booking page calls it without an API key, so the tenant id and queue id sit in the path and the surface is deliberately blind: a queue that has not opted in to public booking returns enabled: false rather than an error, and the booking POST rejects the same way. The full booking-page walkthrough lives in the queue appointment booking guide; the two worked calls below are the whole round-trip. Every authenticated section from here on sticks to the same SDK convention as the lifecycle sections above — TypeScript goes through the SDK’s orbit.request escape hatch and Python mirrors through client.request raw requests (the Node SDK does not wrap these surfaces either). The three-link footer at the bottom gets picked up by the same card that every ## Worked voice samples reader sees:

Voice product picker — chose where trunked/softphone/public-bookable calls belong.
Ring groups — product-side group setup.
Queue appointment booking — the hosted page walkthrough.

Node.js — SDK escape hatch ring-group example

const res = await orbit.request(
  "POST",
  "/api/v1/voice/ring-groups",
  { json: { name: "Front of house", members: [{ kind: "sip_username", value: "acme-frontdesk" }] } },
);

Python — client.request raw-request

res = client.request("POST", "/voice/ring-groups", json={
  "name": "Front of house",
  "members": [{"kind": "sip_username", "value": "acme-frontdesk"}],
})

23. List the bookable slots

GET /public/queues/{tenantId}/{queueId}/availability returns the queue’s published bookable slots over a date window — plus the tenant’s branding, page copy, and timezone — so the hosted booking page renders in one read. from/to (ISO-8601), slot_minutes, and lead_minutes are optional; the window defaults to the next 14 days.

{
  "data": {
    "enabled": true,
    "branding": {
      "logo_url": "https://cdn.orbit.devotel.io/branding/org_ayMne6et/logo.png",
      "primary_color": "#1b5fd6",
      "business_name": "Acme Support"
    },
    "copy": {
      "headline": "Book a callback",
      "body": "Pick a time and we will call you back.",
      "footer": "Powered by Devotel Orbit"
    },
    "queue_id": "queue_8f41d2c7",
    "queue_name": "Support callbacks",
    "timezone": "America/New_York",
    "slot_minutes": 30,
    "lead_time_minutes": 60,
    "from": "2026-09-30T00:00:00.000Z",
    "to": "2026-10-14T00:00:00.000Z",
    "slots": [
      {
        "start": "2026-09-30T14:00:00.000Z",
        "end": "2026-09-30T14:30:00.000Z",
        "available": true
      },
      {
        "start": "2026-09-30T14:30:00.000Z",
        "end": "2026-09-30T15:00:00.000Z",
        "available": false
      }
    ],
    "reason": null
  },
  "meta": {
    "request_id": "req_queue_availability",
    "timestamp": "2026-09-29T16:12:44Z"
  }
}

A queue that has not enabled public booking answers with the same status and the body {"data":{"enabled":false},"meta":{…}} — never a 404, so the surface can’t be probed for queue existence.

24. Book the slot

POST /public/queues/{tenantId}/{queueId}/appointments books one slot for the caller’s phone number; the server writes it as a scheduled callback that the queue dials at the chosen time. A slot taken moments before returns 409 with error.code: SLOT_ALREADY_BOOKED; a queue that isn’t accepting public bookings returns 422 with error.code: INVALID_TENANT.

{
  "data": {
    "id": "cbk_6a91e4d2",
    "status": "scheduled",
    "queue_id": "queue_8f41d2c7",
    "slot_start": "2026-09-30T14:00:00.000Z",
    "slot_end": "2026-09-30T14:30:00.000Z"
  },
  "meta": {
    "request_id": "req_queue_appointment_book",
    "timestamp": "2026-09-29T16:13:01Z"
  }
}

Branch on the deterministic error codes above; a blind retry after a SLOT_ALREADY_BOOKED just burns a different slot.

Ring groups and shared lines, worked

Three loops cover the simultaneous-dial surface: define the group (ring groups), pre-check a nested group edit (cycle check), and track a shared line (create → poll live status). The ring groups guide walks the product-side config end to end.

25. Pre-check a ring group for cycles

POST /voice/ring-groups/validate-cycle is the FE’s optimistic pre-save guard: send the proposed members (and the existing group id on edit, or null on create) and it replies ok: true, or ok: false with the cyclePath that closes the loop — so the save button stays disabled inline instead of 422-ing on submit.

{
  "data": {
    "ok": true,
    "dfsCap": 20
  },
  "meta": {
    "request_id": "req_ring_group_validate_cycle",
    "timestamp": "2026-09-29T16:14:22Z"
  }
}

When the walk closes a loop, the same status carries the diagnostic:

200

{
  "data": {
    "ok": false,
    "code": "INVALID_RING_GROUP_CYCLE",
    "message": "Ring-group member list contains a cycle",
    "cyclePath": ["ringgroup_a1f2d9c0", "ringgroup_b7e4a1d3", "ringgroup_a1f2d9c0"],
    "dfsCap": 20
  },
  "meta": {
    "request_id": "req_ring_group_validate_cycle",
    "timestamp": "2026-09-29T16:14:31Z"
  }
}

26. Create a ring group

POST /voice/ring-groups writes the group; the response echoes the stored row plus a non-blocking warnings array (duplicate PSTN members across groups) that the dashboard surfaces as a toast.

{
  "data": {
    "id": "ringgroup_a1f2d9c0",
    "organization_id": "org_ayMne6et",
    "name": "Front of house",
    "strategy": "simultaneous",
    "ring_timeout_sec": 30,
    "members": [
      { "kind": "sip_username", "value": "acme-frontdesk" },
      { "kind": "pstn", "value": "+14155552671" }
    ],
    "warnings": [],
    "created_at": "2026-09-29T16:15:08Z",
    "updated_at": "2026-09-29T16:15:08Z"
  },
  "meta": {
    "request_id": "req_ring_group_create",
    "timestamp": "2026-09-29T16:15:08Z"
  }
}

Duplicate names return 409; a member that references an unknown SIP credential, a malformed PSTN, or a missing nested group returns 422.

27. Create a shared line

POST /voice/shared-lines creates the tenant-scoped shared line (the extension several operators answer from). The response gives the created line back with its (zero) members — you attach members over the member API next. The shared lines appearance guide covers the operator-side setup.

{
  "data": {
    "id": "sharedLine_6c2a1e9d",
    "name": "Front desk line",
    "description": "Main lobby desk line",
    "primaryExtension": "10",
    "status": "active",
    "members": [],
    "memberCount": 0,
    "createdAt": "2026-09-29T16:16:14Z",
    "updatedAt": "2026-09-29T16:16:14Z"
  },
  "meta": {
    "request_id": "req_shared_line_create",
    "timestamp": "2026-09-29T16:16:14Z"
  }
}

409 fires when name or extension collides within the tenant.

28. Add a shared-line member

POST /voice/shared-lines/{id}/members attaches one member (a SIP extension value or an extension number the server resolves to the credential). canGrab controls whether the member can steal the live call; sortOrder fixes the member list order the dashboard renders.

{
  "data": {
    "id": "slm_9d41f2c7",
    "sharedLineId": "sharedLine_6c2a1e9d",
    "memberKind": "sip_extension",
    "memberValue": "acme-frontdesk",
    "canGrab": true,
    "sortOrder": 1,
    "createdAt": "2026-09-29T16:17:02Z"
  },
  "meta": {
    "request_id": "req_shared_line_member_add",
    "timestamp": "2026-09-29T16:17:02Z"
  }
}

29. Poll the shared line’s live status

GET /voice/shared-lines/{id}/status is the dashboard’s “In use” / “Idle” read — safe to poll on a short interval, and the decide-to-offer-Grab guard.

{
  "data": {
    "sharedLineId": "sharedLine_6c2a1e9d",
    "activeCall": {
      "callSid": "CALL_abc123def456",
      "onDeviceUsername": "acme-frontdesk",
      "startedAt": "2026-09-29T16:17:48Z",
      "direction": "inbound"
    }
  },
  "meta": {
    "request_id": "req_shared_line_status",
    "timestamp": "2026-09-29T16:17:49Z"
  }
}

activeCall is null when nobody on the line is mid-call; the Grab button in section 30 stays disabled off that read.

30. Grab the shared line’s call

POST /voice/shared-lines/{id}/grab moves the answered call onto the grabbingMemberValue’s device and returns the from/to pairing the softswitch re-INVITE will move.

{
  "data": {
    "sharedLineId": "sharedLine_6c2a1e9d",
    "callSid": "CALL_abc123def456",
    "fromDeviceUsername": "acme-frontdesk",
    "toDeviceUsername": "acme-lobby2"
  },
  "meta": {
    "request_id": "req_shared_line_grab",
    "timestamp": "2026-09-29T16:18:04Z"
  }
}

A second member firing Grab in the same instant gets 409 (the claim is atomic); a member without canGrab gets 403.

SIP trunks, worked

BYO-carrier trunk provisioning splits across outbound and inbound plus the probe/test pair that proves the registrar before the row is saved.

31. Create an outbound SIP trunk

POST /voice/sip-trunks provisions the outbound leg. Send the registrar host (with optional port, transport, authentication, codecs, maxConcurrent, failoverTrunkId, and the probe verdict metadata probe_status/probe_error that keeps the live status from reading “Unregistered” while the save is fresh). The response is the stored entry with the digest password masked.

{
  "data": {
    "id": "sip_trk_4d9f2a1c",
    "name": "Carrier primary",
    "direction": "outgoing",
    "enabled": true,
    "host": "sip.acme-carrier.example",
    "port": 5060,
    "transport": "udp",
    "authentication": {
      "username": "car_acme01",
      "password": "••••••••"
    },
    "codecs": ["PCMU", "PCMA"],
    "maxConcurrent": 120,
    "failoverTrunkId": "sip_trk_9c11e0b4",
    "status": "registered",
    "createdAt": "2026-09-29T16:19:14Z",
    "updatedAt": "2026-09-29T16:19:14Z"
  },
  "meta": {
    "request_id": "req_sip_trunk_create_outbound",
    "timestamp": "2026-09-29T16:19:14Z"
  }
}

32. Create an inbound SIP trunk

POST /voice/sip-trunks/incoming provisions the inbound leg. authMode chooses the gate (ip_allowlist, digest, or both); on digest mode the response carries digestUsername plus the one-time digestPassword — record it immediately, because the server masks it on every later read. The credentials_revealed_once flag marks that the plaintext lives only in this first response.

{
  "data": {
    "id": "sip_trk_8b74c0d1",
    "name": "Inbound primary",
    "direction": "incoming",
    "enabled": true,
    "authMode": "digest",
    "allowedIps": ["203.0.113.10/32"],
    "allowedCallerIds": ["+14155552671"],
    "digestUsername": "inb_acme_primary",
    "digestPassword": "dk_live_4f2c9a7b1e3d5f6a",
    "credentials_revealed_once": true,
    "perTrunkLimits": {
      "max_concurrent": 40
    },
    "routingRules": {
      "cdr_webhook_url": "https://hooks.example.com/cdr/inbound"
    },
    "createdAt": "2026-09-29T16:20:11Z",
    "updatedAt": "2026-09-29T16:20:11Z"
  },
  "meta": {
    "request_id": "req_sip_trunk_create_inbound",
    "timestamp": "2026-09-29T16:20:11Z"
  }
}

33. Rotate the inbound trunk’s digest credential

POST /voice/sip-trunks/{id}/credentials/rotate re-issues the digest password on an inbound digest/both trunk. The plaintext is NOT in this response — the server mints a single-use reveal_token the caller fetches once via GET /voice/sip-trunks/{id}/credentials/reveal?token=… inside the 5-minute window; subsequent reads return 410. An ip_allowlist-only trunk 422s.

{
  "data": {
    "trunk_id": "sip_trk_8b74c0d1",
    "digestUsername": "inb_acme_primary",
    "reveal_token": "rvt_01JRG3412k9x",
    "reveal_url": "/api/v1/voice/sip-trunks/sip_trk_8b74c0d1/credentials/reveal?token=rvt_01JRG3412k9x",
    "reveal_expires_at": "2026-09-29T16:26:00Z",
    "rotated_at": "2026-09-29T16:21:00Z"
  },
  "meta": {
    "request_id": "req_sip_trunk_rotate",
    "timestamp": "2026-09-29T16:21:00Z"
  }
}

34. Probe an outbound trunk pre-save

POST /voice/sip-trunks/probe runs a real REGISTER through the probe carrier and returns the verdict (reachable/unreachable) plus the ordered steps that named the failing stage. A failed probe is still a 200 — the verdict travels with the eventual POST /voice/sip-trunks as probe_status.

{
  "data": {
    "reachable": false,
    "status": "unreachable",
    "error_code": "DNS_RESOLUTION_FAILED",
    "error": "DNS lookup for sip.acme-carrier.example returned no address records.",
    "latency_ms": null,
    "tested_at": "2026-09-29T16:22:14Z",
    "steps": [
      {
        "step": "dns_resolve",
        "status": "failed",
        "detail": "no address records returned"
      },
      {
        "step": "register",
        "status": "not_run",
        "detail": null
      }
    ]
  },
  "meta": {
    "request_id": "req_sip_trunk_probe",
    "timestamp": "2026-09-29T16:22:14Z"
  }
}

35. Test a persisted trunk

POST /voice/sip-trunks/{id}/test re-checks a stored trunk. Inbound trunks return a static config verdict (ok / misconfigured + per-issue list); outbound trunks re-run the REGISTER probe and reply with status, latency_ms, the sanitised error, and the steps breakdown — the same shape as section 34, anchored to the trunk id.

{
  "data": {
    "trunk_id": "sip_trk_4d9f2a1c",
    "status": "reachable",
    "latency_ms": 87,
    "error_code": null,
    "error": null,
    "tested_at": "2026-09-29T16:23:42Z",
    "sip_call_id": "call_6d2a4e91",
    "steps": [
      {
        "step": "dns_resolve",
        "status": "ok",
        "detail": null
      },
      {
        "step": "register",
        "status": "ok",
        "detail": "registered over udp"
      }
    ]
  },
  "meta": {
    "request_id": "req_sip_trunk_test",
    "timestamp": "2026-09-29T16:23:42Z"
  }
}

36. Place a test call through the trunk

POST /voice/sip-trunks/{id}/test-call dials a destination constrained to an org-owned DID or a platform test number — never an arbitrary number, so the billing surface stays safe. The response returns the Jambonz call sid plus the resolved trunkId/to pair.

{
  "data": {
    "callSid": "CALL_abc123def456",
    "to": "+15005550001",
    "trunkId": "sip_trk_4d9f2a1c",
    "trunk_test": true
  },
  "meta": {
    "request_id": "req_sip_trunk_test_call",
    "timestamp": "2026-09-29T16:24:51Z"
  }
}

Browser softphone, worked

The softphone lifecycle splits into four calls: token mint → SIP WSS credential → outbound dial → the (internal) HMAC validate the gateway runs between them. The voice product picker guide lays out when softphone belongs next to trunked calls.

37. Mint the browser softphone token

POST /voice/softphone/token returns the LiveKit access token plus the deterministic softphone:<tenant>:<user> room the browser softphone connects to; reconnects land in the same room. media_url is canonical — livekit_url stays as a deprecated alias one minor cycle.

{
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…",
    "room_name": "softphone:ten_1f4c9d2e:user_a9MMc7",
    "media_url": "wss://media.orbit.devotel.io",
    "livekit_url": "wss://media.orbit.devotel.io",
    "ice_servers": [
      { "urls": "stun:stun.orbit.devotel.io:3478" }
    ],
    "ice_servers_expires_at": 1759161600
  },
  "meta": {
    "request_id": "req_softphone_token",
    "timestamp": "2026-09-29T16:26:31Z"
  }
}

38. Issue the SIP WSS credential

POST /voice/softphone/register mints the short-lived SIP credential the WebRTC SDK registers against the SIP-over-WSS gateway. The returned tuple (sipUsername, sipPassword, sipDomain, wssUrl, iceServers) is the deterministic config — an optional wssFallbackUrl shows only when a secondary gateway is provisioned.

{
  "data": {
    "sipUsername": "sipusr_d218aa6",
    "sipPassword": "dMu4r8pY2wq1",
    "sipDomain": "orbit.devotel.io",
    "wssUrl": "wss://sip.orbit.devotel.io",
    "iceServers": [
      { "urls": "stun:stun.orbit.devotel.io:3478" }
    ],
    "callerIdNumber": "+18005551234",
    "expiresAt": 1759165200000
  },
  "meta": {
    "request_id": "req_softphone_register",
    "timestamp": "2026-09-29T16:27:12Z"
  }
}

39. Originate the outbound softphone call

POST /voice/softphone/dial places the PSTN call and bridges it into the per-user LiveKit room the token minted. The response returns the created call row plus the resolved room_name so the dashboard labels the attempts.

{
  "data": {
    "id": "call_7b3e9c2d",
    "direction": "outbound",
    "from": "+18005551234",
    "to": "+14155552671",
    "status": "initiated",
    "room_name": "softphone:ten_1f4c9d2e:user_a9MMc7"
  },
  "meta": {
    "request_id": "req_softphone_dial",
    "timestamp": "2026-09-29T16:28:49Z"
  }
}

40. Internal HMAC credential validate (gateway-internal)

POST /voice/softphone/internal/validate is the SIP gateway’s credential-double-check — not for browser clients. The gateway verifies the member it minted (username, orgId, expiresAt, password) and gets ok: true back, or a 401 when the HMAC is stale/wrong/revoked.

{
  "data": {
    "ok": true
  },
  "meta": {
    "request_id": "req_softphone_validate",
    "timestamp": "2026-09-29T16:29:11Z"
  }
}

Webhook disposition, worked

POST /voice/sip-webhook is the platform’s inbound media/SIP disposition receiver — the sender signs each payload with a project-issued JWT, and the router acknowledges with handled: true when the event moved the call-log row forward, or handled: false (+ deduped: true when a re-delivered event hit the dedupe slot).

41. Acknowledge a signature-valid disposition event

{
  "data": {
    "event": "participant_joined",
    "handled": true
  },
  "meta": {
    "request_id": "req_sip_webhook_handled",
    "timestamp": "2026-09-29T16:30:36Z"
  }
}

A re-delivered event returns handled: false with deduped: true; a SIP participant shape the route doesn’t apply returns handled: false. The envelope stays the same { data, meta } pair as every operation above.

More worked envelopes (sections 42–120 — the null-envelope backfill)

The forty-one sections above plus these ~120 pin the per-route { data, meta } body for the highest-traffic reads and writes the generator still rendered with the literal "data": {} shell. Each numbered section opens with a <Note> route callout so the generator’s route-hinted overlay extraction picks this body over the autogen shell, one route per section.

42. Read an affinity-routing config

GET /api/v1/voice/affinity-routing

{
  "data": {
    "enabled": true,
    "treatment_percent": 25,
    "affinity_weight": 0.7,
    "headroom_weight": 0.3,
    "agent_profiles": {
      "user_9f3ac2d1": ["segment:enterprise", "style:analytical"]
    },
    "profile_count": 1
  },
  "meta": {
    "request_id": "req_afread",
    "timestamp": "2026-09-29T16:14:36Z"
  }
}

43. Update an affinity-routing config

PUT /api/v1/voice/affinity-routing

{
  "data": {
    "enabled": true,
    "treatment_percent": 25,
    "affinity_weight": 0.7,
    "headroom_weight": 0.3,
    "agent_profiles": {
      "user_9f3ac2d1": ["segment:enterprise"]
    },
    "profile_count": 1
  },
  "meta": {
    "request_id": "req_afwrite",
    "timestamp": "2026-09-29T16:21:44Z"
  }
}

44. Read an attribute-routing config

GET /api/v1/voice/attribute-routing

{
  "data": {
    "rules": [
      {
        "id": "vra_4e2d9ac1",
        "attribute": "segment",
        "operator": "eq",
        "value": "enterprise",
        "queue_id": "que_9c31d5b2",
        "priority": 1
      }
    ]
  },
  "meta": {
    "request_id": "req_attrread",
    "timestamp": "2026-09-29T16:40:12Z"
  }
}

45. Update an attribute-routing config

PUT /api/v1/voice/attribute-routing

{
  "data": {
    "rules": [
      {
        "id": "vra_4e2d9ac1",
        "attribute": "segment",
        "operator": "eq",
        "value": "enterprise",
        "queue_id": "que_9c31d5b2",
        "priority": 1
      }
    ]
  },
  "meta": {
    "request_id": "req_attrwrite",
    "timestamp": "2026-09-29T16:47:55Z"
  }
}

46. List AMD answers on your calls

GET /api/v1/voice/calls/search

{
  "data": {
    "items": [
      {
        "call_id": "call_8b2c4d6e1f3a5b7c9d0e2f4a",
        "to": "+14155552671",
        "from": "+18005551234",
        "status": "completed",
        "amd_result": "human",
        "amd_confidence": 0.94,
        "duration_seconds": 61,
        "initiated_at": "2026-10-01T09:00:04Z"
      }
    ],
    "total": 1,
    "has_more": false
  },
  "meta": {
    "request_id": "req_amdlist",
    "timestamp": "2026-10-01T09:05:40Z"
  }
}

47. Read one call row

GET /api/v1/voice/calls/{id}

{
  "data": {
    "id": "call_8b2c4d6e1f3a5b7c9d0e2f4a",
    "direction": "outbound",
    "from": "+18005551234",
    "to": "+14155552671",
    "status": "completed",
    "duration_seconds": 142,
    "hangup_reason": "normal_clearing",
    "started_at": "2026-09-27T09:14:03Z",
    "ended_at": "2026-09-27T09:17:37Z"
  },
  "meta": {
    "request_id": "req_callget",
    "timestamp": "2026-09-27T09:17:38Z"
  }
}

48. Download the recording inline

GET /api/v1/voice/calls/{id}/recording

{
  "data": {
    "recording_id": "rec_9d8c7b6a5c4e3f2d1b0a",
    "duration_seconds": 142,
    "channels": 1,
    "bitrate_kbps": 64,
    "download_url": "https://api.orbit.devotel.io/api/v1/recordings/rec_9d8c7b6a5c4e3f2d1b0a/download"
  },
  "meta": {
    "request_id": "req_recget",
    "timestamp": "2026-09-27T09:17:38Z"
  }
}

49. List the recordings a call produced

GET /api/v1/voice/calls/aggregate

{
  "data": {
    "total_calls": 3,
    "total_duration_seconds": 312,
    "completed": 2,
    "failed": 1
  },
  "meta": {
    "request_id": "req_agg_today",
    "timestamp": "2026-09-27T11:48:02Z"
  }
}

50. Export the filtered call set

GET /api/v1/voice/calls/export

{
  "data": {
    "export_id": "export_3f6a81c2d4e5471a9b0c2d5e",
    "status": "queued",
    "download_url": null,
    "expires_at": "2026-10-01T11:48:02Z"
  },
  "meta": {
    "request_id": "req_callex",
    "timestamp": "2026-09-27T11:47:04Z"
  }
}

51. List the SIP trunk inventory

GET /api/v1/voice/sip-trunks

{
  "data": [
    {
      "id": "spt_8818d72a5dba4dfea49b0114",
      "name": "Primary carrier",
      "direction": "outbound",
      "host": "sip.acme.example",
      "registered": true,
      "latency_ms_p90": 46,
      "calls_24h": 913
    }
  ],
  "meta": {
    "request_id": "req_trunklist",
    "timestamp": "2026-09-29T11:51:52Z"
  }
}

52. Read one SIP trunk

GET /api/v1/voice/sip-trunks/{id}

{
  "data": {
    "id": "spt_8818d72a5dba4dfea49b0114",
    "name": "Primary carrier",
    "direction": "outbound",
    "host": "sip.acme.example",
    "registered": true,
    "latency_ms_p90": 46,
    "calls_24h": 913
  },
  "meta": {
    "request_id": "req_trunkget",
    "timestamp": "2026-09-29T11:55:03Z"
  }
}

53. Reveal the trunk credentials once

GET /api/v1/voice/sip-trunks/{id}/credentials/reveal

{
  "data": {
    "id": "spt_8818d72a5dba4dfea49b0114",
    "username": "org_x_channel",
    "password": "whip_it_live_once_then_scramble",
    "auth_realm": "wholesale.devotel"
  },
  "meta": {
    "request_id": "req_credreveal",
    "timestamp": "2026-09-29T11:59:36Z"
  }
}

54. Provision a SIP-webhook POST authentication rule

GET /api/v1/voice/call-forwarding

{
  "data": {
    "rules": [
      {
        "user_id": "user_9f3ac2d1",
        "destination": "+14155552671",
        "strategy": "simultaneous",
        "maximum_destinations": 4,
        "ring_timeout_seconds": 25,
        "updated_at": "2026-09-29T11:31:41Z"
      }
    ]
  },
  "meta": {
    "request_id": "req_cfread",
    "timestamp": "2026-09-29T11:32:40Z"
  }
}

55. Read my call-forwarding rule as a user

GET /api/v1/voice/call-forwarding/users/{userId}

{
  "data": {
    "user_id": "user_9f3ac2d1",
    "destination": "+14155552671",
    "strategy": "simultaneous",
    "maximum_destinations": 4,
    "ring_timeout_seconds": 25
  },
  "meta": {
    "request_id": "req_cfuser",
    "timestamp": "2026-09-29T11:34:15Z"
  }
}

56. Read the queue’s live counter

GET /api/v1/voice/queues/{id}/live

{
  "data": {
    "holdTimeSubs": 17,
    "liveHandled": 206,
    "inCallNow": 3,
    "queue_in_line": 41,
    "wait_time_max_seconds": 704,
    "service_level": 97.8,
    "agents_logged_in": 11
  },
  "meta": {
    "request_id": "req_qlive",
    "timestamp": "2026-09-29T12:00:58Z"
  }
}

57. Read the agent’s routing-weights map

GET /api/v1/voice/agents/{id}/queue-weights

{
  "data": {
    "que_9c31d5b2": 62,
    "que_81eac8f0": 38
  },
  "meta": {
    "request_id": "req_qwread",
    "timestamp": "2026-09-29T12:04:12Z"
  }
}

58. Patch the agent’s routing weights

PATCH /api/v1/voice/agents/{id}/queue-weights

{
  "data": {
    "que_9c31d5b2": 62,
    "que_81eac8f0": 38
  },
  "meta": {
    "request_id": "req_qwpatch",
    "timestamp": "2026-09-29T12:08:46Z"
  }
}

59. Read the agent’s skill-proficiency map

GET /api/v1/voice/agents/{id}/skill-proficiency

{
  "data": {
    "segment:enterprise": 3,
    "style:analytical": 4
  },
  "meta": {
    "request_id": "req_spread",
    "timestamp": "2026-09-29T12:11:19Z"
  }
}

60. Patch the agent’s skill-proficiency map

PATCH /api/v1/voice/agents/{id}/skill-proficiency

{
  "data": {
    "segment:enterprise": 3,
    "style:analytical": 4
  },
  "meta": {
    "request_id": "req_sppatch",
    "timestamp": "2026-09-29T12:15:33Z"
  }
}

61. Read today’s agent-to-state timeline

GET /api/v1/voice/agents/{id}/state-history

{
  "data": {
    "items": [
      {
        "id": "row_77f4d46cc63b45d5b8e9a19b32fe36c2",
        "agent_id": "user_9f3ac2d1",
        "from_state": "idle",
        "to_state": "on_call",
        "reason": "answered inbound queues",
        "changed_at": "2026-09-29T12:11:04Z"
      }
    ]
  },
  "meta": {
    "request_id": "req_shread",
    "timestamp": "2026-09-29T12:18:31Z"
  }
}

62. List voicemail messages

GET /api/v1/voice/voicemails

{
  "data": {
    "items": [
      {
        "id": "vm_a51e2c94",
        "from": "+14155552671",
        "recorded_at": "2026-10-01T09:08:14Z",
        "duration_seconds": 74,
        "transcript": "Please call me back on the order line."
      }
    ]
  },
  "meta": {
    "request_id": "req_vmlist",
    "timestamp": "2026-10-01T09:09:02Z"
  }
}

63. Read a SIP-credential reveal response

GET /api/v1/voice/sip-trunks/{id}/rate

{
  "data": {
    "id": "spt_8818d72a5dba4dfea49b0114",
    "rate_cents_per_min": 1.4,
    "currency": "USD",
    "usage_count_24h": 913
  },
  "meta": {
    "request_id": "req_trunkrate",
    "timestamp": "2026-09-29T12:20:14Z"
  }
}

64. Arm the business-continuity reroute

POST /api/v1/voice/business-continuity-reroute/activate

{
  "data": {
    "action": "activated",
    "target": "+14155552671",
    "configured_by": "user_admin_01",
    "started_at": "2026-09-29T15:21:42Z",
    "expires_at": "2026-09-29T21:21:42Z"
  },
  "meta": {
    "request_id": "req_bcr_arm",
    "timestamp": "2026-09-29T15:21:42Z"
  }
}

65. Disarm the reroute early

POST /api/v1/voice/business-continuity-reroute/deactivate

{
  "data": {
    "action": "deactivated",
    "started_at": "2026-09-29T15:21:42Z",
    "stopped_at": "2026-09-29T15:23:51Z"
  },
  "meta": {
    "request_id": "req_bcr_disarm",
    "timestamp": "2026-09-29T15:23:51Z"
  }
}

66. Read the business-continuity status

GET /api/v1/voice/business-continuity-reroute

{
  "data": {
    "active": false,
    "target": "+14155552671",
    "started_at": null,
    "expires_at": null
  },
  "meta": {
    "request_id": "req_bcr_stat",
    "timestamp": "2026-09-29T15:24:40Z"
  }
}

67. Create the ACD auto-answer toggle

PUT /api/v1/voice/acd-auto-answer

{
  "data": {
    "enabled": true,
    "granted_count": 32
  },
  "meta": {
    "request_id": "req_acdw",
    "timestamp": "2026-09-29T15:25:06Z"
  }
}

68. Read the ACD auto-answer toggle

GET /api/v1/voice/acd-auto-answer

{
  "data": {
    "enabled": true,
    "granted_count": 32
  },
  "meta": {
    "request_id": "req_acdr",
    "timestamp": "2026-09-29T15:26:20Z"
  }
}

69. Read the caller-ids inventory

GET /api/v1/voice/caller-ids

{
  "data": [
    {
      "id": "cid_9d8c7b6a5c4e3f2d1b0a",
      "number": "+18005551234",
      "verified": true,
      "verification_method": "sms"
    }
  ],
  "meta": {
    "request_id": "req_cidlist",
    "timestamp": "2026-09-29T15:27:49Z"
  }
}

70. Verify a caller-id by SMS challenge

POST /api/v1/voice/caller-ids/verify

{
  "data": {
    "id": "cid_9d8c7b6a5c4e3f2d1b0a",
    "number": "+18005551234",
    "verified": true,
    "verification_method": "sms"
  },
  "meta": {
    "request_id": "req_cidver",
    "timestamp": "2026-09-29T15:30:22Z"
  }
}

71. Re-send the caller-id challenge

POST /api/v1/voice/caller-ids/{id}/resend

{
  "data": {
    "id": "cid_9d8c7b6a5c4e3f2d1b0a",
    "challenge_sent": true,
    "expires_at": "2026-09-29T16:30:22Z"
  },
  "meta": {
    "request_id": "req_cidres",
    "timestamp": "2026-09-29T15:32:41Z"
  }
}

72. Confirm a caller-id challenge code

POST /api/v1/voice/caller-ids/confirm

{
  "data": {
    "id": "cid_9d8c7b6a5c4e3f2d1b0a",
    "verified": true,
    "verification_method": "sms"
  },
  "meta": {
    "request_id": "req_cidconf",
    "timestamp": "2026-09-29T15:33:55Z"
  }
}

73. Read the aux-code catalog

GET /api/v1/voice/aux-codes

{
  "data": [
    {
      "id": "aux_4e2d9ac1",
      "code": "BREAK_15",
      "description": "15-minute break",
      "forced": false
    }
  ],
  "meta": {
    "request_id": "req_auxlist",
    "timestamp": "2026-09-29T15:34:16Z"
  }
}

74. Patch an aux-code definition

PATCH /api/v1/voice/aux-codes/{id}

{
  "data": {
    "id": "aux_4e2d9ac1",
    "code": "BREAK_15",
    "description": "15-minute break",
    "forced": false
  },
  "meta": {
    "request_id": "req_auxpatch",
    "timestamp": "2026-09-29T15:36:04Z"
  }
}

75. List the pause-reason codes

GET /api/v1/voice/agents/pause-reason-codes

{
  "data": [
    {
      "id": "prc_77f4d46cc63b45d5b8e9a19b32fe36c2",
      "name": "Training",
      "prevents_wrap": true
    }
  ],
  "meta": {
    "request_id": "req_prclist",
    "timestamp": "2026-09-29T15:37:46Z"
  }
}

76. Patch a pause-reason code

PATCH /api/v1/voice/agents/pause-reason-codes/{id}

{
  "data": {
    "id": "prc_77f4d46cc63b45d5b8e9a19b32fe36c2",
    "name": "Training",
    "prevents_wrap": true
  },
  "meta": {
    "request_id": "req_prcpatch",
    "timestamp": "2026-09-29T15:39:12Z"
  }
}

77. Read the dial-plan configuration

GET /api/v1/voice/dial-plan

{
  "data": {
    "timeouts": {
      "rna_seconds": 30,
      "queue_seconds": 300
    },
    "block_unrestricted": true
  },
  "meta": {
    "request_id": "req_dpread",
    "timestamp": "2026-09-29T15:40:31Z"
  }
}

78. Update the dial-plan configuration

PUT /api/v1/voice/dial-plan

{
  "data": {
    "timeouts": {
      "rna_seconds": 30,
      "queue_seconds": 300
    },
    "block_unrestricted": true
  },
  "meta": {
    "request_id": "req_dpwrite",
    "timestamp": "2026-09-29T15:42:18Z"
  }
}

79. Read the dialer abandonment ceiling

GET /api/v1/voice/dialer-abandon-ceiling

{
  "data": {
    "max_percent": 3,
    "mode": "warn_and_pause"
  },
  "meta": {
    "request_id": "req_dceilingr",
    "timestamp": "2026-09-29T15:43:44Z"
  }
}

80. Update the dialer abandonment ceiling

PUT /api/v1/voice/dialer-abandon-ceiling

{
  "data": {
    "max_percent": 3,
    "mode": "warn_and_pause"
  },
  "meta": {
    "request_id": "req_dceilingw",
    "timestamp": "2026-09-29T15:45:05Z"
  }
}

81. Read the dialing-restrictions map

GET /api/v1/voice/dialing-restrictions

{
  "data": {
    "restricted_prefixes": ["+1900", "+976"],
    "allow_list": ["+14155552671"]
  },
  "meta": {
    "request_id": "req_drestrict",
    "timestamp": "2026-09-29T15:46:27Z"
  }
}

82. Update the dialing-restrictions map

PUT /api/v1/voice/dialing-restrictions

{
  "data": {
    "restricted_prefixes": ["+1900", "+976"],
    "allow_list": ["+14155552671"]
  },
  "meta": {
    "request_id": "req_drestrictw",
    "timestamp": "2026-09-29T15:47:52Z"
  }
}

83. Read the directory

GET /api/v1/voice/directory

{
  "data": [
    {
      "user_id": "user_9f3ac2d1",
      "display_name": "Fatima Q.",
      "extension": "1001",
      "office": "BOS"
    }
  ],
  "meta": {
    "request_id": "req_dirread",
    "timestamp": "2026-09-29T15:48:19Z"
  }
}

84. Update the directory

PUT /api/v1/voice/directory

{
  "data": {
    "user_id": "user_9f3ac2d1",
    "display_name": "Fatima Q.",
    "extension": "1001",
    "office": "BOS"
  },
  "meta": {
    "request_id": "req_dirwrite",
    "timestamp": "2026-09-29T15:49:33Z"
  }
}

85. Read the maximum-call-duration policy

GET /api/v1/voice/max-call-duration

{
  "data": {
    "max_seconds": 7200,
    "action": "hangup"
  },
  "meta": {
    "request_id": "req_mcdr",
    "timestamp": "2026-09-29T15:50:41Z"
  }
}

86. Update the maximum-call-duration policy

PUT /api/v1/voice/max-call-duration

{
  "data": {
    "max_seconds": 7200,
    "action": "hangup"
  },
  "meta": {
    "request_id": "req_mcdw",
    "timestamp": "2026-09-29T15:51:52Z"
  }
}

87. Read the recording-policy blob

GET /api/v1/voice/recording-policy

{
  "data": {
    "enabled": true,
    "retention_days": 30,
    "pa_mask": true,
    "storage": "orbitsmart"
  },
  "meta": {
    "request_id": "req_rcpolr",
    "timestamp": "2026-09-29T15:53:21Z"
  }
}

88. Update the recording-policy blob

PUT /api/v1/voice/recording-policy

{
  "data": {
    "enabled": true,
    "retention_days": 30,
    "pa_mask": true,
    "storage": "orbitsmart"
  },
  "meta": {
    "request_id": "req_rcpolw",
    "timestamp": "2026-09-29T15:54:39Z"
  }
}

89. Read the preferred regions list

GET /api/v1/voice/regions/preferred

{
  "data": ["us-east-1", "us-west-2", "eu-central-1"],
  "meta": {
    "request_id": "req_regr",
    "timestamp": "2026-09-29T15:55:48Z"
  }
}

90. Update the preferred regions list

PUT /api/v1/voice/regions/preferred

{
  "data": ["us-east-1", "us-west-2", "eu-central-1"],
  "meta": {
    "request_id": "req_regw",
    "timestamp": "2026-09-29T15:57:06Z"
  }
}

91. Read the SIP max-registrations cap

GET /api/v1/voice/sip-max-registrations

{
  "data": {
    "max": 5,
    "current": 3
  },
  "meta": {
    "request_id": "req_sipmaxr",
    "timestamp": "2026-09-29T15:58:29Z"
  }
}

92. Update the SIP max-registrations cap

PUT /api/v1/voice/sip-max-registrations

{
  "data": {
    "max": 5,
    "current": 3
  },
  "meta": {
    "request_id": "req_sipmaxw",
    "timestamp": "2026-09-29T15:59:46Z"
  }
}

93. Read the skill-proficiency-decay table

GET /api/v1/voice/skill-proficiency-decay

{
  "data": [
    {
      "tag": "segment:enterprise",
      "decay_points_per_day": 0.1,
      "floor": 1,
      "updated_at": "2026-09-29T16:00:12Z"
    }
  ],
  "meta": {
    "request_id": "req_spdr",
    "timestamp": "2026-09-29T16:00:51Z"
  }
}

94. Update the skill-proficiency-decay table

PUT /api/v1/voice/skill-proficiency-decay

{
  "data": [
    {
      "tag": "segment:enterprise",
      "decay_points_per_day": 0.1,
      "floor": 1
    }
  ],
  "meta": {
    "request_id": "req_spdw",
    "timestamp": "2026-09-29T16:01:55Z"
  }
}

95. Read the STT provider failover chain

GET /api/v1/voice/stt-provider-chain

{
  "data": ["deepgram", "assemblyai", "google-speech"],
  "meta": {
    "request_id": "req_sttr",
    "timestamp": "2026-09-29T16:02:31Z"
  }
}

96. Set the STT provider failover chain

PUT /api/v1/voice/stt-provider-chain

{
  "data": ["deepgram", "assemblyai", "google-speech"],
  "meta": {
    "request_id": "req_sttw",
    "timestamp": "2026-09-29T16:03:52Z"
  }
}

97. Read the voice-provider BYO credential map

GET /api/v1/voice/voice-provider-credential

{
  "data": {
    "stt": {
      "kind": "deepgram",
      "key_masked": "dg_…k7m3"
    },
    "llm": {
      "kind": "anthropic",
      "key_masked": "sk-ant_…kk9m"
    }
  },
  "meta": {
    "request_id": "req_vpcr",
    "timestamp": "2026-09-29T16:04:33Z"
  }
}

98. Register a BYO voice credential

PUT /api/v1/voice/voice-provider-credential/{kind}

{
  "data": {
    "kind": "anthropic",
    "state": "pending_activation",
    "key_masked": "sk-ant_…kk9m"
  },
  "meta": {
    "request_id": "req_vpcw",
    "timestamp": "2026-09-29T16:05:47Z"
  }
}

99. Activate a pending BYO credential

POST /api/v1/voice/voice-provider-credential/{kind}/activate

{
  "data": {
    "kind": "anthropic",
    "state": "active",
    "key_masked": "sk-ant_…kk9m"
  },
  "meta": {
    "request_id": "req_vpca",
    "timestamp": "2026-09-29T16:06:55Z"
  }
}

100. Revoke a BYO credential

POST /api/v1/voice/voice-provider-credential/{kind}/revoke

{
  "data": {
    "kind": "anthropic",
    "state": "revoked",
    "revoked_at": "2026-09-29T16:07:14Z"
  },
  "meta": {
    "request_id": "req_vpcx",
    "timestamp": "2026-09-29T16:07:14Z"
  }
}

101. Rotate a BYO credential on a schedule

POST /api/v1/voice/voice-provider-credential/{kind}/rotate

{
  "data": {
    "kind": "anthropic",
    "state": "pending_activation",
    "rotation_window_seconds": 300
  },
  "meta": {
    "request_id": "req_vpcrot",
    "timestamp": "2026-09-29T16:08:41Z"
  }
}

102. Read the conferencing summary

GET /api/v1/voice/conferences

{
  "data": [
    {
      "id": "conf_f1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
      "name": "All-hands bridge",
      "participant_count": 17,
      "created_at": "2026-10-01T10:00:14Z"
    }
  ],
  "meta": {
    "request_id": "req_conflist",
    "timestamp": "2026-10-01T10:00:14Z"
  }
}

103. Create a conference

POST /api/v1/voice/conferences

{
  "data": {
    "id": "conf_f1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
    "name": "All-hands bridge",
    "recording": true,
    "pin": "871492"
  },
  "meta": {
    "request_id": "req_confmake",
    "timestamp": "2026-10-01T10:00:41Z"
  }
}

104. Read conference participants page one

GET /api/v1/voice/conferences/{id}/participants

{
  "data": {
    "items": [
      {
        "participant_id": "prt_0a1b2c3d4e5f6a7b8c9d0e1f",
        "user_id": "user_9f3ac2d1",
        "muted": false,
        "joined_at": "2026-10-01T10:01:33Z"
      }
    ],
    "total": 17,
    "has_more": false
  },
  "meta": {
    "request_id": "req_confprt",
    "timestamp": "2026-10-01T10:02:14Z"
  }
}

105. Reach the queue SLA hub

GET /api/v1/voice/sla-hub

{
  "data": {
    "queue_id": "que_9c31d5b2",
    "sla_target_percent": 80,
    "sla_actual_percent": 97.8,
    "breaches_24h": 0
  },
  "meta": {
    "request_id": "req_slahub",
    "timestamp": "2026-10-01T10:04:27Z"
  }
}

106. Read the quality aggregates

GET /api/v1/voice/quality/aggregates

{
  "data": {
    "mos": 4.1,
    "p90_latency_ms": 46,
    "calls_24h": 913
  },
  "meta": {
    "request_id": "req_qagg",
    "timestamp": "2026-10-01T10:05:39Z"
  }
}

107. Read the disaster-recovery drill status

GET /api/v1/voice/emergency-drill

{
  "data": {
    "enabled": false,
    "last_run_at": "2026-06-15T12:00:00Z",
    "notes": "annual drill window only"
  },
  "meta": {
    "request_id": "req_drillr",
    "timestamp": "2026-10-01T10:06:21Z"
  }
}

108. Update the disaster-recovery drill

PUT /api/v1/voice/emergency-drill

{
  "data": {
    "enabled": true,
    "last_run_at": "2026-10-01T10:06:21Z"
  },
  "meta": {
    "request_id": "req_drillw",
    "timestamp": "2026-10-01T10:06:21Z"
  }
}

109. Read the emergency-notification config

GET /api/v1/voice/emergency-notification

{
  "data": {
    "enabled": true,
    "recipients": ["ops-oncall@devotel.io"],
    "trigger_states": ["outbound_failed"]
  },
  "meta": {
    "request_id": "req_enr",
    "timestamp": "2026-10-01T10:07:44Z"
  }
}

110. Update the emergency-notification config

PUT /api/v1/voice/emergency-notification

{
  "data": {
    "enabled": true,
    "recipients": ["ops-oncall@devotel.io"],
    "trigger_states": ["outbound_failed"]
  },
  "meta": {
    "request_id": "req_enw",
    "timestamp": "2026-10-01T10:08:52Z"
  }
}

111. Read the emergency-routing config

GET /api/v1/voice/emergency-routing-config

{
  "data": {
    "fallback_destination": "+14155552671",
    "psap_enabled": false,
    "psap_label": "E911 dispatch desk"
  },
  "meta": {
    "request_id": "req_ertr",
    "timestamp": "2026-10-01T10:09:48Z"
  }
}

112. Update the emergency-routing config

PUT /api/v1/voice/emergency-routing-config

{
  "data": {
    "fallback_destination": "+14155552671",
    "psap_enabled": false,
    "psap_label": "E911 dispatch desk"
  },
  "meta": {
    "request_id": "req_ertw",
    "timestamp": "2026-10-01T10:10:31Z"
  }
}

113. Attach the E911 address to a number

GET /api/v1/voice/emergency-location/{numberId}

{
  "data": {
    "address_label": "HQ — 14th Floor",
    "street": "101 Boston Ave",
    "city": "Boston",
    "state": "MA",
    "postal_code": "02210",
    "country": "US"
  },
  "meta": {
    "request_id": "req_eloc",
    "timestamp": "2026-10-01T10:11:26Z"
  }
}

114. Attach an emergency location record

POST /api/v1/voice/emergency-location

{
  "data": {
    "number_id": "num_a51e2c94",
    "address_label": "HQ — 14th Floor",
    "resolved": true
  },
  "meta": {
    "request_id": "req_elocw",
    "timestamp": "2026-10-01T10:12:41Z"
  }
}

115. Resolve whether an address is PSAP-usable

GET /api/v1/voice/emergency-location/{numberId}/resolve

{
  "data": {
    "resolved": true,
    "address_label": "HQ — 14th Floor",
    "psap_id": "12980"
  },
  "meta": {
    "request_id": "req_elocres",
    "timestamp": "2026-10-01T10:13:48Z"
  }
}

116. Read the emergency callback (PSAP) binding

GET /api/v1/voice/psap-callback/{numberId}

{
  "data": {
    "callback_number": "+14155552671",
    "psap_enabled": false,
    "label": "On-site callback line"
  },
  "meta": {
    "request_id": "req_psapr",
    "timestamp": "2026-10-01T10:14:32Z"
  }
}

117. Resolve whether the PSAP binding is usable

GET /api/v1/voice/psap-callback/{numberId}/resolve

{
  "data": {
    "resolved": true,
    "callback_number": "+14155552671",
    "psap_id": "12980"
  },
  "meta": {
    "request_id": "req_psapres",
    "timestamp": "2026-10-01T10:15:49Z"
  }
}

118. Attach a PSAP callback binding

POST /api/v1/voice/psap-callback

{
  "data": {
    "number_id": "num_a51e2c94",
    "callback_number": "+14155552671",
    "label": "On-site callback line"
  },
  "meta": {
    "request_id": "req_psapw",
    "timestamp": "2026-10-01T10:16:24Z"
  }
}

119. Read the per-queue comparison

GET /api/v1/voice/queues/comparison

{
  "data": {
    "queues": [
      {
        "queue_id": "que_9c31d5b2",
        "service_level": 97.8,
        "agents_logged_in": 11
      }
    ],
    "window": "24h"
  },
  "meta": {
    "request_id": "req_qcmp",
    "timestamp": "2026-10-01T10:17:30Z"
  }
}

120. Read the wallboard hub config

GET /api/v1/voice/supervisor/wallboard-hub

{
  "data": {
    "tiles": ["queue_live", "sla_burn", "agent_grid"],
    "refresh_ms": 5000,
    "version": "2026-10-01.2"
  },
  "meta": {
    "request_id": "req_wbh",
    "timestamp": "2026-10-01T10:18:12Z"
  }
}

Error shapes across these operations

Every operation above answers failures in the same { error, meta } envelope with a stable error.code. The five statuses worth branching on:

Status	`error.code`	Why it fires	What to do
401	`INVALID_API_KEY`	the API key itself fails before the route runs	rotate the key or re-mint it
403	`FORBIDDEN`	the key lacks this operation’s scope	fix the key’s scope set on the developer page
404	`NOT_FOUND`	the id addressed something that does not exist on your tenant	re-list and re-branch
422	`VALIDATION_ERROR`	the body, path, or query payload failed the schema	branch on `error.details`; a blind retry repeats the same 422
429	`RATE_LIMITED`	the window quota is exhausted	retry after `error.details.retry_after` (or the `Retry-After` header) with the same request body

The general envelope rules (the four shapes, sandbox keys, tagged request ids) live on How to read a worked sample, and the full code catalog sits on the Errors matrix.