Dialer API

The Dialer API runs outbound calling campaigns: preview, progressive, and predictive modes for human agents, plus agentless voice broadcast and AI-voice-agent dispatch. You create a campaign, attach contact lists, then either let the pacing engine dial (progressive / predictive) or pull the next contact yourself (preview). Live statistics, local-presence caller-ID coverage, and per-attempt dispositions round out the surface. Base path: /api/v1/dialer Authentication: API key (X-API-Key: dv_live_sk_…) or a Clerk session (Authorization: Bearer <token>). Scopes: read endpoints require dialer:read; create / update / delete endpoints require dialer:write. Response envelope: every endpoint returns { "data": …, "meta": { "request_id", "timestamp" } }. Errors return { "error": { "code", "message" } } (validation failures also carry error.issues). Request samples: the first ten operations below ship the six-language sample group (cURL, Node.js, Python, Go, Ruby, PHP — every operation up to POST /campaigns/{id}/dispositions); every later operation, and every read endpoint that only returns JSON, ships the cURL + TypeScript pair the sample-writing policy guarantees. Hero flows past the cut keep the full group inside Worked sequences below.

Outbound calls placed by the dialer egress only through Orbit’s wholesale voice path. The caller ID you set on a campaign must be a number your account owns (or one you’ve verified) — a foreign number is rejected with 422 UNVERIFIED_CALLER_ID on both create and update.

Using the SDKs

The Node SDK is the only client with typed dialer helpers today (the SDK index documents every other client as core-scope). Pick the preview claim with orbit.dialer.getNextCall() and dial it with orbit.dialer.dial() — worked call sequences for Python and Go (documented client.request / client.Request escape hatch) come later on this page under SDK call flows.

curl -G "https://api.orbit.devotel.io/api/v1/dialer/next-call" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  --data-urlencode "campaign_id=dcmp_abc"

import { Orbit } from "@devotel-orbit/node";

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

// Pull the next preview contact, then dial it.
const next = await orbit.dialer.getNextCall({ campaign_id: "dcmp_abc" });
if (next.data.contact) {
  await orbit.dialer.dial({
    campaign_id: "dcmp_abc",
    contact_id: next.data.contact.id,
  });
}

Returns the typed ApiResponse envelope. See the SDK index at SDK quickstart.

Campaign modes

`mode`	Who handles the answered call	Pacing
`preview`	A human agent, after reviewing the contact	Agent pulls each contact via `GET /next-call`, then calls `POST /dial`.
`progressive`	A human agent	One live dial per ready agent. Server-paced.
`predictive`	A human agent	Over-dials by `pacing_ratio`, bounded by the FCC abandon ceiling. Server-paced.
`agentless`	No agent — plays `broadcast_message_url` and hangs up	Server-paced broadcast.

dispatch_mode is a second axis. The default human fronts the call with a live operator. voice_agent connects each answered leg to the AI voice agent named by voice_agent_id; those campaigns are paced by POST /campaigns/:id/batch-dispatch instead of the human-agent scheduler.

Create a campaign

POST /api/v1/dialer/campaigns

Scope: dialer:write. Created in draft status — activate it later with PATCH /campaigns/:id.

string

required

Human-readable campaign name. 1–200 characters.

string

required

One of preview, progressive, predictive, agentless.

string

required

Caller ID presented on each dial, in E.164 format. Must be a number your account owns.

number

default:"1.2"

Predictive over-dial ratio. 0.8–3.0.

number

default:"0.03"

Rolling abandon-rate ceiling. Greater than 0 and at most 0.03 (the FCC 3% cap). See FCC abandon-rate ceiling.

number

default:"20"

Predictive pacing target — seconds to answer. 5–120.

string

default:"human"

human or voice_agent. voice_agent requires voice_agent_id.

string

AI voice agent that answers each leg when dispatch_mode='voice_agent'. Must reference an existing, non-archived voice agent in your workspace.

number

default:"10"

Maximum simultaneous in-flight legs a single batch-dispatch invocation may originate. 1–200.

array

default:"[]"

Skills an agent must hold to take this campaign’s calls. Accepts a string array (["billing","french"]) or per-skill objects ([{ "skill": "billing", "min_level": 3, "weight": 2 }]).

array

default:"[]"

Rotation pool of E.164 numbers for local-presence dialing. Every entry must be a number your account owns. Required (non-empty) when caller_id_strategy is not single.

string

default:"single"

single (always caller_id_e164), npa_match (present the pool number matching the lead’s area code), or round_robin.

string

HTTPS audio URL played on answer in agentless mode. Required for agentless; rejected for every other mode.

string

HTTPS audio URL dropped when answering-machine detection fires on an agent-driven dial. Not valid for agentless mode.

number

Per-campaign preview countdown the agent has to accept a contact. Only valid for preview mode; omit to use the platform default.

boolean

default:"false"

Record calls on this campaign. Requires recording_consent_acknowledged: true in the same request.

Affirms you have authority to record and the two-party-consent disclaimer will play. Required when recording_enabled is true. Internal API-key callers cannot acknowledge on behalf of an operator (401).

boolean

default:"false"

Request carrier answering-machine detection on each dial.

string

Voice application (UUID) bound to answered legs.

object

default:"{}"

Per-outcome retry backoff keyed by outcome bucket (no_answer, busy, machine, machine_silence, failed). Each entry sets retry delays (60–86400s) and max_attempts (0–10). Empty {} keeps the platform’s uniform retry schedule.

object

Human-agent guided-dialog script (ordered sections plus per-disposition branches). Omit to store the canonical empty script { "version": 1, "sections": [], "branches": {} }.

object

default:"{}"

Arbitrary key-value pairs stored on the campaign.

curl -X POST "https://api.orbit.devotel.io/api/v1/dialer/campaigns" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Q3 outbound — US East",
    "mode": "predictive",
    "caller_id_e164": "+12025551234",
    "caller_id_pool": ["+12025551234", "+13125550199"],
    "caller_id_strategy": "npa_match",
    "pacing_ratio": 1.2,
    "max_abandon_rate": 0.03,
    "preview_decision_seconds": 30,
    "retry_policy": {
      "no_answer": { "retry_after_seconds": 3600, "max_attempts": 3 },
      "busy": { "retry_after_seconds": 600, "max_attempts": 5 },
      "machine": { "retry_after_seconds": 21600, "max_attempts": 2 }
    },
    "recording_enabled": true,
    "recording_consent_acknowledged": true
  }'

import { Orbit } from "@devotel-orbit/node";

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

const campaign = await orbit.dialer.createCampaign({
  name: "Q3 outbound — US East",
  mode: "predictive",
  caller_id_e164: "+12025551234",
  caller_id_pool: ["+12025551234", "+13125550199"],
  caller_id_strategy: "npa_match",
  pacing_ratio: 1.2,
  max_abandon_rate: 0.03,
  preview_decision_seconds: 30,
  retry_policy: {
    no_answer: { retry_after_seconds: 3600, max_attempts: 3 },
    busy: { retry_after_seconds: 600, max_attempts: 5 },
    machine: { retry_after_seconds: 21600, max_attempts: 2 },
  },
  recording_enabled: true,
  recording_consent_acknowledged: true,
});
console.log("campaign:", campaign.data.id, campaign.data.status);

# Python SDK is core-scope — the dialer comes via client.request().
from orbit_sdk import OrbitClient

client = OrbitClient.from_env()

campaign = client.request(
    "POST",
    "/dialer/campaigns",
    json_body={
        "name": "Q3 outbound — US East",
        "mode": "predictive",
        "caller_id_e164": "+12025551234",
        "caller_id_pool": ["+12025551234", "+13125550199"],
        "caller_id_strategy": "npa_match",
        "pacing_ratio": 1.2,
        "max_abandon_rate": 0.03,
        "preview_decision_seconds": 30,
        "retry_policy": {
            "no_answer": {"retry_after_seconds": 3600, "max_attempts": 3},
            "busy": {"retry_after_seconds": 600, "max_attempts": 5},
            "machine": {"retry_after_seconds": 21600, "max_attempts": 2},
        },
        "recording_enabled": True,
        "recording_consent_acknowledged": True,
    },
)
print("campaign:", campaign["data"]["id"], campaign["data"]["status"])

