Read Events

Description #

Returns a list of events across all of a users calendars.

By default, the events you are managing on behalf of the account are excluded from the query results.

The returned events will start before the given to Date and will end on or after the given from Date.

Note that the events you manage are not subject to the default from and to date restrictions and so if you specify neither, you will retrieve all the events you are managing for the account across all of time.

Example Request #

The parameters are encoded in the querystring as specified in appendix B of RFC 6749. Additional linebreaks are added to the request’s path for clarity.

GET /v1/events?from={FROM_DATE}&to={TO_DATE}&tzid={TZID} 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

{
  "pages": {
    "current": 1,
    "total": 2,
    "next_page": "https://api.cronofy.com/v1/events/pages/08a07b034306679e"
  },
  "events": [
    {
      "calendar_id": "cal_U9uuErStTG@EAAAB_IsAsykA2DBTWqQTf-f0kJw",
      "event_uid": "evt_external_54008b1a4a41730f8d5c6037",
      "summary": "Company Retreat",
      "description": "",
      "start": "2014-09-06",
      "end": "2014-09-08",
      "deleted": false,
      "created": "2024-05-03T08:00:01Z",
      "updated": "2024-05-03T09:24:16Z",
      "location": {
        "description": "Beach"
      },
      "participation_status": "needs_action",
      "attendees": [
        {
          "email": "example@cronofy.com",
          "display_name": "Example Person",
          "status": "needs_action"
        }
      ],
      "organizer": {
        "email": "example@cronofy.com",
        "display_name": "Example Person"
      },
      "transparency": "opaque",
      "status": "confirmed",
      "categories": [],
      "recurring": false,
      "event_private": false,
      "options": {
        "delete": true,
        "update": true,
        "change_participation_status": true
      }
    }
  ]
}

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.

from optional #

The oldest Date from which to return events. When provided, this must be within the last 42 days.

If not provided, defaults to the maximum value of 42 days in the past. This value will not accept a time as part of the string, it will ignore the time provided and read from the start of the day.

To surpass this 42 day limit, the emerging plan is needed along with a message to support requesting an extension to the sync period. Plans and pricing can be found here.

to optional #

The Date to return events up until, when provided must be less than or equal to 201 days in the future.

If not provided, defaults to the maximum value of 201 days in the future.

Note that the query times are inclusive of the from date and exclusive of the to date - the results will not include events occurring on the to date. For example, if you request from 2024-05-03 to 2024-05-10, the results will contain events on the days of the 2024-05-03, up to and including the 2024-05-09 but not 2024-05-10. To include the 2024-05-10 you will need to set the to date as 2024-05-11.

This value will also not accept timing as part of the string, it will ignore the time provided and read from the start of the day.

The maximum value of 42 days in the past and 201 days in the future applies from the date you are carrying out the read events query rather than the date specified in the from and to parameters in the query. The reason for this is that the sync window for Cronofy starts 42 days in the past and ends 201 days in the future, so Cronofy only store event information for calendars in this range and can’t return event information when these values are exceeded.

tzid required #

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

Common examples are:

Etc/UTC
Europe/Paris
America/Chicago

It is recommended that you use the same tzid for all requests made for an individual user in order to ensure all their events are returned to you.

include_deleted optional #

A Boolean specifying whether managed and external events that have been deleted should included or excluded from the results.

If not provided, only non-deleted events are returned.

include_moved optional #

A Boolean specifying whether managed and external events that have ever existed within the given window should be included or excluded from the results.

If not provided, only events that are currently within the search period are returned.

last_modified optional #

The Time that events must be modified on or after in order to be returned.

If not provided, all events are returned regardless of when they were last modified.

include_managed optional #

A Boolean specifying whether events that you are managing for the account should be included or excluded from the results.

If not provided, only non-managed events are returned.

Note that the events you manage are not subject to the default from and to date restrictions. So if you don’t specify a from value, you will see managed events that occur in the past beyond the 42 day limit, and if you don’t specify a to value you will see managed events that occur in the future beyond the 201 day limit. If you specify neither, you will retrieve all the events you are managing for the account across all of time.

only_managed optional #

A Boolean specifying whether only events that you are managing for the account should be included in the results.

calendar_ids[] optional #

Restricts the returned events to those within the set of specified calendar_ids.

The calendar_ids[] parameter can be specified multiple times within the query string to include events from multiple calendars:

calendar_ids[]=cal_U9uuErStTG@EAAAB_IsAsykA2DBTWqQTf-f0kJw&calendar_ids[]=cal_U@y23bStTFV7AAAB_iWTeH8WOCDOIW@us5gRzww

The possible calendar_ids can be discovered through the list calendars endpoint.

If no calendars are specified, the default behaviour is to return events from all of the user’s calendars.

localized_times optional #

A Boolean specifying whether the events should have their start and end times returned with any available localization information.

If not provided the start and end times will be returned as simple Time values.

