Guides

Desk bookings

Clearooms manages desk bookings. Every booking is for a desk that already exists in one of your organisation's offices.

Any user on your account can create a booking, for:

  • themselves
  • a different user, for example a manager booking desks for their team, or a PA booking for the person they support
  • a guest

Creating a booking

Send a POST request to /bookings.

desk_id is required, along with either:

  • date, plus end_date unless all_day is true, for a single booking, or
  • dates, for a repeat booking.
An all-day booking
{
  "desk_id": "573657f8-ad17-49eb-95ce-d0f2b8515900",
  "date": "2025-05-08 08:00:00",
  "all_day": true
}
A booking with set times
{
  "desk_id": "573657f8-ad17-49eb-95ce-d0f2b8515900",
  "date": "2025-05-08 08:00:00",
  "end_date": "2025-05-08 19:30:00"
}

All-day bookings

An all-day booking lasts for the opening hours of the office the desk belongs to. When all_day is true, the time part of date, end_date and any dates is ignored.

Repeat bookings

To book the same desk on several dates, send dates instead of date and end_date. Each item is an object with start and end timestamps. Your organisation's settings can limit how many dates one request can book.

You can set all_day here too, to ignore the time part of each timestamp.

{
  "desk_id": "573657f8-ad17-49eb-95ce-d0f2b8515900",
  "dates": [
    { "start": "2025-05-08 08:00:00", "end": "2025-05-08 19:30:00" },
    { "start": "2025-05-15 08:00:00", "end": "2025-05-15 19:30:00" }
  ],
  "all_day": true
}

Each date can appear only once. This request is rejected, because both bookings are on 8 May 2025:

Rejected: two bookings on the same day
{
  "desk_id": "573657f8-ad17-49eb-95ce-d0f2b8515900",
  "dates": [
    { "start": "2025-05-08 08:00:00", "end": "2025-05-08 09:30:00" },
    { "start": "2025-05-08 18:00:00", "end": "2025-05-08 19:30:00" }
  ],
  "all_day": true
}

Shift bookings

If your organisation books desks by shift, such as morning and afternoon, send shift_id with date. The booking's start and end times are taken from the shift, and a shift that crosses midnight ends the next day.

{
  "desk_id": "573657f8-ad17-49eb-95ce-d0f2b8515900",
  "date": "2025-05-08 00:00:00",
  "shift_id": "6f1c2b7e-3d4a-4e5f-9a8b-1c2d3e4f5a6b"
}
  • The shift must be in one of the shift groups used by the desk's office. GET /offices/{officeId}/shift-groups lists them.
  • Shift groups are either shared across the organisation (when global_shifts_enabled is on) or set up per office.
  • Shift booking must be turned on with shift_bookings_enabled in the desk limits. Otherwise the request fails with "Shift booking is not enabled for this office."
  • shift_id can also be changed with PUT /bookings/{bookingId}.

Booking for someone else

user_id is optional. Without it, the booking is for the user making the request, so that user's ID is returned as both user_id and booked_by_user_id:

{
  "user_id": "9b2c547c-8686-49ed-9b18-980fa1fc6934",
  "booked_by_user_id": "9b2c547c-8686-49ed-9b18-980fa1fc6934"
}

To book for a different user, send their user_id. They become user_id, and you are recorded as booked_by_user_id:

{
  "user_id": "d8e898f2-c0fa-49c5-a823-dc73f62fd83c",
  "booked_by_user_id": "9b2c547c-8686-49ed-9b18-980fa1fc6934"
}

Guest bookings

To book a desk for someone without a user account in your organisation, such as a supplier's representative or someone on work experience, send guest_name and guest_email. guest_name can be up to 255 characters.

{
  "desk_id": "573657f8-ad17-49eb-95ce-d0f2b8515900",
  "date": "2025-05-08 08:00:00",
  "all_day": true,
  "guest_name": "John Smith",
  "guest_email": "john.smith@example.com"
}