// Typed helpers don't exist yet — client.Request reaches the route.
ctx := context.Background()

var campaign map[string]any
err := client.Request(ctx, "POST", "/dialer/campaigns",
    nil,
    map[string]any{
        "name":            "Q3 outbound — US East",
        "mode":            "predictive",
        "caller_id_e164":  "+12025551234",
        "caller_id_pool":  []string{"+12025551234", "+13125550199"},
        "caller_id_strategy": "npa_match",
        "pacing_ratio":         1.2,
        "max_abandon_rate":     0.03,
        "preview_decision_seconds": 30,
        "retry_policy": map[string]any{
            "no_answer": map[string]any{"retry_after_seconds": 3600, "max_attempts": 3},
            "busy":      map[string]any{"retry_after_seconds": 600, "max_attempts": 5},
            "machine":   map[string]any{"retry_after_seconds": 21600, "max_attempts": 2},
        },
        "recording_enabled":              true,
        "recording_consent_acknowledged": true,
    },
    &campaign, "")
if err != nil {
    // handle error
}
fmt.Println("campaign:", campaign["data"])

require "orbit_sdk"

client = OrbitSdk::Client.from_env

campaign = client.request(
  "POST",
  "/dialer/campaigns",
  json_body: {
    name: "Q3 outbound — US East",
    mode: "predictive",
    caller_id_e164: "+12025551234",
    caller_id_pool: ["+12025551234", "+13125550199"],
    caller_id_strategy: "npa_match",
    pacing_ratio: 1.2,
    max_abandon_rate: 0.03,
    preview_decision_seconds: 30,
    retry_policy: {
      no_answer: { retry_after_seconds: 3600, max_attempts: 3 },
      busy: { retry_after_seconds: 600, max_attempts: 5 },
      machine: { retry_after_seconds: 21600, max_attempts: 2 }
    },
    recording_enabled: true,
    recording_consent_acknowledged: true
  }
)
puts "campaign: #{campaign.dig("data", "id")} #{campaign.dig("data", "status")}"

<?php
use Devotel\Orbit\OrbitClient;

$client = OrbitClient::fromEnv();

$campaign = $client->request(
    method: "POST",
    path: "/dialer/campaigns",
    jsonBody: [
        "name" => "Q3 outbound — US East",
        "mode" => "predictive",
        "caller_id_e164" => "+12025551234",
        "caller_id_pool" => ["+12025551234", "+13125550199"],
        "caller_id_strategy" => "npa_match",
        "pacing_ratio" => 1.2,
        "max_abandon_rate" => 0.03,
        "preview_decision_seconds" => 30,
        "retry_policy" => [
            "no_answer" => ["retry_after_seconds" => 3600, "max_attempts" => 3],
            "busy"      => ["retry_after_seconds" => 600,  "max_attempts" => 5],
            "machine"   => ["retry_after_seconds" => 21600, "max_attempts" => 2],
        ],
        "recording_enabled" => true,
        "recording_consent_acknowledged" => true,
    ],
);
echo "campaign: " . $campaign["data"]["id"] . " " . $campaign["data"]["status"] . PHP_EOL;

max_abandon_rate is capped at 0.03 (3%) per the FCC Telemarketing Sales Rule — a create that sends a higher value fails validation with 422 VALIDATION_ERROR. See FCC abandon-rate ceiling.

201 Created

{
  "data": {
    "id": "dcmp_abc",
    "name": "Q3 outbound — US East",
    "mode": "predictive",
    "status": "draft",
    "caller_id_e164": "+12025551234",
    "pacing_ratio": 1.2,
    "max_abandon_rate": 0.03,
    "dispatch_mode": "human",
    "concurrency_limit": 10,
    "caller_id_strategy": "single",
    "campaign_script": { "version": 1, "sections": [], "branches": {} },
    "recording_enabled": true,
    "recording_consent_acknowledged_at": "2026-06-18T12:00:00Z",
    "recording_consent_acknowledged_by": "user_123"
  },
  "meta": { "request_id": "req_abc123", "timestamp": "2026-06-18T12:00:00Z" }
}

Errors

Status	`error.code`	Cause
`401`	`RECORDING_CONSENT_REQUIRED`	`recording_consent_acknowledged: true` sent by a non-operator (API-key) caller.
`422`	`VALIDATION_ERROR`	Schema failure — `max_abandon_rate` above `0.03`, `agentless` without `broadcast_message_url`, `voice_agent` without `voice_agent_id`, unknown `voice_agent_id`, recording without consent.
`422`	`UNVERIFIED_CALLER_ID`	`caller_id_e164` or a `caller_id_pool` entry is a number your account doesn’t own and hasn’t verified as an outbound caller ID.
`503`	`TENANT_SCHEMA_INCOMPLETE`	Workspace not yet provisioned for the dialer.

List campaigns

GET /api/v1/dialer/campaigns

Scope: dialer:read. Cursor-paginated, newest first. Soft-deleted campaigns are excluded. Query parameters

Name	Type	Notes
`limit`	integer (1–100)	Default 20.
`cursor`	string	Opaque cursor from the previous response’s `next_cursor`.
`status`	string	Optional filter: `draft`, `active`, `paused`, `completed`, `aborted`. Unknown values are ignored (no filter).

Each row carries a bounded contacts_total / contacts_connected rollup. When a campaign’s contact count exceeds the scan cap, contacts_count_capped is true and the totals are a floor; the envelope’s contacts_count_capped_at reports where the count stops being exact.

curl -G "https://api.orbit.devotel.io/api/v1/dialer/campaigns" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  --data-urlencode "status=active" \
  --data-urlencode "limit=20"

import { Orbit } from "@devotel-orbit/node";

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

// Filter by status over the escape hatch — listCampaigns() takes
// cursor / limit only.
const page = await orbit.request<{ data: { items: unknown[]; next_cursor: string | null; has_more: boolean } }>(
  "GET",
  "/dialer/campaigns?status=active&limit=20",
);
console.log("campaigns:", page.data.items.length, "has_more:", page.data.has_more);

// Or page through everything with the typed cursor helper:
// const page = await orbit.dialer.listCampaigns({ limit: 20 });

{
  "data": {
    "items": [
      {
        "id": "dcmp_abc",
        "name": "Q3 outbound — US East",
        "mode": "predictive",
        "status": "active",
        "caller_id_e164": "+12025551234",
        "pacing_ratio": 1.2,
        "max_abandon_rate": 0.03,
        "abandon_rate_30d": 0.018,
        "contacts_total": 4120,
        "contacts_connected": 386,
        "contacts_count_capped": false,
        "campaign_script": { "version": 1, "sections": [], "branches": {} },
        "created_at": "2026-06-18T10:30:00Z"
      }
    ],
    "next_cursor": "MjAyNi0wNi0xOFQxMDozMDowMC4wMDBa",
    "has_more": false,
    "contacts_count_capped_at": 10000
  },
  "meta": { "request_id": "req_abc123", "timestamp": "2026-06-18T12:00:00Z" }
}

On a workspace that has never created a campaign — or one provisioned before the dialer shipped — this endpoint returns an empty list (items: []) rather than an error, so an empty-state UI renders cleanly.

Campaign stats summary

GET /api/v1/dialer/campaigns/stats

Scope: dialer:read. Totals across every non-deleted campaign — the source of truth for a dashboard KPI strip, independent of pagination. Query parameters

Name	Type	Notes
`tz`	string	IANA timezone (e.g. `America/New_York`) used for the `completed_today` day boundary. Defaults to `UTC`.

curl -G "https://api.orbit.devotel.io/api/v1/dialer/campaigns/stats" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  --data-urlencode "tz=America/New_York"

import { Orbit } from "@devotel-orbit/node";

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

// Workspace-wide counts — escape hatch (no typed helper yet).
const stats = await orbit.request<{ data: { active: number; paused: number; completed_today: number; avg_abandon_rate: number | null } }>(
  "GET",
  "/dialer/campaigns/stats?tz=America/New_York",
);
console.log("active:", stats.data.active, "abandon:", stats.data.avg_abandon_rate);

