API Reference — Overview

The Dialer Digital API is the same control plane our own dashboard runs on: campaigns, lead import, call records, SMS, promises, callbacks, agents, supervision, billing and compliance evidence — all under /v1, all JSON.

It is also compliance-first by construction. Every dial and every SMS goes through the same gated engine, no matter whether it came from a campaign, the dashboard, or your API call. There is no "raw send" endpoint to misuse — see Errors & compliance.

Where to start

Page	What you get
Authentication	Bearer API keys, rotation, 401/403 semantics.
Errors & compliance	The error envelope, and why 422 compliance_blocked is a feature.
Webhooks	Signature verification, step by step, with runnable examples.
Rate limits & caps	The 429 brakes and monthly spend caps that keep bills predictable.
Endpoint reference	Every endpoint, generated from the OpenAPI spec — parameters, schemas, examples.

Base URL

https://api.usa.dialerdigital.com     # US region ingress

All requests use HTTPS and carry a bearer API key (except the signed webhook endpoints and the unauthenticated liveness probe GET /healthz).

The 60-second tour

API=https://api.usa.dialerdigital.com
TOKEN=dd_your_api_key_here            # yours is issued at onboarding — this is not a real key

# Who am I? (validates the key, returns your account + plan + caps)
curl -s $API/v1/me -H "Authorization: Bearer $TOKEN"

# List campaigns
curl -s $API/v1/campaigns -H "Authorization: Bearer $TOKEN"

# Pull call records (append-only CDR, keyset-paginated)
curl -s "$API/v1/call_attempts?from=2026-07-01T00:00:00Z&limit=100" \
  -H "Authorization: Bearer $TOKEN"

Conventions

• JSON in, JSON out. Request bodies above 8 MiB are rejected.
• One error envelope everywhere: {"error": {"code": "...", "message": "..."}}. Branch on code, never on message — details in Errors & compliance.
• X-Request-ID on every response (yours is propagated when well-formed). Quote it in support tickets.
• Timestamps are RFC 3339 / ISO-8601 in UTC (2026-07-01T14:30:00Z); times of day are HH:MM:SS.
• Decimals as strings: pacing ratios and thresholds are rendered as JSON strings to avoid float drift.
• Pagination is keyset-based: pass limit (default 100, max 1000) and the next_cursor from the previous page.
• Versioning is in the path (/v1). Additive changes land within v1; breaking changes would open /v2.

Tenancy and data isolation

Your API key is your account identity — there is no tenant id header, path segment or body field, so there is nothing to spoof. Server-side, every query runs under PostgreSQL row-level security: another account's resource id answers 404 not_found, indistinguishable from a nonexistent id. Existence is never leaked.

How this reference is built

The endpoint reference is generated, not written: at build time a script renders it from the OpenAPI 3.1 spec published by the core service (openapi/dialer-v1.yaml). Core's CI enforces a bidirectional drift gate — every route in the running routers must appear in the spec, and vice versa — so the reference cannot silently diverge from the code.

Every generated page shows the exact core commit it was rendered from, and the spec itself is downloadable at /openapi/dialer-v1.yaml.