Voice API

Build voice applications with Orbit’s Voice API. Make and receive calls, connect AI agents, configure SIP trunks, build IVR menus, host conference calls, and manage voicemail — all through a unified API. Base path: /api/v1/voice

Calls

Initiate a Call

POST /api/v1/voice/calls Start an outbound call. Route it to an AI voice agent, an IVR flow, or a raw SIP destination.

string

required

Destination phone number in E.164 format

string

Caller ID — must be a number registered in your Orbit account. If omitted, the server falls back to your tenant’s default outbound number.

string

default:"outbound"

Call direction: outbound or inbound.

string

AI voice agent to handle the call. The agent must exist in your tenant and not be archived (omit for raw SIP or an Application-bound IVR).

boolean

default:"false"

Whether to record the call

boolean

default:"false"

Request carrier-side Answering Machine Detection for the outbound call.

string

Campaign ID for spend-cap tracking. Recorded on the call log for attribution.

string

IANA timezone (e.g. America/New_York) used for the TCPA quiet-hours check on outbound calls.

object

Arbitrary key-value pairs attached to the call

string

HTTPS URL for programmable call-control. When the call is answered, Orbit fetches this URL and expects a JSON verb sequence — either { "verbs": [...] } or a bare array — describing the flow (say, gather, dial, and so on). Must use the https:// scheme. Mutually exclusive with staticVerbs.

string

default:"POST"

HTTP method used to fetch answer_url: POST or GET.

string

default:"safe-default"

What the call falls back to when the answer_url fetch fails (timeout, non-2xx, or malformed body): safe-default, voicemail, or decline.

array

Inline call-control verb sequence served without a remote fetch. Each entry is an object with a verb field plus its verb-specific params (e.g. { "verb": "say", "text": "Hello" }). Up to 50 verbs. Mutually exclusive with answer_url.

For per-call programmable control, use answer_url or staticVerbs above — supply at most one of them. There are no webhook_url, ivr_id, or max_duration fields; bind IVR menus and TTS prompts to the Application or IVR Flow on the number instead. Any field not listed above is ignored by the server.

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": "+12025551234",
  "agent_id": "agt_abc123",
  "record": true,
  "amd": true
}'

Node.js

import { Orbit } from '@devotel/orbit-sdk'

const orbit = new Orbit({ apiKey: process.env.ORBIT_API_KEY! })

