Scheduling

Required plan: Emerging

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 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 over the next couple of days.

{
  "participants": [
    {
      "members": [
        { "sub": "acc_567236000909002" },
        { "sub": "acc_678347111010113" }
      ],
      "required": "all"
    }
  ],
  "required_duration": { "minutes": 60 },
  "query_periods": [
    {
      "start": "2023-03-25T09:00:00Z",
      "end": "2023-03-25T18:00:00Z"
    },
    {
      "start": "2023-03-26T09:00:00Z",
      "end": "2023-03-26T18: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 endpoint 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.

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.

Typical response #

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

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

In this case both participants are available between 09:00 and 11:00 on March 25 and 11:00 and 17:00 on March 26 UTC.

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.

In This Section