{
  "data": {
    "active": 3,
    "paused": 1,
    "completed_today": 2,
    "avg_abandon_rate": 0.021
  },
  "meta": { "request_id": "req_abc123", "timestamp": "2026-06-18T12:00:00Z" }
}

avg_abandon_rate is null when no active campaign carries a 30-day rate.

Get a campaign

GET /api/v1/dialer/campaigns/{id}

Scope: dialer:read. Returns the full campaign row; campaign_script is always the canonical shape.

curl -X GET "https://api.orbit.devotel.io/api/v1/dialer/campaigns/dcmp_abc" \
  -H "X-API-Key: dv_live_sk_your_key_here"

import { Orbit } from "@devotel-orbit/node";

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

const campaign = await orbit.dialer.getCampaign("dcmp_abc");
console.log(campaign.data.status, campaign.data.caller_id_e164);

Errors

Status	`error.code`	Cause
`404`	`NOT_FOUND`	Campaign not found or soft-deleted.

Update a campaign

PATCH /api/v1/dialer/campaigns/{id}

Scope: dialer:write. Partial update — only the fields you send change. Accepts the same fields as create, plus status.

string

active, paused, completed, or aborted. aborted is the operator-initiated terminal state — once aborted, a campaign cannot be re-activated. Transitioning to active is blocked while your workspace’s compliance emergency-stop is engaged.

Nullable PATCH fields: voice_agent_id, voicemail_message_url, preview_decision_seconds, and call_script_id accept null to clear them. Sending caller_id_e164 or any caller_id_pool entry re-runs the ownership check. Sending retry_policy or campaign_script replaces the whole object.

# Activate a campaign
curl -X PATCH "https://api.orbit.devotel.io/api/v1/dialer/campaigns/dcmp_abc" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "status": "active" }'

# Clear a nullable field — send explicit null to unset it
curl -X PATCH "https://api.orbit.devotel.io/api/v1/dialer/campaigns/dcmp_abc" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "voice_agent_id": null }'

import { Orbit } from "@devotel-orbit/node";

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

// Activate.
await orbit.dialer.updateCampaign("dcmp_abc", { status: "active" });

// Clearing a nullable field takes an explicit null (omit leaves it set).
await orbit.dialer.updateCampaign("dcmp_abc", { voice_agent_id: null });

# Python SDK is core-scope — the dialer comes via client.request().
from orbit_sdk import OrbitClient

client = OrbitClient.from_env()

# Activate.
client.request(
    "PATCH",
    "/dialer/campaigns/dcmp_abc",
    json_body={"status": "active"},
)

# Clear a nullable field: explicit None serialises to null; omitting
# the key leaves the stored value untouched.
client.request(
    "PATCH",
    "/dialer/campaigns/dcmp_abc",
    json_body={"voice_agent_id": None},
)

// Typed helpers don't exist yet — client.Request reaches the route.
ctx := context.Background()

var updated map[string]any

// Activate.
err := client.Request(ctx, "PATCH", "/dialer/campaigns/dcmp_abc",
    nil, map[string]any{"status": "active"}, &updated, "")

// Clear a nullable field: null clears it; an absent key is untouched.
err = client.Request(ctx, "PATCH", "/dialer/campaigns/dcmp_abc",
    nil, map[string]any{"voice_agent_id": nil}, &updated, "")

require "orbit_sdk"

client = OrbitSdk::Client.from_env

# Activate.
client.request(
  "PATCH",
  "/dialer/campaigns/dcmp_abc",
  json_body: { status: "active" }
)

# Clear a nullable field: nil serialises to JSON null; an omitted key
# leaves the stored value untouched.
client.request(
  "PATCH",
  "/dialer/campaigns/dcmp_abc",
  json_body: { voice_agent_id: nil }
)

<?php
use Devotel\Orbit\OrbitClient;

$client = OrbitClient::fromEnv();

// Activate.
$client->request(
    method: "PATCH",
    path: "/dialer/campaigns/dcmp_abc",
    jsonBody: ["status" => "active"],
);

// Clear a nullable field: null clears it; an absent key is untouched.
$client->request(
    method: "PATCH",
    path: "/dialer/campaigns/dcmp_abc",
    jsonBody: ["voice_agent_id" => null],
);

Errors

Status	`error.code`	Cause
`401`	`RECORDING_CONSENT_REQUIRED`	`recording_consent_acknowledged: true` sent by a non-operator (API-key) caller. Recording a call needs an operator identity to attribute the acknowledgement to.
`403`	`ORG_COMPLIANCE_EMERGENCY_STOP`	Tried to activate while the workspace compliance kill switch is on.
`404`	`NOT_FOUND`	Campaign not found or soft-deleted.
`409`	`CAMPAIGN_ABORTED`	Tried to move `status` away from `aborted`. `aborted` is terminal — create a new campaign instead.
`409`	`RECORDING_CONSENT_REQUIRED`	Activating a campaign that records calls but has no consent acknowledgement on file. Send `recording_consent_acknowledged: true` in the same request.
`422`	`VALIDATION_ERROR`	Schema failure (same rules as create), e.g. `max_abandon_rate` above `0.03`, or a `voice_agent_id` that doesn’t reference an existing voice agent.
`422`	`UNVERIFIED_CALLER_ID`	A changed `caller_id_e164` or `caller_id_pool` entry is a number your account doesn’t own and hasn’t verified.
`422`	`VOICEMAIL_DROP_FORBIDDEN_AGENTLESS`	Set `voicemail_message_url` on an `agentless` campaign. Voicemail drop applies only to agent-driven modes; agentless campaigns use `broadcast_message_url`.
`422`	`VOICE_AGENT_MISSING`	The update would leave `dispatch_mode: 'voice_agent'` with no `voice_agent_id`. Set one in the same request, or switch `dispatch_mode` back to `human`.
`503`	`TENANT_SCHEMA_INCOMPLETE`	Workspace not yet provisioned for the dialer.

Soft-delete a campaign

DELETE /api/v1/dialer/campaigns/{id}

Scope: dialer:write. Soft-deletes the campaign and flips its pending contacts to archived. Terminal contacts (connected / failed / dnc / exhausted / wrong_number) are preserved untouched as a compliance audit trail. Campaign, lists, and contacts commit in one transaction.

curl -X DELETE "https://api.orbit.devotel.io/api/v1/dialer/campaigns/dcmp_abc" \
  -H "X-API-Key: dv_live_sk_your_key_here"

import { Orbit } from "@devotel-orbit/node";

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

// 204 No Content — the helper resolves void on success, throws on 409.
await orbit.dialer.deleteCampaign("dcmp_abc");

Errors

Status	`error.code`	Cause
`404`	`NOT_FOUND`	Campaign not found or already soft-deleted.
`409`	`DIALER_CAMPAIGN_IN_FLIGHT`	A contact is currently `dialing`. Pause the campaign, let live legs finish, then retry. `details.in_flight_contacts` returns the count.

List contact lists

GET /api/v1/dialer/campaigns/{id}/lists

Scope: dialer:read. Cursor-paginated. Each list carries total_contacts and a live contacts_dialing badge. Query parameters

Name	Type	Notes
`limit`	integer (1–100)	Default 20.
`cursor`	string	Opaque cursor from the previous response’s `next_cursor`.

curl -G "https://api.orbit.devotel.io/api/v1/dialer/campaigns/dcmp_abc/lists" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  --data-urlencode "limit=20"

import { Orbit } from "@devotel-orbit/node";

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

// Escape hatch — no typed helper for the lists index yet.
const lists = await orbit.request<{ data: { items: unknown[]; next_cursor: string | null; has_more: boolean } }>(
  "GET",
  "/dialer/campaigns/dcmp_abc/lists?limit=20",
);
console.log("lists:", lists.data.items.length);

