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?
Related articles
Configure my AI agent
Customize the name, voice, response style, system instructions and opening hours of your AI agent.
Connect Kalyvox to ChatGPT
Add the Kalyvox connector in ChatGPT and stay in control of the data you share.
Connect Google Calendar or Outlook
Connect Google Calendar or Outlook so the AI checks availability and creates appointments.
Getting started with Kalyvox
Set up your AI phone receptionist in minutes: create your account, get your Kalyvox number, activate call forwarding and customize the greeting.
Go further
Ready to automate your phone reception?
Create your free Kalyvox account and test your AI assistant for 7 days.