Please see the full REST API documentation for API implementation details.

Resource: Meeting Series

A meeting series defines a set of recurring meetings. You can think of a meeting series as a generator of meetings (which might not yet exist). Meeting series are scheduled within a room, and each meeting series includes a recurrence schedule, meeting template, and list of invitees.

Meetings in a meeting series are created when a user accesses an individual meeting (either via the Lucid UI or the API), and are automatically created several days before the meeting is scheduled to start.


Properties

#
Field Type Notes
meeting_series_id integer
meeting_series_url url network location of the UI for this meeting series. (This UI page actually issues a redirect to a meeting within the series.)
room_id tuple meeting room: {room_id, name}
template_id tuple source template: {template_id, name}
name plain text (255)
description plain text meeting purpose or goal
location plain text physical location of the meeting
audio plain text audio or video instructions for joining the meeting
duration tuple meeting duration: {seconds, hh:mm}
recurrence_description plain text Text description of the series schedule; for example "every week on Thursday"
recurrence recurrence recurrence definition for this series
create_ts timestamp
update_ts timestamp

Embed Query Parameter: Invitees

Invitees associated with a meeting series are the default attendees for meetings in that series. Note that attendees can be added, removed, or changed independently on individual meetings.

Invitee resources are very similar, but not identical to, attendees.

  • invitees: All invitees for the meeting series
  • facilitators: Only invitees with the facilitator role
  • participants: Only invitees with the participant role
  • observers: Only invitees with the observer role
  • guests: Only guest invitees

Embed Query Parameter: Agenda Outlines

  • markdown_outline: A simple agenda outline in Markdown format
  • html_outline: A simple agenda outline in HTML format
  • text_outline: A simple agenda outline in text format

Embed Query Parameter: Full Agendas and Records

  • markdown_view: The full agenda (pre-meeting) or record (post-meeting) in Markdown format
  • html_view: The full agenda or record in HTML format
  • text_view: The full agenda or record in text format

Embed Query Parameter: Summary

  • text_summary: A brief plain-text summary (with embedded newlines), suitable for use as the meeting description in an invitation or calendar file.

Embed Query Parameter: Meeting Series Source

  • meeting_series_source: A meeting_series_source object, or null. Integrations may create a meeting series source to indicate a "source event" for a meeting series.

Getting a List of My Meeting Series

GET /lucid/api/v1/meeting_series (must be logged in)

Note: If your goal is to identify when meetings are scheduled (for example, to populate a calendar), use meeting summaries.

Query parameter Notes
room_id Restrict list to meetings in the specified room
after Any meeting series active after the specified time (should be in UTC and either timestamp or ISO8601 formatted) eg: 1375450870 or 2013-08-02T13:41:10Z
before Any meeting series active before the specified time (should be in UTC and either timestamp or ISO8601 formatted) eg: 1438522870 or 2015-08-02T13:41:10Z
updated Any meeting series updated after the specified time (should be in UTC and either timestamp or ISO8601 formatted) eg: 1438522870 or 2015-08-02T13:41:10Z
page Page number, starting from 0
per_page Any integer between 0 and 100, inclusive
sort One of: create_ts , -create_ts , update_ts , -update_ts , start_time , -start_time , end_time , -end_time
embed Comma separated list of embeddables: invitees , facilitators , participants , observers , guests , markdown_view , html_view , text_view , markdown_outline , html_outline , text_outline, text_summary, meeting_series_source
fields See Field Filtering
envelope See Enveloping

Sort Query Parameter

  • create_ts: The initial meeting series creation timestamp
  • update_ts: The meeting series last modification timestamp. This value reflects changes to the series template and schedule, but not to individual meetings in the series.

Embed Query Parameter: Invitees

  • invitees: All invitees invited to the meeting
  • facilitators: Only invitees with the facilitator role
  • participants: Only invitees with the participant role
  • observers: Only invitees with the observer role
  • guests: Only guest invitees

Embed Query Parameter: Agenda Outlines

  • markdown_outline: A simple agenda outline in Markdown format
  • html_outline: A simple agenda outline in HTML format
  • text_outline: A simple agenda outline in text format

Embed Query Parameter: Full Agendas

  • markdown_view: The full agenda in Markdown format
  • html_view: The full agenda in HTML format
  • text_view: The full agenda text format

Embed Query Parameter: Summary

  • text_summary: A brief plain-text summary (with embedded newlines), suitable for use as the meeting description in an invitation or calendar file.

Embed Query Parameter: Meeting Series Source

  • meeting_series_source: A meeting_series_source object, or null. Applications may create a meeting series source to indicate a "source event" for a meeting series.

