Free-busy

Description #

Returns a list of free-busy information 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 free-busy periods 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/free_busy?from={FROM_DATE}&to={TO_DATE}&tzid={TZID} HTTP/1.1
Host: api.cronofy.com
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/free_busy/pages/caa2dca822d5d74d98104489"
  },
  "free_busy": [
    {
      "calendar_id": "cal_U9uuErStTG@EAAAB_IsAsykA2DBTWqQTf-f0kJw",
      "start": "2021-06-24T08:00:00Z",
      "end": "2021-06-24T08:30:00Z",
      "free_busy_status": "busy",
    },
    {
      "calendar_id": "cal_U9uuErStTG@EAAAB_IsAsykA2DBTWqQTf-f0kJw",
      "start": "2021-06-26",
      "end": "2021-06-27",
      "free_busy_status": "free",
    }
  ]
}

Request parameters #

from optional #

The minimum Date from which to return free-busy information.

If not provided, defaults to the minimum value of 42 days in the past.

to optional #

The Date to return free-busy information up until.

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

Note that the results will not include events occurring on this date.

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

calendar_ids[] optional #

Restricts the returned free-busy information to that within the set of specified calendar_ids.

The calendar_ids[] parameter can be specified multiple times within the query string to include free-busy information 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 free-busy periods 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.

include_userinfo optional #

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

include_ids optional #

A Boolean specifying whether the response should include IDs to identify the specific event, namely the event_uid and event_id response parameters.

include_free optional #

A Boolean specifying whether events that have a free_busy_status of free should always be included in the results.

If not provided, events that have a free_busy_status of free are omitted as they do not impact availability.

include_deleted optional #

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

If not provided, only non-deleted events 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.

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 free-busy request.

userinfo optional #

An embedded userinfo response if include_userinfo was specified.

free_busy.calendar_id #

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

free_busy.start #

When localized_times is not specified or is false, the Time or Date representing when the free-busy period starts.

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

{
  "time": "2021-06-24T23:00:00+02:00",
  "tzid": "Europe/Paris"
}

The time attribute is the Time or Date representing when the free-busy period 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

free_busy.end #

When localized_times is not specified or is false, the Time or Date by which the free-busy period ends.

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

{
  "time": "2021-06-24T23:00:00+02:00",
  "tzid": "Europe/Paris"
}

The time attribute is the Time or Date by which the free-busy period 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

free_busy.free_busy_status #

A String defining the free-busy status of the block.

One of:

tentative
the user is probably busy for this period of time
busy
the user is busy for this period of time
free
the user is free for this period of time
unknown
the status of the period is unknown

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

free_busy.event_uid #

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

free_busy.event_id #

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.

free_busy.deleted #

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

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 free-busy 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_ids should be true in order to receive an event_uid which is a consistent identifier for an event
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
include_free should be true to ensure events whose free_busy_status changes to free are never omitted
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/free_busy?tzid=Etc%2FUTC&last_modified={changes_since}&include_ids=true&include_deleted=true&include_managed=true&include_free=true HTTP/1.1
Host: api.cronofy.com
Authorization: Bearer {ACCESS_TOKEN}

Example Response #

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

{
  "pages": {
    "current": 1,
    "total": 1
  },
  "free_busy": [
    {
      "calendar_id": "cal_U9uuErStTG@EAAAB_IsAsykA2DBTWqQTf-f0kJw",
      "event_uid": "evt_external_54008b1a4a41730f8d5c6037",
      "start": "2021-06-24T08:00:00Z",
      "end": "2021-06-24T08:30:00Z",
      "free_busy_status": "busy",
      "deleted": false,
    },
    {
      "calendar_id": "cal_U9uuErStTG@EAAAB_IsAsykA2DBTWqQTf-f0kJw",
      "event_uid": "evt_external_567234999823400000",
      "start": "2021-06-26",
      "end": "2021-06-27",
      "free_busy_status": "free",
      "deleted": true,
    }
  ]
}