REST API.

The REST API lets your CRM or back office place calls for an agent, read calls and recordings, and keep contacts, callbacks, campaign leads and DNC entries in sync. It's included on the Growth and Enterprise plans.

API keys

Owners and admins create keys in Developers in the admin console: a name, the scopes the key may use, and an optional expiry date.

• Keys look like dk_live_ followed by 32 random characters.
• The full key is shown once, when you create it. Store it in your secret manager; the dialer keeps only a hash.
• The key list shows each key's prefix, scopes and when it was last used. Revoke a key to stop it immediately.

Send the key as a bearer token on every request:

curl "$DIALER_URL/api/v1/me" \
  -H "Authorization: Bearer $DIALER_API_KEY"

{
  "tenant": { "id": "0192f6c0-…", "name": "Example Support", "slug": "example" },
  "key": { "id": "0192f6c1-…", "name": "CRM integration", "scopes": ["calls:read", "calls:write"] }
}

In these examples, DIALER_URL is the address you use to sign in to the dialer, and DIALER_API_KEY holds your key.

Scopes

GET /api/v1/me works with any valid key.

Conventions

• JSON only, with snake_case field names.
• Timestamps are ISO-8601 in UTC.
• Phone numbers are returned in E.164 (+14155550148). Where you send a number, any common format works: numbers without a country code use your workspace's country.
• IDs are UUIDs.

Pagination

List endpoints that can grow return a page and a cursor:

{ "data": [ … ], "next_cursor": "eyJjcmVhdGVkQXQiOi…" }

Pass ?limit= (1–100, default 50) and, for the next page, ?cursor= with the next_cursor you received. Results are newest first. next_cursor is null on the last page. Treat the cursor as opaque.

Errors

Errors use HTTP status codes and a JSON body:

{
  "error": {
    "code": "CALLING_HOURS",
    "message": "…",
    "details": { "zones": ["America/Chicago"] }
  }
}

details is optional, and validation errors can add fieldErrors. Branch on code, not on message.

Rate limits

Each key can make 600 requests a minute on Growth and 1,200 on Enterprise. Placing calls has an extra limit of 60 a minute. Over the limit, you get 429 with a Retry-After header.

A workspace past its payment grace period keeps read access, but write requests are refused until the invoice is paid.

Endpoints

All paths are under /api/v1.

Account and users

Calls

Contacts

Callbacks

Campaigns

DNC

Place a call

POST /api/v1/calls rings the customer from an agent's softphone, exactly as if the agent had clicked the number: the agent's browser connects on its own, with no click.

curl -X POST "$DIALER_URL/api/v1/calls" \
  -H "Authorization: Bearer $DIALER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_email": "agent@example.com",
    "to": "+1 415 555 0148",
    "metadata": { "crm_ticket": "T-1042" }
  }'

{ "id": "0192f6c2-…", "status": "initiated" }

• The agent must be Available with their softphone ready; otherwise 409 AGENT_NOT_READY.
• Agents are looked up only inside your workspace. An unknown email or username returns 404; none or several agent fields return 422 VALIDATION.
• DNC and calling hours always block over the API (409 DNC, 409 CALLING_HOURS); there's no override.
• Emergency numbers return 422 EMERGENCY_NUMBER. Usage limits return 402 USAGE_LIMIT; a paused workspace or missing terms return 403.
• If the agent's browser doesn't connect within 60 seconds, the call is canceled and the agent released.

Follow the call with GET /api/v1/calls/{id} or the call.* webhooks.

List calls

curl -G "$DIALER_URL/api/v1/calls" \
  -H "Authorization: Bearer $DIALER_API_KEY" \
  --data-urlencode "since=2026-09-01T00:00:00Z" \
  --data-urlencode "direction=outbound" \
  --data-urlencode "limit=100"

The Call object

Contacts

Create or update a contact. With an external_id, the contact with that ID is updated; otherwise the phone number decides.

curl -X POST "$DIALER_URL/api/v1/contacts" \
  -H "Authorization: Bearer $DIALER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "crm-58213",
    "first_name": "Alex",
    "last_name": "Morgan",
    "company": "Example Co",
    "phone": "+14155550148",
    "timezone": "America/Los_Angeles",
    "tags": ["renewal"],
    "custom_fields": { "plan": "Pro" }
  }'

The Contact object has id, first_name, last_name, company, email, phone, alt_phone, timezone, tags, custom_fields, external_id, created_at, updated_at and last_contacted_at. Creating a contact fires the contact.created webhook.

To handle a data-subject erasure request:

curl -X DELETE "$DIALER_URL/api/v1/contacts/0192f6c3-…?erase=1" \
  -H "Authorization: Bearer $DIALER_API_KEY"

{ "calls": 3, "recordings": 1, "voicemails": 0 }

Callbacks

curl -X POST "$DIALER_URL/api/v1/callbacks" \
  -H "Authorization: Bearer $DIALER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+14155550148",
    "scheduled_at": "2026-09-28T15:00:00Z",
    "assigned_user_id": "0192f6c4-…",
    "notes": "Wants a quote for 20 seats"
  }'

Send a contact_id or a phone (the contact is looked up or created). Leave out assigned_user_id and set queue_id to let the queue's agents claim it. The Callback object has id, contact_id, phone, scheduled_at, status, origin (api for these), assigned_user_id, queue_id, campaign_id, notes, created_at and completed_at. The callback.scheduled webhook fires.

Campaign leads

curl -X POST "$DIALER_URL/api/v1/campaigns/0192f6c5-…/leads" \
  -H "Authorization: Bearer $DIALER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "leads": [
      { "phone": "+14155550148", "first_name": "Alex", "external_id": "crm-58213" },
      { "phone": "+13125550199", "first_name": "Riley", "timezone": "America/Chicago" }
    ]
  }'

{ "created": 1, "updated": 1, "skipped": [] }

Each lead can carry phone (required), first_name, last_name, company, email, timezone, external_id and custom_fields. Contacts are created or updated and added to a list named "API leads · " plus the campaign name, created and attached the first time. The dialer turns them into leads on its next sync, applying DNC, consent and calling-hours rules as usual. Rows it can't use come back in skipped with their index and reason.

DNC

curl -X POST "$DIALER_URL/api/v1/dnc" \
  -H "Authorization: Bearer $DIALER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "phone": "+14155550148", "reason": "Asked on a call" }'

curl -X DELETE "$DIALER_URL/api/v1/dnc/%2B14155550148" \
  -H "Authorization: Bearer $DIALER_API_KEY"

Next: get notified as calls happen with webhooks.