v1 — Stable 16 Endpoints

API Reference

KaiVox provides a public REST API (v1) for integrating appointments, customers, calls, staff, and services into your own applications. All endpoints are tenant-scoped and require an API key.

Base URL

https://kaivoxai.com/api/v1/

For local development: http://kaivox-ai.test/api/v1/

Authentication

All API requests require an API key. You can pass it in three ways:

Method	Example
Bearer token header	`Authorization: Bearer kv1_xxxxxxxxxxxxxxxxxxxxxxxxxx`
Custom header	`X-API-Key: kv1_xxxxxxxxxxxxxxxxxxxxxxxxxx`
Query parameter	`/api/v1/appointments?api_key=kv1_xxx...`

Generate API keys at Settings → API & Integrations → API Keys. Name your key (e.g. "Zapier Integration"), click Generate, and copy the key — it is shown only once. You can revoke or delete keys at any time.

Response Format

All responses use a standardised JSON envelope:

Success response

{
  "success": true,
  "data": { ... },
  "meta": {
    "page": 1,
    "per_page": 20,
    "total": 142
  }
}

Error response

{
  "success": false,
  "message": "Appointment not found.",
  "errors": { "date": ["The date field is required."] }
}

Appointments (6 endpoints)

GET List Appointments

/api/v1/appointments

Returns paginated list of appointments. Supports query filters:

Parameter	Type	Description
`status`	string	Filter by status: `scheduled`, `completed`, `cancelled`, `no_show`
`date`	date (Y-m-d)	Filter to a specific date
`staff_id`	integer	Filter by staff member
`page`	integer	Pagination page (default: 1)
`per_page`	integer	Results per page (max: 100, default: 20)

POST Create Appointment

/api/v1/appointments

Field	Type	Required	Description
`customer_id`	integer	✅	Existing customer ID
`service_id`	integer	✅	Service to book
`staff_id`	integer	❌	Preferred staff member
`appointment_date`	date (Y-m-d)	✅	Date of appointment
`appointment_time`	time (H:i)	✅	Start time
`notes`	string	❌	Internal notes
`source`	string	❌	Booking source (default: `api`)

GET Show Appointment

/api/v1/appointments/{id}

PATCH Update Appointment Status

/api/v1/appointments/{id}/status

Body: {"status": "completed"} — accepts: scheduled, completed, cancelled, no_show

DELETE Cancel Appointment

/api/v1/appointments/{id}

Sets status to cancelled and fires the appointment_cancelled automation trigger.

GET Available Slots

/api/v1/appointments/slots

Parameter	Required	Description
`date`	✅	Date to check (Y-m-d)
`service_id`	✅	Service — determines duration
`staff_id`	❌	Specific staff member

Customers (4 endpoints)

GET List Customers

/api/v1/customers

Supports filters: segment (lead/active/inactive/vip), pipeline_stage, search (name/phone/email), page, per_page.

POST Create Customer

/api/v1/customers

Field	Type	Required
`name`	string	✅
`phone`	string	✅ (unique per tenant)
`email`	string	❌
`segment`	string	❌ (default: `lead`)
`source`	string	❌ (e.g. `api`, `walk_in`)

GET Show Customer

/api/v1/customers/{id}

Returns customer profile including total appointments, total spent, and last visit date.

PATCH Update Customer

/api/v1/customers/{id}

Accepts: segment, pipeline_stage, notes, email. Phone cannot be updated via API.

Calls (2 endpoints)

GET List Call Logs

/api/v1/calls

Supports filters: sentiment (positive/neutral/negative), from_date, to_date, missed (boolean — true returns only missed calls), page, per_page.

GET Show Call + Transcript

/api/v1/calls/{id}

Returns full call record including the full conversation transcript, sentiment, quality score, AI summary, and call outcome.

Staff (2 endpoints)

GET List Active Staff

/api/v1/staff

Returns all active staff members with their specialties and next available slot.

GET Show Staff Member

/api/v1/staff/{id}

Returns individual staff details including working hours and upcoming appointments (date/time only, no customer PII).

Services (2 endpoints)

GET List Active Services

/api/v1/services

Returns all active services with name, duration (minutes), and price.

GET Show Service

/api/v1/services/{id}

Generating API Keys

Go to Settings → API & Integrations in your KaiVox dashboard.
Click "Generate New Key" and give it a descriptive name (e.g. "Zapier", "Website Widget", "CRM Sync").
Copy the key immediately — it is shown only once. If lost, delete and regenerate.
Use the key in your app's Authorization header or as a query parameter.

API keys are tenant-scoped. They can only read and write data belonging to the tenant that generated them. A key cannot access another tenant's data.

Webhook System

In addition to the REST API, KaiVox can push events to your own endpoints via webhooks. Configure webhook URLs at Settings → API & Integrations → Webhook Endpoints.

Event	Fires When
`appointment.created`	A new appointment is booked
`appointment.cancelled`	An appointment is cancelled
`call.ended`	A call completes and is logged
`call.missed`	A call is detected as missed (duration < 15s)

Every webhook delivery is signed with X-KaiVox-Signature (HMAC-SHA256 of the payload using your webhook secret). Failed deliveries are retried up to 3 times. Delivery logs are shown in the Settings page.