Availability

Description #

Inspects calendars to determine the common availablity for people within the specified periods of time.

URL format #

api.cronofy.com/v1/availability

Example Request #

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

{
  "participants": [
    {
      "members": [
        {
          "sub": "acc_567236000909002",
          "calendar_ids": ["cal_n23kjnwrw2_jsdfjksn234"]
        },
        {
          "sub": "acc_678347111010113",
          "available_periods": [
            {
              "start": "2019-07-18T09:00:00Z",
              "end": "2019-07-18T12:00:00Z"
            },
            {
              "start": "2019-07-19T10:00:00Z",
              "end": "2019-07-19T20:00:00Z"
            }
          ]
        }
      ],
      "required": "all"
    }
  ],
  "required_duration": { "minutes": 60 },
  "available_periods": [
    {
      "start": "2019-07-18T09:00:00Z",
      "end": "2019-07-18T18:00:00Z"
    },
    {
      "start": "2019-07-19T09:00:00Z",
      "end": "2019-07-19T18:00:00Z"
    }
  ],
  "buffer": {
    "before": { "minutes": 30 },
    "after": { "minutes": 15 }
  }
}

Example Response #

Periods #

The default response_format of periods looks like this.

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

{
  "available_periods": [
    {
      "start": "2019-07-18T09:00:00Z",
      "end": "2019-07-18T11:00:00Z",
      "participants": [
        { "sub": "acc_567236000909002" },
        { "sub": "acc_678347111010113" }
      ]
    },
    {
      "start": "2019-07-19T11:00:00Z",
      "end": "2019-07-19T17:00:00Z",
      "participants": [
        { "sub": "acc_567236000909002" },
        { "sub": "acc_678347111010113" }
      ]
    }
  ]
}

Slots #

When a response_format of slots or overlapping_slots is specified, the response looks like this.

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

{
  "available_slots": [
    {
      "start": "2019-07-18T09:00:00Z",
      "end": "2019-07-18T10:00:00Z",
      "participants": [
        { "sub": "acc_567236000909002" },
        { "sub": "acc_678347111010113" }
      ]
    },
    {
      "start": "2019-07-19T10:00:00Z",
      "end": "2019-07-19T11:00:00Z",
      "participants": [
        { "sub": "acc_567236000909002" },
        { "sub": "acc_678347111010113" }
      ]
    },
    {
      "start": "2019-07-19T11:00:00Z",
      "end": "2019-07-19T12:00:00Z",
      "participants": [
        { "sub": "acc_567236000909002" },
        { "sub": "acc_678347111010113" }
      ]
    }
  ]
}

Request parameters #

response_format optional BETA  #

This can be one of the following values:

  • periods
  • slots
  • overlapping_slots

The default is periods if not specified.

This works in conjuction with start_interval to control the distribution of the periods/slots.

periods will generate contiguous available periods that are a minimum length of the required_duration.

slots will generate non-overlapping slots with length equal to the required_duration.

overlapping_slots will generate slots starting every start_interval irrespective of whether they overlap with length equal to the required_duration.

participants required  #

An array of the groups of participants whose availability should be taken into account.

At least one group must be specified, a maximum of 10 accounts may be specified over a combination of groups.

participants.members required  #

An array of participants that should have their availability taken into account as part of this group.

At least one participant must be specified and you must have been granted the read_free_busy scope for each participant involved in the availability 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 have both.

participants.members.sub required  #

The internal Cronofy ID for the account, as an ASCII-only String.

This can be retrieved by calling the UserInfo endpoint with a valid access_token

participants.members.available_periods optional  #

An array of 1 to 50 available periods within which the member is available. If omitted it is assumed the member is available whenever they do not have a “busy” event in their calendar.

participants.members.available_periods.start  #

Thestart of an available period as a Time.

It must represent a future point in time.

participants.members.available_periods.end  #

Theend of an available period as a Time.

Must be between 1 minute and 35 days after the correspondingstart.

participants.members.calendar_ids optional  #

Restricts the events contributing towards the members availability to those within the set of specified calendar_ids.

participants.members.buffer optional BETA  #

Buffer values specific to this member. If specified are used instead of any top-level buffer when considering the member’s availability.

participants.members.buffer.before optional BETA  #

A Duration specifying the minimum number of minutes that must be free for this member before an available period starts.

participants.members.buffer.after optional BETA  #

A Duration specifying the minimum number of minutes that must be free for this member after the available period ends.

participants.members.managed_availability optional BETA  #

A Boolean specifying whether managed availability should be taken into account for this member.

participants.members.availability_rule_ids optional BETA  #

An Array of availability_rule_id values referencing Availability Rules stored against the Account.

If not specified or set to null, all availability rules stored against the Account will be used.

If an empty Array is specified, ie [] then all availability rules stored against the Account will be ignored.

participants.required required  #

Either a String of all to specify that all members of the group need to be available for a period to be viable, or an Integer of 1 to specify that at least one member of the group must be available.

required_duration required  #

A Duration describing the minimum period that the participant groups must be satisfied for a period to be deemed as available.

Must be greater than zero minutes in length.

available_periods required  #

An array of 1 to 50 available periods, across up to 35 days of the period of synchronized events, within which suitable matches may be found.

available_periods.start required  #

Thestart of an available period as a Time.

It must represent a future point in time.

available_periods.end required  #

Theend of an available period as a Time.

Must be between 1 minute and 35 days after the correspondingstart.

buffer.before optional BETA  #

A Duration specifying the minimum number of minutes that must be free before the available period starts.

buffer.after optional BETA  #

A Duration specifying the minimum number of minutes that must be free after the available period ends.

start_interval optional BETA  #

A Duration describing the frequency that a sequence can start on.

For example, “every hour” or “every 15 minutes”.

Must be an increment of one of 5, 10, 15, 30, 60 minutes.

max_results optional BETA  #

An Integer describing the maximum number of available periods to return from the query.

Must be between 1 and 200 inclusive. If not provided up to 20 results will be returned.

Response parameters #

available_periods  #

An array of available periods that match the criteria specified in the request.

Up to 20, or the value specified for max_results, periods will be returned with preference being towards the soonest matches.

available_periods.start  #

Thestart of an available period as a Time.

available_periods.end  #

Theend of an available period as a Time.

available_periods.participants  #

An array of participants that are available for the given period.

available_periods.participants.sub  #

The internal Cronofy ID for the account, as an ASCII-only String.

Error responses #

401 Unauthorized #

The request was refused as the provided authentication credentials were not recognized.

Note that whilst many accounts can be part of the availability request that authentication is performed via theaccess_token for only one of them.

When an OAuthrefresh_token is available then it should be used to request a replacement auth_token before the request is retried.

402 Payment Required #

The request was refused as your plan does not include the required feature.

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

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

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

Search