# Calendar

Source: https://developer.nylas.com/docs/reference/api/calendar/

The Nylas Calendar API allows you to create and manage calendars, and access the events they contain. Nylas uses the same commands to manage calendars across providers, and you can refer to specific calendars using the provider's `calendar_id`.

Depending on the provider, a calendar might be accessed by only one person, or shared among several users. Some common calendars might include Personal, Work, or Shared calendars.

A calendar might contain overlapping events or conflicting schedules. You can use the [Get Availability endpoint](/docs/reference/api/calendar/post-availability/) to find the best time for an event by identifying time periods that have no conflicting events among all participants.

## Find a calendar ID

You must specify a `calendar_id` in all calls you make to the Nylas Calendar API. You can use `primary` to specify the primary calendar associated with a grant, or you can look up the ID of the calendar that you want to work with and use that.

For virtual calendars, the `primary` calendar is the first created for a virtual account. You _cannot_ delete a virtual calendar that's designated as `primary`.

For iCloud, there is no `primary` calendar.

## Free/Busy information

The [Get Free/Busy Schedule endpoint](/docs/reference/api/calendar/post-calendars-free-busy/) is available for all providers, including Virtual Calendars, except for iCloud.

The [Get Availability endpoint](/docs/reference/api/calendar/post-availability/) doesn't support the `free_busy` object.

## Virtual calendars

Nylas allows you to create virtual calendars for users and resources that might not have calendars on your providers (for example, external contractors or meeting rooms). You can use the Nylas Calendar and Events APIs with the virtual accounts that power virtual calendars, just like you would any other account. Virtual accounts don't provide email or contacts features, so you can't use them with the Email or Contacts APIs.

For more information, see [Using virtual calendars](/docs/v3/calendar/virtual-calendars/).

## Metadata on calendars

You can add metadata to new and existing calendars by including the `metadata` sub-object in your `POST`, `PUT`, or `PATCH` request. For more information, see the [Metadata documentation](/docs/dev-guide/metadata/).

## Calendar scopes

The table below lists the Calendar endpoints and which scopes they require. The table shortens the full scope URI for space reasons, so add the prefix for the provider when requesting scopes.

The ☑️ in each column indicates the most restrictive scope you can request for each provider and still use that API. More permissive scopes appear under the minimum option. If you're already using one of the permissive scopes, you don't need to add the more restrictive scope.

| Endpoint                                                                                                                               | Google Scopes</br>`https://www.googleapis.com/auth/...` | Microsoft Scopes</br>`https://graph.microsoft.com/...` |
| :------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------ | :----------------------------------------------------- |
| **GET** `/calendars`</br>**GET** `/calendars/<CALENDAR_ID>`</br>**POST** `/calendars/free-busy`</br>**POST** `/calendars/availability` | `/calendar.readonly` ☑️</br>`/calendar`                 | `Calendars.Read` ☑️</br>`Calendars.ReadWrite`          |
| **POST** `/calendars`</br>**PUT** `/calendars/<CALENDAR_ID>`</br>**DELETE** `/calendars/<CALENDAR_ID>`                                 | `/calendar` ☑️                                          | `Calendars.ReadWrite` ☑️                               |

For more information about scopes, see [Using scopes to request user data](/docs/dev-guide/scopes/).

## Calendar activity notifications

You can subscribe to the following triggers so Nylas notifies you about changes to your users' calendar data:

- `calendar.created`
- `calendar.updated`
- `calendar.deleted`

For more information, see the [Calendar webhook notification schemas](/docs/reference/notifications/#calendar-notifications).

## Microsoft event considerations

Microsoft Outlook events are often shared across all calendars in a user's account. If the user creates an event on one of their calendars, you can retrieve it using another calendar ID from their grant.


## Endpoints

- **GET** `/v3/grants/{grant_id}/calendars` - [Return all calendars](https://developer.nylas.com/docs/reference/api/calendar/get-all-calendars/)
- **POST** `/v3/grants/{grant_id}/calendars` - [Create a calendar](https://developer.nylas.com/docs/reference/api/calendar/create-calendar/)
- **GET** `/v3/grants/{grant_id}/calendars/{calendar_id}` - [Return a calendar](https://developer.nylas.com/docs/reference/api/calendar/get-calendars-id/)
- **PUT** `/v3/grants/{grant_id}/calendars/{calendar_id}` - [Update a calendar](https://developer.nylas.com/docs/reference/api/calendar/put-calendars-id/)
- **DELETE** `/v3/grants/{grant_id}/calendars/{calendar_id}` - [Delete a calendar](https://developer.nylas.com/docs/reference/api/calendar/delete-calendars-id/)
- **POST** `/v3/calendars/availability` - [Get availability](https://developer.nylas.com/docs/reference/api/calendar/post-availability/)
- **POST** `/v3/grants/{grant_id}/calendars/free-busy` - [Get free/busy schedule](https://developer.nylas.com/docs/reference/api/calendar/post-calendars-free-busy/)