{
  "data": {
    "items": [
      {
        "id": "dlst_abc",
        "name": "June leads — East",
        "total_contacts": 2000,
        "contacts_dialing": 4,
        "status": "active",
        "created_at": "2026-06-18T10:30:00Z",
        "updated_at": "2026-06-18T11:00:00Z"
      }
    ],
    "next_cursor": null,
    "has_more": false
  },
  "meta": { "request_id": "req_abc123", "timestamp": "2026-06-18T12:00:00Z" }
}

Upload a contact list

POST /api/v1/dialer/campaigns/{id}/lists

Scope: dialer:write. Attaches a new contact list to the campaign and enqueues its contacts.

string

required

List name. 1–200 characters.

array

required

Contacts to dial. At least one. Each entry: phone_e164 (required, E.164), display_name (optional, ≤200 chars), contact_id (optional, links to a CRM contact). Duplicate phone_e164 values within the upload are de-duplicated (first occurrence wins) and reported back.

number

default:"5"

Maximum dial attempts before a contact is exhausted. 1–20.

curl -X POST "https://api.orbit.devotel.io/api/v1/dialer/campaigns/dcmp_abc/lists" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "June leads — East",
    "max_attempts_per_contact": 5,
    "contacts": [
      { "phone_e164": "+14155552671", "display_name": "Jane Doe", "contact_id": "con_abc" }
    ]
  }'

import { Orbit } from "@devotel-orbit/node";

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

// List upload is a JSON body (not multipart) — duplicates in the same
// request are skipped and reported in the response.
const list = await orbit.dialer.uploadList("dcmp_abc", {
  name: "June leads — East",
  max_attempts_per_contact: 5,
  contacts: [
    { phone_e164: "+14155552671", display_name: "Jane Doe", contact_id: "con_abc" },
  ],
});
console.log("list:", list.data.list_id, "inserted:", list.data.contacts_inserted);

# Python SDK is core-scope — the dialer comes via client.request().
from orbit_sdk import OrbitClient

client = OrbitClient.from_env()

# List upload is a JSON body (not multipart).
contacts = [
    {"phone_e164": "+14155552671", "display_name": "Jane Doe", "contact_id": "con_abc"},
]
result = client.request(
    "POST",
    "/dialer/campaigns/dcmp_abc/lists",
    json_body={
        "name": "June leads — East",
        "max_attempts_per_contact": 5,
        "contacts": contacts,
    },
)
print("list:", result["data"]["list_id"], "inserted:", result["data"]["contacts_inserted"])

// Typed helpers don't exist yet — client.Request reaches the route.
ctx := context.Background()

var result map[string]any
err := client.Request(ctx, "POST",
    "/dialer/campaigns/dcmp_abc/lists",
    nil,
    map[string]any{
        "name":                      "June leads — East",
        "max_attempts_per_contact": 5,
        "contacts": []map[string]any{
            {"phone_e164": "+14155552671", "display_name": "Jane Doe", "contact_id": "con_abc"},
        },
    },
    &result, "")
if err != nil {
    // handle error
}
fmt.Println("inserted:", result["data"])

require "orbit_sdk"

client = OrbitSdk::Client.from_env

result = client.request(
  "POST",
  "/dialer/campaigns/dcmp_abc/lists",
  json_body: {
    name: "June leads — East",
    max_attempts_per_contact: 5,
    contacts: [
      { phone_e164: "+14155552671", display_name: "Jane Doe", contact_id: "con_abc" }
    ]
  }
)
puts "list: #{result.dig("data", "list_id")} inserted: #{result.dig("data", "contacts_inserted")}"

<?php
use Devotel\Orbit\OrbitClient;

$client = OrbitClient::fromEnv();

$result = $client->request(
    method: "POST",
    path: "/dialer/campaigns/dcmp_abc/lists",
    jsonBody: [
        "name" => "June leads — East",
        "max_attempts_per_contact" => 5,
        "contacts" => [
            ["phone_e164" => "+14155552671", "display_name" => "Jane Doe", "contact_id" => "con_abc"],
        ],
    ],
);
echo "list: " . $result["data"]["list_id"] . " inserted: " . $result["data"]["contacts_inserted"] . PHP_EOL;

Errors

Status	`error.code`	Cause
`404`	`NOT_FOUND`	Campaign not found or soft-deleted.
`422`	`VALIDATION_ERROR`	Empty `contacts`, more than the per-upload cap, or an invalid `phone_e164`.

Soft-delete a contact list

DELETE /api/v1/dialer/campaigns/{id}/lists/{listId}

Scope: dialer:write. Soft-deletes one list within the campaign. Pending contacts in the list flip to archived; terminal contacts are preserved as audit trail.

curl -X DELETE "https://api.orbit.devotel.io/api/v1/dialer/campaigns/dcmp_abc/lists/dlst_abc" \
  -H "X-API-Key: dv_live_sk_your_key_here"

import { Orbit } from "@devotel-orbit/node";

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

// 204 No Content — resolves void on success, throws on 409.
await orbit.dialer.deleteList("dcmp_abc", "dlst_abc");

Errors

Status	`error.code`	Cause
`404`	`NOT_FOUND`	List not found, not in this campaign, or already soft-deleted.
`409`	`DIALER_LIST_IN_FLIGHT`	A contact in the list is currently `dialing`.

Campaign live stats

GET /api/v1/dialer/campaigns/{id}/stats

Scope: dialer:read. Wallboard detail for one campaign: per-status contact breakdown, a 24-hour call-outcome rollup with average handle time, and a rolling 30-minute abandonment rate that mirrors what the pacing engine throttles against.

curl -X GET "https://api.orbit.devotel.io/api/v1/dialer/campaigns/dcmp_abc/stats" \
  -H "X-API-Key: dv_live_sk_your_key_here"

import { Orbit } from "@devotel-orbit/node";

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

const stats = await orbit.dialer.getCampaignStats("dcmp_abc");
console.log("dialing:", stats.data.contacts_dialing, "30m abandon:", stats.data["last_30m"]);

{
  "data": {
    "id": "dcmp_abc",
    "name": "Q3 outbound — US East",
    "mode": "predictive",
    "status": "active",
    "pacing_ratio": 1.2,
    "abandon_rate_30d": 0.018,
    "max_abandon_rate": 0.03,
    "contacts_pending": 1500,
    "contacts_dialing": 6,
    "contacts_connected": 386,
    "contacts_failed": 120,
    "contacts_dnc": 14,
    "contacts_timezone_blocked": 40,
    "contacts_exhausted": 80,
    "contacts_archived": 0,
    "contacts_callback_scheduled": 22,
    "contacts_wrong_number": 9,
    "contacts_total": 2177,
    "contacts_count_capped": false,
    "last_24h": {
      "calls_connected": 410,
      "calls_no_answer": 220,
      "calls_busy": 35,
      "calls_voicemail": 60,
      "calls_amd_detected": 18,
      "calls_abandoned": 7,
      "avg_handle_time_seconds": 142.4,
      "total_attempts": 750
    },
    "last_30m": {
      "abandoned_count": 1,
      "connected_count": 48,
      "abandon_rate_30m": 0.0208
    }
  },
  "meta": { "request_id": "req_abc123", "timestamp": "2026-06-18T12:00:00Z" }
}

avg_handle_time_seconds is null until a connected call has terminated. contacts_count_capped is true when the contact set exceeds the scan cap (the totals are then a floor). Errors

Status	`error.code`	Cause
`404`	`NOT_FOUND`	Campaign not found or soft-deleted.

Caller-ID coverage

GET /api/v1/dialer/campaigns/{id}/caller-id-coverage

Scope: dialer:read. Local-presence analytics for one campaign: which destination area codes (NPAs) your caller-ID pool can present locally, the rolling answer rate per destination NPA, and the highest-volume under-covered NPAs to add a local number for. Read-only; originates no calls. North American Numbering Plan (+1) numbers only.

curl -X GET "https://api.orbit.devotel.io/api/v1/dialer/campaigns/dcmp_abc/caller-id-coverage" \
  -H "X-API-Key: dv_live_sk_your_key_here"

import { Orbit } from "@devotel-orbit/node";

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

