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 #

api.cronofy.com/v1/calendars

Example Request #

POST /v1/calendars HTTP/1.1
Host: api.cronofy.com
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. This ID should have been discovered by making a list calendars request.

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
  • office365

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.

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 should be used to help a user distinguish between their calendars as they can have multiple calendars with the same 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 should be used to help a user distinguish between their calendars as they can have multiple calendars within the same 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.

When an OAuth refresh_token is available then it should be used to request a replacement auth_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.

Search