Sample Request

GET /lucid/api/v1/meeting_series?fields=meeting_series_id,name,recurrence_description&per_page=3&page=2
Content-Type: application/json; charset=utf-8
Content-Length: 486
X-Requestor: afarrell@lucidmeetings.com
X-Rate-Limit-Limit: 100
X-Rate-Limit-Remaining: 98
X-Rate-Limit-Used: 1
X-Rate-Limit-Reset: 55
X-Total-Count: 14
X-Total-Pages: 5
X-Page-Num: 2
X-Per-Page: 3
Link: <https://site.lucidmeetings.com/lucid/api/v1/meeting_series?fields=meeting_series_id%2Cname%2Crecurrence_description&per_page=3&page=1&after=0&before=2147483646&updated=0&room_id=&sort=-create_ts&embed=&z=>; rel="prev",
      <https://site.lucidmeetings.com/lucid/api/v1/meeting_series?fields=meeting_series_id%2Cname%2Crecurrence_description&per_page=3&page=3&after=0&before=2147483646&updated=0&room_id=&sort=-create_ts&embed=&z=>; rel="next"

[
    {
        "meeting_series_id": 563,
        "name": "Weekly Review",
        "recurrence_description": "every week on Wednesday at 3 PM"
    },
    {
        "meeting_series_id": 562,
        "name": "Project X Update",
        "recurrence_description": "every week on Wednesday at 1 PM, until Nov 29, 2019"
    },
    {
        "meeting_series_id": 561,
        "name": "Team check-in",
        "recurrence_description": "every week on Monday at 3 PM, until Oct 14, 2019"
    }
]

Getting a List of Meeting Series in a Room

GET /lucid/api/v1/rooms/:room_id/meeting_series

Note: If your goal is to identify when meetings are scheduled (for example, to populate a calendar), use meeting summaries.

Query parameter Notes
after Any meeting series active after the specified time (should be in UTC and either timestamp or ISO8601 formatted) eg: 1375450870 or 2013-08-02T13:41:10Z
before Any meeting series active before the specified time (should be in UTC and either timestamp or ISO8601 formatted) eg: 1438522870 or 2015-08-02T13:41:10Z
updated Any meeting series updated after the specified time (should be in UTC and either timestamp or ISO8601 formatted) eg: 1438522870 or 2015-08-02T13:41:10Z
page Page number, starting from 0
per_page Any integer between 0 and 100, inclusive
sort One of: create_ts , -create_ts , update_ts , -update_ts , start_time , -start_time , end_time , -end_time
embed Comma separated list of embeddables: invitees , facilitators , participants , observers , guests , markdown_view , html_view , text_view , markdown_outline , html_outline , text_outline, text_summary, meeting_series_source
fields See Field Filtering
envelope See Enveloping

Sample Request

GET /lucid/api/v1/meeting_series/rooms/133?fields=meeting_series_id,name,recurrence_description&per_page=3&page=2
Content-Type: application/json; charset=utf-8
Content-Length: 483
X-Requestor: afarrell@lucidmeetings.com
X-Rate-Limit-Limit: 100
X-Rate-Limit-Remaining: 98
X-Rate-Limit-Used: 1
X-Rate-Limit-Reset: 55
X-Total-Count: 71
X-Total-Pages: 24
X-Page-Num: 2
X-Per-Page: 3
Link: <https://site.lucidmeetings.com/lucid/api/v1/rooms/133/meeting_series?fields=meeting_series_id%2Cname%2Crecurrence_description&per_page=3&page=1&after=0&before=2147483646&updated=0&sort=-create_ts&embed=&z=>; rel="prev",
      <https://site.lucidmeetings.com/lucid/api/v1/rooms/133/meeting_series?fields=meeting_series_id%2Cname%2Crecurrence_description&per_page=3&page=3&after=0&before=2147483646&updated=0&sort=-create_ts&embed=&z=>; rel="next"
[
    {
        "meeting_series_id": 582,
        "name": "Ops check-in",
        "recurrence_description": "every week on Monday, Wednesday, Friday at 10 AM"
    },
    {
        "meeting_series_id": 580,
        "name": "Project X Huddle",
        "recurrence_description": "every week on Monday, Wednesday, Friday at 10 AM"
    },
    {
        "meeting_series_id": 579,
        "name": "Monthly wrap-up",
        "recurrence_description": "every month on day 27 at 11 AM"
    }
]

Getting a Single Meeting Series

#
Query parameter Notes
embed Comma separated list of embeddables: invitees , facilitators , participants , observers , guests , markdown_view , html_view , text_view , markdown_outline , html_outline , text_outline, text_summary, meeting_series_source
fields See Field Filtering
envelope See Enveloping