// Escape hatch — no typed helper for coverage yet. The pre-launch audit
// walkthrough is at /guides/caller-id-coverage-validation.
const coverage = await orbit.request<{ data: Record<string, unknown> }>(
  "GET",
  "/dialer/campaigns/dcmp_abc/caller-id-coverage",
);
console.log(coverage.data);

Errors

Status	`error.code`	Cause
`404`	`NOT_FOUND`	Campaign not found or soft-deleted.

Voice-agent campaign rollup

GET /api/v1/dialer/voice-agents/{agentId}/campaigns

Scope: dialer:read. Lists the dispatch_mode='voice_agent' campaigns bound to one AI voice agent, with a per-campaign contact and call-outcome rollup over a rolling window. Cursor-paginated (limit / cursor, next_cursor / has_more). Human-mode campaigns never appear here. The envelope discloses contacts_count_capped_at and rollup_window_days. Returns a zeroed rollup (campaign_count: 0) for an unprovisioned workspace rather than an error.

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

import { Orbit } from "@devotel-orbit/node";

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

// Escape hatch — no typed helper for the per-agent rollup yet.
const rollup = await orbit.request<{ data: Record<string, unknown> }>(
  "GET",
  "/dialer/voice-agents/agt_xyz/campaigns",
);
console.log(rollup.data);

Submit a disposition

POST /api/v1/dialer/campaigns/{id}/dispositions

Scope: dialer:write. An agent submits the outcome of a dial attempt; the platform routes the contact’s lifecycle status from the disposition (for example do_not_call adds the number to your do-not-call list, callback_later reschedules the contact).

string

required

The attempt_id returned when the dial leg was placed (from POST /dial or the batch-dispatch legs payload).

string

required

Agent-selected disposition string (1–100 chars). The routing matrix matches it case-insensitively — see Dialer Dispositions.

string

ISO-8601 timestamp. Required when the disposition reschedules a callback (callback_later / callback). Must be in the future and at most 90 days ahead.

string

Free-form agent notes, up to 2000 characters.

The full disposition-to-status matrix and side effects (do-not-call writes, callback scheduling, connect-rate accounting) are documented on the Dialer Dispositions page.

curl -X POST "https://api.orbit.devotel.io/api/v1/dialer/campaigns/dcmp_abc/dispositions" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "attempt_id": "datt_abc123",
    "disposition": "callback_later",
    "callback_scheduled_at": "2026-08-31T18:30:00Z",
    "notes": "Customer asked for an evening callback."
  }'

import { Orbit } from "@devotel-orbit/node";

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

const disposition = await orbit.dialer.submitDisposition("dcmp_abc", {
  attempt_id: "datt_abc123",
  disposition: "callback_later",
  callback_scheduled_at: "2026-08-31T18:30:00Z",
  notes: "Customer asked for an evening callback.",
});
console.log("status:", disposition.data.status);

# Python SDK is core-scope — the dialer comes via client.request().
from orbit_sdk import OrbitClient

client = OrbitClient.from_env()

disposition = client.request(
    "POST",
    "/dialer/campaigns/dcmp_abc/dispositions",
    json_body={
        "attempt_id": "datt_abc123",
        "disposition": "callback_later",
        "callback_scheduled_at": "2026-08-31T18:30:00Z",
        "notes": "Customer asked for an evening callback.",
    },
)
print("status:", disposition["data"]["status"])

// Typed helpers don't exist yet — client.Request reaches the route.
ctx := context.Background()

var disposition map[string]any
err := client.Request(ctx, "POST",
    "/dialer/campaigns/dcmp_abc/dispositions",
    nil,
    map[string]any{
        "attempt_id":            "datt_abc123",
        "disposition":           "callback_later",
        "callback_scheduled_at": "2026-08-31T18:30:00Z",
        "notes":                 "Customer asked for an evening callback.",
    },
    &disposition, "")
if err != nil {
    // handle error
}
fmt.Println("status:", disposition["data"])

require "orbit_sdk"

client = OrbitSdk::Client.from_env

disposition = client.request(
  "POST",
  "/dialer/campaigns/dcmp_abc/dispositions",
  json_body: {
    attempt_id: "datt_abc123",
    disposition: "callback_later",
    callback_scheduled_at: "2026-08-31T18:30:00Z",
    notes: "Customer asked for an evening callback."
  }
)
puts "status: #{disposition.dig("data", "status")}"

<?php
use Devotel\Orbit\OrbitClient;

$client = OrbitClient::fromEnv();

$disposition = $client->request(
    method: "POST",
    path: "/dialer/campaigns/dcmp_abc/dispositions",
    jsonBody: [
        "attempt_id" => "datt_abc123",
        "disposition" => "callback_later",
        "callback_scheduled_at" => "2026-08-31T18:30:00Z",
        "notes" => "Customer asked for an evening callback.",
    ],
);
echo "status: " . $disposition["data"]["status"] . PHP_EOL;

200 OK

{
  "data": {
    "attempt_id": "datt_abc123",
    "disposition": "callback_later",
    "status": "callback_scheduled",
    "callback_scheduled_at": "2026-08-31T18:30:00Z"
  },
  "meta": { "request_id": "req_abc123", "timestamp": "2026-08-31T12:00:00Z" }
}

Errors

Status	`error.code`	Cause
`404`	`NOT_FOUND`	`attempt_id` not found in this campaign.
`422`	`VALIDATION_ERROR`	`callback_scheduled_at` missing on a callback disposition, in the past, or more than 90 days ahead.

Get the next contact (preview mode)

GET /api/v1/dialer/next-call

Scope: dialer:read. For preview-mode campaigns: atomically claims the next eligible contact so two agents polling at once never receive the same row. Progressive / predictive campaigns return 204 No Content — the pacing engine dials those instead. A preview contact stuck dialing for more than five minutes (the agent abandoned the tab) becomes re-claimable. The claim + dial round trip is worked end to end in every supported language under SDK call flows below.

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/dialer/next-call?campaign_id=dcmp_abc" \
  -H "X-API-Key: dv_live_sk_your_key_here"

200 OK

{
  "data": {
    "contact": {
      "id": "dlc_xyz",
      "phone_e164": "+14155552671",
      "display_name": "Jane Doe",
      "contact_id": "con_abc",
      "attempts": 0
    }
  },
  "meta": { "request_id": "req_abc123", "timestamp": "2026-08-31T12:00:00Z" }
}

204 No Content — the campaign is progressive or predictive (the pacing engine handles dialing). Errors

Status	`error.code`	Cause
`400`	`BAD_REQUEST`	`campaign_id` query parameter missing.
`404`	`NOT_FOUND`	Campaign not found or not `active`.

Place a preview dial

POST /api/v1/dialer/dial

Scope: dialer:write. Originates the dial leg for a contact the agent claimed via GET /next-call. Only valid for active preview campaigns; progressive / predictive campaigns dial through the pacing engine. Requires an authenticated operator — an API-key caller cannot dial on behalf of an agent (401 AGENT_REQUIRED). The claim + dial round trip is worked end to end in every supported language under SDK call flows below.

string

required

The preview campaign to dial within.

string

required

The contact (from GET /next-call) to dial.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/dialer/dial" \
  -H "Authorization: Bearer $OPERATOR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "campaign_id": "dcmp_abc",
    "contact_id": "dlc_xyz"
  }'

202 Accepted

{
  "data": {
    "attempt_id": "datt_abc123",
    "jambonz_call_sid": "call_abc",
    "contact_id": "dlc_xyz",
    "campaign_id": "dcmp_abc"
  },
  "meta": { "request_id": "req_abc123", "timestamp": "2026-08-31T12:00:00Z" }
}

Keep the response attempt_id — it’s what the agent submits back on POST /campaigns/:id/dispositions once the call ends. Errors

