Introduction to the Availability API

A quick start guide to using the Availability API to find times that work for all participants.

Finding a time that works for one or more participants is a very common use case for calendar sync. Whether booking an interview, scheduling a healthcare appointment or finding an available expert, understanding everyone's actual availability in real-time is crucial to creating a functional user experience.

The Availability API sits on top of the core Cronofy Calendar API to solve this problem.

availability_api

A big benefit of this being that any calendar the Cronofy supports can be queried simultaneously. So, for example, you can query across both Google and Exchange calendars and find a time that works.

This also means that it works alongside Enterprise Connect and you can mix Enterprise Connect authorizations with direct authorizations as well as meeting rooms and shared mailboxes to find a time that satisfies your use case.

Anatomy of a simple availability query

The first example is a simple query to find a time that works for two people. In this case we're finding times for a 60 min meeting on the 17th and 18th of July.

{
  "participants": [
    {
      "members": [
        { "sub": "acc_567236000909002" },
        { "sub": "acc_678347111010113" }
      ],
      "required": "all"
    }
  ],
  "required_duration": { "minutes": 60 },
  "available_periods": [
    {
      "start": "2017-07-17T09:00:00Z",
      "end": "2017-07-17T18:00:00Z"
    },
    {
      "start": "2017-07-18T09:00:00Z",
      "end": "2017-07-18T18:00:00Z"
    }
  ]
}

Participants

The members element describes the list of participants for this meeting identified by the Cronofy Account ID  as the sub value in each member. You will receive this value when you obtain an authorization for a user's calendars. Alternatively you can look it up using the /v1/account end point with the appropriate Bearer token. 

This account id stays consistent so you can safely store this against your own user record for ease of access.

The second element is required  which indicates, in this case that all members have to be available for a slot to be returned. 

Required Duration

Fairly self-explanatory. The duration of the event you're looking for.

Available Periods

This is an array of periods, described in UTC, that you wish to query for. A typical way to to derive this will be to calculate the standard working hours and generate an array of periods you want to query.

Typical response

Returned is list of time periods that can support the 60 min meeting time we're queried for.

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

In this case both participants are available between 09:00 and 11:00 on July 17th and 11:00 and 17:00 on July 18th.

Summary

This is deliberately a simple example to establish the core concepts of querying. You can explore the full Availability API reference for more details of options. We'll also be following up with additional help articles about individual working hours and more complex member selection amongst other uses.

If you do need any help with this please don't hesitate to contact us via the support widget or email: support@cronofy.com.