Availability
Required plan: EmergingFinding 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_5ba21743f408617d1269ea1e" },
{ "sub": "acc_64b17d868090ea21640c914c" }
],
"required": "all"
}
],
"required_duration": { "minutes": 60 },
"query_periods": [
{
"start": "2023-10-02T09:00:00Z",
"end": "2023-10-02T18:00:00Z"
},
{
"start": "2023-10-03T09:00:00Z",
"end": "2023-10-03T18: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-10-02T09:00:00Z",
"end": "2023-10-02T11:00:00Z",
"participants": [
{ "sub": "acc_5ba21743f408617d1269ea1e" },
{ "sub": "acc_64b17d868090ea21640c914c" }
]
},
{
"start": "2023-10-03T11:00:00Z",
"end": "2023-10-03T17:00:00Z",
"participants": [
{ "sub": "acc_5ba21743f408617d1269ea1e" },
{ "sub": "acc_64b17d868090ea21640c914c" }
]
}
]
}
In this case both participants are available between 09:00 and 11:00 on October 2 and 11:00 and 17:00 on October 3 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
- Real-Time Scheduling Generate branded, self-serve booking links straight from your application.
- Meeting Rooms Meeting Rooms are treated as any another participant when using the Availability API. However there is a feature of the participants query element that is designed specifically to handle the querying requirements for meeting rooms.
- Buffers Specify an amount of time that must be free before and/or after an event
- Constraints Specify an amount of time that must be free before and/or after an event
- Managed Availability When managing an account's availability through Availability Rules or Available Periods you can then use those to impact on their availability when using the Real-Time Scheduling and Availability endpoints.
- Ignoring Calendar Events There are situations where it makes sense to ignore the events in someone's calendars when generating a list of available slots. This article explains how to achieve that with the Cronofy Availability API.
- Sequenced Availability Scheduling a simple set of events is simply a case of making a sequence with the steps defined in the desired order.