Status	`error.code`	Cause
`401`	`AGENT_REQUIRED`	Called by a non-operator (API-key) caller.
`404`	`NOT_FOUND`	No active campaign, or the contact does not exist.
`409`	`WRONG_DIALER_MODE`	Campaign is not in preview mode (other modes dial via the pacing engine).
`409`	`CLAIM_NOT_HELD`	The contact is no longer in `dialing` state — re-fetch via `GET /next-call` first.
`422`	`VALIDATION_ERROR`	Missing `campaign_id` / `contact_id`.
`502`	`CALL_FAILED`	The voice control plane rejected the dial — the contact was re-queued. `error.details` carries the `attempt_id` for correlation.
`503`	`SERVICE_UNAVAILABLE`	The dialer’s voice control-plane application is not configured. Contact support.
`503`	`SOFTSWITCH_UNHEALTHY`	Outbound voice is failing above the health threshold; dispatch is paused and the contact claim is released. Re-fetch via `GET /next-call` to retry once it recovers.
`503`	`TENANT_SCHEMA_INCOMPLETE`	Workspace not yet provisioned for the dialer.

Batch-dispatch voice-agent legs

POST /api/v1/dialer/campaigns/{id}/batch-dispatch

Scope: dialer:write. Paces a dispatch_mode='voice_agent' campaign: originates up to the campaign’s concurrency_limit simultaneous AI-voice-agent legs. Each answered leg connects to the campaign’s voice_agent_id.

number

Optional per-invocation cap on legs to originate. 1–200. The effective cap is the smaller of this and the campaign’s concurrency_limit.

curl -X POST "https://api.orbit.devotel.io/api/v1/dialer/campaigns/dcmp_abc/batch-dispatch" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "max_legs": 25 }'

import { Orbit } from "@devotel-orbit/node";

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

type BatchDispatchLeg = {
  contact_id: string;
  attempt_id: string;
  jambonz_call_sid: string | null;
  ok: boolean;
  error?: string;
};

// Escape hatch — no typed helper for batch-dispatch yet.
const batch = await orbit.request<{ data: { claimed: number; legs: BatchDispatchLeg[] } }>(
  "POST",
  "/dialer/campaigns/dcmp_abc/batch-dispatch",
  { max_legs: 25 },
);
const failed = batch.data.legs.filter((leg) => !leg.ok);
console.log(`claimed ${batch.data.claimed}, failed ${failed.length}`);

# Python SDK is core-scope — the dialer comes via client.request().
from orbit_sdk import OrbitClient

client = OrbitClient.from_env()

batch = client.request(
    "POST",
    "/dialer/campaigns/dcmp_abc/batch-dispatch",
    json_body={"max_legs": 25},
)
failed = [leg for leg in batch["data"]["legs"] if not leg["ok"]]
print(f"claimed {batch['data']['claimed']}, failed {len(failed)}")

// Typed helpers don't exist yet — client.Request reaches the route.
ctx := context.Background()

var batch map[string]any
err := client.Request(ctx, "POST",
    "/dialer/campaigns/dcmp_abc/batch-dispatch",
    nil, map[string]any{"max_legs": 25}, &batch, "")
if err != nil {
    // handle error
}
fmt.Println("claimed:", batch["data"])

require "orbit_sdk"

client = OrbitSdk::Client.from_env

batch = client.request(
  "POST",
  "/dialer/campaigns/dcmp_abc/batch-dispatch",
  json_body: { max_legs: 25 }
)
failed = batch.dig("data", "legs").reject { |leg| leg["ok"] }
puts "claimed #{batch.dig("data", "claimed")}, failed #{failed.size}"

<?php
use Devotel\Orbit\OrbitClient;

$client = OrbitClient::fromEnv();

$batch = $client->request(
    method: "POST",
    path: "/dialer/campaigns/dcmp_abc/batch-dispatch",
    jsonBody: ["max_legs" => 25],
);
$failed = array_filter($batch["data"]["legs"], fn($leg) => !$leg["ok"]);
echo "claimed " . $batch["data"]["claimed"] . ", failed " . count($failed) . PHP_EOL;

A successful call returns one of three statuses:

202 Accepted — every claimed leg was originated.
207 Multi-Status — some legs originated and some failed. Inspect each legs[].ok for the per-leg result.
204 No Content — no eligible contacts were pending, so nothing was dispatched on this tick.

202 Accepted / 207 Multi-Status

{
  "data": {
    "campaign_id": "dcmp_abc",
    "voice_agent_id": "agt_xyz",
    "claimed": 10,
    "legs": [
      {
        "contact_id": "dlc_1",
        "attempt_id": "datt_1",
        "jambonz_call_sid": "call_abc",
        "ok": true
      },
      {
        "contact_id": "dlc_2",
        "attempt_id": "datt_2",
        "jambonz_call_sid": null,
        "ok": false,
        "error": "compliance_deferred:TCPA_DIALING_WINDOW_BLOCKED"
      }
    ]
  },
  "meta": { "request_id": "req_abc123", "timestamp": "2026-08-31T12:00:00Z" }
}

204 No Content — no pending contacts to dispatch on this tick. Errors

Status	`error.code`	Cause
`400`	`BAD_REQUEST`	Campaign id missing.
`404`	`NOT_FOUND`	Campaign not found.
`409`	`WRONG_DISPATCH_MODE`	Campaign’s `dispatch_mode` is not `voice_agent`. Human campaigns dial via `/dial` (preview) or the pacing engine (progressive / predictive).
`409`	`VOICE_AGENT_MISSING`	`dispatch_mode` is `voice_agent` but no `voice_agent_id` is set. PATCH one onto the campaign first.
`409`	`CAMPAIGN_NOT_ACTIVE`	Campaign status is not `active`. Activate it with `PATCH /campaigns/:id` before dispatching.
`422`	`VALIDATION_ERROR`	`max_legs` out of range.
`503`	`SERVICE_UNAVAILABLE`	The dialer’s voice control-plane application is not configured. Contact support.
`503`	`SOFTSWITCH_UNHEALTHY`	Outbound voice is failing above the health threshold; the batch is paused and every claimed contact is released back to pending.
`503`	`TENANT_SCHEMA_INCOMPLETE`	Workspace not yet provisioned for the dialer.

Worked sequences

The trim above cuts every operation after the fifteenth down to the cURL + TypeScript pair. The hero flows past that cut keep the full six-language group here. The preview-dial chain — claim one contact with GET /next-call, originate its leg with POST /dial, then submit the outcome with POST /campaigns/:id/dispositions — is the canonical dialer loop: poll a claim, bridge it, record what happened, repeat. It is the whole operator turn of a preview campaign in three calls. Each step below carries the previous step’s response forward: data.contact.id from the claim feeds the dial, and the dial’s attempt_id feeds the disposition, so one claimed contact is dialed and closed exactly once.

1. Claim the next contact

curl -G "https://api.orbit.devotel.io/api/v1/dialer/next-call" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  --data-urlencode "campaign_id=dcmp_abc"

import { Orbit } from "@devotel-orbit/node";

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

const claim = await orbit.dialer.getNextCall({ campaign_id: "dcmp_abc" });
// claim.data.contact.id ("dlc_xyz") feeds steps 2 and 3.
console.log("claimed:", claim.data.contact?.id);

# Python SDK is core-scope — the dialer comes via client.request().
from orbit_sdk import OrbitClient

client = OrbitClient.from_env()

claim = client.request(
    "GET",
    "/dialer/next-call",
    params={"campaign_id": "dcmp_abc"},
)
contact = claim["data"]["contact"]
# contact["id"] ("dlc_xyz") feeds steps 2 and 3.
print("claimed:", contact["id"] if contact else None)

// Typed helpers don't exist yet — client.Request reaches the route.
ctx := context.Background()

var claim map[string]any
err := client.Request(ctx, "GET", "/dialer/next-call",
    url.Values{"campaign_id": {"dcmp_abc"}}, nil, &claim, "")
if err != nil {
    // handle error
}
// claim["data"]["contact"]["id"] ("dlc_xyz") feeds steps 2 and 3.
fmt.Println("claimed:", claim["data"])

require "orbit_sdk"

client = OrbitSdk::Client.from_env

claim = client.request(
  "GET",
  "/dialer/next-call",
  query: { "campaign_id" => "dcmp_abc" }
)
contact = claim.dig("data", "contact")
# contact["id"] ("dlc_xyz") feeds steps 2 and 3.
puts "claimed: #{contact&.dig("id")}"

<?php
use Devotel\Orbit\OrbitClient;

