List Calendars

Description #

Returns a list of all the authenticated user’s calendars.

URL format #

{data_center_url}/v1/calendars

Example Request #

GET /v1/calendars HTTP/1.1
Host: {data_center_url}
Authorization: Bearer {ACCESS_TOKEN}

Example Response #

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "calendars": [
    {
      "provider_name": "google",
      "profile_id": "pro_n23kjnwrw2",
      "profile_name": "example@cronofy.com",
      "calendar_id": "cal_n23kjnwrw2_jsdfjksn234",
      "calendar_name": "Home",
      "calendar_readonly": false,
      "calendar_deleted": false,
      "calendar_primary": true,
      "calendar_integrated_conferencing_available": true,
      "calendar_attachments_available": false,
      "permission_level": "sandbox"
    },
    {
      "provider_name": "google",
      "profile_id": "pro_n23kjnwrw2",
      "profile_name": "example@cronofy.com",
      "calendar_id": "cal_n23kjnwrw2_n1k323nkj23",
      "calendar_name": "Work",
      "calendar_readonly": true,
      "calendar_deleted": true,
      "calendar_primary": false,
      "calendar_integrated_conferencing_available": false,
      "calendar_attachments_available": false,
      "permission_level": "sandbox"
    },
    {
      "provider_name": "apple",
      "profile_id": "pro_fe145c37de",
      "profile_name": "example@cronofy.com",
      "calendar_id": "cal_fe145c37de_3nkj23wejk1",
      "calendar_name": "Bank Holidays",
      "calendar_readonly": true,
      "calendar_deleted": false,
      "calendar_primary": false,
      "calendar_integrated_conferencing_available": false,
      "calendar_attachments_available": true,
      "permission_level": "sandbox"
    }
  ]
}

Request Parameters #

Response parameters #

calendars.provider_name  #

This specifies the provider of the calendar as a lowercase, ASCII-only String.

Currently one of:

• apple
• cronofy
• exchange
• google
• live_connect

However, this will be expanded over time and therefore consumers should support any value for this field.

The cronofy provider is associated with an Application Calendar

This can help distinguish between connected calendar profiles as they can have the same name.

calendars.profile_id  #

This specifies the ID of the profile, a profile may consist of many calendars, as an ASCII-only String.

This is used for targetting other API actions toward this profile.

calendars.profile_name  #

This specifies the name of the profile that the calendar is part of as a String.

This can help distinguish between connected calendar profiles as they can have the same provider name.

calendars.calendar_id  #

This specifies the ID of the calendar as an ASCII-only String.

This is used for targetting other API actions toward this calendar.

calendars.calendar_name  #

This specifies the name of the calendar as a String.

This can help distinguish between multiple connected calendars within the same calendar profile.

calendars.calendar_readonly  #

This specifies whether the calendar is readonly as a Boolean.

Calendars where calendar_readonly is true will refuse requests to create, update, or delete events.

calendars.calendar_deleted  #

This specifies whether the calendar has been deleted as a Boolean.

Calendars where calendar_deleted is true will refuse requests to create, update, or delete events.

calendars.calendar_primary  #

This specifies whether the calendar is the primary calendar for its profile as a Boolean.

Current support by provider:

• Apple has no concept of primary calendars
• Exchange has a primary calendar which cannot change
• Google has a primary calendar which cannot change
• Office 365 has a primary calendar which cannot change
• Outlook.com has a primary calendar which can change

calendars.calendar_integrated_conferencing_available  #

This specifies whether the calendar supports integrated conferencing as a Boolean. Currently this is true for:

• Google calendars which have Google Meet available.
• Office 365 calendars connected using the Graph API with integrated MS Teams.

calendars.calendar_attachments_available  #

This specifies whether the calendar supports adding attachments to events as a Boolean.

Currently this is true for the following providers:

• Apple
• Exchange
• Google with Drive permission granted
• Office 365

calendars.permission_level  #

This value specifies the current permission level granted to the client for the specified calendar. Permitted values are currently either sandbox or unrestricted.

To edit or delete an external event you must have unrestricted access to the calendar.