Availability

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.

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 an Availability query #

This example is a query to find a time that works for two required people and one meeting room from a group. In this case we’re finding times for a 60 min meeting over the next couple of days.

{
  "participants": [
    {
      "members": [
        { 
          "sub": "acc_5ba21743f408617d1269ea1e",
          "managed_availability": true
         },
        { 
          "sub": "acc_64b17d868090ea21640c914c",
          "managed_availability": true
        }
      ],
      "required": "all"
    },
    {
      "members": [
        { "sub": "res_5ba21743f408617d12693521" },
        { "sub": "res_5ba21743f4000563a26934ea" },
        { "sub": "res_64b17d868090ea21640ad6e0" }
      ],
      "required": 1
    }
  ],
  "required_duration": { "minutes": 60 },
  "query_periods": [
    {
      "start": "2024-07-28T09:00:00Z",
      "end": "2024-07-28T18:00:00Z"
    },
    {
      "start": "2024-07-29T09:00:00Z",
      "end": "2024-07-29T18:00:00Z"
    }
  ],
  "response_format": "slots"
}

Participants #

This is an array of objects describing the rules to use in order to find available times for groups of people and/or resources. Each group describes the list of people to consider and how many need to be available.

The members attribute of each group, describes the the accounts and/or resources identified by the sub value in each member. You will receive this value when you obtain an authorization for a user’s or a resource’s calendars. Alternatively you can look it up using the UserInfo endpoint with the appropriate Bearer token.

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

Passing managed_availability set to true will respect Availability Rules defined for the Account.

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

In the second participant object we’ve used an example of a list of meeting rooms where you just need one to be available. Of course, this model can be used for choosing one or more people from a group.

Required Duration #

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

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

Response Format #

In this example slots is passed to indicate that you want the Cronofy Availability engine to do the slot calculation for you.

Typical response #

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

{
  "available_slots": [
    {
      "start": "2024-07-28T09:00:00Z",
      "end": "2024-07-28T10:00:00Z",
      "participants": [
        { "sub": "acc_5ba21743f408617d1269ea1e" },
        { "sub": "acc_64b17d868090ea21640c914c" },
        { "sub": "res_64b17d868090ea21640ad6e0" }
      ]
    },
    {
      "start": "2024-07-29T16:00:00Z",
      "end": "2024-07-29T17:00:00Z",
      "participants": [
        { "sub": "acc_5ba21743f408617d1269ea1e" },
        { "sub": "acc_64b17d868090ea21640c914c" },
        { "sub": "res_5ba21743f4000563a26934ea" },
        { "sub": "res_64b17d868090ea21640ad6e0" }
      ]
    }
  ]
}

In this case both participants are available between 09:00 and 10:00 on July 28 and 16:00 and 17:00 on July 29 UTC.

In the first period there is also one meeting room available, in the second two meeting rooms are.

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.