Bookings API

Create and manage scheduled bookings programmatically.

POST /bookingsGET /bookingsGET /bookings/:idPOST /bookings/:id/cancelPOST /bookings/:id/reschedule

POST/bookings

Create a new booking for an event type.

💡 Idempotency

Include an Idempotency-Key header to prevent duplicate bookings if a request fails or times out.

Request Body:

Field	Type	Description
`eventTypeId` *	string	Event type to book
`startTime` *	ISO 8601	Meeting start time
`timezone` *	string	Attendee timezone
`attendee` *	object	Attendee details

// Request
{
  "eventTypeId": "evt_abc123",
  "startTime": "2024-01-15T14:00:00Z",
  "timezone": "America/New_York",
  "attendee": {
    "email": "attendee@example.com",
    "firstName": "Jane",
    "lastName": "Smith",
    "phone": "+1234567890"
  }
}

// Response (201 Created)
{
  "booking": {
    "id": "bkg_xyz789",
    "eventTypeId": "evt_abc123",
    "startsAt": "2024-01-15T14:00:00Z",
    "endsAt": "2024-01-15T14:30:00Z",
    "status": "confirmed",
    "confirmationToken": "tok_abc..."
  }
}

GET/bookings

List bookings with optional filters.

Query Parameters:

Param	Type	Description
`status`	string	confirmed, cancelled, pending
`startDate`	date	Filter from date (ISO 8601)
`endDate`	date	Filter to date (ISO 8601)
`page`	number	Page number (default: 1)
`limit`	number	Items per page (default: 20)

GET /bookings?status=confirmed&startDate=2024-01-01&limit=50

GET/bookings/:id

Get full details for a specific booking including attendee info and meeting link.

POST/bookings/:id/cancel

Cancel a booking. Can be done by host (API key) or attendee (cancel token).

// Request
{
  "token": "cancel-token-from-email",  // For attendee
  "reason": "Schedule conflict"
}

// Response (200 OK)
{
  "booking": {
    "id": "bkg_xyz789",
    "status": "cancelled",
    "cancelledAt": "2024-01-14T10:00:00Z"
  }
}

POST/bookings/:id/reschedule

Move a booking to a new time slot. Returns a new booking with a reference to the original.

// Request
{
  "token": "reschedule-token",
  "newStartTime": "2024-01-16T14:00:00Z"
}

// Response (200 OK)
{
  "booking": {
    "id": "bkg_new123",
    "previousBookingId": "bkg_old789",
    "startsAt": "2024-01-16T14:00:00Z",
    "status": "confirmed"
  }
}

Event Types

Availability API