Users commonly create recurring events in their calendar for a number of reasons: weekly meetings, daily check-ins, monthly bill payments, and more. Applications integrating with users’ calendar accounts inevitably encounter events that repeat periodically.

In this blog post, we’ll discuss best practices for retrieving and modifying recurring events, and how the unified Kloudless API simplifies this process across a number of calendar systems with a single implementation.

The structure of recurring events

Users create recurring events by first creating a single calendar event and then indicating it repeats in the future over a specific frequency. Below is an example of this in practice in an Outlook Calendar account.

As a result, a single “master” event exists in the series of calendar events, and several other events are present beyond it that belong to the series. In the image above, the master event is on the third of the month, while all events after are part of the series that repeats every 2 weeks.

The Calendar Event data format includes three attributes related to recurring events that capture this information:

• recurrence: A list of recurrence objects that each contain information about a recurring event.
• recurrence_type: This specific event’s type. Can be one of:
  • solo: A stand-alone event.
  • recurring: A recurring event.
  • recurring_master: The primary/master event in the series of recurring events.
• recurring_master_id The unique identifier for the primary/master event in the series of recurring events. Will be unavailable if the event is not a recurring event or if the event is already the primary/master event in the series.

Here is an example request to retrieve a calendar event (docs):

The response body below only displays the relevant attributes for brevity:

The recurrence attribute in this case contains RRULE data from Google Calendar (docs) in the format specified by RFC 5545. This specifies information such as the frequency of the event and the overall date range of the series.

The example above also contains two IDs; id is the calendar event ID, and recurring_master_id is the series’ master event ID. The attributes below represent the difference when retrieving the calendar event corresponding to the recurring_master_id instead of the id:

Updates to recurring events

Updates to events with recurrence_type set to recurring only update that specific event in the series. This is valuable to update a specific event’s time, reminders, attendees, location, name, description, or other attributes, without affecting the other events in the series.

Use the PATCH endpoint (docs) to update a calendar event. Update the event with the recurring_master_id to change all events in the series, or update any of the other events to change only that event. Here is an example that changes the name of an event:

The same principle applies when deleting events.

Other endpoints, and future plans

Recurring events co-exist seamlessly with non-recurring ones across all Kloudless Calendar API endpoints, including Availability queries, and Activity Monitoring.

The Kloudless Calendar API’s largest advantage is to enable developers to code just once and implement calendar integrations across all the major calendar providers. Most of the attributes in the data format discussed above are part of this unified API’s abstraction layer. In the future, we plan to extend this by also unifying the recurrence data. Developers can then avoid parsing recurrence information from Outlook Calendar differently from the data that matches RFC 5545.

Sign up for free to get started with your calendar integrations!