List Calendars

Required plan: Starter

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,
      "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"
    }
  ]
}

Request Parameters #

data_center_url required

The URL for the data center you want to communicate with. Possible choices are:

  • api-au.cronofy.com - πŸ‡¦πŸ‡Ί Australia
  • api-ca.cronofy.com - πŸ‡¨πŸ‡¦ Canada
  • api-de.cronofy.com - πŸ‡©πŸ‡ͺ Germany
  • api-sg.cronofy.com - πŸ‡ΈπŸ‡¬ Singapore
  • api-uk.cronofy.com - πŸ‡¬πŸ‡§ United Kingdom
  • api.cronofy.com - πŸ‡ΊπŸ‡Έ United States

Find out more about Cronofy's data centers.

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.