# Create and list calendars

Source: https://developer.nylas.com/docs/cookbook/calendar/manage-calendars/

Before you can create or list events, you need a calendar ID. A user often has several calendars: a primary one, shared team calendars, and read-only subscriptions like holidays. Picking the right one, and knowing which you can write to, is the first step in any calendar integration.

The Nylas Calendar API lists every calendar on the account with one call and creates new ones with another, using the same shape across providers so you don't special-case Google against Outlook.

## How do I list a user's calendars?

Send a `GET /v3/grants/{grant_id}/calendars` request. Nylas returns each calendar with an `id`, a `name`, and flags like `is_primary`, `read_only`, and `is_owned_by_user`. You need that `id` for every event call, so listing calendars is usually the first request your integration makes. It works across all 4 providers with one response shape, whether the account is Google, Microsoft, iCloud, or Exchange.

The request below lists the calendars on an account.

```bash
curl --request GET \
  --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/calendars' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --header 'Content-Type: application/json'

```

```json
{
  "request_id": "1",
  "data": {
    "grant_id": "1",
    "description": "<string>",
    "id": "2",
    "is_primary": false,
    "location": "<string>",
    "metadata": {
      "your-key": "<string>"
    },
    "name": "<string>",
    "object": "calendar",
    "read_only": false,
    "timezone": "UTC",
    "is_owned_by_user": false
  }
}


```

## How do I create a calendar?

Send a `POST /v3/grants/{grant_id}/calendars` request with a `name`, plus optional `description`, `location`, and `timezone`. Creating calendars needs calendar write access and is supported on 2 providers: Google and Microsoft. The new calendar appears in the user's account, and its returned `id` is what you pass to the events endpoints to create events on it.

```bash
curl --compressed --request POST \
  --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/calendars' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "My New Calendar",
    "description": "Description of my new calendar",
    "location": "Location description",
    "timezone": "America/Los_Angeles"
  }'

```

If you need a calendar for a room, a piece of equipment, or anything without its own account, use a [virtual calendar](/docs/v3/calendar/virtual-calendars/) instead, which works without a connected provider.

## Things to know about calendars

A few flags on each calendar drive your logic. Most providers mark exactly 1 calendar as primary with the `is_primary` flag, a safe default when a user hasn't picked one; iCloud is the exception, with no primary-calendar concept. The `read_only` flag matters most: shared and subscribed calendars are often read-only, and you can only create or edit events where `read_only` is `false`, so check it before you write across all 4 providers.

`is_owned_by_user` separates calendars the user owns from ones shared with them, which affects what they can edit. For the full calendar object, see [using the Events API](/docs/v3/calendar/using-the-events-api/).

## What's next

- [Find open meeting times across calendars](/docs/cookbook/calendar/find-meeting-times/) using the calendar IDs you list
- [Create Google events](/docs/cookbook/calendar/events/create-events-google/) on a calendar you own
- [Virtual calendars](/docs/v3/calendar/virtual-calendars/) for rooms and resources without an account
- [Update and delete calendar events](/docs/cookbook/calendar/update-delete-events/) once events exist on a calendar