Create or Update Event

Description #

Creates or updates an event within a user’s calendar.

URL format #

api.cronofy.com/v1/calendars/{calendar_id}/events

Example Request #

POST /v1/calendars/cal_n23kjnwrw2_jsdfjksn234/events HTTP/1.1
Host: api.cronofy.com
Authorization: Bearer {ACCESS_TOKEN}
Content-Type: application/json; charset=utf-8

{
  "event_id": "qTtZdczOccgaPncGJaCiLg",
  "summary": "Board meeting",
  "description": "Discuss plans for the next quarter.",
  "start": "2014-08-05T15:30:00Z",
  "end": "2014-08-05T17:00:00Z",
  "location": {
    "description": "Board room"
  }
}

Example Response #

HTTP/1.1 202 Accepted

Request parameters #

calendar_id required  #

The calendar_id of the calendar you wish the event to be added to. This ID should have been discovered by making a list calendars request and must not have a calendar_readonly or calendar_deleted value that is true.

event_id required  #

The String that uniquely identifies the event. The first request made for a calendar_id and event_id combination will create an entry in the calendar and all subsequent requests will update the details of the event.

Usually this will be your own internal ID for the event, encoded as a String.

summary required  #

The String of up to 1024 characters to use as the summary, sometimes referred to as the name, of the event.

description required  #

The plain text String of up to 4096 characters to use as the description, sometimes referred to as the notes, of the event.

tzid optional  #

A String representing a known time zone identifier from the IANA Time Zone Database.

Common examples are:

  • Etc/UTC
  • Europe/Paris
  • America/Chicago

When provided, specifies the default tzid to use for the start and end times of the event if they do not specify their own.

If not provided, Etc/UTC is used by default.

Please note the caveats on time zone usage by provider.

start required  #

The start time can be provided as a simple Time or Date string or an object with two attributes, time and tzid:

{
  "time": "2014-08-05T17:00:00Z",
  "tzid": "Europe/Paris"
}

The time attribute specifies the Time or Date to use as the start of the event. Regardless of the tzid used, this value is always provided in UTC time so as to not be ambiguous.

The tzid attribute specifies a String representing a known time zone identifier from the IANA Time Zone Database.

Common examples are:

  • Etc/UTC
  • Europe/Paris
  • America/Chicago

When provided, specifies the tzid to use for the start time of the event.

If not provided, the tzid attribute of the event is used if specified, otherwise Etc/UTC is used.

Please note the caveats on time zone usage by provider.

When start is specified as a Time, end must be specified as a Time. Likewise, when start is specified as a Date, end must be specified as a Date.

end required  #

The end time can be provided as a simple Time or Date string or an object with two attributes, time and tzid:

{
  "time": "2014-08-05T17:00:00Z",
  "tzid": "Europe/Paris"
}

The time attribute specifies the Time or Date to use as the end time of the event. Regardless of the tzid used, this value is always provided in UTC time so as to not be ambiguous. Also, it must be later in time than the start of the event.

The tzid attribute specifies a String representing a known time zone identifier from the IANA Time Zone Database.

Common examples are:

  • Etc/UTC
  • Europe/Paris
  • America/Chicago

When provided, specifies the tzid to use for the end time of the event.

If not provided, the tzid attribute of the event is used if specified, otherwise Etc/UTC is used.

Please note the caveats on time zone usage by provider.

When start is specified as a Time, end must be specified as a Time. Likewise, when start is specified as a Date, end must be specified as a Date.

Also note that end is exclusive, for Time-based events this makes no noticeable difference, but for Date-based events this can be confusing. It may help to think of the end as the point in time by which the event will have ended. When based on time the event an event with an end of 11:30 is actually expected to end at 11:29.99999 so it would not overlap a following event starting at 11:30. When working with dates the same logic applies so an all day event you wish to cover March 17th would start on March 17th but end before March 18th.

location.description optional  #

The plain text String of up to 1024 characters describing the event’s location.

location.lat optional BETA  #

The String to use as the latitude of the event’s location.

Must be between -180 and 180.

location.long optional BETA  #

The String to use as the longitude of the event’s location.

Must be between -85.05115 and 85.05115.

url optional  #

A String value which must be parseable as a URI as defined as defined in RFC 1738 and RFC 2111.

Omitting the value will leave the URL unchanged. Setting the value to null will remove the URL if supported by the provider.

Support for event URLs is currently limited to Apple and Google. Please note there is an issue with Google whereby URLs are not removable once they are provided.

transparency optional  #

A String value representing the transparency of the event.

Either:

  • opaque
    the account should appear as busy for the duration of the event
  • transparent
    the account should not appear as busy for the duration of the event

If not provided, transparent is used for all-day events, and opaque for Time-based events.

color optional  #

