How Do You Create and Retrieve Bookings Through the API?

Creating a Booking #

POST /api/v1/bookings
Content-Type: application/json

{
  "event_type_id": "evt_8f21c",
  "start": "2026-09-07T09:30:00+05:30",
  "invitee": { "name": "Anil Kumar", "email": "[email protected]" },
  "answers": { "company": "Acme Ltd", "team_size": 45 },
  "timezone": "Asia/Kolkata"
}

On success the response is 201 with the created booking, including its identifier, meeting link, and the reschedule and cancel URLs you can pass to your own users.

Conflict Handling #

If the slot was taken between your availability call and your booking call, the API returns 409 with code slot_unavailable. Re-fetch slots and present the updated options rather than retrying the same start time.

Idempotency #

Send an Idempotency-Key header with a unique value per logical booking attempt. Repeating a request with the same key returns the original result instead of creating a duplicate, which makes network retries safe.

Reading Bookings #

GET /api/v1/bookings?status=upcoming&event_type_id=evt_8f21c
GET /api/v1/bookings/{id}

Filters cover status, event type, host, invitee email, and a created or scheduled date range. Answers to custom questions are returned keyed by question slug.

Modifying and Cancelling #

PATCH  /api/v1/bookings/{id}   { "start": "2026-09-08T11:00:00+05:30" }
DELETE /api/v1/bookings/{id}   { "reason": "Client requested" }

Both operations notify participants and update the connected calendar, exactly as a change made in the interface would.