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-apiFull 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
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
Was this article helpful?
Go further
Ready to automate your phone reception?
Create your free Kalyvox account and test your AI assistant for 7 days.