A hexadecimal color code String (eg. #49BED8) to use as the preferred color of the event.

Support by provider:

  • Apple sets the COLOR property from RFC 7986 in anticipation of future client support
  • Exchange no support
  • Google support for a limited palette, the closest match to the provided color will be used
  • Office 365 no support
  • Outlook.com no support
reminders optional  #

You can provide an array of up to 5 reminders for an event. They should be provided in order of priority for your application, not time order. This is because the providers support a varying number of reminders and we will set as many as they allow, in the order you provide them.

Number of reminders supported per provider:

  • Apple 5 reminders, note that icloud.com will only display two
  • Exchange 1 reminder
  • Google 5 reminders
  • Office 365 1 reminder
  • Outlook.com 1 reminder

For example, if you provide 3 reminders and the provider only supports one, we will use the first one you specify, not the earliest or the latest one.

As a concrete example, whilst we advise erring on the side of setting less reminders rather than more, it is easy to imagine that 3 reminders may be useful for an appointment:

  • 30 minutes before event start - get to the appointment
  • 24 hours before event start - remember about the appointment
  • At event start - the appointment should have started

In a request this would look like:

POST /v1/calendars/cal_n23kjnwrw2_jsdfjksn234/events HTTP/1.1
Host: api.cronofy.com
Authorization: Bearer {ACCESS_TOKEN}
Content-Type: application/json; charset=utf-8

{
  "event_id": "qTtZdczOccgaPncGJaCiLg",
  "summary": "Board meeting",
  "description": "Discuss plans for the next quarter.",
  "start": "2014-08-05T15:30:00Z",
  "end": "2014-08-05T17:00:00Z",
  "location": {
    "description": "Board room"
  },
  "reminders": [
    { "minutes": 30 },
    { "minutes": 1440 },
    { "minutes": 0 }
  ]
}
reminders.minutes required  #

An Integer specifying the number of minutes before the start of the event that the reminder should occur.

Must be between 0 and 40,320, from the time the event starts to 4 weeks before the event starts, inclusive.

reminders_create_only optional  #

A Boolean specifying whether reminders should only be set when creating an event, or for updates as well.

When set to true, if the event already exists then its reminders will be left untouched. This allows you to create an event with default reminders but allow the user to alter them as they wish.

attendees optional  #

Attendees to an event can be invited and removed, if the attendees should not be changed then omitting the attribute will leave the attendees unchanged.

An concrete example of this is shown below where one attendee should be invited and another removed

POST /v1/calendars/cal_n23kjnwrw2_jsdfjksn234/events HTTP/1.1
Host: api.cronofy.com
Authorization: Bearer {ACCESS_TOKEN}
Content-Type: application/json; charset=utf-8

{
  "event_id": "qTtZdczOccgaPncGJaCiLg",
  "summary": "Board meeting",
  "description": "Discuss plans for the next quarter.",
  "start": "2014-08-05T15:30:00Z",
  "end": "2014-08-05T17:00:00Z",
  "location": {
    "description": "Board room"
  },
  "attendees": {
    "invite": [
      {
        "email": "invite@example.com",
        "display_name": "Example Invite"
      }
    ],
    "remove": [
      {
        "email": "remove@example.com",
        "display_name": "Example remove"
      }
    ]
  }
}
attendees.invite optional  #

An array of attendees to invite to the event.

attendees.invite.email required  #

The email address associated with the attendee as a String.

attendees.invite.display_name optional  #

A human-friendly name associated with the attendee as a String, may be null.

attendees.remove optional  #

An array of attendees to remove from the event.

attendees.remove.email required  #

The email address associated with the attendee as a String.

attendees.remove.display_name optional  #

A human-friendly name associated with the attendee as a String, may be null.

Please note, if too many invites are sent by Outlook.com users in a short period of time anti-spam measures may lock their account. They will then need to fully authenticate their account to remove the lock.

event_private optional BETA  #

The Boolean value to determine if this event should be created as private or not.

The default value of this is false.

include_userinfo optional  #

A Boolean specifying whether the response should include an embedded userinfo response.

Caveats #

Time Zone Information  #

Time zone information can be provided with your events so we can insert events with localized times into your users calendars when the underlying provider allows.

Current time zone support by provider:

  • Apple separate time zones for start and end
  • Exchange uses start time zone for both start and end
  • Google uses start time zone for both start and end
  • Office 365 uses start time zone for both start and end
  • Outlook.com uses start time zone for both start and end

Please note that even we when can push a separate time zone for start and end, some clients (for example OSX Calendar.app) will display them as if they are both for the start time zone.

Response parameters #

This request has no response body unless include_userinfo was specified, in which case it will include an embedded userinfo response under a userinfo parameter.

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 read_free_busy scope which was required for the request.

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

Note that the read_events scope implicitly includes this scope as it allows access to a higher level of information than free-busy so you do not have to request both.

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 tzid parameter, you would receive a response like:

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

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

Search