# 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](/developers/api/authorization/request-authorization/index.md). #### URL format ``` {data_center_url}/v1/calendars ``` #### Example Request ```http 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 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 ##### `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](/developers/data-centers/index.md). ##### `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](/developers/api/calendars/list-calendars/index.md). ##### `name` *(required)* The [`String`](/developers/api/data-types/index.md) to use as the name of the calendar. ##### `color` *(optional)* A hexadecimal color code [`String`](/developers/api/data-types/index.md) to use as the preferred color of the calendar. Support by provider: - **Apple** full support - **Exchange** no support - **Google** full support - **Office 365** supports a limited palette, so the closest match to the provided `color` will be used - **Outlook.com** supports a limited palette, so 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`](/developers/api/data-types/index.md). 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](/developers/api/calendars/application-calendars/index.md) 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`](/developers/api/data-types/index.md). 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`](/developers/api/data-types/index.md). 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`](/developers/api/data-types/index.md). This is used for targetting other API actions toward this calendar. ##### `calendar.calendar_name` This specifies the name of the calendar as a [`String`](/developers/api/data-types/index.md). 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`](/developers/api/data-types/index.md). 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`](/developers/api/data-types/index.md). 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](/developers/api/authentication/index.md) were not recognized. You should use a `refresh_token` to [refresh an Access Token`](/developers/api/authorization/refresh-token/index.md) before the request is retried. ##### 403 Forbidden The request was refused as the provided [authorization credentials](/developers/api/authorization/request-authorization/index.md) were recognized but does not grant the `create_calendar` scope. You will need to make an additional [authorization request](/developers/api/authorization/request-authorization/index.md) 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: ```json { "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: ```json { "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. --- [Read in HTML](/developers/api/calendars/create-calendar/)