Create Calendar

Description #

Creates a calendar within a user’s profile.

In order for this to be possible, you must request the create_calendar scope when requesting authorization to access the user’s calendars.

URL format #

{data_center_url}/v1/calendars

Example Request #

POST /v1/calendars HTTP/1.1
Host: {data_center_url}
Authorization: Bearer {ACCESS_TOKEN}
Content-Type: application/json; charset=utf-8

{
  "profile_id": "pro_n23kjnwrw2",
  "name": "New Calendar",
  "color": "#49BED8"
}

Example Response #

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

{
  "calendar": {
    "provider_name": "google",
    "profile_id": "pro_n23kjnwrw2",
    "profile_name": "example@cronofy.com",
    "calendar_id": "cal_n23kjnwrw2_sakdnawerd3",
    "calendar_name": "New Calendar",
    "calendar_readonly": false,
    "calendar_deleted": false
  }
}

Request parameters #

profile_id required  #

The profile_id of the profile you wish the calendar to be added to. You can get this ID by calling the List Calendars API.

name required  #

The String to use as the name of the calendar.

color optional  #

A hexadecimal color code String to use as the preferred color of the calendar.

Support by provider:

• Apple full support
• Exchange no support
• Google full support
• Office 365 no support
• Outlook.com support for a limited palette, the closest match to the provided color will be used

Response parameters #

calendar.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.

calendar.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.

calendar.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.

calendar.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.

calendar.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.

calendar.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.

calendar.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.

Error responses #

401 Unauthorized #

The request was refused as the provided authentication credentials were not recognized.

You should use a refresh_token to refresh an Access Token` before the request is retried.

403 Forbidden #

The request was refused as the provided authorization credentials were recognized but does not grant the create_calendar scope.

You will need to make an additional authorization request including the create_calendar scope before retrying the request.

422 Unprocessable #

The request was unable to be processed due to it containing invalid parameters.

The response will contain a JSON object containing one or more errors relating to the invalid parameters.

For example, if you omitted the required name field, you would receive a response like:

{
  "errors": {
    "name": [
      {
        "key": "errors.required",
        "description": "required"
      }
    ]
  }
}

The key field is intended for programmatic use and the description field is a human-readable equivalent.

423 Locked #

Unlike most of our API calls, calendar creation needs to be proxied through to the underlying provider. Therefore, these requests are generally slower and more liable to failure due to more parties being involved.

Also, it is worth highlighting that some providers (only exchange at this point in time) disallow calendars with duplicate names. If you provide a duplicate name, you will receive a 422 Unprocessable response with a body like:

{
  "errors": {
    "name": [
      {
        "key": "errors.duplicate_calendar_name",
        "description": "A calendar with this name already exists and the provider does not allow duplicates"
      }
    ]
  }
}

The key field is intended for programmatic use and the description field is a human-readable equivalent.