---
title: "Book an appointment on a workspace calendar (appointments:write). Delegates to the exact same handler the voice agent uses (`smart_book_appointment`) — appointments booked here land in the same calendar/timeline as phone-booked ones. Requires an Idempotency-Key header; repeating a key returns the original outcome instead of attempting a second booking. `success` is only returned when the calendar provider returned a durable, confirmed booking id."
method: POST
path: "/v1/appointments/book"
---

# Book an appointment on a workspace calendar (appointments:write). Delegates to the exact same handler the voice agent uses (\`smart_book_appointment\`) — appointments booked here land in the same calendar/timeline as phone-booked ones. Requires an Idempotency-Key header; repeating a key returns the original outcome instead of attempting a second booking. \`success\` is only returned when the calendar provider returned a durable, confirmed booking id.

`POST /v1/appointments/book`

## Request

- Base URL: `https://www.kaicalls.com/api`
- URL: `https://www.kaicalls.com/api/v1/appointments/book`
- Auth: HTTP bearer

## Headers

- `Idempotency-Key` string, required

## Request body

- object
  - `business_id` string: Required when the API key has access to more than one business.
  - `start_time` string, date-time, required
  - `attendee_email` string, email, required
  - `attendee_name` string, required
  - `attendee_phone` string
  - `title` string
  - `description` string
  - `duration_minutes` integer

## Response `200`

Idempotent replay of a prior outcome for this key.

## Other responses

- `201`: Booked — decision success, includes a durable booking_id.
- `202`: queued — provider accepted the request but no durable id could be verified.
- `400`: needs_clarification — missing/invalid input, no attempt made.
- `403`: API key lacks access to the business or scope
- `409`: unavailable — the requested slot is taken.
- `429`: Rate limited
- `502`: hard_failure — provider/config error.
- `503`: retryable_delay — provider timed out, safe to retry.

---

[API](https://skmtc.dev/kaicalls/apis/kaicalls-public-api.md) · [All operations](https://skmtc.dev/kaicalls/apis/kaicalls-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/kaicalls/apis/kaicalls-public-api/revisions/e607fc6cf36e?raw)