Skip to main content

​
Voice API

Make outbound calls, connect AI voice agents, manage active calls in real time, and retrieve call recordings and logs. Base path: /v1/voice

​
Initiate Call

POST /v1/voice/calls Start a new outbound call. The call can be routed to an AI voice agent or a standard IVR flow.
​
to
string
required
Destination phone number in E.164 format (e.g., +14155552671)
​
from
string
required
Caller ID — must be a phone number registered in your Orbit account
​
agent_id
string
AI agent to handle the call (omit for raw SIP or IVR)
​
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 (default 1 hour)
​
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",
    "metadata": { "campaign": "retention" }
  }'

{
  "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.
​
cursor
string
Cursor for pagination
​
limit
integer
default:"20"
Number of results per page (max 100)
curl "https://orbit-api.devotel.io/api/v1/voice/calls?limit=10" \
  -H "X-API-Key: dv_live_sk_your_key_here"

{
  "data": [
    {
      "id": "call_abc123",
      "to": "+14155552671",
      "from": "+12025551234",
      "status": "completed",
      "duration_seconds": 185,
      "recording_url": "https://storage.devotel.io/recordings/call_abc123.wav",
      "created_at": "2026-03-08T11:00:00Z",
      "ended_at": "2026-03-08T11:03:05Z"
    }
  ],
  "meta": {
    "request_id": "req_calls_001",
    "timestamp": "2026-03-08T12:00:00Z",
    "pagination": {
      "cursor": "cur_call_abc",
      "has_more": true,
      "total": 342
    }
  }
}

​
Get Call

GET /v1/voice/calls/{id} Retrieve details of a single call including status, duration, recording URL, and agent interaction summary.
​
id
string
required
Call ID (e.g., call_abc123)
{
  "data": {
    "id": "call_abc123",
    "to": "+14155552671",
    "from": "+12025551234",
    "agent_id": "agt_abc123",
    "status": "completed",
    "duration_seconds": 185,
    "record": true,
    "recording_url": "https://storage.devotel.io/recordings/call_abc123.wav",
    "metadata": { "campaign": "retention" },
    "created_at": "2026-03-08T11:00:00Z",
    "answered_at": "2026-03-08T11:00:08Z",
    "ended_at": "2026-03-08T11:03:05Z"
  },
  "meta": {
    "request_id": "req_call_get",
    "timestamp": "2026-03-08T12:00:00Z"
  }
}

​
Hang Up Call

POST /v1/voice/calls/{id}/hangup Terminate an active call. If an AI agent is connected, it receives a graceful shutdown signal before the call is ended.
​
id
string
required
Call ID of the active call
curl -X POST https://orbit-api.devotel.io/api/v1/voice/calls/call_abc123/hangup \
  -H "X-API-Key: dv_live_sk_your_key_here"

{
  "data": {
    "id": "call_abc123",
    "status": "completed",
    "ended_at": "2026-03-08T12:05:00Z",
    "duration_seconds": 300
  },
  "meta": {
    "request_id": "req_hangup_001",
    "timestamp": "2026-03-08T12:05:00Z"
  }
}

​
Call Statuses

StatusDescription
initiatingCall is being set up
ringingDestination phone is ringing
in_progressCall is connected and active
completedCall ended normally
failedCall could not be connected
busyDestination returned busy signal
no_answerDestination did not answer within timeout
cancelledCall was cancelled before connection