API Reference

Generated from DialerDigital/core commit 6e9f026f0a72 — spec openapi/dialer-v1.yaml v0.36.0. Do not edit by hand; see How this reference is built. Download the OpenAPI spec.

Compliance-first outbound dialer control plane — the authenticated /v1 surface.

Formal reference of the /v1 control-plane API served by Dialer.API.Router (Bandit, port 4000). Source of truth: lib/dialer/api/v1_router.ex (tenant surface), lib/dialer/api/admin_router.ex (platform-admin surface), lib/dialer/api/auth_router.ex (dashboard login and password recovery — the only unauthenticated /v1 surface) and lib/dialer/api/sms_webhook_router.ex (public SMS webhooks, described under webhooks). CI enforces tools/check_openapi_drift.py: every route in the routers must appear here (method + path) and vice versa, and info.version must equal the @version in mix.exs.

Conventions

• JSON in / JSON out. Request bodies above 8 MiB are rejected.
• Errors always use the envelope {"error": {"code": "...", "message": "..."}}. Branch on code (machine-readable), never on message.
• Every response carries X-Request-ID (yours is propagated when sane).
• Timestamps are RFC 3339 / ISO-8601 (UTC). Times of day are HH:MM:SS.
• Decimal fields (pacing ratios, thresholds) are rendered as JSON strings.

Multi-tenancy and 404 semantics

Every route runs with the tenant resolved from the bearer key; all data access flows through Postgres row-level security (RLS). The API never accepts a tenant id from path, query or body. Cross-tenant ids read as 404 not_found because RLS returns zero rows — existence is never leaked (no 403 for foreign ids), and malformed (non-UUID) ids are the same 404.

Canonical errors

• 401 unauthorized — missing/unknown/revoked API key. 403 forbidden — suspended tenant.
• 404 not_found — unknown, malformed or cross-tenant id (RLS; see above).
• 422 compliance_blocked — the compliance engine refused the operation; the body carries gate (which gate refused) and decision_id (citable against the audit chain). Do NOT retry unchanged — the block is evidence, not an error.
• 429 sms_spend_cap_exceeded — month-to-date SMS budget brake; retryable only after a cap raise or the month rollover. 429 throttled — rate brake; retry later with backoff. No Retry-After header is set.
• 502 provider_error / 502 dial_error / 502 sbc_error — an upstream (SMS provider, switch, SIP edge) rejected the operation.

Out of scope here (documented in API.md): GET /healthz (no auth), GET /v1/ws websocket live floor (upgrades before this pipeline; auth via an ephemeral one-shot ?ticket= minted by POST /v1/ws/ticket, never a long-lived bearer), and GET /metrics (Prometheus, port 9568).

Resources

Resource	Endpoints	Description
Identity	4	Authenticated tenant, account settings.
Auth	7	Dashboard login (email + password -> a revocable ddu_ session; sha256 at rest, plaintext shown once) and password recovery (a one-shot, expiring link — the request half never reveals whether an address has an account).
Users	4	Dashboard user accounts (email + password; disabled, never deleted).
API keys	3	Per-tenant API keys (sha256 at rest; plaintext shown once).
Widgets	9	Embeddable agent-widget lifecycle — ddw_ browser tokens + the origin allowlist.
Campaigns	17	Campaign CRUD, lifecycle, manual dial, rewind.
Debts & leads	5	Bulk lead import, debt detail, per-debt CDR, defense packet.
Call attempts (CDR)	2	Append-only CDR query + typed dispositions.
Callbacks	5	Consumer-agreed redial appointments.
Promises to pay	2	Promise-to-pay pipeline.
Agents & seats	12	Seat roster, presence, softphone checkin/checkout.
Supervision	4	Supervisor audio (listen/whisper/barge/takeover), evidence-first.
Calls	7	Live-call control verbs (hold/unhold/mute/unmute/hangup), evidence-first.
Stats & usage	7	Operational counters, blocked-dial rollups, usage metering.
Billing	4	Invoiceable line items.
Reports	2	Packaged compliance artifacts.
Compliance	3	Suppression data the tenant owns: its internal do-not-call list, uploaded as CSV into the same list the pre-dial gate reads.
DIDs (caller IDs)	6	DID registry + CDR-computed health.
Carriers (SIP trunks)	5	SIP trunk registry (BYOC/house) + SBC provisioning.
SMS	3	Gated one-off SMS send + unified ledger.
SMS providers	5	Per-tenant/region SMS routing registry.
Webhooks	8	Outbound webhooks for CRMs: the tenant's endpoint registry, its subscribed events and the signing secret (shown once; rotation with a window).
Inbound routes	6	Inbound DID routing + SBC provisioning.
Recordings	8	Call-recording evidence: retention-locked metadata, signed playback, legal hold, bulk export, per-tenant policy.
Admin (platform operators)	16	Platform-admin surface (separate trust domain, ADMIN_API_TOKEN).
Voice ai	14	AI voice agents: builder + versioned policy, live conversations, transcripts/outcomes, supervisor takeover, the per-tenant AI-dialing kill-switch and today's metrics.
Ws	1
Webhook endpoints	3	Provider-facing, signature-authenticated (no bearer).