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-03-26T09:00:00Z",
              "end": "2019-03-26T12:00:00Z"
            },
            {
              "start": "2019-03-27T10:00:00Z",
              "end": "2019-03-27T20:00:00Z"
            }
          ]
        }
      ],
      "required": "all"
    }
  ],
  "required_duration": { "minutes": 60 },
  "available_periods": [
    {
      "start": "2019-03-26T09:00:00Z",
      "end": "2019-03-26T18:00:00Z"
    },
    {
      "start": "2019-03-27T09:00:00Z",
      "end": "2019-03-27T18:00:00Z"
    }
  ],
  "buffer": {
    "before": { "minutes": 30 },
    "after": { "minutes": 15 }
  }
}

Example Response

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

{
  "available_periods": [
    {
      "start": "2019-03-26T09:00:00Z",
      "end": "2019-03-26T11:00:00Z",
      "participants": [
        { "sub": "acc_567236000909002" },
        { "sub": "acc_678347111010113" }
      ]
    },
    {
      "start": "2019-03-27T11:00:00Z",
      "end": "2019-03-27T17:00:00Z",
      "participants": [
        { "sub": "acc_567236000909002" },
        { "sub": "acc_678347111010113" }
      ]
    },
  ]
}

Request parameters

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 required  #

Thestart of an available period as a Time.

It must represent a future point in time.

participants.members.available_periods.end required  #

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

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

required_duration.minutes required  #

An Integer specifying the number of minutes that an available period must last to be considered viable.

Must be a value of at least 1.

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.

participants.members.managed_availability optional BETA  #

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

buffer.before.minutes optional BETA  #

An Integer specifying the minimum number of minutes that must be free before the available period starts.

Must be a positive value.

buffer.after.minutes optional BETA  #

An Integer specifying the minimum number of minutes that must be free after the available period ends.

Must be a positive value.

start_interval.minutes optional BETA  #

An Integer describing the frequency that an available period can start on.

For example, for 30 the output available periods will only start on 30 minute increments.

Must be one of 5, 10, 15, 30, 60.

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