The localized times are extracted on a best-effort basis from the underlying providers. We do not receive time zone information from all providers and so their events will always be returned with a time zone identifier of Etc/UTC.

As providers expose this data, or we implement deeper integrations with their platforms, the time zone data available to you will be improved without changes being required to your code.

include_geo optional #

A Boolean specifying whether the events should have their location.lat and location.long returned where available.

Verified applications must have geo-location included in their plan or the API call will result in a 402 error.

include_userinfo optional #

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

Response parameters #

pages.current #

An Integer specifying which page of the result set the current request is for.

pages.total #

An Integer specifying the total number of pages in the result set.

pages.next_page optional #

When present, a String specifying the URL for the next page of results.

The next page of results can be retrieved by issuing a GET request to this URL and you will receive a response in the same format as a regular read events request.

userinfo optional #

An embedded userinfo response if include_userinfo was specified.

events.calendar_id #

This specifies the ID of the calendar as an ASCII-only String.

events.event_uid #

This uniquely identifies the event as an ASCII-only String.

events.summary #

The String value of the summary, sometimes referred to as the name, of the event.

events.description #

The plain text String value of the description, sometimes referred to as the notes, of the event.

events.start #

When localized_times is not specified or is false, the Time or Date representing when the event starts.

When localized_times is true, an object with two attributes, time and tzid:

{
  "time": "2014-09-13T23:00:00+02:00",
  "tzid": "Europe/Paris"
}

The time attribute is the Time or Date representing when the event starts. This will be provided with an offset matching that of the corresponding tzid.

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

events.end #

When localized_times is not specified or is false, the Time or Date by which the event ends.

When localized_times is true, an object with two attributes, time and tzid:

{
  "time": "2014-09-13T23:00:00+02:00",
  "tzid": "Europe/Paris"
}

The time attribute is the Time or Date by which the event ends. This will be provided with an offset matching that of the corresponding tzid.

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

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.

events.url #

A String that represents the url value associated with the event.

Support for event URLs is currently limited to Apple and Google.

events.deleted #

This specifies whether the event has been deleted as a Boolean.

events.created #

The Time the event was created.

events.updated #

The Time the event was last updated.

events.location.description optional #

The plain text String describing the event’s location.

events.location.lat optional #

The String representing the event’s latitude.

events.location.long optional #

The String representing the event’s longitude.

events.event_id optional #

When the event is one you are managing for the account, the event_id you specified when creating the event will be returned to allow you to reconcile it against your system.

events.participation_status #

A String representing the participation status of the account with regard to the event.

One of:

needs_action
the event needs action by the account, usually they have been sent an invite but are yet to respond
accepted
they have accepted an invitation to the event
declined
they have declined an invitation to the event
tentative
they have tentatively accepted an invitation to the event
unknown
their participation status for the event is unknown

This is intended to help discern the status of the event for the account without having to understand which of the attendees entries relates to them. It will also be populated when there are no attendees as this is inferred to be a personal entry.

unknown is not expected to be used but is included and documented so there is a documented response for events we may not know how to categorize.

events.attendees.email #

The email address associated with the attendee as a String.

events.attendees.display_name #

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

events.attendees.status #

A String representing the participation status of the attendee with regard to the event.

One of:

needs_action
the event needs action by the attendee, usually they have been sent an invite but are yet to respond
accepted
they have accepted an invitation to the event
declined
they have declined an invitiation to the event
tentative
they have tentatively accepted an invitation to the event
unknown
their participation status for the event is unknown

unknown is not expected to be used but is included and documented so there is a documented response for attendees we may not know how to categorize.

events.organizer.email #

The email address of the organizer as a String.

For Managed Events the value of the organizer parameter is always null.

events.organizer.display_name #

A human-friendly name of the organizer as a String, may be null.

events.transparency #

A String defining whether an event is transparent or not to free-busy searches.

One of:

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
unknown
the transparency of the event is unknown

unknown is not expected to be used but is included and documented so there is a documented response for events we may not know how to categorize.

events.extended_transparency ^ALPHA #

A String providing an enhanced view on a standard transparency value and exposes more about the nature of the event when available from the calendar provider.

This value will always be populated and will match the value of transparency if none of the enhanced values are relevant or available.

Currently only events within Microsoft 365 and Exchange calendars can return the extended values.

This may be one of the standard transparency values as above:

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
unknown
the transparency of the event is unknown

Or an an extended value:

working_elsewhere
indicates the user is working away from their normal site
tentative
indicates an invitation not yet responded to, or which has been responded to tentatively
out_of_office
indicates the user is unavailable due to being out of the office, such as being on vacation

These values map to Microsoft Outlook’s “Show as” UI and to standard transparency as follows:

Outlook Show as	transparency	extended_transparency
Free	transparent	transparent
Busy	opaque	opaque
Working elsewhere	opaque	working_elsewhere
Tentative	opaque	tentative
Away	opaque	out_of_office

