List Calendars

Required plan: Starter

Description #

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

URL format #

api.cronofy.com/v1/calendars

Example Request #

GET /v1/calendars HTTP/1.1
Host: api.cronofy.com
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,
      "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,
      "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,
      "permission_level": "sandbox"
    }
  ]
}

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.

This should be used to help a user distinguish between their calendars as they can have multiple calendars with 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 should be used to help a user distinguish between their calendars as they can have multiple calendars with the same 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 should be used to help a user distinguish between their calendars as they can have multiple calendars within the same 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 only true for Google calendars which have Google Meet available.

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.

In order to perform a edit or delete on external events you must have unrestricted access to the calendar.