Dialer Dispositions

When an agent submits a disposition on an outbound dial-attempt, the platform routes the contact’s lifecycle status based on a canonical mapping. The correct route is critical: a do_not_call disposition that’s mis-routed leaves the contact in the active pool, which creates a TCPA exposure (47 U.S.C. § 227(b)(3) carries a private right of action with

500–

1,500 statutory damages per call). This page documents the disposition matrix and the POST /campaigns/:id/dispositions endpoint that agents call to submit them. Base path: /api/v1/dialer Authentication: Clerk session (Authorization: Bearer <token>) or API key (X-API-Key). Scope: dialer:write on every endpoint listed here.

Contact-status enum

dialer_list_contacts.status is the contact lifecycle. An agent disposition routes the contact to one of these statuses:

Status	Meaning
`pending`	Fresh contact, eligible for the next pacing claim once `next_attempt_at <= now()`.
`dialing`	Currently being dialed (or claimed by an agent in preview mode). Atomic flip via `FOR UPDATE SKIP LOCKED`.
`connected`	Talked, voicemail dropped, or general “outcome captured” (`sale` / `no_sale` / `voicemail` / `interested` / `not_interested`). Terminal for the current attempt; the contact may be re-queued if `attempts < max_attempts`. Note: `busy` / `no_answer` / carrier failures route to `failed` (PS-STATE_MACHINE-12), not `connected`.
`callback_scheduled`	Agent scheduled a callback. `next_attempt_at` is set to the requested ISO timestamp; pacing claim re-picks the contact at that moment.
`wrong_number`	Number was reached but the called party is not the intended contact. Terminal — but not added to the DNC list (the rightful owner may still be contactable on reassignment).
`dnc`	Do-not-call. Terminal. The phone is INSERTed into the tenant `dnc_list` so any future pacing tick across any campaign blocks at the compliance gate (`checkDialerCompliance` → `checkDnc`).
`timezone_blocked`	The TCPA quiet-hours / unresolved-timezone guard blocked the dial — the contact’s local time is outside the permitted calling window or its timezone could not be resolved. Not terminal: the contact is deferred and becomes eligible again once the local window opens or the timezone resolves on a later pacing tick.
`exhausted`	Max attempts consumed without a `connected` outcome. Terminal.
`archived`	Soft-deleted via `DELETE /campaigns/:id` or `DELETE /campaigns/:id/lists/:listId`. Audit-trail only.
`failed`	Carrier-level failure (invalid number, network error) or any non-connect outcome — the routed status for `busy` / `no_answer` / `failed` / `fax_machine_detected` / `operator_intercept` dispositions, and for any unmapped disposition (PS-STATE_MACHINE-12). Excluded from connect-rate maths. The per-leg `busy` / `no_answer` signal is preserved on `dialer_call_attempts.outcome` and the verbatim string on `dialer_call_attempts.disposition`. Terminal for the attempt.

Disposition → status matrix

Disposition matching is case-insensitive and trim-stripped at the request boundary. Any disposition not listed below routes to failed (PS-STATE_MACHINE-12), not connected — unmapped dispositions are deliberately excluded from connect-rate maths so a freeform or newly-added FE disposition cannot silently inflate the connect-rate KPI or pollute the TCPA per-attempt audit. The agent’s chosen string is still persisted verbatim on dialer_call_attempts.disposition; operators adding a new disposition should extend the matrix so it routes intentionally instead of defaulting to failed.

Disposition string	Routes to status	Side effects
`callback_later`	`callback_scheduled`	Requires `callback_scheduled_at` in body. Stamps `next_attempt_at` on the contact.
`callback`	`callback_scheduled`	Same as `callback_later`.
`wrong_number`	`wrong_number`	Terminal — no DNC write.
`dnc`	`dnc`	INSERT INTO tenant `dnc_list` (phone, source=`dialer_disposition`, reason=disposition). Idempotent on phone.
`do_not_call`	`dnc`	Same as `dnc`.
`sale`	`connected`	None beyond the status flip.
`no_sale`	`connected`	None.
`voicemail`	`connected`	None. The voicemail leg is already captured on `dialer_call_attempts.outcome`.
`interested`	`connected`	None.
`not_interested`	`connected`	None.
`busy`	`failed`	None. Non-connect outcome (PS-STATE_MACHINE-12) — excluded from connect-rate maths, not routed to `connected`. The `busy` signal is kept on `dialer_call_attempts.outcome`.
`no_answer`	`failed`	None. Non-connect outcome (PS-STATE_MACHINE-12) — excluded from connect-rate maths. The `no_answer` signal is kept on `dialer_call_attempts.outcome`.
`failed`	`failed`	None. Non-connect outcome (PS-STATE_MACHINE-12) — excluded from connect-rate maths.
`fax_machine_detected`	`failed`	None. Non-connect outcome (PS-STATE_MACHINE-12) — routed to `failed`, excluded from connect-rate maths.
`operator_intercept`	`failed`	None. Non-connect outcome (PS-STATE_MACHINE-12) — routed to `failed`, excluded from connect-rate maths.
any other string	`failed`	None. The literal disposition string is still persisted on `dialer_call_attempts.disposition`. Excluded from connect-rate maths (PS-STATE_MACHINE-12).