$client = OrbitClient::fromEnv();

$claim = $client->request(
    method: "GET",
    path: "/dialer/next-call",
    query: ["campaign_id" => "dcmp_abc"],
);
$contact = $claim["data"]["contact"] ?? null;
// $contact["id"] ("dlc_xyz") feeds steps 2 and 3.
echo "claimed: " . ($contact["id"] ?? "none") . PHP_EOL;

The claim returns "id": "dlc_xyz" inside data.contact (see Get the next contact (preview mode) for the full envelope). A 204 No Content means the campaign is not in preview mode and the pacing engine dials instead — there is nothing to claim.

2. Place the preview dial

POST /dial takes an operator session (Authorization: Bearer <token>; an API key is refused with 401 AGENT_REQUIRED), and contact_id is the claim’s data.contact.id from step 1.

curl -X POST "https://api.orbit.devotel.io/api/v1/dialer/dial" \
  -H "Authorization: Bearer $OPERATOR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "campaign_id": "dcmp_abc",
    "contact_id": "dlc_xyz"
  }'

import { Orbit } from "@devotel-orbit/node";

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

// contact_id threads from the step-1 claim (claim.data.contact.id); no typed dial helper yet.
const dial = await orbit.request<{ data: { attempt_id: string } }>(
  "POST",
  "/dialer/dial",
  { campaign_id: "dcmp_abc", contact_id: claim.data.contact!.id },
);
console.log("attempt:", dial.data.attempt_id);

# contact_id threads from the step-1 claim.
dial = client.request(
    "POST",
    "/dialer/dial",
    json_body={"campaign_id": "dcmp_abc", "contact_id": contact["id"]},
)
print("attempt:", dial["data"]["attempt_id"])

// contact_id threads from the step-1 claim.
var dial map[string]any
err = client.Request(ctx, "POST", "/dialer/dial",
    nil, map[string]any{
        "campaign_id": "dcmp_abc",
        "contact_id":  claim["data"].(map[string]any)["contact"].(map[string]any)["id"],
    }, &dial, "")
if err != nil {
    // handle error
}
fmt.Println("attempt:", dial["data"])

# contact_id threads from the step-1 claim.
dial = client.request(
  "POST",
  "/dialer/dial",
  json_body: { campaign_id: "dcmp_abc", contact_id: contact["id"] }
)
puts "attempt: #{dial.dig("data", "attempt_id")}"

<?php
// $contact threads from the step-1 claim.
$dial = $client->request(
    method: "POST",
    path: "/dialer/dial",
    jsonBody: [
        "campaign_id" => "dcmp_abc",
        "contact_id" => $contact["id"],
    ],
);
echo "attempt: " . $dial["data"]["attempt_id"] . PHP_EOL;

Responses are 202 Accepted; the envelope carries data.attempt_id ("datt_abc123") plus the contact_id you dialed (full envelope under Place a preview dial). Hold the attempt_id for step 3.

3. Submit the disposition

attempt_id is data.attempt_id from step 2 ("datt_abc123"); the disposition string routes the contact’s lifecycle per the Dialer Dispositions matrix.

curl -X POST "https://api.orbit.devotel.io/api/v1/dialer/campaigns/dcmp_abc/dispositions" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "attempt_id": "datt_abc123",
    "disposition": "callback_later",
    "callback_scheduled_at": "2026-08-31T18:30:00Z",
    "notes": "Customer asked for an evening callback."
  }'

import { Orbit } from "@devotel-orbit/node";

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

// attempt_id threads from the step-2 dial response (dial.data.attempt_id).
const disposition = await orbit.dialer.submitDisposition("dcmp_abc", {
  attempt_id: dial.data.attempt_id,
  disposition: "callback_later",
  callback_scheduled_at: "2026-08-31T18:30:00Z",
  notes: "Customer asked for an evening callback.",
});
console.log("status:", disposition.data.status);

# attempt_id threads from the step-2 dial response.
disposition = client.request(
    "POST",
    "/dialer/campaigns/dcmp_abc/dispositions",
    json_body={
        "attempt_id": dial["data"]["attempt_id"],
        "disposition": "callback_later",
        "callback_scheduled_at": "2026-08-31T18:30:00Z",
        "notes": "Customer asked for an evening callback.",
    },
)
print("status:", disposition["data"]["status"])

// attempt_id threads from the step-2 dial response.
var disposition map[string]any
err = client.Request(ctx, "POST",
    "/dialer/campaigns/dcmp_abc/dispositions", nil,
    map[string]any{
        "attempt_id":            dial["data"].(map[string]any)["attempt_id"],
        "disposition":           "callback_later",
        "callback_scheduled_at": "2026-08-31T18:30:00Z",
        "notes":                 "Customer asked for an evening callback.",
    }, &disposition, "")
if err != nil {
    // handle error
}
fmt.Println("status:", disposition["data"])

# attempt_id threads from the step-2 dial response.
disposition = client.request(
  "POST",
  "/dialer/campaigns/dcmp_abc/dispositions",
  json_body: {
    attempt_id: dial.dig("data", "attempt_id"),
    disposition: "callback_later",
    callback_scheduled_at: "2026-08-31T18:30:00Z",
    notes: "Customer asked for an evening callback."
  }
)
puts "status: #{disposition.dig("data", "status")}"

<?php
// $dial threads from the step-2 dial response.
$disposition = $client->request(
    method: "POST",
    path: "/dialer/campaigns/dcmp_abc/dispositions",
    jsonBody: [
        "attempt_id" => $dial["data"]["attempt_id"],
        "disposition" => "callback_later",
        "callback_scheduled_at" => "2026-08-31T18:30:00Z",
        "notes" => "Customer asked for an evening callback.",
    ],
);
echo "status: " . $disposition["data"]["status"] . PHP_EOL;

A callback_later disposition requires a future callback_scheduled_at within 90 days (422 VALIDATION_ERROR otherwise); do_not_call writes the number to your do-not-call list. The full matrix lives on Dialer Dispositions.

Voice-agent batch dispatch

The second hero flow paces a dispatch_mode='voice_agent' campaign instead of the human loop: one scheduler tick calls POST /campaigns/:id/batch-dispatch and the platform originates up to concurrency_limit AI-voice-agent legs. Pin one Idempotency-Key per tick below, so a retried tick replays the original dispatch instead of originating a second batch of legs; retry it unchanged if the call times out.

curl -X POST "https://api.orbit.devotel.io/api/v1/dialer/campaigns/dcmp_abc/batch-dispatch" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Idempotency-Key: vd-batch-001" \
  -H "Content-Type: application/json" \
  -d '{ "max_legs": 25 }'

import { Orbit } from "@devotel-orbit/node";

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

type BatchDispatchLeg = {
  contact_id: string;
  attempt_id: string;
  jambonz_call_sid: string | null;
  ok: boolean;
  error?: string;
};

// One Idempotency-Key per scheduler tick keeps a retried tick from dispatching twice.
const batch = await orbit.request<{ data: { claimed: number; legs: BatchDispatchLeg[] } }>(
  "POST",
  "/dialer/campaigns/dcmp_abc/batch-dispatch",
  { max_legs: 25 },
  { idempotencyKey: "vd-batch-001" },
);
const failed = batch.data.legs.filter((leg) => !leg.ok);
console.log(`claimed ${batch.data.claimed}, failed ${failed.length}`);

# Python SDK is core-scope — the dialer comes via client.request().
from orbit_sdk import OrbitClient

client = OrbitClient.from_env()

# One Idempotency-Key per scheduler tick keeps a retried tick from dispatching twice.
batch = client.request(
    "POST",
    "/dialer/campaigns/dcmp_abc/batch-dispatch",
    json_body={"max_legs": 25},
    idempotency_key="vd-batch-001",
)
failed = [leg for leg in batch["data"]["legs"] if not leg["ok"]]
print(f"claimed {batch['data']['claimed']}, failed {len(failed)}")

// Typed helpers don't exist yet — client.Request reaches the route; the last arg pins the Idempotency-Key per tick.
ctx := context.Background()

