REST API and webhooks.

Base URL

All paths below are relative to this base.

Authentication

Every request authenticates with an API key, created in the agency dashboard under Settings → API keys. The full key is shown once at creation; only a SHA-256 hash and a short prefix are stored, so a lost key is revoked and replaced, never recovered. Keys are agency-scoped.

Authorization: Bearer YOUR_API_KEY

Conventions

Errors

{ "error": { "type": "insufficient_scope", "message": "This API key is read-only." } }

Status codes: 401 authentication_error, 403 insufficient_scope, 404 not_found, 400/500 api_error.

Pagination

List endpoints take limit (1–100, default 25) and cursor. Pass the returned cursor back to page.

{ "data": [ ... ], "has_more": true, "next_cursor": "2026-10-20T14:03:00.000Z" }

Single objects return directly. Only allowlisted public fields are returned; internal IDs and secrets never leave the API.

Clients

Receptionist & Knowledge base

Calls

Appointments (read only)

There is no endpoint to create or reschedule an appointment. Appointments are created by the AI during calls. See Calendar booking.

Numbers · Usage · Analytics

Webhook management

Subscribe

POST /webhooks
{
  "url": "https://yourapp.com/hooks/voiceai",
  "events": ["call.completed", "appointment.booked"],
  "description": "CRM sync"
}

Use "events": ["*"] to subscribe to everything.

Event catalog

Envelope

{ "id": "evt_uuid", "type": "call.completed", "created_at": "...", "data": { ... } }

Signature verification

Each delivery is signed. Header:

X-VoiceAI-Signature: t=<unix_ts>,v1=<hex>

where v1 = HMAC-SHA256(secret, t + "." + rawBody). Verify against the raw body before parsing JSON.

// Node
const crypto = require('crypto');
function verify(rawBody, header, secret) {
  const p = Object.fromEntries(header.split(',').map(x => x.split('=')));
  const expected = crypto.createHmac('sha256', secret)
    .update(p.t + '.' + rawBody).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(p.v1));
}

Deliveries are logged and retried on failure. Stored payloads keep a short-lived recording_url; use recording_api_url or GET /calls/:id/recording for a fresh one.

Payloads

call.completed / call.transferred

id, caller_phone, customer_name, customer_phone, customer_email,
customer_address, service_requested, urgency_level, sentiment,
appointment_booked, appointment_time,
ai_summary, summary, transcript,
recording_url      (short-lived),
recording_api_url  (durable, auth with your API key),
ended_reason, transfer_status, is_spam, spam_reason,
call_language, started_at, ended_at

Carries the whole call, so you can ingest it from the webhook alone with no follow-up GET.

appointment.booked

id, client_id, business_name, customer_name, customer_phone,
appointment_time, end_time, duration_minutes, timezone,
service_type, staff_name, notes,
status ("confirmed"), booking_source ("ai_receptionist"),
google_event_id, google_calendar_id, calendar_link, created_at

Calendar booking

Automated booking is Google Calendar only. The AI checks live availability and writes the event during the call only when the client has Google Calendar connected. Without it, the AI captures the request but does not confirm a slot, and appointment.booked does not fire.

Recipe: non-Google calendars

1. Subscribe a webhook to  call.completed
2. On each event, read:    data.appointment_booked, data.appointment_time,
                           customer_name, customer_phone, service_requested
3. Create the event in your calendar (Microsoft Graph, Acuity,
   Calendly, Cal.com, iCloud) from those fields.