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: /v1/voice

Calls

Initiate a Call

POST /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

from

string

required

Caller ID — must be a number registered in your Orbit account

agent_id

string

AI agent to handle the call (omit for raw SIP or IVR)

ivr_id

string

IVR flow ID to execute when the call connects

webhook_url

string

URL to receive call status callbacks

record

boolean

default:"false"

Whether to record the call

max_duration

integer

default:"3600"

Maximum call duration in seconds

metadata

object

Arbitrary key-value pairs attached to the call

curl -X POST https://orbit-api.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,
    "webhook_url": "https://example.com/webhooks/calls"
  }'

{
  "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 /v1/voice/calls Retrieve call logs with cursor-based pagination and optional filters.

cursor

string

Cursor for pagination

limit

integer

default:"20"

Results per page (max 100)

status

string

Filter by status: initiating, ringing, in_progress, completed, failed

from

string

Filter by caller number

string

Filter by destination number

Get Call Details

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

Hang Up a Call

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

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 /v1/voice/sip-trunks

name

string

required

A descriptive name for the trunk

termination_uri

string

required

SIP URI for outbound call routing (e.g., sip:trunk.carrier.com:5060)

origination_uris

string[]

SIP URIs that Orbit should accept inbound calls from

auth_username

string

SIP authentication username

auth_password

string

SIP authentication password

codecs

string[]

default:"[\"PCMU\", \"PCMA\", \"OPUS\"]"

Preferred audio codecs in priority order

encryption

string

default:"tls_srtp"

Transport encryption: tls_srtp, tls, or none

curl -X POST https://orbit-api.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",
    "termination_uri": "sip:trunk.carrier.com:5060",
    "origination_uris": ["sip:orbit-gw.devotel.io"],
    "auth_username": "orbit_user",
    "auth_password": "secure_password",
    "codecs": ["OPUS", "PCMU"],
    "encryption": "tls_srtp"
  }'

{
  "data": {
    "id": "trunk_abc123",
    "name": "Primary Carrier",
    "termination_uri": "sip:trunk.carrier.com:5060",
    "status": "active",
    "codecs": ["OPUS", "PCMU"],
    "encryption": "tls_srtp",
    "created_at": "2026-03-08T12:00:00Z"
  },
  "meta": {
    "request_id": "req_trunk_001",
    "timestamp": "2026-03-08T12:00:00Z"
  }
}

List SIP Trunks

GET /v1/voice/sip-trunks

Get SIP Trunk

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

Update SIP Trunk

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

Delete SIP Trunk

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

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 /v1/voice/ivr

name

string

required

IVR flow name

greeting

string

required

Text-to-speech greeting played when a caller connects

language

string

default:"en-US"

Language for TTS and speech recognition

Menu definition with DTMF key-to-action mappings

Show child attributes

Array of menu options

DTMF key (1–9, 0, *, #)

Action: transfer_agent, transfer_number, play_message, submenu, voicemail

Target ID (agent ID, phone number, submenu ID, or voicemail box ID)

Text-to-speech message for play_message action

timeout_seconds

integer

default:"10"

Seconds to wait for DTMF input before replaying the menu

max_retries

integer

default:"3"

Maximum menu replays before fallback action

fallback_action

string

default:"voicemail"

Action when max retries reached: voicemail, transfer_number, hangup

curl -X POST https://orbit-api.devotel.io/api/v1/voice/ivr \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Main Menu",
    "greeting": "Welcome to Acme Corp. Press 1 for sales, 2 for support, or 3 to leave a voicemail.",
    "language": "en-US",
    "menu": {
      "options": [
        { "key": "1", "action": "transfer_agent", "target": "agt_sales" },
        { "key": "2", "action": "transfer_agent", "target": "agt_support" },
        { "key": "3", "action": "voicemail", "target": "vmail_general" }
      ]
    },
    "timeout_seconds": 8,
    "fallback_action": "voicemail"
  }'

{
  "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 /v1/voice/ivr

Update IVR Flow

PUT /v1/voice/ivr/{id}

Delete IVR Flow

DELETE /v1/voice/ivr/{id}

Conferences

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

Create Conference

POST /v1/voice/conferences

name

string

required

Conference name

max_participants

integer

default:"50"

Maximum number of participants

record

boolean

default:"false"

Record the conference

mute_on_join

boolean

default:"false"

Mute participants when they join

webhook_url

string

URL for conference event callbacks

curl -X POST https://orbit-api.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",
    "max_participants": 25,
    "record": true,
    "mute_on_join": true
  }'

{
  "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 /v1/voice/conferences/{id}/participants

number

string

required

Phone number to dial into the conference

muted

boolean

default:"false"

Join the participant in muted state

Remove Participant

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

End Conference

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

Voicemail

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

Create Voicemail Box

POST /v1/voice/voicemail

name

string

required

Voicemail box name

greeting

string

Custom TTS greeting (default: “Please leave a message after the tone.”)

transcribe

boolean

default:"true"

Automatically transcribe voicemail messages using STT

max_duration

integer

default:"120"

Maximum voicemail recording duration in seconds

notification_email

string

Email to send voicemail notifications to

webhook_url

string

URL for voicemail event callbacks

curl -X POST https://orbit-api.devotel.io/api/v1/voice/voicemail \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "General Inbox",
    "greeting": "You have reached Acme Corp. We are currently unavailable. Please leave a message.",
    "transcribe": true,
    "notification_email": "team@acme.com"
  }'

{
  "data": {
    "id": "vmail_abc123",
    "name": "General Inbox",
    "transcribe": true,
    "max_duration": 120,
    "messages_count": 0,
    "created_at": "2026-03-08T12:00:00Z"
  },
  "meta": {
    "request_id": "req_vmail_001",
    "timestamp": "2026-03-08T12:00:00Z"
  }
}

List Voicemail Messages

GET /v1/voice/voicemail/{id}/messages Retrieve voicemail messages with transcriptions.

{
  "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
    }
  }
}

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

Examples

Node.js

const orbit = new Devotel({ apiKey: 'dv_live_sk_xxxx' })

const call = await orbit.voice.calls.create({
  to: '+14155552671',
  from: '+18005551234',
  agentId: 'agt_support',
  record: true,
})

console.log(call.data.id) // call_abc123

Python

orbit = OrbitClient(api_key="dv_live_sk_xxxx")

call = orbit.voice.calls.create(
    to="+14155552671",
    from_number="+18005551234",
    agent_id="agt_support",
    record=True,
)

print(call.data.id)  # call_abc123

API Reference

​Voice API

​Calls

​Initiate a Call

​List Calls

​Get Call Details

​Hang Up a Call

​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

​Create Conference

​Add Participant

​Remove Participant

​End Conference

​Voicemail

​Create Voicemail Box

​List Voicemail Messages

​Call Statuses

​Examples

​Node.js

​Python

Voice API

Calls

Initiate a Call

List Calls

Get Call Details

Hang Up a Call

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

Create Conference

Add Participant

Remove Participant

End Conference

Voicemail

Create Voicemail Box

List Voicemail Messages

Call Statuses

Examples

Node.js

Python