Sample Request

GET /lucid/api/v1/meeting_series/584?embed=meeting_series_source
Content-Type: application/json; charset=utf-8
Content-Length: 2024
X-Rate-Limit-Limit: 100
X-Rate-Limit-Remaining: 97
X-Rate-Limit-Used: 2
X-Rate-Limit-Reset: 13
{
    "meeting_series_id": 584,
    "room_id": {
        "value": 133,
        "display": "Meeting Room"
    },
    "name": "Team check-in",
    "description": "Share updates and clear blocks on the week's work",
    "location": "Lucid HQ",
    "duration": {
        "value": 1800,
        "display": "30 minutes"
    },
    "recurrence_description": "every week on Monday, Wednesday, Friday",
    "recurrence": {
        "recurrence_id": 562,
        "rrule": "FREQ=WEEKLY;INTERVAL=1;BYDAY=MO,WE,FR;WKST=MO",
        "dtstart": "20191025T100000",
        "dtuntil": null,
        "rcount": null,
        "timezone_name": "America/Los_Angeles",
        "start_ts": {
            "value": 1572022800,
            "iso_8601": "2019-10-25T17:00:00Z",
            "pretty": {
                "time": "10 AM",
                "date": "October 25, 2019",
                "timezone": "Los Angeles"
            }
        },
        "until_ts": null,
        "event_duration": {
            "value": 1800,
            "display": "30 minutes"
        },
        "added_dates": null,
        "excluded_dates": null
        }
        "rrule_parts": {
            "freq": "WEEKLY",
            "interval": "1",
            "bymonthdays": null,
            "daysofweek": [
                "MO",
                "WE",
                "FR"
            ],
            "weekstart": "MO"
        }
    }
}

Getting an Individual Meeting within a Meeting Series

#

To access an individual meeting within a meeting series, you can specify the meeting by meeting_series_id and start time. Start time may be specified as a Unix timestamp or as an ISO 8601 date/time in UTC. (See Timestamps in Field Types.) If a meeting is scheduled at the specified time but the meeting has not yet been generated, it will generated and returned. The response is a meeting response.

We recommend that developers use a narrow query for meeting summaries to identify the correct URL for the meeting.

GET /lucid/api/v1/meeting_series/:meeting_series_id/meeting_at/:time

Examples

Here are two requests for the same meeting in a series, the first using the Unix timestamp and the second the date, "2019-11-08T01:00:00Z":

GET /lucid/api/v1/meeting_series/559/meeting_at/1573174800
GET /lucid/api/v1/meeting_series/559/meeting_at/2019-11-08T01%3A00%3A00Z

Creating a New Meeting Series

#

Meeting Series (like Meetings) are always created in a specific room context. This allows the creation function to inherit all the room templates and default settings for meetings in the room.

POST /lucid/api/v1/rooms/:room_id/meeting_series
Field Required Notes
template_id no The room template to be used for meetings in this series. (If omitted, the default template for the room will be applied.)
name yes The meeting name
description no The meeting goal or purpose
location no The physical location of the meeting, if any
duration_minutes no The meeting duration in minutes.
duration_seconds no The meeting duration in seconds. This will override duration_minutes if present.
skip_attendees no Pass true to omit any default attendees associated with the room template.
meeting_series_source no An object with fields source_type, source_id, and optionally source_data. See Meeting Series Sources.
The following parameters specify the schedule of the meeting series. Refer to recurrence for more details.
dtstart yes The start time of the first meeting in the series, as a Unix timestamp or ISO 8601 date without time zone. If not specified as a timestamp, must be a date/time in the time zone specified by timezone_name (or windows_timezone).
dtuntil no An end date for the series, as a Unix timestamp or ISO 8601 date without time zone. If not specified as a timestamp, must be a date/time in the time zone specified by timezone_name (or windows_timezone). Disallowed if rcount is specified.
rcount no The number of meetings in the series. Disallowed if dtuntil is specified.
timezone_name yes, or windows_timezone Timezone for the series, specified as a name from the tz database.
rrule_parts yes, or rrule An object specifying the recurrence rule in parts.
rrule yes, or rrule_parts An RRULE string.
The following parameters are provided as a convenience for programs that use Windows time zone names and that do not have easy access to the IANA tz names. Lucid Meetings will look up the corresponding timezone_name to use for the meeting series (and will return an error on failure).
windows_timezone Timezone for the series, specified as a Windows time zone name. (See the "Name of Time Zone" column in Microsoft Time Zone Index Values.) Mapping to IANA time zone names is provided by the Unicode Common Locale Data Repository.
windows_region no Optional region to more specifically identify the timezone to use for the specified windows_timezone.

