Developer Hub

Build on
KaiVox AI

Integrate KaiVox into your product with our REST API and real-time webhooks. 16 endpoints, HMAC-signed events, and full documentation — everything you need to connect your stack.

Get API Keys Talk to us

16 API endpoints

Real-time webhooks

HMAC-SHA256 signing

Bearer token auth

List appointments — GET /api/v1/appointments

curl \
  "https://kaivox.tech/api/v1/appointments?status=scheduled&date_from=2026-10-01" \
  -H "Authorization: Bearer kv_live_xxxxx"

// Response
{
  "success": true,
  "data": [{
    "id": 1234,
    "customer_name": "Anita Sharma",
    "appointment_date": "2026-10-15",
    "start_time": "10:00:00",
    "status": "scheduled",
    "service": { "name": "Consultation" }
  }],
  "meta": { "total": 47, "page": 1 }
}

Quick start

From zero to first call in 3 steps

For a business that wants its own software to talk to KaiVox, or a developer building for one.

1. Switch on API access

The business owner opens Settings → Features and turns on API & Integrations (Professional and Business plans).

2. Create a key

Settings → API & Integrations → Generate key. The key is shown once, so copy it into your server’s secrets. Revoke it any time.

3. Make a request

Send the key as Authorization: Bearer kv_live_…. Start with GET /api/v1/services, then book with POST /api/v1/appointments.

Book an appointment — POST /api/v1/appointments

curl -X POST https://kaivox.tech/api/v1/appointments \
  -H "Authorization: Bearer kv_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_name": "Anita Sharma",
    "customer_phone": "+919876543210",
    "appointment_date": "2026-10-20",
    "start_time": "10:30",
    "duration_minutes": 30
  }'

Verify a webhook (PHP)

$body      = file_get_contents('php://input');
$expected  = 'sha256=' . hash_hmac('sha256', $body, $secret);
$received  = $_SERVER['HTTP_X_KAIVOX_SIGNATURE'] ?? '';

if (!hash_equals($expected, $received)) {
    http_response_code(401);   // not from KaiVox
    exit;
}
$event = json_decode($body, true);   // $event['event'], $event['data']
http_response_code(200);

Your signing secret is shown next to each webhook under Settings → API & Integrations. Answer with any 2xx status; anything else is logged as failed and can be retried from the delivery log.

REST API

REST API — 16 Endpoints across 5 Resources

All endpoints use JSON. Authentication via Bearer token or X-API-Key header. Standardised response format with pagination metadata.

Appointments

Full CRUD — list, create, show, update status, cancel. Plus available slots.

GET /api/v1/appointments POST /api/v1/appointments GET /api/v1/appointments/{id} PATCH /api/v1/appointments/{id} DELETE /api/v1/appointments/{id} GET /api/v1/appointments/slots

Customers

List with search and filter. Create, show, update segment and pipeline stage.

GET /api/v1/customers POST /api/v1/customers GET /api/v1/customers/{id} PATCH /api/v1/customers/{id}

Calls

List with sentiment and date filters. Show individual call with full transcript.

GET /api/v1/calls GET /api/v1/calls/{id}

Staff

List active staff with availability. Show individual staff member.

GET /api/v1/staff GET /api/v1/staff/{id}

Services

List active services. Show individual service with pricing and duration.

GET /api/v1/services GET /api/v1/services/{id}

Real-Time Webhooks

Subscribe to KaiVox events and get instant HTTP POST notifications to your endpoint. Every event is signed with HMAC-SHA256 so you can verify it's genuinely from KaiVox.

appointment.booked New appointment confirmed

appointment.cancelled Appointment cancelled

appointment.completed Appointment marked completed

call.ended Call finished: duration, sentiment, summary

call.missed Missed call logged

customer.created New customer added to CRM

HMAC-SHA256 Signing

Every webhook payload includes an X-KaiVox-Signature header. Verify it against your webhook secret to ensure authenticity. Delivery log tracks every attempt with HTTP status + retry on failure (max 3).

Webhook payload — appointment.booked POST → your-endpoint.com

{
  "event": "appointment.booked",
  "timestamp": "2026-10-15T10:00:00Z",
  "tenant_id": 42,
  "data": {
    "appointment_id": 1234,
    "customer_name": "Anita Sharma",
    "appointment_date": "2026-10-20",
    "start_time": "10:30:00",
    "source": "voice"   // voice | manual | api
  }
}

// Headers
X-KaiVox-Signature: sha256=abc123...
X-KaiVox-Event: appointment.booked
Content-Type: application/json

Auth

Authentication

Two ways to authenticate with the KaiVox API.

Bearer Token (Recommended)

Include your API key in the Authorization header. Recommended for server-to-server requests.

Authorization: Bearer kv_live_xxxxxxxxxx

X-API-Key Header

Alternative header authentication. Useful when the Authorization header is already in use by your infrastructure.

X-API-Key: kv_live_xxxxxxxxxx

Ideas

What You Can Build

Real integration scenarios you can build on the API today.

EHR / EMR Integration

Sync appointments booked via KaiVox voice AI directly into your EMR system. Patient name, service, time — all automatically transferred.

Healthcare · Dental · Mental Health

POS / Booking System Sync

Push KaiVox appointments into your existing booking software. Avoid double-booking and keep your front desk and back-office in sync.

Salons · Gyms · Restaurants

Custom Notifications

Listen to call.missed and appointment.cancelled webhooks to trigger your own notification flows — Slack alerts, custom SMS, internal dashboards.

All industries

Business Intelligence

Pull call logs, sentiment scores, and appointment data into your BI tool (Looker, Metabase, Tableau) for cross-system reporting.

Multi-location businesses

AI Workflow Orchestration

Use KaiVox webhooks to trigger downstream AI workflows — qualify leads from calls, auto-update CRM, or create tasks in your project management tool.

Software teams

Your own booking page

Show real free slots on your website with GET /appointments/slots and create the booking with POST /appointments. The AI receptionist and your site share one diary.

Clinics · Salons · Gyms

Rate Limits

Limit	Value
Requests per API key	60 per minute
Over the limit	HTTP 429, wait for `Retry-After` seconds

Every response carries X-RateLimit-Limit and X-RateLimit-Remaining. API access is included on the Professional and Business plans.

Standard Response Format

// Success { "success": true, "data": { /* resource or array */ }, "meta": { "page": 1, "total": 47 } } // Error { "success": false, "error": "Appointment not found." } // Validation (HTTP 422) { "message": "The name field is required.", "errors": { "name": ["The name field is required."] } }

Build onKaiVox AI