var batch map[string]any
err := client.Request(ctx, "POST",
    "/dialer/campaigns/dcmp_abc/batch-dispatch",
    nil, map[string]any{"max_legs": 25}, &batch, "vd-batch-001")
if err != nil {
    // handle error
}
fmt.Println("claimed:", batch["data"])

require "orbit_sdk"

client = OrbitSdk::Client.from_env

# One Idempotency-Key per scheduler tick keeps a retried tick from dispatching twice.
batch = client.request(
  "POST",
  "/dialer/campaigns/dcmp_abc/batch-dispatch",
  json_body: { max_legs: 25 },
  idempotency_key: "vd-batch-001"
)
failed = batch.dig("data", "legs").reject { |leg| leg["ok"] }
puts "claimed #{batch.dig("data", "claimed")}, failed #{failed.size}"

<?php
use Devotel\Orbit\OrbitClient;

$client = OrbitClient::fromEnv();

// One Idempotency-Key per scheduler tick keeps a retried tick from dispatching twice.
$batch = $client->request(
    method: "POST",
    path: "/dialer/campaigns/dcmp_abc/batch-dispatch",
    jsonBody: ["max_legs" => 25],
    idempotencyKey: "vd-batch-001",
);
$failed = array_filter($batch["data"]["legs"], fn($leg) => !$leg["ok"]);
echo "claimed " . $batch["data"]["claimed"] . ", failed " . count($failed) . PHP_EOL;

The response is 202 Accepted when every claimed leg originated, 207 Multi-Status when some failed (inspect legs[].ok), or 204 No Content when no contact was pending; the worked envelope is under Batch-dispatch voice-agent legs above.

SDK call flows

The full preview round trip — claim the next contact with GET /next-call, dial it with POST /dial — in every supported language. Only the Node SDK has typed dialer helpers today — the Python SDK and Go SDK are core-scope, so for the dialer you drop to the documented escape hatch: client.request(method, path, ...) in Python and client.Request(ctx, method, path, ...) in Go. The voice-agent batch-dispatch call follows the same pattern and is worked in full under Batch-dispatch voice-agent legs above; the disposition call follows it too. All languages carry the same auth, retry, and Idempotency-Key behavior as the typed resource.

# 1) Claim the next preview contact.
curl -G "https://api.orbit.devotel.io/api/v1/dialer/next-call" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  --data-urlencode "campaign_id=dcmp_abc"
# → { "data": { "contact": { "id": "dlc_xyz", … } } }

# 2) Dial the claimed contact (operator session token required).
curl -X POST "https://api.orbit.devotel.io/api/v1/dialer/dial" \
  -H "Authorization: Bearer $OPERATOR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "campaign_id": "dcmp_abc",
    "contact_id": "dlc_xyz"
  }'

import { Orbit } from "@devotel-orbit/node";

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

// 1) Claim the next preview contact (typed helper).
const next = await orbit.dialer.getNextCall({ campaign_id: "dcmp_abc" });

// 2) Dial the claimed contact via the escape hatch (operator token required).
if (next.data.contact) {
  const dial = await orbit.request<{ data: { attempt_id: string } }>(
    "POST",
    "/dialer/dial",
    { campaign_id: "dcmp_abc", contact_id: next.data.contact.id },
  );
  console.log("attempt:", dial.data.attempt_id);
}

# Python SDK is core-scope — the dialer comes via client.request().
from orbit_sdk import OrbitClient

client = OrbitClient.from_env()

# 1) Claim the next preview contact.
claim = client.request(
    "GET",
    "/dialer/next-call",
    params={"campaign_id": "dcmp_abc"},
)
contact = claim.get("data", {}).get("contact")
print("claim:", contact)

# 2) Dial the claimed contact (operator-scoped key required).
if contact:
    result = client.request(
        "POST",
        "/dialer/dial",
        json_body={"campaign_id": "dcmp_abc", "contact_id": contact["id"]},
    )
    print("attempt:", result["data"]["attempt_id"])

// Go SDK is source-only — client.Request hits uncovered routes.
ctx := context.Background()

// 1) Claim the next preview contact.
var claim map[string]any
err := client.Request(ctx, "GET", "/dialer/next-call",
    url.Values{"campaign_id": {"dcmp_abc"}}, nil, &claim, "")

// 2) Dispatch the voice-agent batch.
var batch map[string]any
err = client.Request(ctx, "POST",
    "/dialer/campaigns/dcmp_abc/batch-dispatch",
    nil, map[string]any{"max_legs": 25}, &batch, "")

# 1) Claim the next preview contact.
require "orbit_sdk"

client = OrbitSdk::Client.from_env

claim = client.request(
  "GET",
  "/dialer/next-call",
  query: { "campaign_id" => "dcmp_abc" }
)
contact = claim.dig("data", "contact")

# 2) Dial the claimed contact (operator-scoped key required).
if contact
  result = client.request(
    "POST",
    "/dialer/dial",
    json_body: { campaign_id: "dcmp_abc", contact_id: contact["id"] }
  )
  puts "attempt: #{result.dig("data", "attempt_id")}"
end

<?php
use Devotel\Orbit\OrbitClient;

$client = OrbitClient::fromEnv();

// 1) Claim the next preview contact.
$claim = $client->request(
    method: "GET",
    path: "/dialer/next-call",
    query: ["campaign_id" => "dcmp_abc"],
);
$contact = $claim["data"]["contact"] ?? null;

// 2) Dial the claimed contact (operator-scoped key required).
if ($contact !== null) {
    $result = $client->request(
        method: "POST",
        path: "/dialer/dial",
        jsonBody: [
            "campaign_id" => "dcmp_abc",
            "contact_id" => $contact["id"],
        ],
    );
    echo "attempt: " . $result["data"]["attempt_id"] . PHP_EOL;
}

FCC abandon-rate ceiling

max_abandon_rate is capped at 0.03 (3%) per the FCC Telemarketing Sales Rule. Any create or update that sends a higher value is rejected with 422 VALIDATION_ERROR. The pacing engine also auto-flips a campaign to status: 'aborted' if its rolling 30-day abandon rate trips the ceiling. aborted is terminal and cannot be re-activated — review the abort reason and create a new campaign.

API Reference

All Endpoints

Dialer API: preview, progressive, and predictive campaigns

Dialer API

Using the SDKs

Campaign modes

Create a campaign

List campaigns

Campaign stats summary

Get a campaign

Update a campaign

Soft-delete a campaign

List contact lists

Upload a contact list

Soft-delete a contact list

Campaign live stats

Caller-ID coverage

Voice-agent campaign rollup

Submit a disposition

Get the next contact (preview mode)

Place a preview dial

Batch-dispatch voice-agent legs

Worked sequences

1. Claim the next contact

2. Place the preview dial

3. Submit the disposition

Voice-agent batch dispatch

SDK call flows

FCC abandon-rate ceiling

See also

​Dialer API

​Using the SDKs

​Campaign modes

​Create a campaign

​List campaigns

​Campaign stats summary

​Get a campaign

​Update a campaign

​Soft-delete a campaign

​List contact lists

​Upload a contact list

​Soft-delete a contact list

​Campaign live stats

​Caller-ID coverage

​Voice-agent campaign rollup

​Submit a disposition

​Get the next contact (preview mode)

​Place a preview dial

​Batch-dispatch voice-agent legs

​Worked sequences

​1. Claim the next contact

​2. Place the preview dial

​3. Submit the disposition

​Voice-agent batch dispatch

​SDK call flows

​FCC abandon-rate ceiling

​See also

Dialer API

Using the SDKs

Campaign modes

Create a campaign

List campaigns

Campaign stats summary

Get a campaign

Update a campaign

Soft-delete a campaign

List contact lists

Upload a contact list

Soft-delete a contact list

Campaign live stats

Caller-ID coverage

Voice-agent campaign rollup

Submit a disposition

Get the next contact (preview mode)

Place a preview dial

Batch-dispatch voice-agent legs

Worked sequences

1. Claim the next contact

2. Place the preview dial

3. Submit the disposition

Voice-agent batch dispatch

SDK call flows

FCC abandon-rate ceiling

See also