Sequenced Availability ALPHA

Description #

Inspects calendars to determine the common availability for a number of pre-defined events.

For example scheduling a series of events for an interview process.

URL format #

api.cronofy.com/v1/sequenced_availability

Example Request #

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

{
  "sequence":[
    {
      "sequence_id":"123",
      "ordinal":1,
      "participants":[
        {
          "members":[
            {
              "sub":"acc_567236000909002",
              "calendar_ids":[ "cal_n23kjnwrw2_jsdfjksn234" ]
            }
          ],
          "required":"all"
        }
      ],
      "required_duration":{ "minutes": 60 },
      "start_interval":{ "minutes": 60 },
      "buffer":{
        "before":{
          "minimum": { "minutes" : 30 },
          "maximum": { "minutes" : 60 }
        },
        "after":{
          "minimum": { "minutes" : 15 },
          "maximum": { "minutes" : 30 }
        }
      }
    },
    {
      "sequence_id":"456",
      "ordinal":2,
      "participants":[
        {
          "members":[
            {
              "sub":"acc_678347111010113",
              "available_periods": [
                {
                  "start": "2019-09-21T09:00:00Z",
                  "end": "2019-09-21T12:00:00Z"
                },
                {
                  "start": "2019-09-22T10:00:00Z",
                  "end": "2019-09-22T20:00:00Z"
                }
              ]
            }
          ],
          "required":"all"
        }
      ],
      "required_duration":{ "minutes": 60 },
      "start_interval":{ "minutes": 60 },
      "buffer":{
        "before":{
          "minimum": { "minutes" : 30 },
          "maximum": { "minutes" : 60 }
        },
        "after":{
          "minimum": { "minutes" : 15 },
          "maximum": { "minutes" : 30 }
        }
      }
    }
  ],
  "available_periods": [
    {
      "start": "2019-09-21T09:00:00Z",
      "end": "2019-09-21T18:00:00Z"
    },
    {
      "start": "2019-09-22T09:00:00Z",
      "end": "2019-09-22T18:00:00Z"
    }
  ]
}

Example Response #

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

{
  "sequences":[
    {
      "sequence":[
        {
          "sequence_id":"123",
          "start": "2019-09-21T09:00:00Z",
          "end": "2019-09-21T10:00:00Z",
          "participants":[ { "sub":"acc_567236000909002" } ]
        },
        {
          "sequence_id":"456",
          "start": "2019-09-21T10:00:00Z",
          "end": "2019-09-21T11:00:00Z",
          "participants":[ { "sub":"acc_678347111010113" } ]
        }
      ]
    },
    {
      "sequence":[
        {
          "sequence_id":"123",
          "start": "2019-09-21T11:00:00Z",
          "end": "2019-09-21T12:00:00Z",
          "participants":[ { "sub":"acc_567236000909002" } ]
        },
        {
          "sequence_id":"456",
          "start": "2019-09-21T12:00:00Z",
          "end": "2019-09-21T13:00:00Z",
          "participants":[ { "sub":"acc_678347111010113" } ]
        }
      ]
    }
  ]
}

Request parameters #

API_KEY required  #

The client_secret of the client.

sequence required  #

An array containing the parts of the sequence to find availability for.

A maximum of 5 parts can be specified for a sequence

sequence.sequence_id required  #

A String value to identify this part of the sequence, must be unique for this request.

sequence.ordinal  #

A Integer value to define the order of this part of the sequence, this is used to determine desired order of the sequence.

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

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

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

sequence.participants.members.available_periods  #

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.

sequence.participants.members.available_periods.start required  #

Thestart of an available period as a Time.

It must represent a future point in time.

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

sequence.participants.members.calendar_ids  #

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

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

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

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

sequence.available_periods.start required  #

Thestart of an available period as a Time.

It must represent a future point in time.

sequence.available_periods.end required  #

Theend of an available period as a Time.

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

sequence.buffer.before.minimum  #

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

sequence.buffer.before.maximum  #

A Duration specifying the maximum number of minutes that must be free before the event starts.

sequence.buffer.after.minimum.  #

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

sequence.buffer.before.maximum  #

A Duration specifying the maximum number of minutes that must be free after the event ends.

sequence.start_interval  #

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

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

Must be one of 5, 10, 15, 20, 30, or 60 minutes.

Response parameters #

sequences  #

An array of possible sequences that match the criteria specified in the request.

sequences.sequence  #

An array of available periods which meet the criteria specifed in the request.

sequences.sequence.sequence_id  #

A value to identify this part of the sequence.

sequences.sequence.start  #

Thestart of an available period as a Time.

sequences.sequence.end  #

Theend of an available period as a Time.

sequences.sequence.participants  #

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

sequences.sequence.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