Bookings API

Schedule appointments, manage availability, and handle booking workflows.

List Bookings

GET/api/v1/bookings

Retrieve a list of bookings

Query Parameters

Parameter	Type	Description
`schedule_id`	`string`	Filter by schedule
`event_type_id`	`string`	Filter by event type
`status`	`string`	Filter by status (PENDING, CONFIRMED, CANCELLED, COMPLETED, NO_SHOW)
`upcoming`	`boolean`	Only future bookings
`start_date`	`string`	Bookings on or after this date
`end_date`	`string`	Bookings on or before this date
`attendee_email`	`string`	Search by attendee email
`limit`	`number`	Max results Default: `50`
`offset`	`number`	Skip results Default: `0`

Request

curl -X GET "https://api.webkasa.app/api/v1/bookings?upcoming=true&status=CONFIRMED" \
  -H "Authorization: Bearer wk_live_xxx..."

Response

200 OK

{
  "data": [
    {
      "id": "bk_abc123",
      "schedule_id": "sch_xyz789",
      "start_time": "2024-02-15T10:00:00Z",
      "end_time": "2024-02-15T11:00:00Z",
      "status": "CONFIRMED",
      "title": "Consultation Call",
      "attendee_name": "John Doe",
      "attendee_email": "john@example.com",
      "created_at": "2024-01-01T00:00:00Z"
    }
  ],
  "meta": {
    "total": 25,
    "limit": 50,
    "offset": 0,
    "hasMore": false
  }
}

Get Booking

GET/api/v1/bookings/{id}

Retrieve a single booking by ID

Request

curl -X GET "https://api.webkasa.app/api/v1/bookings/bk_abc123" \
  -H "Authorization: Bearer wk_live_xxx..."

Create Booking

POST/api/v1/bookings

Create a new booking

Request Body

Parameter	Type	Description
`schedule_id` required	`string`	Schedule ID for the booking
`start_time` required	`string`	Start time (ISO 8601)
`end_time` required	`string`	End time (ISO 8601)
`attendee.name` required	`string`	Attendee name
`attendee.email` required	`string`	Attendee email
`event_type_id`	`string`	Event type ID
`timezone`	`string`	Timezone for the booking
`title`	`string`	Booking title
`location`	`string`	Meeting location
`location_type`	`string`	Location type (in_person, phone, video, custom)
`attendee.phone`	`string`	Attendee phone
`attendee.timezone`	`string`	Attendee timezone
`attendee.notes`	`string`	Additional notes
`metadata`	`object`	Custom metadata

Request

curl -X POST "https://api.webkasa.app/api/v1/bookings" \
  -H "Authorization: Bearer wk_live_xxx..." \
  -H "Content-Type: application/json" \
  -d '{
    "schedule_id": "sch_abc123",
    "event_type_id": "evt_xyz789",
    "start_time": "2024-02-15T10:00:00Z",
    "end_time": "2024-02-15T11:00:00Z",
    "timezone": "America/Los_Angeles",
    "title": "Consultation Call",
    "location": "Zoom",
    "location_type": "video",
    "attendee": {
      "name": "John Doe",
      "email": "john@example.com",
      "phone": "+1234567890",
      "timezone": "America/New_York",
      "notes": "First-time visitor"
    },
    "metadata": {
      "source": "website"
    }
  }'

Response

201 Created

{
  "data": {
    "id": "bk_abc123",
    "schedule_id": "sch_abc123",
    "status": "PENDING",
    "start_time": "2024-02-15T10:00:00Z",
    "created_at": "2024-01-01T00:00:00Z"
  }
}

409 Conflict

{
  "error": "This time slot is already booked",
  "code": "SLOT_TAKEN"
}

Available Slots

GET/api/bookings/slots

Generate WebKasa-owned available booking slots

Connected Google and Outlook calendars are applied automatically as busy-time blockers.

Query Parameters

Parameter	Type	Description
`scheduleId` required	`string`	Schedule ID to generate available slots for
`startDate`	`string`	Start date (YYYY-MM-DD), defaults to today
`endDate`	`string`	End date (YYYY-MM-DD), defaults to 14 days from start
`timezone`	`string`	Timezone used for formatted slot labels

Request

curl "https://app.webkasa.app/api/bookings/slots?scheduleId=sch_abc123&startDate=2024-02-15&endDate=2024-02-22&timezone=America/New_York"

Response

200 OK

{
  "schedule": {
    "id": "sch_abc123",
    "name": "Consultations",
    "timezone": "America/New_York",
    "slotDuration": 30
  },
  "days": [
    {
      "date": "2024-02-15",
      "slots": [
        {
          "start": "2024-02-15T15:00:00.000Z",
          "end": "2024-02-15T15:30:00.000Z",
          "status": "available"
        }
      ]
    }
  ]
}

404 Not Found

{
  "error": "Schedule not found or inactive"
}

Update Booking

PATCH/api/v1/bookings/{id}

Update booking status or details

Valid status transitions:

PENDING → CONFIRMED, CANCELLED
CONFIRMED → COMPLETED, CANCELLED, NO_SHOW

Request

curl -X PATCH "https://api.webkasa.app/api/v1/bookings/bk_abc123" \
  -H "Authorization: Bearer wk_live_xxx..." \
  -H "Content-Type: application/json" \
  -d '{
    "status": "CONFIRMED",
    "metadata": {
      "confirmed_by": "admin"
    }
  }'

Response

200 OK

{
  "data": {
    "id": "bk_abc123",
    "status": "CONFIRMED",
    "updated_at": "2024-01-02T00:00:00Z"
  }
}

400 Bad Request

{
  "error": "Cannot transition from CANCELLED to CONFIRMED"
}

Cancel Booking

DELETE/api/v1/bookings/{id}

Cancel a booking (soft delete)

Request

curl -X DELETE "https://api.webkasa.app/api/v1/bookings/bk_abc123" \
  -H "Authorization: Bearer wk_live_xxx..."

Response

200 OK

{
  "data": {
    "id": "bk_abc123",
    "status": "CANCELLED",
    "cancelled": true
  }
}