unknown is not expected to be used but is included and documented so there is a documented response for events we may not know how to categorize.

events.status #

A String defining the overall status of the event. This is provided from the calendar providers but does not represent a summary of the attendee statuses.

One of:

tentative
the event is probably going to occur
confirmed
the event is going to occur
cancelled
the event is no longer going to occur
unknown
the status of the event is unknown

unknown is not expected to be used but is included and documented so there is a documented response for events we may not know how to categorize.

events.conferencing.provider_name optional #

The String value for the conferencing provider used for the meeeting.

events.conferencing.join_url optional #

The String value for the conferencing URL that can be used to join the meeting.

meeting_url optional #

The String value for the conferencing URL that can be used to join the meeting, if the event is an external event (not created by Cronofy).

events.categories #

An array of Strings exposing the categories assigned to the event.

Each category is a free-text String. For the underlying providers that do not support the concept of categories, this will always be an empty array.

events.tags optional #

An Object describing zero or more contextual Tag values currently attached to the event.

events.attachments optional ^ALPHA #

An Array of the ids of attachments currently attached to the event.

events.recurring #

A Boolean specifying whether this is a recurring event.

events.series_identifier optional #

A String indicating the recurring series the event is a part of, when relevant.

Recurring events are created as external events and so this parameter will only be present on the following recurring events and not the original managed event from which the recurrence is created.

events.event_private #

A Boolean specifying whether this is a private event.

events.options.delete #

A Boolean specifying whether permission exists to delete this event.

events.options.update #

A Boolean specifying whether permission exists to update this event.

events.options.change_participation_status #

A Boolean specifying whether permission exists to change the user’s participation status with regard to this event.

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.

Incremental Synchronization #

When performing incremental synchronization, usually in reaction to a change push notification, there is a recommended combination to fetch incremental changes in order to update your cache of event information.

tzid is required - it is generally recommended this is a consistent value such as Etc/UTC
both from and to should be omitted from the request to ensure all changes are received
include_deleted should be true to receive details of events that have been deleted, not just those updated or changed
include_managed should be true to ensure events you are managing are included if you have such access
last_modified should be provided to only return the events changed on or after the specified time - this can be tracked by your application seperately, or the changes_since parameter of the push notification used if you are processing every notification

Example Request #

GET /v1/events?tzid=Etc%2FUTC&last_modified={changes_since}&include_ids=true&include_deleted=true&include_managed=true&include_free=true 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

{
  "pages": {
    "current": 1,
    "total": 1
  },
  "events": [
    {
      "calendar_id": "cal_U9uuErStTG@EAAAB_IsAsykA2DBTWqQTf-f0kJw",
      "event_uid": "evt_external_54008b1a4a41730f8d5c6037",
      "summary": "Company Retreat",
      "description": "",
      "start": "2014-09-06",
      "end": "2014-09-08",
      "deleted": false,
      "created": "2024-05-03T08:00:01Z",
      "updated": "2024-05-03T09:24:16Z",
      "location": {
        "description": "Beach"
      },
      "participation_status": "needs_action",
      "attendees": [
        {
          "email": "example@cronofy.com",
          "display_name": "Example Person",
          "status": "needs_action"
        }
      ],
      "organizer": {
        "email": "example@cronofy.com",
        "display_name": "Example Person"
      },
      "transparency": "opaque",
      "status": "confirmed",
      "categories": [],
      "recurring": false,
      "event_private": false,
      "options": {
        "delete": true,
        "update": true,
        "change_participation_status": true
      }
    }
  ]
}

Read Events

Description #

Example Request #

Example Response #

Request parameters #

data_center_url required

from optional #

to optional #

tzid required #

include_deleted optional #

include_moved optional #

last_modified optional #

include_managed optional #

only_managed optional #

calendar_ids[] optional #

localized_times optional #

include_geo optional #

include_userinfo optional #

Response parameters #

pages.current #

pages.total #

pages.next_page optional #

userinfo optional #

events.calendar_id #

events.event_uid #

events.summary #

events.description #

events.start #

events.end #

events.url #

events.deleted #

events.created #

events.updated #

events.location.description optional #

events.location.lat optional #

events.location.long optional #

events.event_id optional #

events.participation_status #

events.attendees.email #

events.attendees.display_name #

events.attendees.status #

events.organizer.email #

events.organizer.display_name #

events.transparency #

events.extended_transparency ALPHA #

events.status #

events.conferencing.provider_name optional #

events.conferencing.join_url optional #

meeting_url optional #

events.categories #

events.tags optional #

events.attachments optional ALPHA #

events.recurring #

events.series_identifier optional #

events.event_private #

events.options.delete #

events.options.update #

events.options.change_participation_status #

Error responses #

401 Unauthorized #

403 Forbidden #

422 Unprocessable #

Incremental Synchronization #

Example Request #

Example Response #

events.extended_transparency ^ALPHA #

events.attachments optional ^ALPHA #