API Quickstart

This walkthrough takes ~5 minutes and covers minting a key, validating it, subscribing to events, and listing your calls.

1. Mint an API key

In your Voka dashboard, go to Integrations → API Keys and click Create new key.

Pick the scopes you need:

Scope	What it lets the key do
read_assistants	List + read your voice assistants
read_calls	List + read calls; pull transcripts
read_analytics	Read call quality scores + insights
outbound_calls	Place outbound calls via the API
manage_webhooks	Create + delete webhook subscriptions
send_sms	Send SMS (coming soon)

Marketplace preset

If you're building an n8n / Zapier / Make integration, click the Integration preset button — it pre-checks read_assistants, read_calls, and manage_webhooks (the minimum for trigger + sample-data flows).

The full key is shown once. Copy it now — you can't recover it later, only rotate.

2. Validate the key

curl https://voice.vokaai.com/api/v1/auth/whoami \
  -H "Authorization: Bearer voka_live_..."

Successful response:

{
  "customer_id": "0bf91...",
  "customer_name": "Acme Dental",
  "mode": "live",
  "permissions": {
    "read_calls": true,
    "read_assistants": true,
    "manage_webhooks": true,
    "outbound_calls": true,
    "read_analytics": true
  }
}

This is the same call every n8n / Zapier / Make connection module uses to label your saved connection. If it returns 200, your wrapper integration will too.

3. List your calls

curl "https://voice.vokaai.com/api/v1/calls?limit=5" \
  -H "Authorization: Bearer voka_live_..."

{
  "data": [
    {
      "id": "550e8400-...",
      "direction": "inbound",
      "status": "completed",
      "started_at": "2026-05-10T12:00:00Z",
      "duration_seconds": 205,
      "from_number": "+12025551111",
      "to_number": "+12025552222",
      "assistant_id": "550e8400-...",
      "assistant_name": "Reception Agent",
      "has_transcript": true,
      "recording_available": true
    }
  ],
  "next_cursor": null
}

4. Subscribe to call.completed

curl https://voice.vokaai.com/api/v1/webhook-subscriptions \
  -H "Authorization: Bearer voka_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.example.com/webhooks/voka",
    "events": ["call.completed", "call.transcript.ready"]
  }'

Response (the secret is shown once — store it):

{
  "id": "sub_01H...",
  "url": "https://your-app.example.com/webhooks/voka",
  "events": ["call.completed", "call.transcript.ready"],
  "secret": "whsec_...",
  "is_active": true
}

Within seconds of the next completed call, your endpoint will receive a signed POST. See HMAC verification for the signature check.

5. Pull a transcript on demand

curl https://voice.vokaai.com/api/v1/calls/550e8400-.../transcript \
  -H "Authorization: Bearer voka_live_..."

If the transcript is cached, the response is sub-100ms. If not, we fetch from the carrier and persist for next time.

{
  "call_id": "550e8400-...",
  "conversation_id": "conv_abc123",
  "transcript": {
    "full_text": "Caller: hi...\n\nAssistant: ...",
    "segments": [
      { "speaker": "caller", "text": "hi", "timestamp": "2026-05-10T12:00:00Z" },
      { "speaker": "assistant", "text": "How can I help?", "timestamp": "2026-05-10T12:00:01Z" }
    ]
  }
}

If the call is still settling at the carrier, you'll get a 202 with status: "pending" — subscribe to call.transcript.ready for push delivery instead of polling.

What's next

• Authentication — full bearer-token + scope reference
• Endpoint reference — every public endpoint with curl + Node snippets
• Webhook events — every event payload with samples
• HMAC verification — Node + Python signature check