Sample Request

In this example, rrule_parts is provided for the recurrence schedule. The same result could be obtained by instead specifying rrule as "FREQ=WEEKLY;INTERVAL=1;BYDAY=MO,WE,FR;WKST=MO".

POST /lucid/api/v1/rooms/133/meeting_series
Content-Type: application/json
{
    "name": "Team check-in",
    "template_id": 18,
    "location": "Lucid HQ",
    "duration_minutes": 30,
    "dtstart": "20191025T10:00:00",
    "dtuntil": "20191231T23:00:00",
    "timezone_name": "America/Los_Angeles",
    "skip_attendees": true,
    "rrule_parts": {
        "freq": "weekly",
        "daysofweek": ["MO","WE","FR"]
    }
}
201 Created
Location: https://site.lucidmeetings.com/lucid/api/v1/rooms/133/meeting_series/588
Content-Type: application/json
{
    "meeting_series_id": 588,
    "room_id": {
        "value": 133,
        "display": "Meeting Room"
    },
    "template_id": {
        "value": 18,
        "display": "Blank Agenda"
    },
    "name": "Team check-in",
    "description": "",
    "location": "Lucid HQ",
    "audio": "",
    "duration": {
        "value": 1800,
        "display": "30 minutes"
    },
    "recurrence_description": "every week on Monday, Wednesday, Friday at 10 AM, until Jan 1, 2020",
    "recurrence": {
        "meeting_series_id": 588,
        "rrule": "FREQ=WEEKLY;INTERVAL=1;BYDAY=MO,WE,FR;WKST=MO",
        "dtstart": "20191025T100000",
        "dtuntil": "20200101T103000",
        "rcount": null,
        "timezone_name": "America/Los_Angeles",
        "start_ts": {
            "value": 1572022800,
            "iso_8601": "2019-10-25T17:00:00Z",
            "pretty": {
                "time": "10 AM",
                "date": "October 25, 2019",
                "timezone": "Los Angeles"
            }
        },
        "until_ts": {
            "value": 1577903400,
            "iso_8601": "2020-01-01T18:30:00Z",
            "pretty": {
                "time": "10:30 AM",
                "date": "January 1, 2020",
                "timezone": "Los Angeles"
            }
        },
        "event_duration": {
            "value": 1800,
            "display": "30 minutes"
        },
        "added_dates": null,
        "excluded_dates": null,
        "create_ts": {
            "value": 1572044000,
            "iso_8601": "2019-10-25T22:53:20Z",
            "pretty": {
                "time": "3:53 PM",
                "date": "October 25, 2019",
                "timezone": "Los Angeles"
            }
        },
        "update_ts": {
            "value": 1572044000,
            "iso_8601": "2019-10-25T22:53:20Z",
            "pretty": {
                "time": "3:53 PM",
                "date": "October 25, 2019",
                "timezone": "Los Angeles"
            }
        },
        "rrule_parts": {
            "freq": "WEEKLY",
            "interval": "1",
            "bymonthdays": null,
            "daysofweek": [
                "MO",
                "WE",
                "FR"
            ],
            "weekstart": "MO"
        }
    }
}

Updating a Meeting Series via PATCH

#

As described above, a meeting series generates meetings as they are needed. Changes to the schedule of the meeting series can invalidate some of its meetings. For that reason, some changes to a meeting series will delete some or all of its pending and canceled meetings, as noted in in the table below.

Updating a meeting series will not delete a meeting that has been held (so meeting records will be preserved). This is in contrast to deleting a meeting series, which deletes all the meetings in the series regardless of their state.

Consider whether ending the current series and creating a new one might serve your purposes better than making major modifications to an existing meeting series. (See Sample Request: Changing the end date of the series.)

PATCH /lucid/api/v1/meeting_series/:meeting_series_id
Field Notes
name Updates the meeting name for the series and all pending meetings.
description Updates the meeting description (goal or purpose) for the series and all pending meetings.
location Updates the location for the series and all pending meetings.
template_id Deletes future pending and canceled meetings so they can be re-created with the new template.
duration_seconds Updates the length of all pending meetings.
duration_minutes Updates the length of all pending meetings.
dtstart Deletes all pending and canceled meetings so they can be re-created on the new schedule.
dtuntil Deletes pending and canceled meetings that are after the new UNTIL date, if any.
timezone_name Interacts with dtstart and dtuntil. See Note on Changing the Time Zone, below.
rcount Deletes pending and canceled meetings after the specified number of meetings, if any.
rrule Deletes all pending and canceled meetings so they can be re-created on the new schedule.
rrule_parts Deletes all pending and canceled meetings so they can be re-created on the new schedule.
rrule_parts must be complete; that is, it must include all the "parts" to use for the new recurrence pattern.
The following parameters are provided as a convenience for programs that use Windows time zone names and that do not have easy access to the IANA tz names. Lucid Meetings will look up the corresponding timezone_name to use for the meeting series (and will return an error on failure).
windows_timezone Used to look up a timezone_name, and interacts with dtstart and dtuntil. See Note on Changing the Time Zone, below.
windows_region

