Sites & Organisation

Rooms

A Room is a physical space in which appointments are delivered. Rooms have a capacity, an optional custom availability schedule, and tags that drive allocation when an appointment is booked.

The Room object

Attributes

  • idobject-idrequired

    Unique identifier of the room.

  • organisation_iduuidrequired

    ID of the organisation the room belongs to.

  • site_iduuidrequired

    ID of the site the room belongs to. A room is scoped to exactly one site.

  • namestringrequired

    Display name for the room. Visible to staff in the calendar and admin UI; not shown to customers.

  • capacityintegerrequired

    How many concurrent bookings the room can host. 1 means single-occupancy (appointments exclusively block the room); values > 1 enable multi-guest sharing when the appointment type opts in via allocate_multi_capacity_rooms.

  • availability_rulesobject[]required

    Per-day availability windows that override the site's opening hours for this room. Empty array means the room follows site opening hours.

  • suitable_for_tagsstring[]required

    Tag IDs that this room is suitable for. The availability engine matches these against the booking's required tags to decide if the room can host the appointment (e.g. a "wet room" tag for hydrotherapy treatments).

  • tag_idsstring[]required

    Free-form tag IDs attached to the room for reporting and filtering. Distinct from suitable_for_tags — these don't affect allocation logic.

  • tagsobject[]optional

    Hydrated Tag records for the room's tag_ids.

  • zonesobject[]optional

    Hydrated Zone records this room belongs to. Zones group rooms in the floor plan and are used for spatial constraints in availability.

{
  "id": "5dcb47800000000000000000",
  "organisation_id": "0193b6e0-3b56-7000-9f50-9d3d5e2c1111",
  "site_id": "0193b6e0-3b56-7000-9f50-9d3d5e2c2222",
  "name": "Treatment Room 1",
  "capacity": 1,
  "availability_rules": [
    "string"
  ],
  "suitable_for_tags": [
    "64a9f3b2c3d8e1f4a5b6c7d8"
  ],
  "tag_ids": [
    "64a9f3b2c3d8e1f4a5b6c7d8"
  ],
  "tags": [
    "string"
  ],
  "zones": [
    "string"
  ]
}
get/shop/rooms

List rooms

listRooms

Returns a paginated list of Rooms the caller can see, ordered by their order field then by name. Filter to a single site with site_id; omit it to list every room in every site the caller has access to.

Requires the RESERVATIONS_VIEW permission on the requested site.

Query parameters

  • site_idstringoptional

    Filter results by the site they belong to

  • pageintegeroptional

    The page to retrieve results from

  • per_pageintegeroptional

    The number of results to return per page

Responses

  • 200

    A paginated list of Rooms.

  • 401

    The user is unauthenticated

  • 403

    The authenticated user does not have permission.

post/shop/rooms

Create a room

createRoom

Creates a new Room at the given site. The minimum body is name, capacity, and site_id. The room initially follows the site's opening hours; pass use_custom_opening_hours = true together with availability_rules to override.

Requires the SETTINGS_MANAGE permission on the room's site.

Query parameters

  • site_idstringoptional

    Filter results by the site they belong to

  • pageintegeroptional

    The page to retrieve results from

  • per_pageintegeroptional

    The number of results to return per page

Request body

  • namestringrequired

    Display name for the room. Shown to staff in the calendar and admin UI. Plain text only.

  • capacityintegerrequired

    How many concurrent bookings the room can host. 1 means exclusive single-occupancy. Multi-guest sharing requires an appointment type with allocate_multi_capacity_rooms = true.

  • site_iduuidrequired

    ID of the site this room belongs to. The caller's API key must have access to this site, otherwise the request 422s.

  • organisation_iduuidoptional

    Optional organisation ID. Defaults to the caller's primary organisation when omitted.

  • When true, the room uses its own availability_rules instead of the site's opening hours. When false (or omitted), the site's hours are used and availability_rules is ignored.

  • availability_rulesobject[]optional

    Per-day availability windows for the room. Only honoured when use_custom_opening_hours = true. Each rule must specify weekday, time_from, and time_to.

  • suitable_for_tagsstring[]optional

    Tag IDs the room is suitable for. Used by the availability engine to match rooms against an appointment type's required tags.

  • tag_idsstring[]optional

    Free-form tag IDs for reporting and filtering. Distinct from suitable_for_tags. Tags must belong to the caller's organisation and apply to rooms.

  • zone_idsstring[]optional

    Zone IDs the room belongs to. Zones must exist at the same site_id; mismatched zones are rejected with 422.

Responses

  • 201

    A single Room.

  • 401

    The user is unauthenticated

  • 403

    The authenticated user does not have permission.

  • 422

    The request didn't pass validation

get/shop/rooms/order

List ordered rooms

listOrderedRooms

Returns the site's Rooms in their current display order. Used together with PUT /shop/rooms/order to power a drag-and-drop ordering UI in the admin panel.

Requires the RESERVATIONS_VIEW permission on the site.

Query parameters

  • site_idstringrequired

    Filter results by the site they belong to

Responses

  • 200

    The site's rooms in display order. Used to drive a drag-and-drop ordering UI alongside the matching PUT /shop/rooms/order endpoint.

  • 401

    The user is unauthenticated

  • 403

    The authenticated user does not have permission.

  • 422

    The request didn't pass validation

put/shop/rooms/order

Update room order

updateRoomOrder

Replaces the display order of the site's Rooms. The order of room_ids in the body is the new order — element 0 becomes order=0, element 1 becomes order=1, and so on.

