The Calendar API helps you get, create, update, and delete events and manage calendars.
To use the Calendar API, you need an access token that you can get by authenticating with a user account or a service account.
The API scopes are calendar and calendar.read.
There are three types of calendars: a "default calendar" that all users have, a "calendar" that you can selectively add or delete, and a "team/group calendar" that belongs to a team or group.
You can create a "calendar" using the following API operation.
| HTTP request | Description |
|---|---|
| POST /calendars | Create a calendar |
You can get calendars that a user can access using the following API operations.
| HTTP request | Description |
|---|---|
| GET/users/{userId}/calendar | Get shared properties of the default calendar |
| GET /users/{userId}/calendar-personals | Get private properties of calendars |
You can set whether to display calendars and how they are ordered on the desktop or mobile app, using the following API operation.
| HTTP request | Description |
|---|---|
| PATCH /users/{userId}/calendar-personals/{calendarId} | Update private properties of a calendar |
You can manage calendar events using the following API operations, which require you to specify a calendarId.
| HTTP request | Description |
|---|---|
| POST /users/{userId}/calendars/{calendarId}/events | Create an event |
| GET /users/{userId}/calendars/{calendarId}/events | Get events |
| GET /users/{userId}/calendars/{calendarId}/events/{eventId} | Get an event |
| PUT /users/{userId}/calendars/{calendarId}/events/{eventId} | Update an event |
| DELETE /users/{userId}/calendars/{calendarId}/events/{eventId} | Delete an event |
You can manage events of the default calendar using the following API operations, which do not require you to specify a calendarId.
| HTTP request | Description |
|---|---|
| POST /users/{userId}/calendar/events | Create an event in the default calendar |
| GET /users/{userId}/calendar/events | Get events of the default calendar |
| GET /users/{userId}/calendar/events/{eventId} | Get an event of the default calendar |
| PUT /users/{userId}/calendar/events/{eventId} | Update an event of the default calendar |
| DELETE /users/{userId}/calendar/events/{eventId} | Delete an event of the default calendar |
An event is requested or returned using the eventComponents object.
Here is an example of the eventComponents object.
{ "eventComponents": [ { "eventId": "EventID1234567890abcdefghijk", "summary": "Example of an event", "start": { "dateTime": "2023-05-14T08:00:00", "timeZone": "America/New_York" }, "end": { "dateTime": "2023-05-14T09:00:00", "timeZone": "America/New_York" }, "description" : "Test event", "location" : "Meeting room 1", "transparency": "OPAQUE" } ]}The above example includes the content (summary), start and end times (dateTime), the time zones (timeZone), memo (description), location (location), and busy/free status (transparency) of the event.
The eventId specified when you create an event is unique across all events. If not specified, it is automatically assigned.
You can specify the organizer and attendees of an event. For both, the email is required and the displayName is optional.
{ "eventComponents": [ { "eventId": "EventID1234567890abcdefghijk", "summary": "Example of an event", "start": { "dateTime": "2023-05-14T08:00:00", "timeZone": "America/New_York" }, "end": { "dateTime": "2023-05-14T09:00:00", "timeZone": "America/New_York" }, "description" : "Test event", "location" : "Meeting room 1", "organizer": { "email" : "organizer@example.com", "displayName" : "Meeting organizer" }, "attendees" : [ { "email" : "attendee@example.com", "displayName" : "Attendee", "partstat" : "ACCEPTED", "isOptional" : true } ] } ]}To specify a resource, set the isResource property to true and specify the resource ID (id) and the resource unique value (resourceValue).
Both id and resourceValue are the values assigned to the resource. You can check the resourceValue in the response.
... "attendees": [ { "id": "12345678/12345678@97d9ddb4-ae93-4469-8471-123456781234", "resourceValue": "https://calendar.worksmobile.com/resources/resource/12345678/12345678@97d9ddb4-ae93-4469-8471-123456781234", "isResource": true } ]...The eventComponents object contains one or more Event objects with the same eventId.
If the eventComponents object contains a single Event object, it is a one-time event or a recurring event without exceptions. Recurrence information is represented as a recurrence array, and if there is no recurrence array, it is a one-time event.
If the eventComponents object contains multiple Events, it is a recurring event with exceptions.
Here is an example of the eventComponts object including exceptions.
{ "eventComponents": [ { "eventId": "EventID1234567890abcdefg", "summary": "Example of a recurring event" "start": { "dateTime": "2023-05-24T08:00:00", "timeZone": "America/New_York" }, "end": { "dateTime": "2023-05-24T09:00:00", "timeZone": "America/New_York" }, "recurrence": [ "RRULE:FREQ=DAILY;UNTIL=20230525T230000Z;INTERVAL=1", "EXDATE;TZID=America/New_York:20230525T080000" ] }, { "eventId": "EventID1234567890abcdefg", "summary": "Exceptional event", "start": { "dateTime": "2023-05-25T08:30:00", "timeZone": "America/New_York" }, "end": { "dateTime": "2023-05-25T09:30:00", "timeZone": "America/New_York" }, "recurringEventId": "TZID=America/New_York:20230525T080000" } ]}The first Event object represents a recurring event that repeats from 2023-05-24T08:00:00 to 2023-05-24T09:00:00 in Seoul time. Since it has the recurrence property, it is a recurring event. The recurrence information is specified in RRULE.
In this example, INTEREVAL is 1 and FREQ is DAILY, so it is an event that repeats daily until 20230525T230000Z. 20230525T230000Z is in UTC, which means that the last event in Seoul time is on January 26 at 8 o'clock.EXDATE represents the non-recurring event ID, which corresponds to TZID=America/New_York:20230525T080000.
The second Event object shows the details of the exceptional event. The recurringEventId matches the value of EXDATE included in the recurrence object of the recurring event, TZID=America/New_York:20230525T080000. You can see that the content and the start and end times of the event in the object differ from those of the recurring event.