This article refers to /api/Meetings/Distinct endpoint.
Instance Type
Use the instance_type field to determine what type of meeting this is. A meeting can be one of three options:
instance = This is a single time event.
series_master = Starting event for a series of recurring events going into the future.
exception = Event was originally an occurrence in a set of recurring events but has been modified in some way to make it no longer part of the normally scheduled series of events.
Occurrences
Occurrences are the times a recurring event takes place as scheduled. Use the occurrences property on the meeting response to list the times the event was scheduled for in the past and going into the future.
Rescheduling
What happens when the series_master schedule changes?
Here are some examples of changes a user can make:
The user reschedules the time on the series_master and chooses to update all occurrences, even those in the past.
The user reschedules only the events going forward
The user cancels all of the events on the series master
The series is changed by the organizer but one of the invitee calendars being monitored hasn't accepted the update and the two calendars have different times for all the occurrences.
SigParser will use the following logic to ensure changes are handled in a way that preserves the past while allowing changes to the future.
When SigParser first sees an event it will populate the occurrences in the past and in the future to a limit.
Each time SigParser sees the recurring event again it will populate the future only. The past events won't be modified.
Anytime a series_master changes or more occurrences are added the lastmodified date will change on it.
When the user reschedules "all events going foward" that will generate a new series_master from that point forward and the future occurrences will be removed from the old series_master.
Why not expose occurrences as rows with instance_type = "occurrence"?
Occurrences aren't real meetings in the same way as instance, series_master and exception. Google and Microsoft 365 Graph APIs don't treat them consistently and they are very transient. The meeting IDs from the APIs aren't consistent across mailbox providers. There isn't a clean way to track changes to the individual occurrences.
As such it is difficult to expose a feed of meetings for occurrences like we do for the other meeting types.
Maybe in the future we'll create a new API endpoint which does a better job of exposing occurrences as rows. But there likely wouldn't be any sort of sync option for that API. You could just ask it for meetings for an email address or domain and get a list of all the meetings with occurrences.
Other Considerations
Google/Microsoft 365 only - We only support exceptions and occurrences for these two providers. Exchange not yet supported.
icaluid vs icaluid_distinct - All meetings in a series (series_master, exception) have the same icaluid. You need to use icaluid_distinct to differentiate the individual instances.