Requires the SETTINGS_MANAGE permission on the site.

Request body

  • room_idsstring[]required

    Ordered list of room IDs. Element 0 becomes the first-displayed room, element 1 the second, and so on.

  • site_iduuidrequired

    ID of the site whose room order is being updated. The caller's API key must have access to this site.

Responses

  • 200

    The site's rooms in display order. Used to drive a drag-and-drop ordering UI alongside the matching PUT /shop/rooms/order endpoint.

  • 401

    The user is unauthenticated

  • 403

    The authenticated user does not have permission.

  • 422

    The request didn't pass validation

get/shop/rooms/{roomId}

Retrieve a room

getRoom

Returns the full Room for the given ID. Use this to populate an admin edit screen or to look up the room's capacity and availability when checking schedules.

Requires the RESERVATIONS_VIEW permission on the room's site.

Path parameters

  • roomIdobject-idrequired

    The ID of the room.

Responses

  • 200

    A single Room.

  • 401

    The user is unauthenticated

  • 403

    The authenticated user does not have permission.

  • 404

    The resource couldn't be found

put/shop/rooms/{roomId}

Update a room

updateRoom

Partially updates a Room. Every field is optional; only fields you send are written. Sending an empty availability_rules array clears the room's custom availability (server normalises it to null).

Requires the SETTINGS_MANAGE permission on the room's site.

Path parameters

  • roomIdobject-idrequired

    The ID of the room.

Request body

  • namestringoptional

    New display name for the room.

  • capacityintegeroptional

    New concurrent-bookings capacity. Reducing capacity below the count of active bookings doesn't kick anyone out — existing bookings keep their slot.

  • Toggle whether the room uses its own availability_rules or the site's opening hours.

  • availability_rulesobject[]optional

    Replace the room's per-day availability windows. Send an empty array to clear (server normalises to null).

  • suitable_for_tagsstring[]optional
  • tag_idsstring[]optional
  • zone_idsstring[]optional

Responses

  • 200

    A single Room.

  • 401

    The user is unauthenticated

  • 403

    The authenticated user does not have permission.

  • 404

    The resource couldn't be found

  • 422

    The request didn't pass validation

delete/shop/rooms/{roomId}

Delete a room

deleteRoom

Soft-deletes the room. Existing appointments are unaffected, but the room is removed from new-booking allocations.

Requires the SETTINGS_MANAGE permission on the room's site.

Path parameters

  • roomIdobject-idrequired

    The ID of the room.

Responses

  • 204

    Room deleted successfully.

  • 401

    The user is unauthenticated

  • 403

    The authenticated user does not have permission.

  • 404

    The resource couldn't be found

post/shop/rooms/{roomId}/copy

Duplicate a room

copyRoom

Creates a copy of an existing Room. The copy is created at the same site (or at site_id if you override it). Useful for seeding a second identically-configured room — e.g. "Treatment Room 2" off "Treatment Room 1".

Requires the SETTINGS_MANAGE permission on the destination site.

Path parameters

  • roomIdobject-idrequired

    The ID of the room.

Request body

  • namestringoptional

    New display name. Defaults to the source's name when omitted — be careful, you'll end up with two rooms with the same name.

  • capacityintegeroptional

    Override capacity on the new copy. Defaults to the source room's capacity when omitted.

  • site_iduuidoptional

    Override the destination site. Defaults to the source's site. The caller's API key must have access to the chosen site.

  • organisation_iduuidoptional

    Override the destination organisation.

  • When true, the room follows its own opening hours (defined via availability_rules) rather than inheriting the parent site's. Inherited from the source when omitted.

  • availability_rulesobject[]optional
  • suitable_for_tagsstring[]optional
  • tag_idsstring[]optional
  • zone_idsstring[]optional

Responses

  • 201

    A single Room.

  • 401

    The user is unauthenticated

  • 403

    The authenticated user does not have permission.

  • 404

    The resource couldn't be found

  • 422

    The request didn't pass validation

get/shop/room-scheduled-availability

List a room's scheduled availability

listRoomScheduledAvailability

Returns the resolved availability windows for one or more rooms over the requested date range. Rooms derive their schedule from the parent site's bookable hours plus any per-room custom-availability rules; the response mixes both and tags each row with an availability_type.

Use either a date-range (date_from / date_to) or a date-time range (date_time_from / date_time_to). All date/datetime parameters are parsed in the calling site's timezone using the YYYY-MM-DD HH:mm:ss format (date-only values are also accepted).

Rooms are processed in the order supplied; the response is sorted by start time within each room.

Requires the view ability on every supplied room.

Query parameters

  • room_idsstringrequired

    Comma-separated list of room IDs to compute availability for. The calling user must be able to view every room; a single forbidden room returns 403.

  • date_fromdateoptional

    Restrict results to those on or after this date, ISO-8601 YYYY-MM-DD.

  • date_todateoptional

    Restrict results to those on or before this date, ISO-8601 YYYY-MM-DD.

  • date_time_fromstringoptional

    Inclusive start timestamp (YYYY-MM-DD HH:mm:ss) to compute availability for. Required when date_from/date_to are not supplied. Use this form for sub-day queries.

  • date_time_tostringoptional

    Exclusive end timestamp. Required when date_from/date_to are not supplied. Must be strictly after date_time_from.

Responses

  • 200

    The resolved room availability windows.

  • 401

    The user is unauthenticated

  • 403

    The authenticated user does not have permission.

  • 422

    The request didn't pass validation