const call = await orbit.voice.calls.create({
  to: '+14155552671',
  from: '+12025551234',
  agent_id: 'agt_abc123',
  record: true,
  amd: true,
})
console.log(call.data.id)

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"], "Content-Type": "application/json"}
r = requests.post("https://api.orbit.devotel.io/api/v1/voice/calls", headers=headers, json={
  "to": "+14155552671",
  "from": "+12025551234",
  "agent_id": "agt_abc123",
  "record": True,
  "amd": True
})
print(r.json())

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/voice/calls", bytes.NewBuffer([]byte(`{
  "to": "+14155552671",
  "from": "+12025551234",
  "agent_id": "agt_abc123",
  "record": true,
  "amd": true
}`)))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	http.DefaultClient.Do(req)
}

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/voice/calls');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, <<<JSON
{
  "to": "+14155552671",
  "from": "+12025551234",
  "agent_id": "agt_abc123",
  "record": true,
  "amd": true
}
JSON);
echo curl_exec($ch);

{
  "data": {
    "id": "call_abc123",
    "to": "+14155552671",
    "from": "+12025551234",
    "agent_id": "agt_abc123",
    "status": "initiating",
    "record": true,
    "created_at": "2026-03-08T12:00:00Z"
  },
  "meta": {
    "request_id": "req_call_001",
    "timestamp": "2026-03-08T12:00:00Z"
  }
}

List Calls

GET /api/v1/voice/calls Retrieve call logs with cursor-based pagination and optional filters.

string

Cursor for pagination

integer

default:"25"

Results per page (max 200)

string

Filter by call status. Free-text (up to 40 characters) so carrier-reported values pass through unchanged; an unrecognized value simply matches its own rows (or none) rather than returning an error. Repeat the parameter to filter by several statuses at once (e.g. ?status=completed&status=busy).Canonical lifecycle values in use: queued, initiated, ringing, in-progress, active, answered, completed, busy, no-answer, failed, canceled, cancelled, missed, transferred, hangup_failed.

string

Filter by caller number

string

Filter by destination number

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/voice/calls?status=completed&limit=20" \
  -H "X-API-Key: dv_live_sk_your_key_here"

Node.js

import { Orbit } from '@devotel/orbit-sdk'

const orbit = new Orbit({ apiKey: process.env.ORBIT_API_KEY! })

const calls = await orbit.voice.calls.list({ status: 'completed', limit: 20 })
console.log(calls.data)

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
r = requests.get("https://api.orbit.devotel.io/api/v1/voice/calls", headers=headers,
                 params={"status": "completed", "limit": 20})
print(r.json())

package main

import (
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.orbit.devotel.io/api/v1/voice/calls?status=completed&limit=20", nil)
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	http.DefaultClient.Do(req)
}

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/voice/calls?status=completed&limit=20');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
]);
echo curl_exec($ch);

Get Call Details

GET /api/v1/voice/calls/{id} Retrieve full details of a call including status, duration, recording URL, and agent interaction summary.

cURL

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

Node.js

const call = await orbit.voice.calls.get('call_abc123')
console.log(call.data)

Python

import os, requests
headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
r = requests.get("https://api.orbit.devotel.io/api/v1/voice/calls/call_abc123", headers=headers)
print(r.json())

package main

import (
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.orbit.devotel.io/api/v1/voice/calls/call_abc123", nil)
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	http.DefaultClient.Do(req)
}

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/voice/calls/call_abc123');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['X-API-Key: ' . getenv('ORBIT_API_KEY')]);
echo curl_exec($ch);

Hang Up a Call

POST /api/v1/voice/calls/{id}/hangup Terminate an active call. AI agents receive a graceful shutdown signal before disconnection.

cURL

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

Node.js

await orbit.voice.calls.hangup('call_abc123')

Python

import os, requests
headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
r = requests.post("https://api.orbit.devotel.io/api/v1/voice/calls/call_abc123/hangup", headers=headers)
print(r.json())

package main

import (
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/voice/calls/call_abc123/hangup", nil)
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	http.DefaultClient.Do(req)
}

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/voice/calls/call_abc123/hangup');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, ['X-API-Key: ' . getenv('ORBIT_API_KEY')]);
echo curl_exec($ch);

Accept / Decline an Inbound Call

POST /api/v1/voice/calls/{id}/accept Accept an incoming call before it auto-rings the configured number-handler. Use when the softphone or programmatic handler wants to answer in lieu of the default routing. POST /api/v1/voice/calls/{id}/decline Reject an incoming call. The carrier receives 486 Busy Here.

cURL

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

Node.js

await orbit.voice.calls.accept('call_abc123')
// or: await orbit.voice.calls.decline('call_abc123')

Python

import os, requests
headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
r = requests.post("https://api.orbit.devotel.io/api/v1/voice/calls/call_abc123/accept", headers=headers)
print(r.json())

package main

import (
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/voice/calls/call_abc123/accept", nil)
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	http.DefaultClient.Do(req)
}

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/voice/calls/call_abc123/accept');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, ['X-API-Key: ' . getenv('ORBIT_API_KEY')]);
echo curl_exec($ch);

Mute / Unmute a Call Leg

POST /api/v1/voice/calls/{id}/mute POST /api/v1/voice/calls/{id}/unmute Mute or unmute the operator side of a connected call. Mute is per-leg — the participant on the other side keeps speaking and their audio still records.

cURL

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

Node.js

await orbit.voice.calls.mute('call_abc123')
await orbit.voice.calls.unmute('call_abc123')

Python

import os, requests
headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
r = requests.post("https://api.orbit.devotel.io/api/v1/voice/calls/call_abc123/mute", headers=headers)
print(r.json())

package main

import (
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/voice/calls/call_abc123/mute", nil)
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	http.DefaultClient.Do(req)
}

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/voice/calls/call_abc123/mute');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, ['X-API-Key: ' . getenv('ORBIT_API_KEY')]);
echo curl_exec($ch);

Hold / Unhold

POST /api/v1/voice/calls/{id}/hold POST /api/v1/voice/calls/{id}/unhold Place the remote party on hold (carrier-side music or silence depending on the trunk’s hold_music configuration). Unhold restores audio in both directions.

cURL

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

Node.js

await orbit.voice.calls.hold('call_abc123')
await orbit.voice.calls.unhold('call_abc123')

Python

import os, requests
headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
r = requests.post("https://api.orbit.devotel.io/api/v1/voice/calls/call_abc123/hold", headers=headers)
print(r.json())

package main

import (
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/voice/calls/call_abc123/hold", nil)
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	http.DefaultClient.Do(req)
}

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/voice/calls/call_abc123/hold');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, ['X-API-Key: ' . getenv('ORBIT_API_KEY')]);
echo curl_exec($ch);

Send DTMF Tones

POST /api/v1/voice/calls/{id}/dtmf

string

required

String of DTMF digits to send (0–9, *, #, A–D), up to 32 characters. Each digit plays for duration_ms followed by a gap_ms silence — by default 200ms tone / 50ms gap.

integer

default:"200"

Per-digit tone duration in milliseconds. Range 50–1000.

integer

default:"50"

Inter-digit gap in milliseconds. Range 50–500.

Use to navigate carrier IVRs from a programmatic outbound call (PIN entry, account confirmations, etc.).

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/voice/calls/call_abc123/dtmf" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "digits": "1234#" }'

Node.js

await orbit.voice.calls.sendDTMF('call_abc123', { digits: '1234#' })

Python

import os, requests
headers = {"X-API-Key": os.environ["ORBIT_API_KEY"], "Content-Type": "application/json"}
r = requests.post("https://api.orbit.devotel.io/api/v1/voice/calls/call_abc123/dtmf",
                  headers=headers, json={"digits": "1234#"})
print(r.json())

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/voice/calls/call_abc123/dtmf",
		bytes.NewBuffer([]byte(`{"digits":"1234#"}`)))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	http.DefaultClient.Do(req)
}

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/voice/calls/call_abc123/dtmf');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, '{"digits":"1234#"}');
echo curl_exec($ch);

POST /api/v1/voice/calls/{id}/transfer Cold-transfer the call to a new destination. Hangs up the original leg the moment the new leg connects.

string

required

Destination phone number, agent ID (agt_*), or extension (ext_*).

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/voice/calls/call_abc123/transfer" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "to": "+14155557890" }'

Node.js

await orbit.voice.calls.transfer('call_abc123', {
  to: '+14155557890',
})

Python

import os, requests
headers = {"X-API-Key": os.environ["ORBIT_API_KEY"], "Content-Type": "application/json"}
r = requests.post("https://api.orbit.devotel.io/api/v1/voice/calls/call_abc123/transfer",
                  headers=headers, json={"to": "+14155557890"})
print(r.json())

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/voice/calls/call_abc123/transfer",
		bytes.NewBuffer([]byte(`{"to":"+14155557890"}`)))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	http.DefaultClient.Do(req)
}

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/voice/calls/call_abc123/transfer');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, '{"to":"+14155557890"}');
echo curl_exec($ch);

Warm Transfer

POST /api/v1/voice/calls/{id}/warm-transfer Start a warm transfer — the calling agent stays connected while a third leg is dialled. The original caller is placed on hold; once the third party answers, the agent has a private “whisper” window with them before completing the handoff.

string

E.164 destination for the warm-transfer consult leg (e.g. +14155557890). Mutually exclusive with queueId — supply exactly one.

string

Queue to transfer into instead of a direct number (attended-transfer-to-queue). Mutually exclusive with destination — supply exactly one. Request is rejected when both or neither are present.

boolean

default:"false"

When true, speak a context sentence to the consult leg on answer before audio bridges.

string

Custom whisper text to speak to the consult leg (max 220 characters), e.g. “Customer Jane Doe, escalation tier 2”. When omitted and contextWhisper is true, a context sentence is generated automatically.

string

Caller ID (E.164) to present on the consult leg. Must be a number your organization owns — a number you do not own is rejected. When omitted, the platform default caller ID is used.

boolean

default:"true"

When true (the default), the agent gets a private consult window with the third party before the handoff can be completed. Set to false to bridge the caller in as soon as the consult leg answers.

string

Optional reason for the transfer, recorded on the call’s transfer history for transfer-rate analytics. One of wrong-queue, escalation, language-mismatch, expertise, or other.

integer

Queue transfers only (used with queueId). Routing priority from 0 to 99 for the agent match — lower wins. Ignored when transferring to a destination.

string[]

Queue transfers only (used with queueId). Skill tags (up to 20) the matched agent must have — only agents with every listed skill are eligible. Ignored when transferring to a destination.

POST /api/v1/voice/calls/{id}/warm-transfer/complete Bridge the original caller into the consult leg and disconnect the original agent. The two non-agent legs are now connected. POST /api/v1/voice/calls/{id}/warm-transfer/cancel Abort the warm transfer and return the original caller to the agent. The consult leg is hung up.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/voice/calls/call_abc123/warm-transfer" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "destination": "+14155557890", "contextWhisper": true, "context": "Customer Jane Doe, escalation tier 2" }'

Node.js

await orbit.voice.calls.warmTransfer('call_abc123', {
  destination: '+14155557890',
  contextWhisper: true,
  context: 'Customer Jane Doe, escalation tier 2',
})
// later:
await orbit.voice.calls.warmTransferComplete('call_abc123')
// or to abort:
await orbit.voice.calls.warmTransferCancel('call_abc123')

Python

import os, requests
headers = {"X-API-Key": os.environ["ORBIT_API_KEY"], "Content-Type": "application/json"}
r = requests.post("https://api.orbit.devotel.io/api/v1/voice/calls/call_abc123/warm-transfer",
                  headers=headers,
                  json={"destination": "+14155557890", "contextWhisper": True, "context": "Customer Jane Doe, escalation tier 2"})
print(r.json())

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/voice/calls/call_abc123/warm-transfer",
		bytes.NewBuffer([]byte(`{"destination":"+14155557890","contextWhisper":true,"context":"Customer Jane Doe, escalation tier 2"}`)))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	http.DefaultClient.Do(req)
}

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/voice/calls/call_abc123/warm-transfer');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS,
  '{"destination":"+14155557890","contextWhisper":true,"context":"Customer Jane Doe, escalation tier 2"}');
echo curl_exec($ch);

Recording

Recordings are configured per-call via record: true on POST /api/v1/voice/calls, or started/stopped mid-call via the endpoints below. Storage is tenant-isolated; URLs expire after 1 hour and require re-fetching via the call detail endpoint.

Start / Stop Mid-Call Recording

POST /api/v1/voice/calls/{id}/recording/start Begin recording an in-progress call. Idempotent — calling on an already-recording call returns the existing recording id. This endpoint takes no body parameters; channel layout and silence trimming are determined by the call’s recording configuration. POST /api/v1/voice/calls/{id}/recording/stop Stop the in-progress recording and finalise the file. Subsequent reads of GET /api/v1/voice/calls/{id}/recording will return the fully-encoded URL.

cURL

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

Node.js

await orbit.voice.recordings.start('call_abc123')
await orbit.voice.recordings.stop('call_abc123')

Python

import os, requests
headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
r = requests.post("https://api.orbit.devotel.io/api/v1/voice/calls/call_abc123/recording/start",
                  headers=headers)
print(r.json())

package main

import (
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/voice/calls/call_abc123/recording/start", nil)
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	http.DefaultClient.Do(req)
}

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/voice/calls/call_abc123/recording/start');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
]);
echo curl_exec($ch);

Retrieve a Call Recording

GET /api/v1/voice/calls/{id}/recording Returns the recording metadata + a 1-hour-expiring signed URL. If the call is still being recorded, status is in_progress and signed_url is null.

cURL

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

Node.js

const rec = await orbit.voice.recordings.get('call_abc123')
console.log(rec.data.signed_url)

Python

import os, requests
headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
r = requests.get("https://api.orbit.devotel.io/api/v1/voice/calls/call_abc123/recording", headers=headers)
print(r.json())

package main

import (
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.orbit.devotel.io/api/v1/voice/calls/call_abc123/recording", nil)
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	http.DefaultClient.Do(req)
}

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/voice/calls/call_abc123/recording');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['X-API-Key: ' . getenv('ORBIT_API_KEY')]);
echo curl_exec($ch);

{
  "data": {
    "call_id": "call_abc123",
    "status": "completed",
    "duration_seconds": 312,
    "format": "mp3",
    "channels": 2,
    "size_bytes": 4980000,
    "signed_url": "https://storage.devotel.io/recordings/call_abc123.mp3?Expires=1735689600&Signature=...",
    "signed_url_expires_at": "2026-03-09T12:00:00Z",
    "created_at": "2026-03-08T11:55:48Z"
  },
  "meta": {
    "request_id": "req_rec_001",
    "timestamp": "2026-03-08T12:00:00Z"
  }
}

Conference Recording

POST /api/v1/voice/conferences/{id}/recording/start POST /api/v1/voice/conferences/{id}/recording/stop Same semantics as call recording but for conference rooms — captures the mixed audio of every participant.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/voice/conferences/conf_abc123/recording/start" \
  -H "X-API-Key: dv_live_sk_your_key_here"

Node.js

await orbit.voice.conferences.startRecording('conf_abc123')
await orbit.voice.conferences.stopRecording('conf_abc123')

Python

import os, requests
headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
r = requests.post("https://api.orbit.devotel.io/api/v1/voice/conferences/conf_abc123/recording/start", headers=headers)
print(r.json())

package main

import (
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("POST",
		"https://api.orbit.devotel.io/api/v1/voice/conferences/conf_abc123/recording/start", nil)
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	http.DefaultClient.Do(req)
}

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/voice/conferences/conf_abc123/recording/start');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, ['X-API-Key: ' . getenv('ORBIT_API_KEY')]);
echo curl_exec($ch);

SIP Trunks

Bring your own carrier by connecting SIP trunks to Orbit. Orbit acts as an SBC (Session Border Controller) with TLS and SRTP encryption.

Create SIP Trunk

POST /api/v1/voice/sip-trunks

string

required

A descriptive name for the trunk (1-120 characters)

string

required

Hostname or IP address of the SIP trunk endpoint (1-253 characters)

number

default:"5060"

SIP port (1-65535). Defaults to 5060 if omitted.

string

default:"udp"

Transport protocol: udp, tcp, or tls. Defaults to udp if omitted.

object

Optional SIP authentication credentials

Show Properties

string

SIP authentication username (max 128 characters)

string

SIP authentication password (max 256 characters)

string[]

Preferred audio codecs in priority order (max 20 codecs, each ≤32 characters). When omitted, no codec preference is stored and the carrier’s negotiated default applies.

boolean

default:"true"

Whether the trunk is enabled for outbound calling. Defaults to true if omitted.

number

Maximum concurrent calls on this trunk (1-2000)

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/voice/sip-trunks" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Primary Carrier",
  "host": "trunk.carrier.com",
  "port": 5060,
  "transport": "tls",
  "authentication": {
    "username": "orbit_user",
    "password": "secure_password"
  },
  "codecs": ["OPUS", "PCMU"],
  "enabled": true,
  "maxConcurrent": 50
}'

Node.js

import { Orbit } from '@devotel/orbit-sdk'

const orbit = new Orbit({ apiKey: process.env.ORBIT_API_KEY! })

const trunk = await orbit.voice.sipTrunks.create({
  name: 'Primary Carrier',
  host: 'trunk.carrier.com',
  port: 5060,
  transport: 'tls',
  authentication: {
    username: 'orbit_user',
    password: 'secure_password',
  },
  codecs: ['OPUS', 'PCMU'],
  enabled: true,
  maxConcurrent: 50,
})
console.log(trunk.data.id)

Python

import os, requests
headers = {"X-API-Key": os.environ["ORBIT_API_KEY"], "Content-Type": "application/json"}
r = requests.post("https://api.orbit.devotel.io/api/v1/voice/sip-trunks", headers=headers, json={
  "name": "Primary Carrier",
  "host": "trunk.carrier.com",
  "port": 5060,
  "transport": "tls",
  "authentication": {
    "username": "orbit_user",
    "password": "secure_password"
  },
  "codecs": ["OPUS", "PCMU"],
  "enabled": True,
  "maxConcurrent": 50
})
print(r.json())

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/voice/sip-trunks", bytes.NewBuffer([]byte(`{
  "name": "Primary Carrier",
  "host": "trunk.carrier.com",
  "port": 5060,
  "transport": "tls",
  "authentication": {
    "username": "orbit_user",
    "password": "secure_password"
  },
  "codecs": ["OPUS", "PCMU"],
  "enabled": true,
  "maxConcurrent": 50
}`)))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	http.DefaultClient.Do(req)
}

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/voice/sip-trunks');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, <<<JSON
{
  "name": "Primary Carrier",
  "host": "trunk.carrier.com",
  "port": 5060,
  "transport": "tls",
  "authentication": {
    "username": "orbit_user",
    "password": "secure_password"
  },
  "codecs": ["OPUS", "PCMU"],
  "enabled": true,
  "maxConcurrent": 50
}
JSON);
echo curl_exec($ch);

{
  "data": {
    "id": "trunk_abc123",
    "name": "Primary Carrier",
    "host": "trunk.carrier.com",
    "port": 5060,
    "transport": "tls",
    "authentication": {
      "username": "orbit_user"
    },
    "codecs": ["OPUS", "PCMU"],
    "enabled": true,
    "created_at": "2026-03-08T12:00:00Z"
  },
  "meta": {
    "request_id": "req_trunk_001",
    "timestamp": "2026-03-08T12:00:00Z"
  }
}

List SIP Trunks

GET /api/v1/voice/sip-trunks

Get SIP Trunk

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

Update SIP Trunk

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

Delete SIP Trunk

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

cURL

# List
curl -X GET "https://api.orbit.devotel.io/api/v1/voice/sip-trunks" \
  -H "X-API-Key: dv_live_sk_your_key_here"
# Get
curl -X GET "https://api.orbit.devotel.io/api/v1/voice/sip-trunks/trunk_abc123" \
  -H "X-API-Key: dv_live_sk_your_key_here"
# Update
curl -X PUT "https://api.orbit.devotel.io/api/v1/voice/sip-trunks/trunk_abc123" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Primary Carrier (renamed)" }'
# Delete
curl -X DELETE "https://api.orbit.devotel.io/api/v1/voice/sip-trunks/trunk_abc123" \
  -H "X-API-Key: dv_live_sk_your_key_here"

Node.js

await orbit.voice.sipTrunks.list()
await orbit.voice.sipTrunks.get('trunk_abc123')
await orbit.voice.sipTrunks.update('trunk_abc123', { name: 'Primary Carrier (renamed)' })
await orbit.voice.sipTrunks.delete('trunk_abc123')

Python

import os, requests
h = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
requests.get("https://api.orbit.devotel.io/api/v1/voice/sip-trunks", headers=h)
requests.get("https://api.orbit.devotel.io/api/v1/voice/sip-trunks/trunk_abc123", headers=h)
requests.put("https://api.orbit.devotel.io/api/v1/voice/sip-trunks/trunk_abc123",
             headers={**h, "Content-Type": "application/json"},
             json={"name": "Primary Carrier (renamed)"})
requests.delete("https://api.orbit.devotel.io/api/v1/voice/sip-trunks/trunk_abc123", headers=h)

package main

import (
	"net/http"
	"os"
)

func main() {
	base := "https://api.orbit.devotel.io/api/v1/voice/sip-trunks"
	key := os.Getenv("ORBIT_API_KEY")
	for _, r := range []struct{ m, u string }{{"GET", base}, {"GET", base + "/trunk_abc123"}, {"DELETE", base + "/trunk_abc123"}} {
		req, _ := http.NewRequest(r.m, r.u, nil)
		req.Header.Set("X-API-Key", key)
		http.DefaultClient.Do(req)
	}
}

PHP

<?php
$key = getenv('ORBIT_API_KEY');
$base = 'https://api.orbit.devotel.io/api/v1/voice/sip-trunks';
foreach (['GET' => $base, 'DELETE' => "$base/trunk_abc123"] as $method => $url) {
  $ch = curl_init($url);
  curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => $method,
    CURLOPT_HTTPHEADER => ["X-API-Key: $key"],
  ]);
  echo curl_exec($ch);
}

IVR (Interactive Voice Response)

Build programmable voice menus that route callers through options, collect DTMF input, and transfer to agents or queues.

Create IVR Flow

POST /api/v1/voice/ivr-flows

The IVR flow body is a graph definition, not a flat list of greeting/menu fields. The greeting, per-option prompts, timeouts, and fallbacks are all expressed as nodes and edges inside the required definition object. The API ignores any top-level field other than name, definition, and active.

string

required

IVR flow name (1–200 characters).

object

required

The IVR flow graph, expressed as an XYFlow-style { nodes, edges } object (the same shape the dashboard IVR builder canvas produces). It is structurally validated before persistence — an invalid graph is rejected with 422 IVR_FLOW_GRAPH_INVALID and a list of node/edge errors.Validation rules: exactly one entry node (type ivrStart, or any node with data.isEntry = true); at least one exit node (end, hangup, transfer, voicemail, ringGroup, dialByName, or offerCallback); every edge must reference existing nodes; every node must be reachable from the entry; and every reachable node must have a path to an exit (a loop with no escape is rejected to avoid burning carrier minutes). Limits: 1000 nodes, 2000 edges.

Show definition

object[]

required

Flow nodes.

Show node

string

required

Unique node id (referenced by edges).

string

required

Node type. Entry: ivrStart. Interactive: menu. Terminal/exit: transfer, voicemail, hangup, end, ringGroup, dialByName, offerCallback.

object

Per-node config (camelCase). For a menu node: ttsText (the spoken menu prompt), optional language, timeout (seconds), and menuOptions — an array of { key, label } where key is a DTMF key (0–9, *, #). For a transfer node: transferTo — a PSTN number (E.164) or on-net extension. Per invariant #45, outbound voice must exit via the Devotel softswitch, so a free-form sip:/sips: transferTo is rejected with transfer_external_sip.

object[]

required

Directed edges connecting nodes.

Show edge

string

required

Source node id.

string

required

Target node id.

string

For edges leaving a menu node, the DTMF key this branch is taken on (e.g. "1"). Matched against menuOptions[].key.

string

Optional edge id.

boolean

default:"true"

Whether the flow is active.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/voice/ivr-flows" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Main Menu",
  "active": true,
  "definition": {
    "nodes": [
      { "id": "start", "type": "ivrStart", "data": {} },
      { "id": "menu", "type": "menu", "data": {
          "ttsText": "Welcome to Acme Corp. Press 1 for sales, 2 for support, or 3 to leave a voicemail.",
          "language": "en-US",
          "timeout": 8,
          "menuOptions": [
            { "key": "1", "label": "Sales" },
            { "key": "2", "label": "Support" },
            { "key": "3", "label": "Voicemail" }
          ]
        }
      },
      { "id": "sales", "type": "transfer", "data": { "transferTo": "+14155550101" } },
      { "id": "support", "type": "transfer", "data": { "transferTo": "+14155550102" } },
      { "id": "voicemail", "type": "voicemail", "data": { "greeting": "Please leave a message after the tone." } }
    ],
    "edges": [
      { "id": "e0", "source": "start", "target": "menu" },
      { "id": "e1", "source": "menu", "target": "sales", "sourceHandle": "1" },
      { "id": "e2", "source": "menu", "target": "support", "sourceHandle": "2" },
      { "id": "e3", "source": "menu", "target": "voicemail", "sourceHandle": "3" }
    ]
  }
}'

Node.js

const ivr = await orbit.voice.ivr.create({
  name: 'Main Menu',
  active: true,
  definition: {
    nodes: [
      { id: 'start', type: 'ivrStart', data: {} },
      {
        id: 'menu',
        type: 'menu',
        data: {
          ttsText: 'Welcome to Acme Corp. Press 1 for sales, 2 for support, or 3 to leave a voicemail.',
          language: 'en-US',
          timeout: 8,
          menuOptions: [
            { key: '1', label: 'Sales' },
            { key: '2', label: 'Support' },
            { key: '3', label: 'Voicemail' },
          ],
        },
      },
      { id: 'sales', type: 'transfer', data: { transferTo: '+14155550101' } },
      { id: 'support', type: 'transfer', data: { transferTo: '+14155550102' } },
      { id: 'voicemail', type: 'voicemail', data: { greeting: 'Please leave a message after the tone.' } },
    ],
    edges: [
      { id: 'e0', source: 'start', target: 'menu' },
      { id: 'e1', source: 'menu', target: 'sales', sourceHandle: '1' },
      { id: 'e2', source: 'menu', target: 'support', sourceHandle: '2' },
      { id: 'e3', source: 'menu', target: 'voicemail', sourceHandle: '3' },
    ],
  },
})

Python

import os, requests
headers = {"X-API-Key": os.environ["ORBIT_API_KEY"], "Content-Type": "application/json"}
r = requests.post("https://api.orbit.devotel.io/api/v1/voice/ivr-flows", headers=headers, json={
  "name": "Main Menu",
  "active": True,
  "definition": {
    "nodes": [
      {"id": "start", "type": "ivrStart", "data": {}},
      {"id": "menu", "type": "menu", "data": {
        "ttsText": "Welcome to Acme Corp. Press 1 for sales, 2 for support, or 3 to leave a voicemail.",
        "language": "en-US",
        "timeout": 8,
        "menuOptions": [
          {"key": "1", "label": "Sales"},
          {"key": "2", "label": "Support"},
          {"key": "3", "label": "Voicemail"}
        ]
      }},
      {"id": "sales", "type": "transfer", "data": {"transferTo": "+14155550101"}},
      {"id": "support", "type": "transfer", "data": {"transferTo": "+14155550102"}},
      {"id": "voicemail", "type": "voicemail", "data": {"greeting": "Please leave a message after the tone."}}
    ],
    "edges": [
      {"id": "e0", "source": "start", "target": "menu"},
      {"id": "e1", "source": "menu", "target": "sales", "sourceHandle": "1"},
      {"id": "e2", "source": "menu", "target": "support", "sourceHandle": "2"},
      {"id": "e3", "source": "menu", "target": "voicemail", "sourceHandle": "3"}
    ]
  }
})
print(r.json())

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	body := []byte(`{
  "name": "Main Menu",
  "active": true,
  "definition": {
    "nodes": [
      {"id": "start", "type": "ivrStart", "data": {}},
      {"id": "menu", "type": "menu", "data": {
        "ttsText": "Welcome to Acme Corp. Press 1 for sales.",
        "timeout": 8,
        "menuOptions": [{"key": "1", "label": "Sales"}]
      }},
      {"id": "sales", "type": "transfer", "data": {"transferTo": "+14155550101"}}
    ],
    "edges": [
      {"id": "e0", "source": "start", "target": "menu"},
      {"id": "e1", "source": "menu", "target": "sales", "sourceHandle": "1"}
    ]
  }
}`)
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/voice/ivr-flows", bytes.NewBuffer(body))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	http.DefaultClient.Do(req)
}

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/voice/ivr-flows');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
  'name' => 'Main Menu',
  'active' => true,
  'definition' => [
    'nodes' => [
      ['id' => 'start', 'type' => 'ivrStart', 'data' => (object) []],
      ['id' => 'menu', 'type' => 'menu', 'data' => [
        'ttsText' => 'Welcome to Acme Corp. Press 1 for sales.',
        'timeout' => 8,
        'menuOptions' => [['key' => '1', 'label' => 'Sales']],
      ]],
      ['id' => 'sales', 'type' => 'transfer', 'data' => ['transferTo' => '+14155550101']],
    ],
    'edges' => [
      ['id' => 'e0', 'source' => 'start', 'target' => 'menu'],
      ['id' => 'e1', 'source' => 'menu', 'target' => 'sales', 'sourceHandle' => '1'],
    ],
  ],
]));
echo curl_exec($ch);

{
  "data": {
    "id": "ivr_abc123",
    "name": "Main Menu",
    "status": "active",
    "options_count": 3,
    "created_at": "2026-03-08T12:00:00Z"
  },
  "meta": {
    "request_id": "req_ivr_001",
    "timestamp": "2026-03-08T12:00:00Z"
  }
}

List IVR Flows

GET /api/v1/voice/ivr-flows

Update IVR Flow

PUT /api/v1/voice/ivr-flows/{id}

Delete IVR Flow

DELETE /api/v1/voice/ivr-flows/{id}

cURL

# List
curl -X GET "https://api.orbit.devotel.io/api/v1/voice/ivr-flows" \
  -H "X-API-Key: dv_live_sk_your_key_here"
# Update
curl -X PUT "https://api.orbit.devotel.io/api/v1/voice/ivr-flows/ivr_abc123" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Renamed Menu" }'
# Delete
curl -X DELETE "https://api.orbit.devotel.io/api/v1/voice/ivr-flows/ivr_abc123" \
  -H "X-API-Key: dv_live_sk_your_key_here"

Node.js

await orbit.voice.ivr.list()
await orbit.voice.ivr.update('ivr_abc123', { name: 'Renamed Menu' })
await orbit.voice.ivr.delete('ivr_abc123')

Python

import os, requests
h = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
requests.get("https://api.orbit.devotel.io/api/v1/voice/ivr-flows", headers=h)
requests.put("https://api.orbit.devotel.io/api/v1/voice/ivr-flows/ivr_abc123",
             headers={**h, "Content-Type": "application/json"}, json={"name": "Renamed Menu"})
requests.delete("https://api.orbit.devotel.io/api/v1/voice/ivr-flows/ivr_abc123", headers=h)

package main

import (
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.orbit.devotel.io/api/v1/voice/ivr-flows", nil)
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	http.DefaultClient.Do(req)
}

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/voice/ivr-flows');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['X-API-Key: ' . getenv('ORBIT_API_KEY')]);
echo curl_exec($ch);

Conferences

Host multi-party conference calls with moderation controls, recording, and real-time participant management.

List Conferences

GET /api/v1/voice/conferences Lists conferences for your tenant, paginated by started_at descending.

string

Comma-separated status filter — pending, in-progress, completed, failed, cancelled.

integer

default:"50"

Page size (max 100).

string

Opaque pagination cursor returned in the previous response’s meta.cursor.

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/voice/conferences?status=in-progress&limit=20" \
  -H "X-API-Key: dv_live_sk_your_key_here"

Node.js

const conferences = await orbit.voice.conferences.list({
  status: 'in-progress',
  limit: 20,
})
for (const conf of conferences.data) {
  console.log(conf.id, conf.name, conf.status)
}

Python

import os, requests
headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
r = requests.get("https://api.orbit.devotel.io/api/v1/voice/conferences",
                 headers=headers, params={"status": "in-progress", "limit": 20})
print(r.json())

package main

import (
	"net/http"
	"net/url"
	"os"
)

func main() {
	u, _ := url.Parse("https://api.orbit.devotel.io/api/v1/voice/conferences")
	q := u.Query()
	q.Set("status", "in-progress")
	q.Set("limit", "20")
	u.RawQuery = q.Encode()
	req, _ := http.NewRequest("GET", u.String(), nil)
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	http.DefaultClient.Do(req)
}

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/voice/conferences?status=in-progress&limit=20');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['X-API-Key: ' . getenv('ORBIT_API_KEY')]);
echo curl_exec($ch);

{
  "data": [
    {
      "id": "conf_abc1234567890abcdef1234567890abcd",
      "name": "Q1 Planning Call",
      "status": "in-progress",
      "caller_id": "+18005551234",
      "started_at": "2026-03-08T12:00:00Z",
      "ended_at": null,
      "duration_seconds": null,
      "max_participants": 25,
      "recording_url": null,
      "created_by": "usr_xyz",
      "created_at": "2026-03-08T12:00:00Z"
    }
  ],
  "meta": {
    "request_id": "req_conf_list_001",
    "cursor": null,
    "has_more": false,
    "timestamp": "2026-03-08T12:00:01Z"
  }
}

Get Conference

GET /api/v1/voice/conferences/{id} Returns a single conference with its participants embedded under participants. For rooms with more than 32 legs, paginate via GET /api/v1/voice/conferences/{id}/participants.

cURL

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

Node.js

const conf = await orbit.voice.conferences.get('conf_abc123')
console.log(conf.data.name, conf.data.participants.length)

Python

import os, requests
headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
r = requests.get("https://api.orbit.devotel.io/api/v1/voice/conferences/conf_abc123", headers=headers)
print(r.json())

package main

import (
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("GET",
		"https://api.orbit.devotel.io/api/v1/voice/conferences/conf_abc123", nil)
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	http.DefaultClient.Do(req)
}

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/voice/conferences/conf_abc123');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['X-API-Key: ' . getenv('ORBIT_API_KEY')]);
echo curl_exec($ch);

{
  "data": {
    "id": "conf_abc1234567890abcdef1234567890abcd",
    "name": "Q1 Planning Call",
    "status": "in-progress",
    "caller_id": "+18005551234",
    "started_at": "2026-03-08T12:00:00Z",
    "ended_at": null,
    "duration_seconds": null,
    "max_participants": 25,
    "recording_url": null,
    "participants": [
      {
        "id": "cpart_abc",
        "phone_number": "+14155552671",
        "status": "answered",
        "leg_call_sid": "CA-…",
        "joined_at": "2026-03-08T12:00:14Z",
        "left_at": null,
        "is_host": true
      }
    ]
  },
  "meta": {
    "request_id": "req_conf_get_001",
    "timestamp": "2026-03-08T12:00:15Z"
  }
}

Get Aggregate Metrics

GET /api/v1/voice/conferences/aggregate Returns server-side rollup KPIs over a rolling window (default 30 days). Powers the dashboard’s conference stat strip — avg duration, success rate, peak concurrent participants. Pass window_days to widen or narrow the rollup (max 365).

integer

default:"30"

Window in days the rollup spans (1-365).

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/voice/conferences/aggregate?window_days=7" \
  -H "X-API-Key: dv_live_sk_your_key_here"

Node.js

const metrics = await orbit.voice.conferences.aggregate({ windowDays: 7 })
console.log(
  metrics.data.avg_duration_seconds,
  metrics.data.success_rate,
  metrics.data.peak_concurrent_participants,
)

Python

import os, requests
headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
r = requests.get("https://api.orbit.devotel.io/api/v1/voice/conferences/aggregate",
                 headers=headers, params={"window_days": 7})
print(r.json())

package main

import (
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("GET",
		"https://api.orbit.devotel.io/api/v1/voice/conferences/aggregate?window_days=7", nil)
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	http.DefaultClient.Do(req)
}

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/voice/conferences/aggregate?window_days=7');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['X-API-Key: ' . getenv('ORBIT_API_KEY')]);
echo curl_exec($ch);

{
  "data": {
    "total_count": 142,
    "active_count": 3,
    "avg_duration_seconds": 1820,
    "success_rate": 0.9437,
    "peak_concurrent_participants": 18,
    "total_participants_window": 612,
    "window_days": 7
  },
  "meta": {
    "request_id": "req_conf_agg_001",
    "timestamp": "2026-03-08T12:00:00Z"
  }
}

Create Conference

POST /api/v1/voice/conferences

string

required

Conference name (max 200 chars).

string[]

required

Seed participants to dial when the conference is created. Each entry must be E.164. 0-32 entries (pass an empty array to create an empty conference).

string

E.164 caller-id used for each seed-participant dial. Must be a voice-capable number owned by your organization.

boolean

default:"false"

Record every participant leg on creation. Subject to per-jurisdiction recording consent gates.

integer

default:"8"

Cap on simultaneously-bridged legs (max 32).

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/voice/conferences" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Q1 Planning Call",
  "participants": ["+14155552671", "+14155552672"],
  "from": "+18005551234",
  "record": true,
  "maxParticipants": 25
}'

Node.js

const conf = await orbit.voice.conferences.create({
  name: 'Q1 Planning Call',
  participants: ['+14155552671', '+14155552672'],
  from: '+18005551234',
  record: true,
  maxParticipants: 25,
})
console.log(conf.data.id)

Python

import os, requests
headers = {"X-API-Key": os.environ["ORBIT_API_KEY"], "Content-Type": "application/json"}
r = requests.post("https://api.orbit.devotel.io/api/v1/voice/conferences", headers=headers, json={
  "name": "Q1 Planning Call",
  "participants": ["+14155552671", "+14155552672"],
  "from": "+18005551234",
  "record": True,
  "maxParticipants": 25
})
print(r.json())

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/voice/conferences", bytes.NewBuffer([]byte(`{
  "name": "Q1 Planning Call",
  "participants": ["+14155552671", "+14155552672"],
  "from": "+18005551234",
  "record": true,
  "maxParticipants": 25
}`)))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	http.DefaultClient.Do(req)
}

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/voice/conferences');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
  'name' => 'Q1 Planning Call',
  'participants' => ['+14155552671', '+14155552672'],
  'from' => '+18005551234',
  'record' => true,
  'maxParticipants' => 25,
]));
echo curl_exec($ch);

{
  "data": {
    "id": "conf_abc123",
    "name": "Q1 Planning Call",
    "status": "waiting",
    "pin": "482901",
    "dial_in_number": "+18005559999",
    "max_participants": 25,
    "record": true,
    "created_at": "2026-03-08T12:00:00Z"
  },
  "meta": {
    "request_id": "req_conf_001",
    "timestamp": "2026-03-08T12:00:00Z"
  }
}

Add Participant

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

string

required

E.164 phone number to dial into the conference (e.g. +14155552671)

string

Optional caller ID to present on the dialed leg. Defaults to the conference’s configured outbound number when omitted.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/voice/conferences/conf_abc123/participants" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "phone_number": "+14155552671" }'

Node.js

await orbit.voice.conferences.addParticipant('conf_abc123', {
  phone_number: '+14155552671',
})

Python

import os, requests
headers = {"X-API-Key": os.environ["ORBIT_API_KEY"], "Content-Type": "application/json"}
r = requests.post("https://api.orbit.devotel.io/api/v1/voice/conferences/conf_abc123/participants",
                  headers=headers, json={"phone_number": "+14155552671"})
print(r.json())

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("POST",
		"https://api.orbit.devotel.io/api/v1/voice/conferences/conf_abc123/participants",
		bytes.NewBuffer([]byte(`{"phone_number":"+14155552671"}`)))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	http.DefaultClient.Do(req)
}

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/voice/conferences/conf_abc123/participants');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, '{"phone_number":"+14155552671"}');
echo curl_exec($ch);

Remove Participant

DELETE /api/v1/voice/conferences/{id}/participants/{participantId}

cURL

curl -X DELETE "https://api.orbit.devotel.io/api/v1/voice/conferences/conf_abc123/participants/part_xyz" \
  -H "X-API-Key: dv_live_sk_your_key_here"

Node.js

await orbit.voice.conferences.removeParticipant('conf_abc123', 'part_xyz')

Python

import os, requests
headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
r = requests.delete("https://api.orbit.devotel.io/api/v1/voice/conferences/conf_abc123/participants/part_xyz",
                    headers=headers)
print(r.status_code)

package main

import (
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("DELETE",
		"https://api.orbit.devotel.io/api/v1/voice/conferences/conf_abc123/participants/part_xyz", nil)
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	http.DefaultClient.Do(req)
}

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/voice/conferences/conf_abc123/participants/part_xyz');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'DELETE');
curl_setopt($ch, CURLOPT_HTTPHEADER, ['X-API-Key: ' . getenv('ORBIT_API_KEY')]);
echo curl_exec($ch);

End Conference

POST /api/v1/voice/conferences/{id}/end

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/voice/conferences/conf_abc123/end" \
  -H "X-API-Key: dv_live_sk_your_key_here"

Node.js

await orbit.voice.conferences.end('conf_abc123')

Python

import os, requests
headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
r = requests.post("https://api.orbit.devotel.io/api/v1/voice/conferences/conf_abc123/end", headers=headers)
print(r.json())

package main

import (
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("POST",
		"https://api.orbit.devotel.io/api/v1/voice/conferences/conf_abc123/end", nil)
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	http.DefaultClient.Do(req)
}

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/voice/conferences/conf_abc123/end');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, ['X-API-Key: ' . getenv('ORBIT_API_KEY')]);
echo curl_exec($ch);

Call Forwarding (Find-me / Follow-me)

Per-user call-forwarding rules — where a user’s inbound calls ring. Each user has at most one rule covering the handling mode, an ordered list of destinations, a per-leg ring timeout, an optional active window, and an anonymous-call rejection toggle. Any authenticated user manages their own rule; org owners/admins can also manage rules on behalf of other users in the organization for onboarding and offboarding. mode is one of:

Mode	Behaviour
`none`	Ring the user’s own registered devices only (no forwarding).
`forward_all`	Forward every inbound call to the `destinations`.
`sim_ring`	Ring the user’s devices and the `destinations` simultaneously.
`sequential`	Ring the `destinations` one after another (find-me / follow-me).
`forward_after_timeout`	Ring the user’s devices, then forward to `destinations` after `ring_timeout_sec`.

PSTN forwarding destinations are configuration only. The outbound leg that dials a forwarded pstn number is placed over the Devotel wholesale softswitch — the same termination path as every other outbound call.

Get My Rule

GET /api/v1/voice/call-forwarding Returns the authenticated user’s own rule. When the user has never configured forwarding, a synthetic none rule is returned (this endpoint never 404s).

cURL

curl "https://api.orbit.devotel.io/api/v1/voice/call-forwarding" \
  -H "X-API-Key: dv_live_sk_your_key_here"

Node.js

const rule = await orbit.voice.callForwarding.get()

Python

import os, requests
headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
r = requests.get("https://api.orbit.devotel.io/api/v1/voice/call-forwarding", headers=headers)
print(r.json())

{
  "data": {
    "mode": "sequential",
    "destinations": [
      { "kind": "pstn", "value": "+15551234567", "label": "Mobile" },
      { "kind": "sip", "value": "sip:alex@example.com" }
    ],
    "ring_timeout_sec": 20,
    "active_from": null,
    "active_until": null,
    "note": "Out of office until Monday",
    "reject_anonymous": false
  },
  "meta": {
    "request_id": "req_cf_001",
    "timestamp": "2026-06-28T12:00:00Z"
  }
}

Upsert My Rule

PUT /api/v1/voice/call-forwarding Creates or replaces the authenticated user’s rule (idempotent upsert keyed on the user).

string

required

One of none, forward_all, sim_ring, sequential, forward_after_timeout.

object[]

Ordered forwarding targets (max 5). Each entry is { kind, value, label? }. kind is pstn (the value must be an E.164 number, for example +15551234567) or sip (the value must be a sip:-prefixed URI). A malformed destination returns 400. Defaults to an empty array.

integer

Seconds to ring before the rule falls through to the next leg or voicemail (5–120). Defaults to 20.

string | null

ISO-8601 timestamp the rule starts applying. null or omitted means always-on.

string | null

ISO-8601 timestamp the rule stops applying. null or omitted means always-on.

string | null

Optional free-text note (max 280 characters).

boolean

When true, inbound legs with a withheld/anonymous caller-id are declined before any fan-out. Defaults to false.

cURL

curl -X PUT "https://api.orbit.devotel.io/api/v1/voice/call-forwarding" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "mode": "sequential",
  "destinations": [
    { "kind": "pstn", "value": "+15551234567", "label": "Mobile" },
    { "kind": "sip", "value": "sip:alex@example.com" }
  ],
  "ring_timeout_sec": 20
}'

Node.js

const rule = await orbit.voice.callForwarding.set({
  mode: 'sequential',
  destinations: [
    { kind: 'pstn', value: '+15551234567', label: 'Mobile' },
    { kind: 'sip', value: 'sip:alex@example.com' },
  ],
  ring_timeout_sec: 20,
})

Python

import os, requests
headers = {"X-API-Key": os.environ["ORBIT_API_KEY"], "Content-Type": "application/json"}
r = requests.put("https://api.orbit.devotel.io/api/v1/voice/call-forwarding", headers=headers, json={
  "mode": "sequential",
  "destinations": [
    {"kind": "pstn", "value": "+15551234567", "label": "Mobile"},
    {"kind": "sip", "value": "sip:alex@example.com"}
  ],
  "ring_timeout_sec": 20
})
print(r.json())

{
  "data": {
    "mode": "sequential",
    "destinations": [
      { "kind": "pstn", "value": "+15551234567", "label": "Mobile" },
      { "kind": "sip", "value": "sip:alex@example.com" }
    ],
    "ring_timeout_sec": 20,
    "active_from": null,
    "active_until": null,
    "note": null,
    "reject_anonymous": false
  },
  "meta": {
    "request_id": "req_cf_002",
    "timestamp": "2026-06-28T12:00:00Z"
  }
}

Clear My Rule

DELETE /api/v1/voice/call-forwarding Reverts the authenticated user’s rule back to none in one shot — clears destinations, active window, note, and anonymous-call rejection. Returns 204 No Content.

List Org Rules (admin)

GET /api/v1/voice/call-forwarding/users Org owner/admin only. Returns every configured per-user rule in the organization, each annotated with the user’s name, email, and last-updated timestamp. GET /api/v1/voice/call-forwarding/users/{userId} PUT /api/v1/voice/call-forwarding/users/{userId} DELETE /api/v1/voice/call-forwarding/users/{userId} Org owner/admin only. Read, upsert (same body as the self-service PUT above), or clear the rule for another user in your organization. The target user must belong to your organization, otherwise the request returns 404.

{
  "data": {
    "users": [
      {
        "user_id": "usr_abc123",
        "user_name": "Alex Rivera",
        "user_email": "alex@example.com",
        "updated_at": "2026-06-27T09:30:00Z",
        "mode": "forward_after_timeout",
        "destinations": [{ "kind": "pstn", "value": "+15551234567" }],
        "ring_timeout_sec": 25,
        "active_from": null,
        "active_until": null,
        "note": null,
        "reject_anonymous": true
      }
    ]
  },
  "meta": {
    "request_id": "req_cf_003",
    "timestamp": "2026-06-28T12:00:00Z"
  }
}

Voicemail

Manage voicemail boxes for receiving and transcribing voice messages when calls go unanswered.

Create Voicemail Box

POST /api/v1/voice/voicemail-boxes Creates a department voicemail box scoped to your organization. A box is a shared mailbox (for example sales or support): voicemails captured against a box-bound number are visible to every member you list, and to no one else.

string

required

Slug-shaped identifier, unique within your organization. Lowercase a-z, digits, hyphen or underscore; the first character must be a letter or digit. Max 64 characters (for example sales, support-eu).

string

required

Human-readable display label shown in the dashboard (1–120 characters).

string[]

User ids subscribed to this box (max 50). Every id must belong to your organization, otherwise the request returns 422. Omit to create an empty roster you can populate later with PUT.

integer | null

Voicemail retention window in days (1–2555). Set to null or omit to inherit your organization’s default retention.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/voice/voicemail-boxes" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "support",
  "label": "Support Team",
  "members": ["usr_abc123", "usr_def456"],
  "retention_days": 90
}'

Node.js

const box = await orbit.voice.voicemailBoxes.create({
  name: 'support',
  label: 'Support Team',
  members: ['usr_abc123', 'usr_def456'],
  retention_days: 90,
})

Python

import os, requests
headers = {"X-API-Key": os.environ["ORBIT_API_KEY"], "Content-Type": "application/json"}
r = requests.post("https://api.orbit.devotel.io/api/v1/voice/voicemail-boxes", headers=headers, json={
  "name": "support",
  "label": "Support Team",
  "members": ["usr_abc123", "usr_def456"],
  "retention_days": 90
})
print(r.json())

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/voice/voicemail-boxes", bytes.NewBuffer([]byte(`{
  "name": "support",
  "label": "Support Team",
  "members": ["usr_abc123", "usr_def456"],
  "retention_days": 90
}`)))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	http.DefaultClient.Do(req)
}

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/voice/voicemail-boxes');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
  'name' => 'support',
  'label' => 'Support Team',
  'members' => ['usr_abc123', 'usr_def456'],
  'retention_days' => 90,
]));
echo curl_exec($ch);

{
  "data": {
    "id": "vmbox_abc123",
    "organization_id": "org_acme",
    "name": "support",
    "label": "Support Team",
    "members": ["usr_abc123", "usr_def456"],
    "inbound_route_id": null,
    "retention_days": 90,
    "created_at": "2026-03-08T12:00:00Z",
    "updated_at": "2026-03-08T12:00:00Z"
  },
  "meta": {
    "request_id": "req_vmail_001",
    "timestamp": "2026-03-08T12:00:00Z"
  }
}

List Voicemail Messages

GET /api/v1/voice/voicemails Retrieve voicemail messages across the org with transcriptions, with cursor pagination and filters by direction, status, and unread state. GET /api/v1/voice/voicemails/{id} Get a single voicemail message including transcription and recording URL. PATCH /api/v1/voice/voicemails/{id}/read Mark a voicemail as read. DELETE /api/v1/voice/voicemails/{id} Permanently delete a voicemail message.

cURL

# List
curl -X GET "https://api.orbit.devotel.io/api/v1/voice/voicemails?status=unread&limit=20" \
  -H "X-API-Key: dv_live_sk_your_key_here"
# Get
curl -X GET "https://api.orbit.devotel.io/api/v1/voice/voicemails/vmsg_001" \
  -H "X-API-Key: dv_live_sk_your_key_here"
# Mark read
curl -X PATCH "https://api.orbit.devotel.io/api/v1/voice/voicemails/vmsg_001/read" \
  -H "X-API-Key: dv_live_sk_your_key_here"
# Delete
curl -X DELETE "https://api.orbit.devotel.io/api/v1/voice/voicemails/vmsg_001" \
  -H "X-API-Key: dv_live_sk_your_key_here"

Node.js

await orbit.voice.voicemails.list({ status: 'unread', limit: 20 })
await orbit.voice.voicemails.get('vmsg_001')
await orbit.voice.voicemails.markRead('vmsg_001')
await orbit.voice.voicemails.delete('vmsg_001')

Python

import os, requests
h = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
requests.get("https://api.orbit.devotel.io/api/v1/voice/voicemails",
             headers=h, params={"status": "unread", "limit": 20})
requests.get("https://api.orbit.devotel.io/api/v1/voice/voicemails/vmsg_001", headers=h)
requests.patch("https://api.orbit.devotel.io/api/v1/voice/voicemails/vmsg_001/read", headers=h)
requests.delete("https://api.orbit.devotel.io/api/v1/voice/voicemails/vmsg_001", headers=h)

package main

import (
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.orbit.devotel.io/api/v1/voice/voicemails?status=unread&limit=20", nil)
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	http.DefaultClient.Do(req)
}

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/voice/voicemails?status=unread&limit=20');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['X-API-Key: ' . getenv('ORBIT_API_KEY')]);
echo curl_exec($ch);

{
  "data": [
    {
      "id": "vmsg_001",
      "voicemail_id": "vmail_abc123",
      "caller": "+14155552671",
      "duration_seconds": 35,
      "transcription": "Hi, this is Jane. I wanted to follow up on my order. Please call me back.",
      "recording_url": "https://storage.devotel.io/voicemail/vmsg_001.wav",
      "listened": false,
      "created_at": "2026-03-08T14:30:00Z"
    }
  ],
  "meta": {
    "request_id": "req_vmsg_001",
    "timestamp": "2026-03-08T15:00:00Z",
    "pagination": {
      "cursor": "cur_vmsg_abc",
      "has_more": false,
      "total": 1
    }
  }
}

Conference Operations (advanced)

Beyond Add Participant / Remove Participant, the conference API exposes a complete moderation surface.

Mute / Unmute a Participant

POST /api/v1/voice/conferences/{id}/participants/{participantId}/mute POST /api/v1/voice/conferences/{id}/participants/{participantId}/unmute

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/voice/conferences/conf_abc123/participants/part_xyz/mute" \
  -H "X-API-Key: dv_live_sk_your_key_here"

Node.js

await orbit.voice.conferences.muteParticipant('conf_abc123', 'part_xyz')
await orbit.voice.conferences.unmuteParticipant('conf_abc123', 'part_xyz')

Python

import os, requests
headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
r = requests.post(
  "https://api.orbit.devotel.io/api/v1/voice/conferences/conf_abc123/participants/part_xyz/mute",
  headers=headers)
print(r.json())

package main

import (
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("POST",
		"https://api.orbit.devotel.io/api/v1/voice/conferences/conf_abc123/participants/part_xyz/mute", nil)
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	http.DefaultClient.Do(req)
}

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/voice/conferences/conf_abc123/participants/part_xyz/mute');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, ['X-API-Key: ' . getenv('ORBIT_API_KEY')]);
echo curl_exec($ch);

Mute / Unmute Everyone

POST /api/v1/voice/conferences/{id}/mute-all POST /api/v1/voice/conferences/{id}/unmute-all Useful for “all-hands” conferences where the moderator wants to control the floor. Already-muted participants keep their state.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/voice/conferences/conf_abc123/mute-all" \
  -H "X-API-Key: dv_live_sk_your_key_here"

Node.js

await orbit.voice.conferences.muteAll('conf_abc123')
await orbit.voice.conferences.unmuteAll('conf_abc123')

Python

import os, requests
headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
r = requests.post("https://api.orbit.devotel.io/api/v1/voice/conferences/conf_abc123/mute-all", headers=headers)
print(r.json())

package main

import (
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("POST",
		"https://api.orbit.devotel.io/api/v1/voice/conferences/conf_abc123/mute-all", nil)
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	http.DefaultClient.Do(req)
}

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/voice/conferences/conf_abc123/mute-all');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, ['X-API-Key: ' . getenv('ORBIT_API_KEY')]);
echo curl_exec($ch);

Hold / Unhold a Participant

POST /api/v1/voice/conferences/{id}/participants/{participantId}/hold POST /api/v1/voice/conferences/{id}/participants/{participantId}/unhold

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/voice/conferences/conf_abc123/participants/part_xyz/hold" \
  -H "X-API-Key: dv_live_sk_your_key_here"

Node.js

await orbit.voice.conferences.holdParticipant('conf_abc123', 'part_xyz')
await orbit.voice.conferences.unholdParticipant('conf_abc123', 'part_xyz')

Python

import os, requests
headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
r = requests.post(
  "https://api.orbit.devotel.io/api/v1/voice/conferences/conf_abc123/participants/part_xyz/hold",
  headers=headers)
print(r.json())

package main

import (
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("POST",
		"https://api.orbit.devotel.io/api/v1/voice/conferences/conf_abc123/participants/part_xyz/hold", nil)
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	http.DefaultClient.Do(req)
}

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/voice/conferences/conf_abc123/participants/part_xyz/hold');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, ['X-API-Key: ' . getenv('ORBIT_API_KEY')]);
echo curl_exec($ch);

Lock / Unlock Conference

POST /api/v1/voice/conferences/{id}/lock POST /api/v1/voice/conferences/{id}/unlock When locked, no new participants can join — existing participants stay connected. Use to seal a conference for a confidential discussion.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/voice/conferences/conf_abc123/lock" \
  -H "X-API-Key: dv_live_sk_your_key_here"

Node.js

await orbit.voice.conferences.lock('conf_abc123')
await orbit.voice.conferences.unlock('conf_abc123')

Python

import os, requests
headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
r = requests.post("https://api.orbit.devotel.io/api/v1/voice/conferences/conf_abc123/lock", headers=headers)
print(r.json())

package main

import (
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("POST",
		"https://api.orbit.devotel.io/api/v1/voice/conferences/conf_abc123/lock", nil)
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	http.DefaultClient.Do(req)
}

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/voice/conferences/conf_abc123/lock');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, ['X-API-Key: ' . getenv('ORBIT_API_KEY')]);
echo curl_exec($ch);

End / Delete a Conference

POST /api/v1/voice/conferences/{id}/end End the active conference and disconnect every participant gracefully. The conference row is retained for analytics. DELETE /api/v1/voice/conferences/{id} Hard-delete the conference row (only allowed when status is ended).

cURL

curl -X DELETE "https://api.orbit.devotel.io/api/v1/voice/conferences/conf_abc123" \
  -H "X-API-Key: dv_live_sk_your_key_here"

Node.js

await orbit.voice.conferences.end('conf_abc123')
await orbit.voice.conferences.delete('conf_abc123')

Python

import os, requests
headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
requests.delete("https://api.orbit.devotel.io/api/v1/voice/conferences/conf_abc123", headers=headers)

package main

import (
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("DELETE",
		"https://api.orbit.devotel.io/api/v1/voice/conferences/conf_abc123", nil)
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	http.DefaultClient.Do(req)
}

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/voice/conferences/conf_abc123');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'DELETE');
curl_setopt($ch, CURLOPT_HTTPHEADER, ['X-API-Key: ' . getenv('ORBIT_API_KEY')]);
echo curl_exec($ch);

Call Queues

Queue inbound calls by skill / priority and route them to the next available agent. Pairs with the AI agent layer for hybrid human + AI front-desk experiences.

Create a Queue

POST /api/v1/voice/queues

string

required

Queue name (visible to supervisors in the wallboard).

string

default:"longest-idle"

Strategy used to pick an agent when several match a queued call. One of: longest-idle (oldest idle agent wins — default), least-busy (lowest occupancy), skill-weighted (highest weighted-proficiency score), round-robin (true rotation by last-dispatched), fixed-order (linear hunt by agent dispatch order), percent-allocation (weighted random by per-agent allocation percentage), last-agent-preferred (route back to the agent who last handled this caller, falling back to longest-idle).

integer

default:"300"

Maximum hold time (seconds, 30–3600) before the call falls through to overflowAction.

integer

Per-queue maximum hold-time ceiling (seconds, 60–3600). When a caller waits on hold longer than this, the queue raises a supervisor hold-time alert and starts the overflow-escalation path. Omitted leaves the ceiling unset (no hold-time escalation — the default).

string

default:"voicemail"

Action when max-wait expires. One of: voicemail, callback, hangup, overflow_queue. When set to overflow_queue, overflowQueueId is required.

string

Target queue id (same tenant) calls overflow into. Required when overflowAction is overflow_queue; must be omitted otherwise.

string

Public URL of an MP3 played while waiting.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/voice/queues" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Support Tier 1",
  "routingStrategy": "longest-idle",
  "maxWaitSeconds": 240,
  "overflowAction": "voicemail",
  "holdMusicUrl": "https://cdn.example.com/hold-music.mp3"
}'

Node.js

const q = await orbit.voice.queues.create({
  name: 'Support Tier 1',
  routingStrategy: 'longest-idle',
  maxWaitSeconds: 240,
  overflowAction: 'voicemail',
  holdMusicUrl: 'https://cdn.example.com/hold-music.mp3',
})

Python

import os, requests
headers = {"X-API-Key": os.environ["ORBIT_API_KEY"], "Content-Type": "application/json"}
r = requests.post("https://api.orbit.devotel.io/api/v1/voice/queues", headers=headers, json={
  "name": "Support Tier 1",
  "routingStrategy": "longest-idle",
  "maxWaitSeconds": 240,
  "overflowAction": "voicemail",
  "holdMusicUrl": "https://cdn.example.com/hold-music.mp3"
})
print(r.json())

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/voice/queues", bytes.NewBuffer([]byte(`{
  "name": "Support Tier 1",
  "routingStrategy": "longest-idle",
  "maxWaitSeconds": 240,
  "overflowAction": "voicemail"
}`)))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	http.DefaultClient.Do(req)
}

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/voice/queues');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
  'name' => 'Support Tier 1', 'routingStrategy' => 'longest-idle',
  'maxWaitSeconds' => 240, 'overflowAction' => 'voicemail',
]));
echo curl_exec($ch);

List / Update / Delete

GET /api/v1/voice/queues PUT /api/v1/voice/queues/{id} DELETE /api/v1/voice/queues/{id}

cURL

# List
curl -X GET "https://api.orbit.devotel.io/api/v1/voice/queues" \
  -H "X-API-Key: dv_live_sk_your_key_here"
# Update
curl -X PUT "https://api.orbit.devotel.io/api/v1/voice/queues/queue_abc" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "maxWaitSeconds": 180 }'
# Delete
curl -X DELETE "https://api.orbit.devotel.io/api/v1/voice/queues/queue_abc" \
  -H "X-API-Key: dv_live_sk_your_key_here"

Node.js

await orbit.voice.queues.list()
await orbit.voice.queues.update('queue_abc', { maxWaitSeconds: 180 })
await orbit.voice.queues.delete('queue_abc')

Python

import os, requests
h = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
requests.get("https://api.orbit.devotel.io/api/v1/voice/queues", headers=h)
requests.put("https://api.orbit.devotel.io/api/v1/voice/queues/queue_abc",
             headers={**h, "Content-Type": "application/json"}, json={"maxWaitSeconds": 180})
requests.delete("https://api.orbit.devotel.io/api/v1/voice/queues/queue_abc", headers=h)

package main

import (
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.orbit.devotel.io/api/v1/voice/queues", nil)
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	http.DefaultClient.Do(req)
}

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/voice/queues');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['X-API-Key: ' . getenv('ORBIT_API_KEY')]);
echo curl_exec($ch);

Enqueue a Call

POST /api/v1/voice/queues/{id}/enqueue

string

required

Call control ID of the live call to add to the queue.

string

required

Caller’s number in E.164 format.

integer

default:"10"

Routing priority from 0 to 99. Lower wins — 0 is the highest priority and routes ahead of everyone else. Use for VIP customers and escalations.

string[]

Skill tags the answering agent must have. Only agents with every listed skill are eligible to take the call. Defaults to no skill requirement.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/voice/queues/queue_abc/enqueue" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "callControlId": "cc_abc123", "callerNumber": "+14155550123", "priority": 5, "requiredSkills": ["billing"] }'

Node.js

await orbit.voice.queues.enqueue('queue_abc', { callControlId: 'cc_abc123', callerNumber: '+14155550123', priority: 5, requiredSkills: ['billing'] })

Python

import os, requests
headers = {"X-API-Key": os.environ["ORBIT_API_KEY"], "Content-Type": "application/json"}
r = requests.post("https://api.orbit.devotel.io/api/v1/voice/queues/queue_abc/enqueue",
                  headers=headers, json={"callControlId": "cc_abc123", "callerNumber": "+14155550123", "priority": 5, "requiredSkills": ["billing"]})
print(r.json())

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("POST",
		"https://api.orbit.devotel.io/api/v1/voice/queues/queue_abc/enqueue",
		bytes.NewBuffer([]byte(`{"callControlId":"cc_abc123","callerNumber":"+14155550123","priority":5,"requiredSkills":["billing"]}`)))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	http.DefaultClient.Do(req)
}

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/voice/queues/queue_abc/enqueue');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, '{"callControlId":"cc_abc123","callerNumber":"+14155550123","priority":5,"requiredSkills":["billing"]}');
echo curl_exec($ch);

Queue Stats

GET /api/v1/voice/queues/{id}/stats Returns live counts: waiting, connected, abandoned_24h, avg_wait_seconds_24h, plus per-agent presence.

cURL

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

Node.js

const stats = await orbit.voice.queues.stats('queue_abc')
console.log(stats.data.waiting)

Python

import os, requests
headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
r = requests.get("https://api.orbit.devotel.io/api/v1/voice/queues/queue_abc/stats", headers=headers)
print(r.json())

package main

import (
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("GET",
		"https://api.orbit.devotel.io/api/v1/voice/queues/queue_abc/stats", nil)
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	http.DefaultClient.Do(req)
}

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/voice/queues/queue_abc/stats');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['X-API-Key: ' . getenv('ORBIT_API_KEY')]);
echo curl_exec($ch);

Set Agent Status

POST /api/v1/voice/agents/{id}/status

string

required

Agent presence: available, busy, away, offline.

string

Required when status is away (for example lunch, break, training). Lowercase ASCII letters, digits, _ or -, up to 64 characters.

Drives queue routing — available agents are eligible for the next call.

cURL

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

Node.js

await orbit.voice.agents.setStatus('agt_jane', { status: 'available' })

Python

import os, requests
headers = {"X-API-Key": os.environ["ORBIT_API_KEY"], "Content-Type": "application/json"}
r = requests.post("https://api.orbit.devotel.io/api/v1/voice/agents/agt_jane/status",
                  headers=headers, json={"status": "available"})
print(r.json())

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("POST",
		"https://api.orbit.devotel.io/api/v1/voice/agents/agt_jane/status",
		bytes.NewBuffer([]byte(`{"status":"available"}`)))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	http.DefaultClient.Do(req)
}

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/voice/agents/agt_jane/status');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, '{"status":"available"}');
echo curl_exec($ch);

Ring Groups

A ring group rings multiple destinations (SIP usernames, PSTN numbers, or other ring groups) on a single inbound number. Use for “ring all sales reps until someone answers” patterns, plus hunt-group walks and nested team-of-teams structures.

Create / List / Get / Delete

POST /api/v1/voice/ring-groups

string

required

Unique ring group name within the organization (max 100 chars).

string

default:"simultaneous"

Ring strategy. Implemented today: simultaneous, sequential, round_robin, longest_idle, fewest_calls. See the Strategies section below for how each one selects members.

object[]

required

Array of { kind, value } entries. kind is one of "sip_username" (references a row in tenant_sip_credentials), "pstn" (an E.164-ish digits-only number, ^\+?[0-9]{7,20}$), or "ring_group" (id of another ring group in the same org — cycle-checked at save time). Min 1, max 100 members per group.

integer

default:"30"

Per-step ring timeout in seconds (5-300). For simultaneous it’s the overall ring duration before the actionHook fires; for sequential it’s the per-username ring duration.

GET /api/v1/voice/ring-groups GET /api/v1/voice/ring-groups/{id} DELETE /api/v1/voice/ring-groups/{id}

Strategies

simultaneous — fork the INVITE to every leaf in parallel; first answer wins. PSTN leaves are dialed in parallel with SIP usernames.
sequential — walk SIP usernames in array order, advancing on no-answer via /jambonz/lookup-next. PSTN leaves are appended after the SIP walk so “try Alice’s desk, then Bob’s desk, then ring my mobile” works without a parallel fork.
round_robin — Redis-pinned cursor at {devotel}:ringgroup:rr:<groupId> rotates picks across members one at a time. One target per call so per-call billing aligns with the answerOnBridge contract.
longest_idle — Redis hash at {devotel}:ringgroup:li:<groupId> records per-member last-selected timestamp. Picker chooses the longest-idle member; never-selected members beat any timestamped member; alphabetical tie-break gives deterministic convergence across replicas.
fewest_calls — Redis hash at {devotel}:ringgroup:fc:<groupId> tracks per-member calls handled. Picker chooses the member with the fewest handled calls; never-selected members count as zero and beat any member with a positive count; alphabetical tie-break gives deterministic convergence across replicas. The count is incremented at dial-time when the dial verb is emitted to the picked member. One target per call so per-call billing aligns with the answerOnBridge contract.

Wiring a ring group to an inbound number: save the route via PUT /api/v1/numbers/{phoneNumber}/routing with type: "ring_group", config: {}, and ring_group_id: "<group_id>" — the group identity lives on the route row, not in config.

cURL

# Create
curl -X POST "https://api.orbit.devotel.io/api/v1/voice/ring-groups" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Sales All-Rings",
  "strategy": "simultaneous",
  "ringTimeoutSec": 30,
  "members": [
    { "kind": "sip_username", "value": "alice" },
    { "kind": "sip_username", "value": "bob" },
    { "kind": "pstn",         "value": "+14155557890" }
  ]
}'
# List / Get / Delete
curl -X GET "https://api.orbit.devotel.io/api/v1/voice/ring-groups" -H "X-API-Key: $K"
curl -X GET "https://api.orbit.devotel.io/api/v1/voice/ring-groups/rg_abc" -H "X-API-Key: $K"
curl -X DELETE "https://api.orbit.devotel.io/api/v1/voice/ring-groups/rg_abc" -H "X-API-Key: $K"

Node.js

await orbit.voice.ringGroups.create({
  name: 'Sales All-Rings',
  strategy: 'simultaneous',
  ringTimeoutSec: 30,
  members: [
    { kind: 'sip_username', value: 'alice' },
    { kind: 'sip_username', value: 'bob' },
    { kind: 'pstn',         value: '+14155557890' },
  ],
})
await orbit.voice.ringGroups.list()
await orbit.voice.ringGroups.get('rg_abc')
await orbit.voice.ringGroups.delete('rg_abc')

Python

import os, requests
headers = {"X-API-Key": os.environ["ORBIT_API_KEY"], "Content-Type": "application/json"}
r = requests.post("https://api.orbit.devotel.io/api/v1/voice/ring-groups", headers=headers, json={
  "name": "Sales All-Rings",
  "strategy": "simultaneous",
  "ringTimeoutSec": 30,
  "members": [
    {"kind": "sip_username", "value": "alice"},
    {"kind": "pstn",         "value": "+14155557890"}
  ]
})
print(r.json())

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	body := []byte(`{
  "name": "Sales All-Rings",
  "strategy": "simultaneous",
  "ringTimeoutSec": 30,
  "members": [{"kind":"sip_username","value":"alice"}]
}`)
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/voice/ring-groups", bytes.NewBuffer(body))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	http.DefaultClient.Do(req)
}

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/voice/ring-groups');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
  'name' => 'Sales All-Rings',
  'strategy' => 'simultaneous',
  'ringTimeoutSec' => 30,
  'members' => [['kind' => 'sip_username', 'value' => 'alice']],
]));
echo curl_exec($ch);

Paging Groups

A paging group broadcasts a one-way (or two-way) announcement to a set of deskphones and softphone users at once — the “page the warehouse” / overhead-intercom pattern that replaces a legacy PBX paging system. Members are resolved at page-time into two delivery channels: registered SIP deskphones (rung directly via an internal user-to-user INVITE) and in-app softphone users.

Paging legs are internal user: targets on Orbit’s own SIP edge — they never traverse a carrier trunk or reach the PSTN.

Create / List / Get / Update / Delete

POST /api/v1/voice/paging-groups

string

required

Unique paging group name within the organization (max 100 chars). A duplicate name returns 409.

string

Optional human-readable description (max 500 chars).

string

default:"simplex"

Page mode. One of simplex (one-way announcement) or duplex (two-way intercom). Until the live two-way conference bridge lands, a duplex page still rings every deskphone and plays the announcement (a functional one-way notification), so no member is dropped.

object[]

default:"[]"

Array of { kind, value } entries. kind is one of "sip_username" (a registered softphone/deskphone in tenant_sip_credentials) or "user_id" (an organization user whose softphone receives an in-app page). Max 200 members per group.

integer

default:"30"

Maximum announcement duration in seconds (5-300).

string

Optional URL of an audio file played as an attention chime before the announcement (max 2048 chars).

GET /api/v1/voice/paging-groups — cursor-paginated list (?cursor=&limit= up to 100). Each item carries memberCount. GET /api/v1/voice/paging-groups/{id} PATCH /api/v1/voice/paging-groups/{id} — partial update; any subset of the create fields. DELETE /api/v1/voice/paging-groups/{id} — hard delete (204; 404 if unknown).

Trigger a Page

POST /api/v1/voice/paging-groups/{id}/page

string

Optional one-shot message read out via TTS instead of the pager’s live mic (1-500 chars).

string

Override the group’s configured mode for this page only (simplex or duplex) — e.g. force simplex on a duplex group for an emergency announcement.

The response reports both delivery channels so the UI can render “Paged N softphone users + M deskphones (K legs failed)“:

{
  "pagingGroupId": "pagingGroup_abc",
  "name": "Warehouse Floor",
  "mode": "simplex",
  "maxAnnouncementSeconds": 30,
  "recipientsResolved": 3,
  "recipientsNotified": 3,
  "sipDeskphonesTargeted": 8,
  "sipDeskphonesPaged": 7,
  "sipDeskphonesFailed": 1
}

cURL

# Create
curl -X POST "https://api.orbit.devotel.io/api/v1/voice/paging-groups" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Warehouse Floor",
  "mode": "simplex",
  "maxAnnouncementSeconds": 30,
  "members": [
    { "kind": "sip_username", "value": "dock-phone-1" },
    { "kind": "user_id",      "value": "user_abc" }
  ]
}'
# List / Get / Update / Delete
curl -X GET "https://api.orbit.devotel.io/api/v1/voice/paging-groups" -H "X-API-Key: $K"
curl -X GET "https://api.orbit.devotel.io/api/v1/voice/paging-groups/pagingGroup_abc" -H "X-API-Key: $K"
curl -X PATCH "https://api.orbit.devotel.io/api/v1/voice/paging-groups/pagingGroup_abc" \
  -H "X-API-Key: $K" -H "Content-Type: application/json" \
  -d '{ "name": "Warehouse Floor (Day Shift)" }'
curl -X DELETE "https://api.orbit.devotel.io/api/v1/voice/paging-groups/pagingGroup_abc" -H "X-API-Key: $K"
# Trigger a page
curl -X POST "https://api.orbit.devotel.io/api/v1/voice/paging-groups/pagingGroup_abc/page" \
  -H "X-API-Key: $K" -H "Content-Type: application/json" \
  -d '{ "message": "Shipment arriving at dock 3" }'

Node.js

await orbit.voice.pagingGroups.create({
  name: 'Warehouse Floor',
  mode: 'simplex',
  maxAnnouncementSeconds: 30,
  members: [
    { kind: 'sip_username', value: 'dock-phone-1' },
    { kind: 'user_id',      value: 'user_abc' },
  ],
})
await orbit.voice.pagingGroups.list()
await orbit.voice.pagingGroups.get('pagingGroup_abc')
await orbit.voice.pagingGroups.update('pagingGroup_abc', { name: 'Warehouse Floor (Day Shift)' })
await orbit.voice.pagingGroups.delete('pagingGroup_abc')
await orbit.voice.pagingGroups.page('pagingGroup_abc', { message: 'Shipment arriving at dock 3' })

Python

import os, requests
headers = {"X-API-Key": os.environ["ORBIT_API_KEY"], "Content-Type": "application/json"}
r = requests.post("https://api.orbit.devotel.io/api/v1/voice/paging-groups", headers=headers, json={
  "name": "Warehouse Floor",
  "mode": "simplex",
  "maxAnnouncementSeconds": 30,
  "members": [
    {"kind": "sip_username", "value": "dock-phone-1"},
    {"kind": "user_id",      "value": "user_abc"}
  ]
})
print(r.json())
# Trigger a page
requests.post(
  "https://api.orbit.devotel.io/api/v1/voice/paging-groups/pagingGroup_abc/page",
  headers=headers, json={"message": "Shipment arriving at dock 3"})

Shared Lines

Shared Line Appearance (SLA) mirrors one “line” (a primary extension) onto several physical phones — the receptionist / exec-assistant pattern where an inbound call rings every member and any member can answer or grab a parked call. This endpoint family manages the line configuration and member roster; the inbound call-fork that makes a call ring multiple phones is handled by the voice call plane.

Shared lines are inbound fork-and-park only — no outbound termination is wired here.

Create / List / Get / Update / Delete

POST /api/v1/voice/shared-lines

string

required

Unique shared line name within the organization (max 100 chars). A duplicate name or extension returns 409.

string

Optional description (max 500 chars).

string

required

The primary extension mirrored onto the member phones (max 32 chars). Unique within the organization.

string

default:"active"

Line status. One of active or inactive.

GET /api/v1/voice/shared-lines — cursor-paginated list (?cursor=&limit= up to 100). Each item carries memberCount. GET /api/v1/voice/shared-lines/{id} — returns the line plus its members[] ordered by sortOrder then createdAt. PATCH /api/v1/voice/shared-lines/{id} — partial update. DELETE /api/v1/voice/shared-lines/{id} — hard delete; member rows cascade.

Members

POST /api/v1/voice/shared-lines/{id}/members

string

default:"sip_extension"

One of sip_extension (a registered phone in tenant_sip_credentials, existence-checked org-scoped at add — an unknown username returns 422) or user_id (an organization user whose softphone is resolved by the fork layer at call-time).

string

required

The SIP username or user id, depending on memberKind (max 128 chars). Adding the same value twice returns 409.

boolean

default:"true"

Whether this member may grab (pick up) a call already ringing/parked on the line.

integer

Optional button position (0-999). When omitted, the next sequential position is assigned automatically.

A line is capped at 50 members; adding past the cap returns 409. DELETE /api/v1/voice/shared-lines/{id}/members/{memberId} — remove a member (204; 404 if unknown).

cURL

# Create a line
curl -X POST "https://api.orbit.devotel.io/api/v1/voice/shared-lines" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Reception",
  "primaryExtension": "100",
  "status": "active"
}'
# List / Get / Update / Delete
curl -X GET "https://api.orbit.devotel.io/api/v1/voice/shared-lines" -H "X-API-Key: $K"
curl -X GET "https://api.orbit.devotel.io/api/v1/voice/shared-lines/sharedLine_abc" -H "X-API-Key: $K"
curl -X PATCH "https://api.orbit.devotel.io/api/v1/voice/shared-lines/sharedLine_abc" \
  -H "X-API-Key: $K" -H "Content-Type: application/json" -d '{ "status": "inactive" }'
curl -X DELETE "https://api.orbit.devotel.io/api/v1/voice/shared-lines/sharedLine_abc" -H "X-API-Key: $K"
# Add / remove a member
curl -X POST "https://api.orbit.devotel.io/api/v1/voice/shared-lines/sharedLine_abc/members" \
  -H "X-API-Key: $K" -H "Content-Type: application/json" \
  -d '{ "memberKind": "sip_extension", "memberValue": "front-desk-1", "canGrab": true }'
curl -X DELETE "https://api.orbit.devotel.io/api/v1/voice/shared-lines/sharedLine_abc/members/sharedLineMember_xyz" \
  -H "X-API-Key: $K"

Node.js

await orbit.voice.sharedLines.create({
  name: 'Reception',
  primaryExtension: '100',
  status: 'active',
})
await orbit.voice.sharedLines.list()
await orbit.voice.sharedLines.get('sharedLine_abc')
await orbit.voice.sharedLines.update('sharedLine_abc', { status: 'inactive' })
await orbit.voice.sharedLines.delete('sharedLine_abc')
await orbit.voice.sharedLines.members.add('sharedLine_abc', {
  memberKind: 'sip_extension',
  memberValue: 'front-desk-1',
  canGrab: true,
})
await orbit.voice.sharedLines.members.remove('sharedLine_abc', 'sharedLineMember_xyz')

Python

import os, requests
headers = {"X-API-Key": os.environ["ORBIT_API_KEY"], "Content-Type": "application/json"}
r = requests.post("https://api.orbit.devotel.io/api/v1/voice/shared-lines", headers=headers, json={
  "name": "Reception",
  "primaryExtension": "100",
  "status": "active"
})
line_id = r.json()["data"]["id"]
requests.post(
  f"https://api.orbit.devotel.io/api/v1/voice/shared-lines/{line_id}/members",
  headers=headers,
  json={"memberKind": "sip_extension", "memberValue": "front-desk-1", "canGrab": True})

Devices

Register physical desk phones for zero-touch provisioning. Each device pairs a MAC address with a vendor and (optionally) a SIP credential; the response returns a provisioningUrl your IT team plugs into the vendor redirect server (Polycom ZTP / Yealink RPS / Cisco EDOS / Grandstream GDMS). On first boot the phone fetches its rendered config and registers against Orbit’s SIP edge.

Provisioning points the phone at Orbit’s SIP edge (sip.orbit.devotel.io), which routes through to the Devotel softswitch — phones are never provisioned to register directly at an upstream carrier.

Create / List / Get / Update / Delete

POST /api/v1/voice/devices

string

required

The phone’s MAC address (12-17 chars, with or without separators). Normalised server-side; a MAC already registered returns 409.

string

required

Device vendor. One of polycom, yealink, cisco, or grandstream.

string

Optional model identifier (max 64 chars).

string

Optional id of a SIP credential in your organization to bind to the phone. Must belong to your organization (a foreign id returns 404). Until set, the phone has nothing to register with.

string

Optional operator-facing label (max 64 chars).

string

Optional free-text notes (max 1000 chars).

string

ISO 8601 timestamp after which an un-booted device row auto-expires. Defaults to 30 days from creation; pass null for no expiry (long-tail fleet rollouts).

GET /api/v1/voice/devices — list every device in your organization. GET /api/v1/voice/devices/{id} PATCH /api/v1/voice/devices/{id} — update label, sipCredentialId, model, notes, disabled, or claimExpiresAt. A field present with value null clears the column. DELETE /api/v1/voice/devices/{id} — soft delete.

cURL

# Register a device
curl -X POST "https://api.orbit.devotel.io/api/v1/voice/devices" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "macAddress": "aabbccddeeff",
  "vendor": "yealink",
  "model": "T54W",
  "sipCredentialId": "sipcred_abc",
  "label": "Front desk"
}'
# List / Get / Update / Delete
curl -X GET "https://api.orbit.devotel.io/api/v1/voice/devices" -H "X-API-Key: $K"
curl -X GET "https://api.orbit.devotel.io/api/v1/voice/devices/sipdev_abc" -H "X-API-Key: $K"
curl -X PATCH "https://api.orbit.devotel.io/api/v1/voice/devices/sipdev_abc" \
  -H "X-API-Key: $K" -H "Content-Type: application/json" -d '{ "disabled": true }'
curl -X DELETE "https://api.orbit.devotel.io/api/v1/voice/devices/sipdev_abc" -H "X-API-Key: $K"

Node.js

const device = await orbit.voice.devices.create({
  macAddress: 'aabbccddeeff',
  vendor: 'yealink',
  model: 'T54W',
  sipCredentialId: 'sipcred_abc',
  label: 'Front desk',
})
// Paste device.provisioningUrl into the vendor redirect server.
await orbit.voice.devices.list()
await orbit.voice.devices.get('sipdev_abc')
await orbit.voice.devices.update('sipdev_abc', { disabled: true })
await orbit.voice.devices.delete('sipdev_abc')

Python

import os, requests
headers = {"X-API-Key": os.environ["ORBIT_API_KEY"], "Content-Type": "application/json"}
r = requests.post("https://api.orbit.devotel.io/api/v1/voice/devices", headers=headers, json={
  "macAddress": "aabbccddeeff",
  "vendor": "yealink",
  "model": "T54W",
  "sipCredentialId": "sipcred_abc",
  "label": "Front desk"
})
print(r.json()["data"]["provisioningUrl"])

Call Flip / Call Pull

Move a live call between devices without dropping it — the mobile-↔-desktop continuity pattern. The agent flips a call on one registered device (issuing a short-lived handoff token) and pulls it onto another device (their mobile soft-client, another desk phone) by claiming that token. This API manages the handoff ledger; the actual SIP re-INVITE that moves the leg is performed by the voice call plane.

Per Orbit’s outbound-termination invariant, the moved (mobile-terminated) leg is re-INVITEd via the Devotel wholesale softswitch — never an upstream carrier’s call-control API.

Flip a Call

POST /api/v1/voice/call-flip

string

required

SID of the live call being flipped (1-128 chars).

string

Optional SIP username (from tenant_sip_credentials.username) that the call is pinned to. When omitted, any registered device in the organization may pull the call; when set, only that device may pull (otherwise the pull returns 403).

string

Optional reference to a call_logs.id for join-time lookup.

string

Optional E.164 number of the remote leg, shown in the pending-flips list.

string

Optional display name of the remote leg.

Returns 201 with the handoff, including the full token (returned only on this call), a 4-digit shortCode for DTMF pulls (*7 then the code on a legacy desk phone), and expiresAt. The token TTL is 120 seconds. Re-issuing a flip for the same callSid by the same user while one is active returns the existing token (idempotent).

Pull a Call

POST /api/v1/voice/call-flip/pull

string

required

The token returned by the flip endpoint (or the 4-digit short-code on the dial-code path).

string

required

The pulling device’s SIP username. When the flip pinned a targetDeviceUsername, this must match.

Returns 200 with the resolved callSid on success. A token that was already pulled or has expired returns 410; a device mismatch returns 403; an unknown token returns 404.

List / Cancel

GET /api/v1/voice/call-flip — list every live (un-pulled, un-expired) handoff in the organization. Tokens are never returned by this endpoint. POST /api/v1/voice/call-flip/{id}/cancel — cancel an outstanding flip (the agent changed their mind). A subsequent pull then returns 410. By default only the user who issued the flip may cancel it; owners, admins, and supervisors may cancel any flip in their organization.

cURL

# Flip the live call (returns token + shortCode + expiresAt)
curl -X POST "https://api.orbit.devotel.io/api/v1/voice/call-flip" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "callSid": "call_abc", "remotePartyNumber": "+14155557890" }'
# Pull the call onto another device
curl -X POST "https://api.orbit.devotel.io/api/v1/voice/call-flip/pull" \
  -H "X-API-Key: $K" -H "Content-Type: application/json" \
  -d '{ "token": "flip_…", "pulledByDeviceUsername": "alice-mobile" }'
# List pending flips / cancel one
curl -X GET "https://api.orbit.devotel.io/api/v1/voice/call-flip" -H "X-API-Key: $K"
curl -X POST "https://api.orbit.devotel.io/api/v1/voice/call-flip/flip_…/cancel" -H "X-API-Key: $K"

Node.js

const flip = await orbit.voice.callFlip.flip({
  callSid: 'call_abc',
  remotePartyNumber: '+14155557890',
})
// flip.token + flip.shortCode + flip.expiresAt
await orbit.voice.callFlip.pull({
  token: flip.token,
  pulledByDeviceUsername: 'alice-mobile',
})
await orbit.voice.callFlip.list()
await orbit.voice.callFlip.cancel(flip.id)

Python

import os, requests
headers = {"X-API-Key": os.environ["ORBIT_API_KEY"], "Content-Type": "application/json"}
flip = requests.post("https://api.orbit.devotel.io/api/v1/voice/call-flip", headers=headers,
  json={"callSid": "call_abc", "remotePartyNumber": "+14155557890"}).json()["data"]
requests.post("https://api.orbit.devotel.io/api/v1/voice/call-flip/pull", headers=headers,
  json={"token": flip["token"], "pulledByDeviceUsername": "alice-mobile"})

Hot-Desking

Let agents sign in to a shared physical desk phone so it re-skins as their own extension for the duration of a shift, then falls back to the shared inbound pool on sign-out — the retail / healthcare / hybrid-office “hardware-first” pattern (Cisco Extension Mobility, RingCentral Hot Desking, 8x8 Shared Phone Desks). There is one active session per device and one per user: signing in to a second device automatically signs you out of the first, and signing in to a device already bound to someone else displaces their session. Displaced sessions are returned in the sign-in response so the dashboard can show who was bumped. POST /api/v1/voice/hot-desking/sign-in

string

required

SIP username of the shared desk phone — the same username you manage under SIP Credentials. Lowercase/uppercase letters, digits, ., _ or -; 3–128 characters (for example acme-shared-5F-2).

string

Optional human-readable device label captured at sign-in time (max 120 chars) so the audit trail survives a later device rename.

string

Optional ISO-8601 scheduled auto-sign-out. Must be in the future and within 24 hours, otherwise the request returns 400.

Returns 201 with { session, displaced } on a fresh bind, or 200 with the existing session when the same user re-signs in to the same device (idempotent no-op). A concurrent sign-in race returns 409.

Sign Out

POST /api/v1/voice/hot-desking/sign-out Releases the calling user’s active session and returns the device to the shared inbound pool. Returns 200 with the released session. A second sign-out returns 410 (with the prior release reason and timestamp) when you have a prior session, or 404 when you were never signed in.

List Active Sessions

GET /api/v1/voice/hot-desking — list the organization’s active (not signed-out) hot-desk sessions, newest first, capped at 200. Powers the dashboard’s hot-desking board.

My Session

GET /api/v1/voice/hot-desking/me — returns the calling user’s active session, or null under data when not signed in to any device.

cURL

# Sign in to a shared desk phone
curl -X POST "https://api.orbit.devotel.io/api/v1/voice/hot-desking/sign-in" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "deviceSipUsername": "acme-shared-5F-2" }'
# Who am I signed in as?
curl "https://api.orbit.devotel.io/api/v1/voice/hot-desking/me" -H "X-API-Key: $K"
# List active sessions for the org
curl "https://api.orbit.devotel.io/api/v1/voice/hot-desking" -H "X-API-Key: $K"
# Sign out
curl -X POST "https://api.orbit.devotel.io/api/v1/voice/hot-desking/sign-out" -H "X-API-Key: $K"

Node.js

const signIn = await orbit.voice.hotDesking.signIn({
  deviceSipUsername: 'acme-shared-5F-2',
})
// signIn.session + signIn.displaced
await orbit.voice.hotDesking.me()
await orbit.voice.hotDesking.list()
await orbit.voice.hotDesking.signOut()

Python

import os, requests
headers = {"X-API-Key": os.environ["ORBIT_API_KEY"], "Content-Type": "application/json"}
sign_in = requests.post("https://api.orbit.devotel.io/api/v1/voice/hot-desking/sign-in",
  headers=headers, json={"deviceSipUsername": "acme-shared-5F-2"}).json()["data"]
requests.post("https://api.orbit.devotel.io/api/v1/voice/hot-desking/sign-out", headers=headers)

{
  "data": {
    "session": {
      "id": "hds_0123456789abcdef0123456789abcdef",
      "deviceSipUsername": "acme-shared-5F-2",
      "userId": "usr_abc123",
      "deviceLabelSnapshot": "Front Desk 5F",
      "userDisplayNameSnapshot": null,
      "signedInAt": "2026-06-28T09:00:00Z",
      "expiresAt": null,
      "signedOutAt": null,
      "releaseReason": null,
      "activeForSeconds": 0
    },
    "displaced": []
  }
}

Hoteling

Hot-desking lets a user claim a shared desk phone now; hoteling adds the advance-booking layer on top — an agent or knowledge-worker reserves a specific desk/extension for a future date/time window, the system prevents double-booking, and a no-show or elapsed reservation is auto-released so a desk is never dead-locked by an absent booker (the Cisco / RingCentral / 8x8 “book a desk” pattern). These endpoints back the reservation calendar shown under Voice → Hot-Desking. A booking is rejected with 409 HOTELING_DOUBLE_BOOKED when its [startsAt, endsAt) window overlaps an existing active reservation for the same device; the conflicting reservation is returned under error.details.conflict.

Book a Reservation

POST /api/v1/voice/hoteling/reservations

string

required

SIP username of the shared desk phone being booked — the same username you manage under SIP Credentials. 3–128 characters of letters, digits, ., _ or - (for example acme-shared-5F-2).

string

required

ISO-8601 inclusive start of the booked window (for example 2026-07-20T09:00:00Z).

string

required

ISO-8601 exclusive end of the booked window. Must be after startsAt, in the future, and at most 24 hours after startsAt; startsAt itself may be at most 90 days ahead.

string

Optional human-readable device label captured at booking time (max 120 chars) so the audit trail survives a later device rename.

string

Optional free-text note shown on the booking calendar (max 500 chars).

Returns 201 with the created reservation, or 409 HOTELING_DOUBLE_BOOKED when the window overlaps an existing reservation for the same desk.

List Reservations

GET /api/v1/voice/hoteling/reservations

string

default:"me"

me returns the caller’s reservations; team returns the whole organization’s.

string

Optional ISO-8601 lower bound — only reservations ending after this instant are returned.

string

Optional ISO-8601 upper bound — only reservations starting before this instant are returned.

string

Optional filter to a single shared desk.

Returns the matching reservations ordered by window start, capped at 200. Elapsed windows are auto-released before the list is read.

Cancel a Reservation

DELETE /api/v1/voice/hoteling/reservations/{id} Cancels an active reservation. The booker can cancel their own; owner/admin can cancel any. Returns 410 when the reservation is already cancelled, fulfilled, or expired, and 404 when it does not exist for your organization.

Release Elapsed Reservations

POST /api/v1/voice/hoteling/reservations/sweep owner/admin only. Flips any reservation whose window has fully elapsed to expired, freeing the desk. This also runs automatically on every reservation read/book — call it explicitly only to force an immediate sweep. Returns { "released": <count> }.

cURL

K="dv_live_sk_your_key_here"
# Book a desk for a future window
curl -X POST "https://api.orbit.devotel.io/api/v1/voice/hoteling/reservations" \
  -H "X-API-Key: $K" \
  -H "Content-Type: application/json" \
  -d '{
  "deviceSipUsername": "acme-shared-5F-2",
  "startsAt": "2026-07-20T09:00:00Z",
  "endsAt": "2026-07-20T17:00:00Z"
}'
# List my upcoming reservations
curl "https://api.orbit.devotel.io/api/v1/voice/hoteling/reservations?scope=me" -H "X-API-Key: $K"
# Cancel a reservation
curl -X DELETE "https://api.orbit.devotel.io/api/v1/voice/hoteling/reservations/hdr_0123456789abcdef0123456789abcdef" -H "X-API-Key: $K"
# Release elapsed / no-show reservations (owner/admin)
curl -X POST "https://api.orbit.devotel.io/api/v1/voice/hoteling/reservations/sweep" -H "X-API-Key: $K"

Node.js

const res = await fetch("https://api.orbit.devotel.io/api/v1/voice/hoteling/reservations", {
  method: "POST",
  headers: { "X-API-Key": process.env.ORBIT_API_KEY!, "Content-Type": "application/json" },
  body: JSON.stringify({
    deviceSipUsername: "acme-shared-5F-2",
    startsAt: "2026-07-20T09:00:00Z",
    endsAt: "2026-07-20T17:00:00Z",
  }),
})
const { data } = await res.json()

Python

import os, requests
headers = {"X-API-Key": os.environ["ORBIT_API_KEY"], "Content-Type": "application/json"}
booking = requests.post(
    "https://api.orbit.devotel.io/api/v1/voice/hoteling/reservations",
    headers=headers,
    json={
        "deviceSipUsername": "acme-shared-5F-2",
        "startsAt": "2026-07-20T09:00:00Z",
        "endsAt": "2026-07-20T17:00:00Z",
    },
).json()["data"]

{
  "data": {
    "id": "hdr_0123456789abcdef0123456789abcdef",
    "deviceSipUsername": "acme-shared-5F-2",
    "userId": "usr_abc123",
    "deviceLabelSnapshot": "Front Desk 5F",
    "userDisplayNameSnapshot": null,
    "startsAt": "2026-07-20T09:00:00Z",
    "endsAt": "2026-07-20T17:00:00Z",
    "status": "reserved",
    "notes": null,
    "fulfilledSessionId": null,
    "fulfilledAt": null,
    "releasedReason": null,
    "durationMinutes": 480
  }
}

Extensions

SIP extensions for soft-phone registration. Each extension binds one user to a SIP credential pair (managed via the SIP Credentials endpoints) and can receive direct calls or appear in ring groups. Extensions are managed end-to-end through the dashboard at Voice → Extensions. The underlying call-flow surface (registering, rotating credentials, observing register state) is exposed via the SIP Credentials API at /api/v1/sip-credentials/* (see SIP Credentials).

Calendars

Holiday calendars are per-organization named lists of closure dates. Attach one to an inbound route (holiday_calendar_id) and the route treats those dates as closed regardless of weekday business hours — calls route to your closed-hours handling (voicemail or a fallback). Each calendar carries an IANA timezone, used to decide which calendar day the current time falls on.

Create a Calendar

POST /api/v1/voice/calendars Requires the owner or admin role.

string

required

Calendar name. Must be unique within your organization — a duplicate name returns 409.

string

IANA timezone, e.g. Europe/Istanbul. Defaults to UTC.

object[]

Closure dates. Each entry is { "date": "YYYY-MM-DD", "label": "..." } where label is optional. Dates must be today or later (in the calendar’s timezone); up to 366 entries.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/voice/calendars" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Istanbul Public Holidays",
  "timezone": "Europe/Istanbul",
  "dates": [
    { "date": "2026-04-23", "label": "National Sovereignty Day" },
    { "date": "2026-05-01", "label": "Labour Day" }
  ]
}'

Node.js

await orbit.voice.calendars.create({
  name: 'Istanbul Public Holidays',
  timezone: 'Europe/Istanbul',
  dates: [
    { date: '2026-04-23', label: 'National Sovereignty Day' },
    { date: '2026-05-01', label: 'Labour Day' },
  ],
})

Python

import os, requests
headers = {"X-API-Key": os.environ["ORBIT_API_KEY"], "Content-Type": "application/json"}
r = requests.post("https://api.orbit.devotel.io/api/v1/voice/calendars", headers=headers, json={
  "name": "Istanbul Public Holidays",
  "timezone": "Europe/Istanbul",
  "dates": [{"date": "2026-04-23", "label": "National Sovereignty Day"}]
})
print(r.json())

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	body := []byte(`{
  "name": "Istanbul Public Holidays",
  "timezone": "Europe/Istanbul",
  "dates": [{"date":"2026-04-23","label":"National Sovereignty Day"}]
}`)
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/voice/calendars", bytes.NewBuffer(body))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	http.DefaultClient.Do(req)
}

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/voice/calendars');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
  'name' => 'Istanbul Public Holidays',
  'timezone' => 'Europe/Istanbul',
  'dates' => [['date' => '2026-04-23', 'label' => 'National Sovereignty Day']],
]));
echo curl_exec($ch);

List / Get / Delete

GET /api/v1/voice/calendars GET /api/v1/voice/calendars/{id} DELETE /api/v1/voice/calendars/{id} The list response includes a usage_count on each calendar — how many of your inbound routes reference it. Deleting a calendar is permanent; any inbound route pointing at it has its holiday_calendar_id reset to null (the route keeps working, with no holiday closures). Delete returns 204.

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/voice/calendars" -H "X-API-Key: $K"
curl -X GET "https://api.orbit.devotel.io/api/v1/voice/calendars/cal_abc" -H "X-API-Key: $K"
curl -X DELETE "https://api.orbit.devotel.io/api/v1/voice/calendars/cal_abc" -H "X-API-Key: $K"

Node.js

await orbit.voice.calendars.list()
await orbit.voice.calendars.get('cal_abc')
await orbit.voice.calendars.delete('cal_abc')

Python

import os, requests
h = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
requests.get("https://api.orbit.devotel.io/api/v1/voice/calendars", headers=h)
requests.get("https://api.orbit.devotel.io/api/v1/voice/calendars/cal_abc", headers=h)
requests.delete("https://api.orbit.devotel.io/api/v1/voice/calendars/cal_abc", headers=h)

package main

import (
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.orbit.devotel.io/api/v1/voice/calendars", nil)
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	http.DefaultClient.Do(req)
}

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/voice/calendars');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['X-API-Key: ' . getenv('ORBIT_API_KEY')]);
echo curl_exec($ch);

Update a Calendar

PATCH /api/v1/voice/calendars/{id} Requires the owner or admin role. Send any subset of name, timezone, or dates; omitted fields are left unchanged. When you send dates, it fully replaces the existing list rather than merging.

cURL

curl -X PATCH "https://api.orbit.devotel.io/api/v1/voice/calendars/cal_abc" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "dates": [{ "date": "2026-12-25", "label": "Christmas Day" }] }'

Node.js

await orbit.voice.calendars.update('cal_abc', {
  dates: [{ date: '2026-12-25', label: 'Christmas Day' }],
})

Python

import os, requests
headers = {"X-API-Key": os.environ["ORBIT_API_KEY"], "Content-Type": "application/json"}
requests.patch("https://api.orbit.devotel.io/api/v1/voice/calendars/cal_abc", headers=headers, json={
  "dates": [{"date": "2026-12-25", "label": "Christmas Day"}]
})

Monitoring

Live supervisor surface — listen-in, whisper to the agent, or barge into a call for real-time coaching. All operations require the voice:monitor scope.

Start Listening (silent monitoring)

POST /api/v1/voice/calls/{id}/listen Open a one-way audio bridge to the supervisor — neither call leg hears the supervisor. POST /api/v1/voice/calls/{id}/unlisten Disconnect the supervisor leg.

cURL

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

Node.js

await orbit.voice.supervisor.listen('call_abc123')
await orbit.voice.supervisor.unlisten('call_abc123')

Python

import os, requests
headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
r = requests.post("https://api.orbit.devotel.io/api/v1/voice/calls/call_abc123/listen", headers=headers)
print(r.json())

package main

import (
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("POST",
		"https://api.orbit.devotel.io/api/v1/voice/calls/call_abc123/listen", nil)
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	http.DefaultClient.Do(req)
}

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/voice/calls/call_abc123/listen');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, ['X-API-Key: ' . getenv('ORBIT_API_KEY')]);
echo curl_exec($ch);

Whisper to the Agent

POST /api/v1/voice/calls/{id}/whisper Audio plays only to the agent leg. The customer cannot hear. Use to coach the agent mid-call.

cURL

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

Node.js

await orbit.voice.supervisor.whisper('call_abc123')

Python

import os, requests
headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
r = requests.post("https://api.orbit.devotel.io/api/v1/voice/calls/call_abc123/whisper", headers=headers)
print(r.json())

package main

import (
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("POST",
		"https://api.orbit.devotel.io/api/v1/voice/calls/call_abc123/whisper", nil)
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	http.DefaultClient.Do(req)
}

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/voice/calls/call_abc123/whisper');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, ['X-API-Key: ' . getenv('ORBIT_API_KEY')]);
echo curl_exec($ch);

Barge In

POST /api/v1/voice/calls/{id}/barge Add the supervisor as a third audible participant. Both call legs hear the supervisor.

cURL

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

Node.js

await orbit.voice.supervisor.barge('call_abc123')

Python

import os, requests
headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
r = requests.post("https://api.orbit.devotel.io/api/v1/voice/calls/call_abc123/barge", headers=headers)
print(r.json())

package main

import (
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("POST",
		"https://api.orbit.devotel.io/api/v1/voice/calls/call_abc123/barge", nil)
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	http.DefaultClient.Do(req)
}

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/voice/calls/call_abc123/barge');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, ['X-API-Key: ' . getenv('ORBIT_API_KEY')]);
echo curl_exec($ch);

Live Monitoring Snapshot

GET /api/v1/voice/monitoring Returns a denormalised snapshot of every active call, queue, and agent presence — drives the wallboard / Voice → Monitoring page.

cURL

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

Node.js

const snap = await orbit.voice.monitoring.snapshot()
console.log(snap.data.active_calls)

Python

import os, requests
headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
r = requests.get("https://api.orbit.devotel.io/api/v1/voice/monitoring", headers=headers)
print(r.json())

package main

import (
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.orbit.devotel.io/api/v1/voice/monitoring", nil)
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	http.DefaultClient.Do(req)
}

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/voice/monitoring');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['X-API-Key: ' . getenv('ORBIT_API_KEY')]);
echo curl_exec($ch);

{
  "data": {
    "active_calls": 14,
    "queued_calls": 3,
    "available_agents": 7,
    "busy_agents": 5,
    "calls": [
      {
        "id": "call_abc123",
        "from": "+14155552671",
        "to": "+18005551234",
        "agent_id": "agt_support_jane",
        "duration_seconds": 87,
        "queue_id": "queue_support",
        "started_at": "2026-03-08T11:58:33Z"
      }
    ]
  }
}

Real-time Transcripts

GET /api/v1/voice/calls/{callId}/transcript/stream Server-Sent Events (SSE) stream of live STT transcript chunks for an in-progress call. Each event carries a JSON body of:

{ "speaker": "agent" | "caller", "text": "...", "ts": "ISO-8601" }

Use for live captions, real-time agent assist, or downstream sentiment / intent classification. The stream closes when the call ends. GET /api/v1/voice/calls/{id}/transcript Final, post-call transcript (one shot, no streaming). Available once the recording has been processed (~30s after hangup). POST /api/v1/voice/transcribe Submit an arbitrary audio URL for asynchronous transcription. Returns a transcript_id to poll for the result.

cURL

# SSE stream
curl -N -X GET "https://api.orbit.devotel.io/api/v1/voice/calls/call_abc123/transcript/stream" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Accept: text/event-stream"
# Final post-call transcript
curl -X GET "https://api.orbit.devotel.io/api/v1/voice/calls/call_abc123/transcript" \
  -H "X-API-Key: dv_live_sk_your_key_here"
# Submit audio URL for async transcription
curl -X POST "https://api.orbit.devotel.io/api/v1/voice/transcribe" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "audio_url": "https://example.com/audio.mp3", "language": "en-US" }'

Node.js

// Final transcript
const tx = await orbit.voice.transcripts.get('call_abc123')
console.log(tx.data.utterances)
// Async submit
const job = await orbit.voice.transcripts.submit({
  audio_url: 'https://example.com/audio.mp3',
  language: 'en-US',
})
console.log(job.data.transcript_id)

Python

import os, requests
h = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
requests.get("https://api.orbit.devotel.io/api/v1/voice/calls/call_abc123/transcript", headers=h)
requests.post("https://api.orbit.devotel.io/api/v1/voice/transcribe",
              headers={**h, "Content-Type": "application/json"},
              json={"audio_url": "https://example.com/audio.mp3", "language": "en-US"})

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/voice/transcribe",
		bytes.NewBuffer([]byte(`{"audio_url":"https://example.com/audio.mp3","language":"en-US"}`)))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	http.DefaultClient.Do(req)
}

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/voice/transcribe');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, '{"audio_url":"https://example.com/audio.mp3","language":"en-US"}');
echo curl_exec($ch);

AI Call Intelligence

Post-call analysis — sentiment trajectory, key moments, summary, action items, customer effort score. Powered by the agent runtime’s call intelligence model.

Per-Call Intelligence

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

cURL

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

Node.js

const intel = await orbit.voice.intelligence.getForCall('call_abc123')
console.log(intel.data.summary)

Python

import os, requests
headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
r = requests.get("https://api.orbit.devotel.io/api/v1/voice/calls/call_abc123/intelligence", headers=headers)
print(r.json())

package main

import (
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("GET",
		"https://api.orbit.devotel.io/api/v1/voice/calls/call_abc123/intelligence", nil)
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	http.DefaultClient.Do(req)
}

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/voice/calls/call_abc123/intelligence');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['X-API-Key: ' . getenv('ORBIT_API_KEY')]);
echo curl_exec($ch);

{
  "data": {
    "call_id": "call_abc123",
    "summary": "Customer called to dispute a duplicate charge dated 2026-03-05 for $89.00. Agent confirmed the charge was a billing system retry artifact, refunded immediately, sent confirmation email.",
    "sentiment": {
      "overall": "neutral_to_positive",
      "trajectory": "improved",
      "agent_score": 0.82,
      "caller_score": 0.65
    },
    "key_moments": [
      { "ts": 12, "type": "intent_detected", "label": "billing_dispute" },
      { "ts": 47, "type": "frustration_peak", "score": 0.78 },
      { "ts": 134, "type": "resolution_offered" },
      { "ts": 189, "type": "satisfaction_signal", "score": 0.85 }
    ],
    "action_items": [
      "Send refund confirmation email by EOD",
      "Flag billing system for duplicate-charge investigation"
    ],
    "customer_effort_score": 2.4,
    "agent_compliance_flags": [],
    "language": "en-US",
    "processed_at": "2026-03-08T12:08:14Z"
  }
}

Run Sentiment On-Demand

POST /api/v1/voice/calls/{id}/sentiment Forces a re-run of the sentiment analyzer. Used when a call’s transcript has been edited or when the org’s sentiment model has changed.

cURL

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

Node.js

await orbit.voice.intelligence.runSentiment('call_abc123')

Python

import os, requests
headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
r = requests.post("https://api.orbit.devotel.io/api/v1/voice/calls/call_abc123/sentiment", headers=headers)
print(r.json())

package main

import (
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("POST",
		"https://api.orbit.devotel.io/api/v1/voice/calls/call_abc123/sentiment", nil)
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	http.DefaultClient.Do(req)
}

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/voice/calls/call_abc123/sentiment');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, ['X-API-Key: ' . getenv('ORBIT_API_KEY')]);
echo curl_exec($ch);

List Intelligence Records

GET /api/v1/voice/intelligence/calls List intelligence records for the org with filters by sentiment, agent, date range, and customer-effort threshold.

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/voice/intelligence/calls?sentiment=negative&limit=50" \
  -H "X-API-Key: dv_live_sk_your_key_here"

Node.js

await orbit.voice.intelligence.listCalls({ sentiment: 'negative', limit: 50 })

Python

import os, requests
headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
r = requests.get("https://api.orbit.devotel.io/api/v1/voice/intelligence/calls",
                 headers=headers, params={"sentiment": "negative", "limit": 50})
print(r.json())

package main

import (
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("GET",
		"https://api.orbit.devotel.io/api/v1/voice/intelligence/calls?sentiment=negative&limit=50", nil)
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	http.DefaultClient.Do(req)
}

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/voice/intelligence/calls?sentiment=negative&limit=50');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['X-API-Key: ' . getenv('ORBIT_API_KEY')]);
echo curl_exec($ch);

Trends

GET /api/v1/voice/intelligence/trends Aggregated time-series of sentiment + effort score, bucketed by day / week. Drives the Voice → Intelligence → Trends dashboard.

string

ISO-8601 start of the trend window. Defaults to 30 days ago.

string

ISO-8601 end of the trend window. Defaults to now.

string

default:"day"

Aggregation bucket: hour, day, week.

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/voice/intelligence/trends?from=2026-02-01&to=2026-03-08&bucket=day" \
  -H "X-API-Key: dv_live_sk_your_key_here"

Node.js

await orbit.voice.intelligence.trends({
  from: '2026-02-01',
  to: '2026-03-08',
  bucket: 'day',
})

Python

import os, requests
headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
r = requests.get("https://api.orbit.devotel.io/api/v1/voice/intelligence/trends", headers=headers,
                 params={"from": "2026-02-01", "to": "2026-03-08", "bucket": "day"})
print(r.json())

package main

import (
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("GET",
		"https://api.orbit.devotel.io/api/v1/voice/intelligence/trends?from=2026-02-01&to=2026-03-08&bucket=day", nil)
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	http.DefaultClient.Do(req)
}

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/voice/intelligence/trends?from=2026-02-01&to=2026-03-08&bucket=day');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['X-API-Key: ' . getenv('ORBIT_API_KEY')]);
echo curl_exec($ch);

Voice Quality (VAQI)

Voice Aggregated Quality Index — a 0–100 score derived from MOS, jitter, packet-loss, and one-way audio detection. Surface for SIP-trunk health and per-call diagnostics.

Aggregates

GET /api/v1/voice/quality/aggregates Per-period rollup of every active SIP trunk: average MOS, p95 jitter, packet loss percentage, VAQI score. Used by the Voice → Quality dashboard.

Per-Carrier Quality

GET /api/v1/voice/quality/carriers Same shape as /aggregates but bucketed by upstream carrier. Use to compare provider performance across the same time window.

Worst Calls

GET /api/v1/voice/quality/worst-calls Top-N calls in the period by lowest VAQI / highest packet loss / highest jitter. Drives the “Investigate” CTA in the dashboard.

VAQI Detail

GET /api/v1/voice/vaqi Full per-call quality matrix (MOS, jitter, packet loss, RTT, audio gaps) with optional call_id filter for a single-call drill-down.

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/voice/quality/aggregates" -H "X-API-Key: $K"
curl -X GET "https://api.orbit.devotel.io/api/v1/voice/quality/carriers" -H "X-API-Key: $K"
curl -X GET "https://api.orbit.devotel.io/api/v1/voice/quality/worst-calls?limit=10" -H "X-API-Key: $K"
curl -X GET "https://api.orbit.devotel.io/api/v1/voice/vaqi?call_id=call_abc123" -H "X-API-Key: $K"

Node.js

await orbit.voice.quality.aggregates()
await orbit.voice.quality.carriers()
await orbit.voice.quality.worstCalls({ limit: 10 })
await orbit.voice.quality.vaqi({ call_id: 'call_abc123' })

Python

import os, requests
h = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
requests.get("https://api.orbit.devotel.io/api/v1/voice/quality/aggregates", headers=h)
requests.get("https://api.orbit.devotel.io/api/v1/voice/quality/carriers", headers=h)
requests.get("https://api.orbit.devotel.io/api/v1/voice/quality/worst-calls", headers=h, params={"limit": 10})
requests.get("https://api.orbit.devotel.io/api/v1/voice/vaqi", headers=h, params={"call_id": "call_abc123"})

package main

import (
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.orbit.devotel.io/api/v1/voice/quality/aggregates", nil)
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	http.DefaultClient.Do(req)
}

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/voice/quality/aggregates');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['X-API-Key: ' . getenv('ORBIT_API_KEY')]);
echo curl_exec($ch);

Softphone Token

POST /api/v1/voice/softphone/token Mints a short-lived JWT (default 60s expiry) for browser-based softphone clients to register against the Orbit Media / Jambonz cluster without exposing a long-lived API key. Orbit Media is forked from LiveKit OSS under Apache-2 — see attribution. POST /api/v1/voice/softphone/dial Server-initiated outbound dial from a softphone session — the softphone client passes the to and Orbit places the call from the bound extension’s caller-ID.

cURL

# Mint a JWT
curl -X POST "https://api.orbit.devotel.io/api/v1/voice/softphone/token" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "extension_id": "ext_alice", "ttl_seconds": 60 }'
# Server-initiated outbound dial
curl -X POST "https://api.orbit.devotel.io/api/v1/voice/softphone/dial" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "to": "+14155557890", "extension_id": "ext_alice" }'

Node.js

const jwt = await orbit.voice.softphone.mintToken({
  extension_id: 'ext_alice',
  ttl_seconds: 60,
})
await orbit.voice.softphone.dial({ to: '+14155557890', extension_id: 'ext_alice' })

Python

import os, requests
headers = {"X-API-Key": os.environ["ORBIT_API_KEY"], "Content-Type": "application/json"}
r = requests.post("https://api.orbit.devotel.io/api/v1/voice/softphone/token", headers=headers,
                  json={"extension_id": "ext_alice", "ttl_seconds": 60})
print(r.json())

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("POST",
		"https://api.orbit.devotel.io/api/v1/voice/softphone/token",
		bytes.NewBuffer([]byte(`{"extension_id":"ext_alice","ttl_seconds":60}`)))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	http.DefaultClient.Do(req)
}

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/voice/softphone/token');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, '{"extension_id":"ext_alice","ttl_seconds":60}');
echo curl_exec($ch);

Voice Clones

Custom-trained TTS voices for AI agents. Voices are tenant-scoped. A clone is sourced from an existing recorded call on your account — you do not upload an audio sample. The source call must have a granted, active recording-consent receipt, and you must attest to the voice owner’s permission when you create the clone.

Create

POST /api/v1/voice/clones Request body:

Field	Type	Required	Description
`name`	string	yes	Display name for the voice (1–80 chars).
`call_id`	string	yes	ID of an existing recorded call to clone the voice from. The call must carry a granted, non-revoked recording-consent receipt.
`voice_owner_relationship`	string	yes	Your relationship to the person being cloned. One of `self`, `employee`, `actor_with_release`, `customer_with_written_consent`, `other`.
`biometric_consent_acknowledged`	boolean	yes	Must be `true`. Confirms you understand that a voiceprint is biometric data governed by laws such as BIPA (Illinois), CUBI (Texas), and the EU AI Act.
`voice_owner_consent_evidence_url`	string	conditional	HTTPS URL to your stored proof of the voice owner’s consent (for example a signed PDF, a DocuSign envelope, or an in-app consent screenshot).
`voice_owner_consent_text`	string	conditional	Free-form attestation (≥ 50 chars) describing how consent was obtained.

You must supply at least one of voice_owner_consent_evidence_url or voice_owner_consent_text. A request that clones a call without a granted recording-consent receipt, or without a consent attestation, is rejected with 400. The response returns the clone id, its status (processing, ready, or failed), the source_call_id, and created_at. Cloning runs asynchronously; poll GET /api/v1/voice/clones until the status is ready.

List / Delete

GET /api/v1/voice/clones DELETE /api/v1/voice/clones/{id} Voice IDs returned by GET /api/v1/voice/clones can be referenced from agent configuration via tts_voice_id.

cURL

# Create — clone from an existing recorded call
curl -X POST "https://api.orbit.devotel.io/api/v1/voice/clones" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Brand Voice — EN",
  "call_id": "call_abc123",
  "voice_owner_relationship": "employee",
  "biometric_consent_acknowledged": true,
  "voice_owner_consent_evidence_url": "https://storage.example.com/consent/alice.pdf",
  "voice_owner_consent_text": "Alice signed our recorded voice-cloning release on 2026-06-30; PDF stored at the evidence URL."
}'
# List
curl -X GET "https://api.orbit.devotel.io/api/v1/voice/clones" -H "X-API-Key: $K"
# Delete
curl -X DELETE "https://api.orbit.devotel.io/api/v1/voice/clones/clone_abc" -H "X-API-Key: $K"

Node.js

await orbit.voice.clones.create({
  name: 'Brand Voice — EN',
  call_id: 'call_abc123',
  voice_owner_relationship: 'employee',
  biometric_consent_acknowledged: true,
  voice_owner_consent_evidence_url: 'https://storage.example.com/consent/alice.pdf',
  voice_owner_consent_text:
    'Alice signed our recorded voice-cloning release on 2026-06-30; PDF stored at the evidence URL.',
})
await orbit.voice.clones.list()
await orbit.voice.clones.delete('clone_abc')

Python

import os, requests
h = {"X-API-Key": os.environ["ORBIT_API_KEY"], "Content-Type": "application/json"}
r = requests.post("https://api.orbit.devotel.io/api/v1/voice/clones", headers=h, json={
  "name": "Brand Voice — EN",
  "call_id": "call_abc123",
  "voice_owner_relationship": "employee",
  "biometric_consent_acknowledged": True,
  "voice_owner_consent_evidence_url": "https://storage.example.com/consent/alice.pdf",
  "voice_owner_consent_text": "Alice signed our recorded voice-cloning release on 2026-06-30; PDF stored at the evidence URL."
})
print(r.json())

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	body := []byte(`{
  "name": "Brand Voice — EN",
  "call_id": "call_abc123",
  "voice_owner_relationship": "employee",
  "biometric_consent_acknowledged": true,
  "voice_owner_consent_evidence_url": "https://storage.example.com/consent/alice.pdf",
  "voice_owner_consent_text": "Alice signed our recorded voice-cloning release on 2026-06-30; PDF stored at the evidence URL."
}`)
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/voice/clones", bytes.NewBuffer(body))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	http.DefaultClient.Do(req)
}

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/voice/clones');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
  'name' => 'Brand Voice — EN',
  'call_id' => 'call_abc123',
  'voice_owner_relationship' => 'employee',
  'biometric_consent_acknowledged' => true,
  'voice_owner_consent_evidence_url' => 'https://storage.example.com/consent/alice.pdf',
  'voice_owner_consent_text' => 'Alice signed our recorded voice-cloning release on 2026-06-30; PDF stored at the evidence URL.',
]));
echo curl_exec($ch);

Coaching Notes

Supervisors attach a structured, acknowledgeable coaching note to a specific call, targeting the agent who handled it. Notes appear on the agent’s coaching timeline; the agent acknowledges each one. Writing a note requires an owner, admin, or supervisor role.

Create a Coaching Note

POST /api/v1/voice/calls/{id}/coaching-notes

string

required

The call the note is anchored to.

string

required

The agent the note coaches. Must be the agent who handled this call — a mismatch is rejected with 422 AGENT_MISMATCH.

string

required

The coaching text (1–4000 characters).

string

default:"general"

Note category: positive (commendation), improvement (coachable moment), warning (policy or performance flag), or general (informational).

string[]

Optional QA-rubric references this note maps to (up to 10).

string

Optional follow-up action for the agent (up to 500 characters).

List Coaching Notes on a Call

GET /api/v1/voice/calls/{id}/coaching-notes Owners, admins, and supervisors see every note on the call. An agent sees only the notes addressed to them.

Acknowledge a Coaching Note

PUT /api/v1/voice/calls/{id}/coaching-notes/{noteId}/acknowledge Only the agent the note is addressed to may acknowledge it. Acknowledgement is idempotent — a repeat call returns the original acknowledgement timestamp.

cURL

# Author a note
curl -X POST "https://api.orbit.devotel.io/api/v1/voice/calls/call_abc123/coaching-notes" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "agent_user_id": "usr_agent_42",
  "body": "Strong discovery questions. Confirm the account number before disclosing balances next time.",
  "severity": "improvement",
  "suggested_action": "Review the identity-verification script section 2."
}'
# Agent acknowledges
curl -X PUT "https://api.orbit.devotel.io/api/v1/voice/calls/call_abc123/coaching-notes/cnote_9f2/acknowledge" \
  -H "X-API-Key: dv_live_sk_your_key_here"

Node.js

await orbit.voice.coachingNotes.create('call_abc123', {
  agent_user_id: 'usr_agent_42',
  body: 'Strong discovery questions. Confirm the account number before disclosing balances next time.',
  severity: 'improvement',
  suggested_action: 'Review the identity-verification script section 2.',
})

await orbit.voice.coachingNotes.acknowledge('call_abc123', 'cnote_9f2')

Python

import os, requests
headers = {"X-API-Key": os.environ["ORBIT_API_KEY"], "Content-Type": "application/json"}
requests.post("https://api.orbit.devotel.io/api/v1/voice/calls/call_abc123/coaching-notes",
              headers=headers, json={
  "agent_user_id": "usr_agent_42",
  "body": "Strong discovery questions. Confirm the account number before disclosing balances next time.",
  "severity": "improvement"
})

Coaching Plans

A coaching plan wraps a longitudinal, multi-session improvement program for one agent — a goal, an optional due date, and a lifecycle that closes with an outcome. Writes require an owner, admin, or supervisor role; an agent can read only their own plans.

Create a Coaching Plan

POST /api/v1/voice/coaching-plans

string

required

The agent the plan addresses.

string

required

The goal statement (1–2000 characters), e.g. “Reduce average handle time by 20% over four weeks.”

string

Optional target completion timestamp (ISO 8601). Omit for an open-ended plan the supervisor closes manually.

List Coaching Plans

GET /api/v1/voice/coaching-plans

string

Filter to one agent’s plans.

string

Filter to plans authored by one supervisor.

string

Filter by lifecycle status: active, completed, or cancelled.

integer

default:"50"

Results to return (1–200). Active plans sort first, then by due date.

Get a Coaching Plan

GET /api/v1/voice/coaching-plans/{id}

Update a Coaching Plan

PUT /api/v1/voice/coaching-plans/{id} Only active plans can be updated — updating a closed plan returns 409 PLAN_CLOSED. Supply at least one of agent_user_id, goal, or due_at.

Close a Coaching Plan

POST /api/v1/voice/coaching-plans/{id}/close

string

default:"completed"

Terminal status: completed or cancelled.

string

required

Supervisor judgement of the result: met, partial, or missed.

string

Optional narrative on what changed (up to 2000 characters).

Coaching-Plan Effectiveness

GET /api/v1/voice/coaching-plans/{id}/effectiveness Returns a data-driven before/after report: the agent’s Average Handle Time, First-Contact Resolution, and CSAT measured over a window before the plan compared against an equal window after it, with each metric classified as improved, regressed, flat, or insufficient_data. Active plans report in-flight progress from the plan’s start; closed plans measure from the close date.

integer

default:"14"

Length in days of both the before and after comparison windows (1–90).

integer

default:"24"

Look-ahead used by the First-Contact-Resolution calculation (1–168).

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/voice/coaching-plans" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "agent_user_id": "usr_agent_42",
  "goal": "Reduce average handle time by 20% over four weeks.",
  "due_at": "2026-08-01T00:00:00Z"
}'
# Later, close it
curl -X POST "https://api.orbit.devotel.io/api/v1/voice/coaching-plans/cplan_7a1/close" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "status": "completed", "outcome": "met" }'
# Read the effectiveness report
curl -X GET "https://api.orbit.devotel.io/api/v1/voice/coaching-plans/cplan_7a1/effectiveness?window_days=14" \
  -H "X-API-Key: dv_live_sk_your_key_here"

Node.js

const plan = await orbit.voice.coachingPlans.create({
  agent_user_id: 'usr_agent_42',
  goal: 'Reduce average handle time by 20% over four weeks.',
  due_at: '2026-08-01T00:00:00Z',
})

await orbit.voice.coachingPlans.close(plan.data.id, { status: 'completed', outcome: 'met' })

const report = await orbit.voice.coachingPlans.effectiveness(plan.data.id, { window_days: 14 })
console.log(report.data.kpis)

Python

import os, requests
headers = {"X-API-Key": os.environ["ORBIT_API_KEY"], "Content-Type": "application/json"}
r = requests.post("https://api.orbit.devotel.io/api/v1/voice/coaching-plans", headers=headers, json={
  "agent_user_id": "usr_agent_42",
  "goal": "Reduce average handle time by 20% over four weeks.",
  "due_at": "2026-08-01T00:00:00Z"
})
plan_id = r.json()["data"]["id"]
requests.get(f"https://api.orbit.devotel.io/api/v1/voice/coaching-plans/{plan_id}/effectiveness",
             headers=headers, params={"window_days": 14})

Real-Time Agent Assist

Stream real-time guidance to an agent while a call is live. An LLM reads the running transcript and emits cards — a suggested reply, relevant knowledge-base articles, and a next-best action — over Server-Sent Events.

Agent-Assist Stream

GET /api/v1/voice/calls/{callId}/agent-assist/stream The response is an SSE stream (Content-Type: text/event-stream). It opens with an event: connected handshake frame carrying the current call status, followed by an event: status frame. Each new suggestion arrives as an event: assist frame whose data is the card JSON. : ping comment lines keep the connection alive, and an event: end frame is sent when the call completes.

cURL

curl -N -X GET "https://api.orbit.devotel.io/api/v1/voice/calls/call_abc123/agent-assist/stream" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Accept: text/event-stream"

Node.js

const res = await fetch(
  'https://api.orbit.devotel.io/api/v1/voice/calls/call_abc123/agent-assist/stream',
  { headers: { 'X-API-Key': process.env.ORBIT_API_KEY!, Accept: 'text/event-stream' } },
)

const reader = res.body!.getReader()
const decoder = new TextDecoder()
for (;;) {
  const { value, done } = await reader.read()
  if (done) break
  process.stdout.write(decoder.decode(value))
}

id: 1
event: connected
data: {"call_id":"call_abc123","status":"in_progress"}

id: 2
event: assist
data: {"kind":"suggested_reply","text":"Offer the annual plan — it saves them 15%.","kb_articles":[{"title":"Annual billing","url":"..."}]}

Real-Time Supervisor Assist

The supervisor-facing companion to agent assist. Instead of a suggested reply, it surfaces an oversight action card — intervene, escalate, offer, or monitor — to a supervisor watching a live call, so they can decide in the moment whether to whisper-coach, barge in, relay a resource, or keep watching. Requires an owner, admin, or supervisor role; supervisors see only calls on queues they supervise.

Supervisor-Assist Stream

GET /api/v1/voice/supervisor/calls/{callId}/assist/stream Same SSE shape as agent assist: an event: connected handshake, an event: status frame, event: assist action cards as they are generated, : ping keep-alives, and a closing event: end frame.

cURL

curl -N -X GET "https://api.orbit.devotel.io/api/v1/voice/supervisor/calls/call_abc123/assist/stream" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Accept: text/event-stream"

Node.js

const res = await fetch(
  'https://api.orbit.devotel.io/api/v1/voice/supervisor/calls/call_abc123/assist/stream',
  { headers: { 'X-API-Key': process.env.ORBIT_API_KEY!, Accept: 'text/event-stream' } },
)
// consume res.body as an SSE stream (see Agent Assist example)

Real-Time Compliance Monitor

Score a live call against a compliance ruleset as it happens. An LLM evaluates the running transcript for mandatory disclosures (recording-consent notice, mini-Miranda, FDCPA language), profanity, and script adherence, and streams per-rule findings to a monitoring panel. Critical and warning breaches also raise a voice.compliance.violation event so a supervisor is alerted even without the panel open.

Compliance-Monitor Stream

GET /api/v1/voice/calls/{callId}/compliance/stream An SSE stream that opens with an event: connected handshake and an event: status frame, then emits an event: compliance frame each time the monitor scores a rule. : ping comments keep the connection alive; an event: end frame closes it when the call completes. Each event: compliance frame carries a findings array — one entry per rule, each with a kind (disclosure, profanity, or script_adherence), a status (satisfied, pending, or violated), a severity (info, warning, or critical), and a short detail (plus an optional transcript excerpt). The frame also carries an overall_adherence score in [0, 1] and an escalated array listing the rule_ids that raised a voice.compliance.violation supervisor alert on that tick.

cURL

curl -N -X GET "https://api.orbit.devotel.io/api/v1/voice/calls/call_abc123/compliance/stream" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Accept: text/event-stream"

Node.js

const res = await fetch(
  'https://api.orbit.devotel.io/api/v1/voice/calls/call_abc123/compliance/stream',
  { headers: { 'X-API-Key': process.env.ORBIT_API_KEY!, Accept: 'text/event-stream' } },
)
// consume res.body as an SSE stream (see Agent Assist example)

id: 1
event: connected
data: {"call_id":"call_abc123","status":"in_progress"}

id: 2
event: compliance
data: {"id":"cmp_01","call_id":"call_abc123","generated_at":"2026-07-03T10:15:04Z","model":"gpt-4o-mini","overall_adherence":0.72,"escalated":["mini_miranda"],"findings":[{"rule_id":"recording_consent","kind":"disclosure","status":"satisfied","severity":"critical","detail":"Recording-consent disclosure read in the opening line."},{"rule_id":"mini_miranda","kind":"disclosure","status":"violated","severity":"critical","detail":"Mini-Miranda not stated before discussing the debt.","excerpt":"So you owe $420 on the account…"},{"rule_id":"profanity","kind":"profanity","status":"satisfied","severity":"info","detail":"No profanity or abusive language detected."},{"rule_id":"script_adherence","kind":"script_adherence","status":"violated","severity":"warning","detail":"Skipped the identity-verification step in the approved flow.","excerpt":"Let's just get you set up with a plan."}]}

Dial Plan

A dial plan applies PBX-style digit-translation rules to outbound destinations before the call is placed — strip an access prefix, prepend a country code, or rewrite a short code to a full number. The plan applies across your whole organization and requires an owner or admin role.

Get the Dial Plan

GET /api/v1/voice/dial-plan Returns the current plan. When none is configured, returns { "enabled": false, "rules": [] } so you can render an empty state without handling a 404.

Replace the Dial Plan

PUT /api/v1/voice/dial-plan Replaces the plan in full. The response echoes the normalized plan — no-op rules are dropped and defaults are applied — so it reflects exactly what the translation engine will run.

boolean

required

Whether the plan is active. When false, destinations are dialed unchanged.

object[]

required

Ordered translation rules (up to 100). The first matching rule is applied.

Show rule

string

required

The pattern to match against the dialed digits. Dialable characters only (+, 0–9, *, #), up to 32 characters.

string

default:"prefix"

How match is compared: prefix or exact.

string

Optional label for the rule (up to 128 characters).

integer

Only apply when the dialed number has at least this many digits (1–64).

integer

Only apply when the dialed number has at most this many digits (1–64).

integer

Remove this many leading digits before dialing (0–20).

string

Digits to prepend after stripping (up to 20 dialable characters).

string

Replace the matched number outright with this value (up to 32 dialable characters).

Each rule must do something — set replace_with, or set strip_digits/prepend. A rule that would leave the number unchanged is rejected with 400.

cURL

curl -X PUT "https://api.orbit.devotel.io/api/v1/voice/dial-plan" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "enabled": true,
  "rules": [
    { "name": "Strip 9 access code", "match": "9", "match_type": "prefix", "strip_digits": 1 },
    { "name": "Local to E.164", "match": "0", "match_type": "prefix", "strip_digits": 1, "prepend": "+44" }
  ]
}'

Node.js

await orbit.voice.dialPlan.update({
  enabled: true,
  rules: [
    { name: 'Strip 9 access code', match: '9', match_type: 'prefix', strip_digits: 1 },
    { name: 'Local to E.164', match: '0', match_type: 'prefix', strip_digits: 1, prepend: '+44' },
  ],
})

Python

import os, requests
headers = {"X-API-Key": os.environ["ORBIT_API_KEY"], "Content-Type": "application/json"}
requests.put("https://api.orbit.devotel.io/api/v1/voice/dial-plan", headers=headers, json={
  "enabled": True,
  "rules": [
    {"name": "Strip 9 access code", "match": "9", "match_type": "prefix", "strip_digits": 1},
    {"name": "Local to E.164", "match": "0", "match_type": "prefix", "strip_digits": 1, "prepend": "+44"}
  ]
})

Dialing Restrictions

Dialing restrictions are a class-of-service policy: they cap which categories of number each user is allowed to dial outbound — toll-free, domestic, international, or premium-rate. The policy applies across your organization and requires an owner or admin role.

Get Dialing Restrictions

GET /api/v1/voice/dialing-restrictions Returns the current policy, or defaults (enabled: false) when none is set.

Replace Dialing Restrictions

PUT /api/v1/voice/dialing-restrictions

boolean

required

Whether the policy is enforced. When false, no class-of-service check runs.

string

ISO 3166 alpha-2 code (e.g. US, GB) used to classify destinations as domestic vs international.

string[]

Extra premium-rate prefixes to treat as the premium class, in + E.164 form (up to 100).

string[]

Classes any user may dial unless overridden. Values: tollfree, domestic, international, premium.

object

Per-user overrides keyed by user id. Each value is { "allowed_classes": [...] } listing the classes that user may dial.

cURL

curl -X PUT "https://api.orbit.devotel.io/api/v1/voice/dialing-restrictions" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "enabled": true,
  "home_country": "US",
  "default_allowed_classes": ["tollfree", "domestic"],
  "users": {
    "usr_agent_42": { "allowed_classes": ["tollfree", "domestic", "international"] }
  }
}'

Node.js

await orbit.voice.dialingRestrictions.update({
  enabled: true,
  home_country: 'US',
  default_allowed_classes: ['tollfree', 'domestic'],
  users: {
    usr_agent_42: { allowed_classes: ['tollfree', 'domestic', 'international'] },
  },
})

Python

import os, requests
headers = {"X-API-Key": os.environ["ORBIT_API_KEY"], "Content-Type": "application/json"}
requests.put("https://api.orbit.devotel.io/api/v1/voice/dialing-restrictions", headers=headers, json={
  "enabled": True,
  "home_country": "US",
  "default_allowed_classes": ["tollfree", "domestic"],
  "users": {"usr_agent_42": {"allowed_classes": ["tollfree", "domestic", "international"]}}
})

Voicemail Greeting

Each user manages their own personal voicemail greeting — upload an audio file, synthesize one from text, fetch the current greeting, or remove it to fall back to your tenant default. Any authenticated user can manage their own greeting; no admin role is required.

Get the Current Greeting

GET /api/v1/voice/voicemail/greeting Returns voicemail_greeting_url and voicemail_greeting_uploaded_at (both null when no personal greeting is set).

Upload a Greeting

POST /api/v1/voice/voicemail/greeting Send multipart/form-data with a single audio file. MP3 and WAV are accepted, up to 2 MB. Non-audio uploads return 415; a file over the limit returns 413.

Synthesize a Greeting from Text

POST /api/v1/voice/voicemail/greeting/tts

string

required

The greeting script to speak (1–500 characters).

string

Optional voice to synthesize with.

string

Optional BCP-47 language code such as en or en-US.

Delete the Greeting

DELETE /api/v1/voice/voicemail/greeting Removes your personal greeting and reverts to the tenant default.

cURL

# Upload an audio file
curl -X POST "https://api.orbit.devotel.io/api/v1/voice/voicemail/greeting" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -F "file=@greeting.mp3;type=audio/mpeg"

# Or synthesize from text
curl -X POST "https://api.orbit.devotel.io/api/v1/voice/voicemail/greeting/tts" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "text": "You have reached Alex. Please leave a message after the tone.", "language": "en-US" }'

# Revert to the tenant default
curl -X DELETE "https://api.orbit.devotel.io/api/v1/voice/voicemail/greeting" \
  -H "X-API-Key: dv_live_sk_your_key_here"

Python

import os, requests
headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
# Upload
with open("greeting.mp3", "rb") as f:
    requests.post("https://api.orbit.devotel.io/api/v1/voice/voicemail/greeting",
                  headers=headers, files={"file": ("greeting.mp3", f, "audio/mpeg")})
# Synthesize
requests.post("https://api.orbit.devotel.io/api/v1/voice/voicemail/greeting/tts",
              headers={**headers, "Content-Type": "application/json"},
              json={"text": "You have reached Alex. Please leave a message after the tone.", "language": "en-US"})

Post-Call Surveys (CSAT & NPS)

Configure IVR post-call surveys and read their results. After a qualifying call ends, the caller is offered a single-digit survey — a 1–5 CSAT rating or a 0–10 NPS rating. The endpoints below manage the survey configuration and return the aggregated analytics; the survey itself is delivered by the voice platform.

CSAT Analytics

GET /api/v1/voice/csat/surveys/{id}/analytics Returns totals, average score (1–5), satisfaction percentage (share scoring 4 or 5), a per-score breakdown, and a daily trend.

string

required

The survey id.

string

default:"30d"

Reporting window: 7d, 30d, 90d, or all.

string

Optional filter to one agent’s calls.

CSAT Configuration

GET /api/v1/voice/csat/surveys/{id}/config PATCH /api/v1/voice/csat/surveys/{id}/config Read or update the survey’s delivery settings. PATCH accepts any of the fields below (at least one is required).

boolean

Whether the survey is offered after calls.

string

How the survey is delivered: ivr_post_call (spoken at the end of the call) or message.

object

IVR prompt and gating settings.

Show ivr_config

string

The spoken prompt (up to 500 characters).

string

Optional HTTPS URL to a pre-recorded prompt, played instead of prompt_text.

integer

How long to wait for a keypress (1000–30000 ms).

integer

Retries on an invalid or missing digit (1–3).

string

Spoken after a valid response.

boolean

Skip the survey when the call was answered by a machine or fax.

integer

Skip the survey for calls shorter than this (0–3600 seconds).

integer

Offer the survey to this percentage of eligible calls (1–100).

string[]

Only survey calls whose final disposition code is in this list.

string[]

Never survey calls whose final disposition code is in this list (takes precedence over the allowlist).

NPS Analytics

GET /api/v1/voice/nps/surveys/{id}/analytics Returns totals, the NPS score (promoters minus detractors, −100 to +100), the promoter/passive/detractor breakdown, and a daily trend. Accepts the same window and agent_user_id query parameters as CSAT analytics.

NPS Configuration

GET /api/v1/voice/nps/surveys/{id}/config PATCH /api/v1/voice/nps/surveys/{id}/config Read or update the NPS survey settings. The body matches the CSAT config above (enabled, delivery_mode, ivr_config), with an NPS 0–10 prompt.

cURL

# Read CSAT results for the last 30 days
curl -X GET "https://api.orbit.devotel.io/api/v1/voice/csat/surveys/svy_abc123/analytics?window=30d" \
  -H "X-API-Key: dv_live_sk_your_key_here"

# Enable the CSAT survey and set the prompt
curl -X PATCH "https://api.orbit.devotel.io/api/v1/voice/csat/surveys/svy_abc123/config" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "enabled": true,
  "delivery_mode": "ivr_post_call",
  "ivr_config": { "prompt_text": "Please rate this call from 1 to 5.", "sample_rate_pct": 50 }
}'

Node.js

const analytics = await orbit.voice.csat.analytics('svy_abc123', { window: '30d' })

await orbit.voice.csat.updateConfig('svy_abc123', {
  enabled: true,
  delivery_mode: 'ivr_post_call',
  ivr_config: { prompt_text: 'Please rate this call from 1 to 5.', sample_rate_pct: 50 },
})

Python

import os, requests
headers = {"X-API-Key": os.environ["ORBIT_API_KEY"], "Content-Type": "application/json"}
requests.get("https://api.orbit.devotel.io/api/v1/voice/csat/surveys/svy_abc123/analytics",
             headers=headers, params={"window": "30d"})
requests.patch("https://api.orbit.devotel.io/api/v1/voice/csat/surveys/svy_abc123/config",
               headers=headers, json={
  "enabled": True,
  "delivery_mode": "ivr_post_call",
  "ivr_config": {"prompt_text": "Please rate this call from 1 to 5.", "sample_rate_pct": 50}
})

Call Statuses

Status	Description
`initiating`	Call is being set up
`ringing`	Destination phone is ringing
`in_progress`	Call is connected and active
`completed`	Call ended normally
`failed`	Call could not be connected
`busy`	Destination returned busy signal
`no_answer`	Destination did not answer within timeout
`cancelled`	Call was cancelled before connection

​Voice API

​Calls

​Initiate a Call

​List Calls

​Get Call Details

​Hang Up a Call

​Accept / Decline an Inbound Call

​Mute / Unmute a Call Leg

​Hold / Unhold

​Send DTMF Tones

​Transfer (Blind)

​Warm Transfer

​Recording

​Start / Stop Mid-Call Recording

​Retrieve a Call Recording

​Conference Recording

​SIP Trunks

​Create SIP Trunk

​List SIP Trunks

​Get SIP Trunk

​Update SIP Trunk

​Delete SIP Trunk

​IVR (Interactive Voice Response)

​Create IVR Flow

​List IVR Flows

​Update IVR Flow

​Delete IVR Flow

​Conferences

​List Conferences

​Get Conference

​Get Aggregate Metrics

​Create Conference

​Add Participant

​Remove Participant

​End Conference

​Call Forwarding (Find-me / Follow-me)

​Get My Rule

​Upsert My Rule

​Clear My Rule

​List Org Rules (admin)

​Voicemail

​Create Voicemail Box

​List Voicemail Messages

​Conference Operations (advanced)

​Mute / Unmute a Participant

​Mute / Unmute Everyone

​Hold / Unhold a Participant

​Lock / Unlock Conference

​End / Delete a Conference

​Call Queues

​Create a Queue

​List / Update / Delete

​Enqueue a Call

​Queue Stats

​Set Agent Status

​Ring Groups

​Create / List / Get / Delete

​Strategies

​Paging Groups

​Create / List / Get / Update / Delete

​Trigger a Page

​Shared Lines

​Create / List / Get / Update / Delete

​Members

​Devices

​Create / List / Get / Update / Delete

​Call Flip / Call Pull

​Flip a Call

​Pull a Call

​List / Cancel

​Hot-Desking

​Sign In

​Sign Out

​List Active Sessions

​My Session

​Hoteling

​Book a Reservation

​List Reservations

​Cancel a Reservation

​Release Elapsed Reservations

Voice API

Calls

Initiate a Call

List Calls

Get Call Details

Hang Up a Call

Accept / Decline an Inbound Call

Mute / Unmute a Call Leg

Hold / Unhold

Send DTMF Tones

Transfer (Blind)

Warm Transfer

Recording

Start / Stop Mid-Call Recording

Retrieve a Call Recording

Conference Recording

SIP Trunks

Create SIP Trunk

List SIP Trunks

Get SIP Trunk

Update SIP Trunk

Delete SIP Trunk

IVR (Interactive Voice Response)

Create IVR Flow

List IVR Flows

Update IVR Flow

Delete IVR Flow

Conferences

List Conferences

Get Conference

Get Aggregate Metrics

Create Conference

Add Participant

Remove Participant

End Conference

Call Forwarding (Find-me / Follow-me)

Get My Rule

Upsert My Rule

Clear My Rule

List Org Rules (admin)

Voicemail

Create Voicemail Box

List Voicemail Messages

Conference Operations (advanced)

Mute / Unmute a Participant

Mute / Unmute Everyone

Hold / Unhold a Participant

Lock / Unlock Conference

End / Delete a Conference

Call Queues

Create a Queue

List / Update / Delete

Enqueue a Call

Queue Stats

Set Agent Status

Ring Groups

Create / List / Get / Delete

Strategies

Paging Groups

Create / List / Get / Update / Delete

Trigger a Page

Shared Lines

Create / List / Get / Update / Delete

Members

Devices

Create / List / Get / Update / Delete

Call Flip / Call Pull

Flip a Call

Pull a Call

List / Cancel

Hot-Desking

Sign In

Sign Out

List Active Sessions

My Session

Hoteling

Book a Reservation

List Reservations

Cancel a Reservation

Release Elapsed Reservations