Bookings API

All endpoints require a valid Bearer token. See Authentication.

Booking schema

Field	Type	Description
`id`	UUID	Unique booking identifier
`lead_id`	UUID	Associated lead
`calcom_booking_id`	integer	Cal.com booking ID (if booked via Cal.com)
`calcom_booking_uid`	string	Cal.com booking UID
`event_type_id`	integer	Cal.com event type ID
`start_time`	datetime	Appointment start (ISO 8601)
`end_time`	datetime	Appointment end (ISO 8601)
`status`	string	Booking status
`meeting_url`	string	Video meeting URL (if applicable)
`metadata`	object	Additional booking data (service, notes, etc.)
`created_at`	datetime	When the booking was created
`updated_at`	datetime	When the booking was last updated
`lead`	object	Brief lead info (id, name, email, phone, channel, status)

Booking statuses

Status	Meaning
`confirmed`	Appointment is booked and confirmed
`cancelled`	Appointment was cancelled
`rescheduled`	Appointment was moved to a different time
`no_show`	Customer didn't show up
`completed`	Appointment took place

List bookings

GET /api/v1/bookings

Query parameters:

Parameter	Type	Default	Description
`page`	integer	1	Page number
`size`	integer	20	Results per page (max: 100)
`lead_id`	UUID	—	Filter by lead ID
`status`	string	—	Filter by booking status

Response:

{
  "bookings": [
    {
      "id": "770a9400-...",
      "lead_id": "550e8400-...",
      "start_time": "2026-03-20T14:00:00Z",
      "end_time": "2026-03-20T14:30:00Z",
      "status": "confirmed",
      "meeting_url": null,
      "created_at": "2026-03-07T10:00:00Z",
      "lead": {
        "id": "550e8400-...",
        "name": "Jane Smith",
        "email": "jane@example.com",
        "phone": "+49123456789",
        "channel": "whatsapp",
        "status": "booked"
      }
    }
  ],
  "total": 15,
  "page": 1,
  "size": 20
}

Get a booking

GET /api/v1/bookings/{booking_id}

Returns the full booking record including lead details and metadata.

Get available slots

Fetch open appointment slots from Cal.com for a given date range.

GET /api/v1/bookings/available-slots?start_date=2026-03-15&end_date=2026-03-22

Query parameters:

Parameter	Type	Required	Description
`start_date`	string	Yes	Start date (YYYY-MM-DD)
`end_date`	string	Yes	End date (YYYY-MM-DD)

Response:

{
  "slots": [
    {
      "start": "2026-03-15T10:00:00Z",
      "end": "2026-03-15T10:30:00Z"
    },
    {
      "start": "2026-03-15T11:00:00Z",
      "end": "2026-03-15T11:30:00Z"
    }
  ],
  "start_date": "2026-03-15",
  "end_date": "2026-03-22",
  "event_type_id": 123456
}

Update a booking

PATCH /api/v1/bookings/{booking_id}
Content-Type: application/json

{
  "status": "cancelled"
}

Updatable fields:

Field	Type	Description
`status`	string	New status (e.g. `cancelled`, `completed`, `no_show`)
`start_time`	datetime	New start time (for rescheduling)
`end_time`	datetime	New end time
`meeting_url`	string	Video meeting link
`metadata`	object	Additional data

Setting status to cancelled triggers the cancellation flow.

Cancel a booking

DELETE /api/v1/bookings/{booking_id}

Cancels the booking and returns 204 No Content.