Guides

Meetings

A meeting is always booked in one or more rooms that already exist in your organisation.

Creating a meeting

Send a POST request to /meetings.

The required fields are subject, private, start_time, start_time_tz, end_time and end_time_tz, plus the room: either room (one room ID) or rooms (an array of IDs, where the first is the primary room). Times use the format YYYY-MM-DD HH:MM.

The response is an array of the meetings created, because one request can create several meetings.

{
  "subject": "Our meeting",
  "private": false,
  "start_time": "2025-05-11 09:30",
  "start_time_tz": "Europe/London",
  "end_time": "2025-05-11 10:30",
  "end_time_tz": "Europe/London",
  "room": "2f9bb219-f4a9-4b4b-b8c2-48193368f311"
}

Multi-room meetings

A meeting can span several rooms. That's useful for adjoining rooms split by a partition wall, or for a large meeting such as a company-wide conference or customer event.

Send additional_rooms as an array of room IDs. room is still required, and must be one of those rooms.

{
  "room": "1a875496-dad3-4cf8-a1a1-8718fe331186",
  "additional_rooms": [
    "1a875496-dad3-4cf8-a1a1-8718fe331186",
    "bbca52f5-c340-490f-8b66-855945cc93a1",
    "56e40513-d139-4f65-8533-3d86e7ac85c2"
  ]
}

Online meetings

To add an online meeting link, for example Microsoft Teams, set online_meeting to true and send online_meeting_provider.

To have Clearooms create the online meeting in the chosen platform, set online_meeting_type to "generate":

Generate a Teams meeting
{
  "online_meeting": true,
  "online_meeting_provider": "teamsForBusiness",
  "online_meeting_type": "generate"
}

If you already have a link, send it as online_meeting_custom_link instead:

Attach an existing link
{
  "online_meeting": true,
  "online_meeting_provider": "teamsForBusiness",
  "online_meeting_custom_link": "https://example.com"
}

Setup and cleanup times

Some meetings need time before and after to prepare and clear the room. Add setup_time and cleanup_time with their units:

Field Type Notes
setup_time integer 0 or more. Send with setup_time_unit.
setup_time_unit string "minutes" or "hours"
cleanup_time integer 0 or more. Send with cleanup_time_unit.
cleanup_time_unit string "minutes" or "hours"
{
  "subject": "Our meeting",
  "private": false,
  "start_time": "2025-05-11 09:30",
  "start_time_tz": "Europe/London",
  "end_time": "2025-05-11 10:30",
  "end_time_tz": "Europe/London",
  "room": "2f9bb219-f4a9-4b4b-b8c2-48193368f311",
  "setup_time": 30,
  "setup_time_unit": "minutes",
  "cleanup_time": 15,
  "cleanup_time_unit": "minutes"
}

Attendees

Send attendees as an array of objects:

{
  "subject": "Our meeting",
  "private": false,
  "start_time": "2025-05-11 09:30",
  "start_time_tz": "Europe/London",
  "end_time": "2025-05-11 10:30",
  "end_time_tz": "Europe/London",
  "room": "2f9bb219-f4a9-4b4b-b8c2-48193368f311",
  "attendees": [
    {
      "email": "john.doe@example.com",
      "name": "John Doe",
      "type": "ORGANISER",
      "state": "ACCEPTED",
      "editable": true,
      "required": true,
      "attendance_type": "in_person"
    },
    {
      "email": "jane.doe@example.com",
      "name": "Jane Doe",
      "type": "ATTENDEE",
      "state": "ACCEPTED",
      "editable": true,
      "required": true,
      "attendance_type": "remote"
    },
    {
      "email": "james.doe@example.com",
      "name": "James Doe",
      "type": "ATTENDEE",
      "state": "PENDING",
      "editable": true,
      "required": false,
      "attendance_type": "remote",
      "guest": true
    }
  ]
}

Multiple meetings

occurrence_type defaults to "single". To create several meetings in one request, set it to "repeat" or "multi" and send dates.

Repeat

For meetings that recur on a regular pattern at the same time of day, such as "every Monday" or "the first Wednesday of the month". Send dates, an rrule (RFC 5545) and occurrence_type set to "repeat".

{
  "occurrence_type": "repeat",
  "rrule": "DTSTART:20250514T112500Z\nRRULE:FREQ=WEEKLY;INTERVAL=1;BYDAY=WE;UNTIL=20250705T225959Z",
  "dates": [
    { "start": "2025-05-14 12:25", "end": "2025-05-14 12:45" },
    { "start": "2025-05-21 12:25", "end": "2025-05-21 12:45" },
    { "start": "2025-05-28 12:25", "end": "2025-05-28 12:45" },
    { "start": "2025-06-04 12:25", "end": "2025-06-04 12:45" },
    { "start": "2025-06-11 12:25", "end": "2025-06-11 12:45" },
    { "start": "2025-06-18 12:25", "end": "2025-06-18 12:45" },
    { "start": "2025-06-25 12:25", "end": "2025-06-25 12:45" },
    { "start": "2025-07-02 12:25", "end": "2025-07-02 12:45" }
  ]
}

Multi

For several meetings that don't follow a fixed pattern. Send dates and occurrence_type set to "multi".

{
  "occurrence_type": "multi",
  "dates": [
    { "start": "2025-05-14 12:20", "end": "2025-05-14 12:50" },
    { "start": "2025-05-16 12:20", "end": "2025-05-16 12:50" },
    { "start": "2025-05-21 12:20", "end": "2025-05-21 12:50" },
    { "start": "2025-05-29 12:20", "end": "2025-05-29 12:50" }
  ]
}

Private meetings

Set private to true when creating or updating a meeting to make it private.

When someone who isn't the organiser or an attendee fetches a private meeting:

  • subject is returned as "Private Meeting", translated into their language
  • description and description_html are empty strings
  • attendees is an empty array, if your organisation's hide_attendees_on_private_meetings setting is on
A private meeting, seen by someone else
{
  "subject": "Private Meeting",
  "description": "",
  "description_html": "",
  "attendees": []
}