Note on Changing the Time Zone

Although timezone_name, dtstart, and dtuntil are expressed as distinct fields, they interact to specify points in time. If you make an update to timezone_name alone, the effective time of the first meeting in the series is held constant: for example, a 1 pm meeting in the America/New_York time zone becomes a 10 am meeting in America/Los Angeles. The same applies to the dtuntil date.

In other words, changing the time zone alone changes the time zone used to intepret the series, but does not adjust its start date and time. (Because different time zones have different rules for daylight saving or other time transitions, it may affect the time of meetings later in the series.)

If your intent is to modify a meeting series that is was scheduled at the wrong time because the wrong time zone was used (for example, it was scheduled for 10 am America/New York and should have been scheduled for 10 am America/Los Angeles), specify both dtstart and timezone_name.

Sample Request: Updating name and location

PATCH /lucid/api/v1/meeting_series/
Content-Type: application/json
{
    "name": "Team Sync-up",
    "location": "Lucid HQ and Remote via Video"
}
200 OK
Content-Type: application/json
{
    "meeting_series_id": 588,
    "room_id": {
        "value": 133,
        "display": "Meeting Room"
    },
    "template_id": {
        "value": 18,
        "display": "Blank Agenda"
    },
    "name": "Team Sync-up",
    "description": "",
    "location": "Lucid HQ and Remote via Video",

... additional data as in CREATE.

Sample Request: Changing the end date of the series

The new "until" date is earlier than the current one, so any meetings that have already been created after this date will be deleted.

PATCH /lucid/api/v1/meeting_series/
Content-Type: application/json
{
   "dtuntil": "2019-12-01T23:00:00"
}

Sample Request: Changing the recurrence schedule

This series was on Monday, Wednesday, and Friday, but will now be on Tuesdays and Fridays. Because the series started on a Friday, it is not necessary to specify a new dtstart.

PATCH /lucid/api/v1/meeting_series/
Content-Type: application/json
{
   "rrule": "FREQ=WEEKLY;INTERVAL=1;BYDAY=TU,FR;WKST=MO"
}

Deleting a Meeting Series

#
DELETE /lucid/api/v1/meeting_series/:meeting_series_id

WARNING Note that deleting a meeting series deletes all of its meetings, including records for meetings that have been held. In many cases it will be more appropriate to change the end date of the meeting series (cancelling future meetings).

Sample Request

DELETE /lucid/api/v1/meeting_series/500


204 No Content


#

An individual meeting series resource contains a set of collections that are managed in context: invitees.

Invitees

Please see the invitees resource for more information.

GET /lucid/api/v1/meeting_series/:meeting_series_id/invitees
GET /lucid/api/v1/meeting_series/:meeting_series_id/invitees/:invitee_id

The Lucid Meetings API provides collection shortcuts for interacting with subsets of the meeting series invitees: facilitators , participants , observers , and guests .

GET /lucid/api/v1/meeting_series/:meeting_series_id/facilitators
GET /lucid/api/v1/meeting_series/:meeting_series_id/facilitators/:invitee_id
GET /lucid/api/v1/meeting_series/:meeting_series_id/participants
GET /lucid/api/v1/meeting_series/:meeting_series_id/participants/:invitee_id
GET /lucid/api/v1/meeting_series/:meeting_series_id/observers
GET /lucid/api/v1/meeting_series/:meeting_series_id/observers/:invitee_id
GET /lucid/api/v1/meeting_series/:meeting_series_id/guests
GET /lucid/api/v1/meeting_series/:meeting_series_id/guests/:invitee_id

Meeting Summaries

Meeting summaries provide brief information about scheduled meetings, including those that are specified by a meeting series but that have not yet been generated. You can use meeting summaries to populate a calendar or to look up the resource URL to use to access an individual meeting within a series. Please see the meeting summaries resource for more information.

GET /lucid/api/v1/meeting_summaries/:meeting_summary_id/meeting_summaries