DNC writes are platform-wide per tenant. A dnc disposition in Campaign A blocks future dials to the same phone in Campaign B, C, etc. on the same tenant — the DNC list is read by every pacing tick across every campaign in the tenant. Inserts are idempotent (UNIQUE on phone), so the first-write wins and existing entries’ source / reason are preserved.

Submit disposition

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

Scope: dialer:write.

attempt_id

string

required

The dialer_call_attempts.id returned when the dial leg was placed.

disposition

string

required

Agent-selected disposition string. Matched case-insensitively against the matrix above. 1–100 chars.

notes

string

Free-form agent notes. Max 2000 chars. Accepted but not currently persisted — the field is validated at the request boundary but is not yet written to the attempt (no storage column has landed). Treat it as a no-op until a future release adds persistence; do not rely on it surviving the request.

callback_scheduled_at

string

ISO-8601 timestamp with timezone offset. REQUIRED when disposition routes to callback_scheduled (callback_later / callback). Must be strictly in the future and ≤90 days ahead.

cURL

# Schedule a callback
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": "dcall_xyz",
    "disposition": "callback_later",
    "notes": "Customer asked for tomorrow morning EST",
    "callback_scheduled_at": "2026-05-25T13:00:00-04:00"
  }'

cURL

# Mark as DNC
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": "dcall_xyz",
    "disposition": "do_not_call",
    "notes": "Customer requested removal from all outreach"
  }'

200 OK

{
  "data": {
    "attempt_id": "dcall_xyz",
    "disposition": "callback_later",
    "status": "callback_scheduled",
    "callback_scheduled_at": "2026-05-25T13:00:00-04:00"
  },
  "meta": { "request_id": "req_abc123", "timestamp": "2026-05-24T12:00:00Z" }
}

Errors

Status	`error.code`	Cause
`404`	`NOT_FOUND`	`attempt_id` not found in this campaign (or cross-tenant).
`422`	`VALIDATION_ERROR`	`callback_scheduled_at` missing on callback disposition, in the past, or >90 days ahead.
`503`	`TENANT_SCHEMA_INCOMPLETE`	The tenant schema was provisioned before migration 280 ran. Contact support.

List campaigns

GET /api/v1/dialer/campaigns

Scope: dialer:read. Cursor-paginated. Returns campaigns excluding soft-deleted (status = 'deleted') rows. Query parameters

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

{
  "data": {
    "items": [
      {
        "id": "dcmp_abc",
        "name": "Q2 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,
        "recording_enabled": true,
        "recording_consent_acknowledged_at": "2026-05-22T10:30:00Z",
        "created_at": "2026-05-22T10:30:00Z"
      }
    ],
    "next_cursor": "MjAyNi0wNS0yMlQxMDozMDowMC4wMDBa",
    "has_more": false
  },
  "meta": { "request_id": "req_abc123", "timestamp": "2026-05-24T12:00:00Z" }
}

Get next contact (preview mode)

GET /api/v1/dialer/next-call?campaign_id=dcmp_abc

Scope: dialer:read. Agent readiness endpoint for preview-mode campaigns. Atomically claims the next eligible contact (CTE + FOR UPDATE SKIP LOCKED) so two agents polling concurrently can never receive the same row. For progressive / predictive campaigns this endpoint returns 204 No Content — pacing is handled server-side by the scheduler. Stale-claim recovery: A preview contact stuck in dialing for >5 minutes (agent abandoned the tab) is automatically re-claimable. Without this, abandoned previews would block the contact forever. 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-05-24T12:00:00Z" }
}

204 No Content — campaign is in progressive or predictive mode (pacing engine handles dial). Errors

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

Soft-delete a campaign

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

Scope: dialer:write. Soft-deletes the campaign. Pending contacts flip to archived; terminal contacts (connected / failed / dnc / exhausted / wrong_number) are left untouched as TCPA-dispute audit trail. All three updates (campaign, lists, contacts) commit in a single transaction. Errors

Status	`error.code`	Cause
`404`	`NOT_FOUND`	Campaign id not found or already soft-deleted.
`409`	`DIALER_CAMPAIGN_IN_FLIGHT`	At least one contact is currently in status `dialing`. Pause the campaign and wait for live legs to terminate, then retry. The `details.in_flight_contacts` count is returned.

FCC abandon-rate ceiling

max_abandon_rate is hard-capped at 0.03 (3%) per the FCC Telemarketing Sales Rule. Any POST or PATCH request that sends a value above this is rejected with 422 VALIDATION_ERROR. The scheduler also auto-flips campaigns to status: 'aborted' if the rolling 30-day abandon rate trips the ceiling — aborted is terminal and cannot be re-activated; create a new campaign after reviewing the abort reason.

Getting Started

Channels

AI Agents

Flows

Numbers & Verify

Concepts

Billing

Webhooks

Compliance

Legal

Changelog

Dialer Dispositions

Dialer Dispositions

Contact-status enum

Disposition → status matrix

Submit disposition

List campaigns

Get next contact (preview mode)

Soft-delete a campaign

FCC abandon-rate ceiling

See also

​Dialer Dispositions

​Contact-status enum

​Disposition → status matrix

​Submit disposition

​List campaigns

​Get next contact (preview mode)

​Soft-delete a campaign

​FCC abandon-rate ceiling

​See also

Dialer Dispositions

Contact-status enum

Disposition → status matrix

Submit disposition

List campaigns

Get next contact (preview mode)

Soft-delete a campaign

FCC abandon-rate ceiling

See also