Agent configuration6 min read

Kalyvox API documentation (Zapier & webhooks)

Endpoints, authentication, webhooks and OpenAPI spec for the Kalyvox public API.

Kalyvox exposes a public REST API that gives access to the call tickets of your workspace and can push a webhook on every new call. This is the API behind the official Zapier integration; you can also call it directly from your own tools (Make, n8n, an internal back office…).

Base URL and specification

All requests are made over HTTPS against:

https://auth.kalyvox.ai/functions/v1/zapier-api

Full example: https://auth.kalyvox.ai/functions/v1/zapier-api/v1/auth/test

The OpenAPI 3.1 specification (schemas, parameters, examples, webhook) is public: https://kalyvox.ai/openapi/kalyvox-zapier-v1.json. You can import it into Postman, Insomnia or Swagger Editor.

Authentication

The API is authenticated with a workspace API key sent in the Authorization: Bearer header. The key identifies the workspace: no tenant identifier is ever accepted from request parameters.

Create a key

In Kalyvox, go to Settings > Integrations > Zapier, then “Create a key”. The key (format kvx_live_…) is shown only once — copy it immediately. You can revoke a key at any time from the same screen; subsequent requests then return 401.

curl -H "Authorization: Bearer kvx_live_xxx" \
  https://auth.kalyvox.ai/functions/v1/zapier-api/v1/auth/test

{"id":"3f1c...","name":"Acme Plumbing","brand":"kalyvox"}

Treat the key like a password

A key grants access to call tickets, including phone numbers and transcripts. Never put it in front-end code or in a public repository.

Endpoints

Method	Path	Description
GET	/v1/auth/test	Validates the API key and returns the associated workspace.
GET	/v1/tickets/recent?limit=3	Most recent call tickets (1 to 100), newest first.
GET	/v1/tickets/search	Filtered, cursor-paginated search.
POST	/v1/webhook-subscriptions	Subscribes a Zapier hook URL to an event (REST hook).
DELETE	/v1/webhook-subscriptions/:id	Deactivates the subscription.

GET /v1/tickets/recent

Parameter limit (integer, 1 to 100, default 3). Returns a JSON array of tickets, newest first.

curl -H "Authorization: Bearer kvx_live_xxx" \
  "https://auth.kalyvox.ai/functions/v1/zapier-api/v1/tickets/recent?limit=5"

GET /v1/tickets/search

Available parameters: limit (1-100, default 20), created_after and created_before (ISO 8601), status (open, in_progress, closed, pending, resolved), urgency (normal, high), intent (scenario key, max 80 chars), caller_phone (E.164, max 32 chars) and cursor.

curl -H "Authorization: Bearer kvx_live_xxx" \
  "https://auth.kalyvox.ai/functions/v1/zapier-api/v1/tickets/search?status=open&urgency=high&limit=20"

{
  "results": [ /* … tickets … */ ],
  "next_cursor": "eyJjIjoiMjAyNi0wOC0y..."
}

To fetch the next page, pass next_cursor back as ?cursor=. When next_cursor is null, you have reached the last page.

Webhook subscriptions

POST /v1/webhook-subscriptions with a JSON body containing target_url (https Zapier hook URL; accepted aliases: hookUrl, url) and optionally event (only supported value: ticket.created).

curl -X POST \
  -H "Authorization: Bearer kvx_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"target_url":"https://hooks.zapier.com/hooks/standard/123/abc/","event":"ticket.created"}' \
  https://auth.kalyvox.ai/functions/v1/zapier-api/v1/webhook-subscriptions

{"id":"9c1e...","event":"ticket.created","target_url":"https://hooks.zapier.com/..."}

To unsubscribe: DELETE /v1/webhook-subscriptions/{id}. The subscription is deactivated and pending deliveries are cancelled.

The ticket.created webhook

On every new call ticket, Kalyvox sends a JSON POST to the subscribed URL. The body is exactly the object returned by /v1/tickets/recent. Reply with a 2xx status: on failure Kalyvox retries up to 5 times (30s, 2min, 10min, 1h, 6h).

Ticket schema

{
  "id": "0f0a9f6c-4c4e-4f5f-9a2b-2a1f4c0f9a11",
  "created_at": "2026-08-27T09:14:02.318Z",
  "status": "open",
  "intent": "new_lead",
  "urgency": "high",
  "caller_name": "Jane Cooper",
  "caller_phone": "+13125550142",
  "caller_email": "jane@example.com",
  "summary": "Water heater leaking, asks for an emergency visit today.",
  "call_id": "call_8fa2",
  "appointment_booked": true,
  "appointment_start": "2026-08-27T15:00:00.000Z",
  "appointment_end": "2026-08-27T16:00:00.000Z",
  "transcript": "assistant: Thanks for calling Acme Plumbing...\nuser: My water heater is leaking.",
  "language": "en",
  "metadata": {
    "sub_intent_key": "emergency",
    "is_escalated": false,
    "assigned": false
  }
}

caller_email, appointment_start and appointment_end are only populated when a non-cancelled appointment is attached to the call. transcript is plain text, one line per turn.

Errors and limits

Errors share a single format. The request_id is also returned in the x-request-id response header: share it with support for any investigation.

{
  "error": {
    "code": "invalid_request",
    "message": "limit must be between 1 and 100.",
    "request_id": "0d2f5b1e-9a2c-4a5f-9b71-6d0a1c93f2e4"
  }
}

400 invalid_request — invalid parameter or body.
401 unauthorized — missing, invalid or revoked key.
404 not_found — resource unknown for this workspace.
429 rate_limited — more than 120 requests per minute per key.
500 internal_error — Kalyvox-side error, retry.

Availability

The API is included from the Pro plan. On lower plans, key creation is not offered in Settings > Integrations.

Was this article helpful?

EXPLORE KALYVOX

Go further

7-DAY FREE TRIAL

Ready to automate your phone reception?

Create your free Kalyvox account and test your AI assistant for 7 days.

Try for free