Voice API

Initiate outbound calls, manage active calls, and access call recordings

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., [phone])

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": "[phone]",
    "from": "[phone]",
    "agent_id": "agt_abc123",
    "record": true,
    "webhook_url": "https://example.com/webhooks/calls",
    "metadata": { "campaign": "retention" }
  }'

201

{
  "data": {
    "id": "call_abc123",
    "to": "[phone]",
    "from": "[phone]",
    "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"

200

{
  "data": [
    {
      "id": "call_abc123",
      "to": "[phone]",
      "from": "[phone]",
      "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)

200

{
  "data": {
    "id": "call_abc123",
    "to": "[phone]",
    "from": "[phone]",
    "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"

200

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

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