Check calendar availability
The Nylas APIs offer multiple ways to get information about end users' availability, so you can book meetings or run other time-based operations. This page describes the Availability endpoint and how to work with it.
How the Availability endpoint works
You can use the Availability endpoint to find space in an end user's primary calendar for a meeting with specific and detailed criteria. These endpoints allow you to query for availability amongst a group of participants, so you can book collective meetings or you can book one person who is available. The endpoints return a list of time_slots which meet the criteria you set in your request, along with information about which participants meet the criteria.
Each Availability request has a few main components:
If you want to find simple information about a single participant's availability, see the Free/Busy documentation.
Meeting information
The properties at the top level of an Availability request specify when you want to book the meeting, and the participants you want to include. Nylas checks the participants' availability during the specified time period.
{
"participants": [
{
"email": "user@example.com",
"calendar_ids": [
"primary"
],
"open_hours": [
{
"value": null,
"days": [
0,
1,
2
],
"timezone": "America/Toronto",
"start": "9:00",
"end": "17:00"
}
]
}
],
"start_time": 1659366000,
"end_time": 1659733200,
"interval_minutes": 30,
"duration_minutes": 30,
"round_to": 15,
"availability_rules": {
"availability_method": "collective",
"buffer": {
"before": 15,
"after": 15
}
}
} The order in which you include the participants' email addresses doesn't matter, but they must be in the same organization. If you need to check availability for people outside of your organization, you must do so separately.
⚠️ You can pass up to 50 email addresses in an Availability request, but a large list might slow down response times or cause provider rate limiting. When possible, Nylas recommends you keep your list of participants small.
You can also set the interval_minutes parameter, which specifies the calendar granularity. For example, if you want to book a half-hour meeting some time after 10:00am, but you want it to start at a 15 minute interval, set interval_minutes to 15. In this case, Nylas checks for available half-hour time slots beginning at 10:00am, then at 10:15, 10:30, 10:45, and so on. By default, Nylas sets interval_minutes to 30. The minimum interval is 5.
The interval_minutes and round_to parameters are independent, but you can use them together.
Open hours and availability rules
Open hours are optional, and they let you combine a calendar's technical availability with a participant's preferred availability. Think of this as setting the "working hours" on a calendar, so nobody books a meeting in the middle of the night with your team on the East Coast.
You can set default_open_hours in the availability_rules object. This default applies to all participants. You can then override it on a per-participant basis in the participants object.
The examples below show...
- A
default_open_hoursobject that sets the open hours to between 9:00am and 5:00pm in the Chicago timezone, Monday through Friday. It also excludes (prevents meetings on) December 24th, December 25th, and January 1st. - A participant's
open_hoursitem that overrides thedefault_open_hoursand sets their working hours to between 9:00am and 5:00pm Toronto time, on Monday, Tuesday, and Wednesday only. It also excludes January 31st as a day they're taking off from work.
"availability_rules": {
...
"default_open_hours": [{
"days": [1, 2, 3, 4, 5],
"timezone": "America/Chicago",
"start": "9:00",
"end": "17:00",
"exdates": ["2023-12-24", "2023-12-25", "2024-01-01"]
}]
} "participants": [{
"email": "jane.doe@example.com",
"calendar_ids": "primary",
"open_hours": [{
"days": [1, 2, 3],
"timezone": "America/Toronto",
"start": "9:00",
"end": "17:00",
"exdates": ["2024-01-31"]
}]
}] Availability responses
When you make a POST request to the Availability endpoint, Nylas returns the availability information as entries in a time_slots array. Each entry represents a time slot where all participants are available. You can then use the time slots to book your meeting.
The following JSON snippets show example responses to Availability requests.
{
"request_id": "5fa64c92-e840-4357-86b9-2aa364d35b88",
"data": {
"time_slots": [
{
"emails": [
"user2@example.com",
"user1@example.com"
],
"start_time": 1659367800,
"end_time": 1659369600
},
{
"emails": [
"user2@example.com",
"user1@example.com"
],
"start_time": 1605805200,
"end_time": 1605807000
}
]
}
} {
"request_id": "5fa64c92-e840-4357-86b9-2aa364d35b88",
"data": {
"order": [
"user1@example.com",
"user2@example.com"
],
"time_slots": [
{
"emails": [
"user2@example.com",
"user1@example.com"
],
"start_time": 1659367800,
"end_time": 1659369600
},
{
"emails": [
"user1@example.com"
],
"start_time": 1659376800,
"end_time": 1659378600
}
]
}
} Add buffer time
In some cases, you might want to allow an attendee to book a meeting, but you also want to block out time before or after the meeting for your teammate to preform related actions. For example, you might want to give a support agent 10 minutes to review bug reports before a booking, or give a medical professional 20 minutes after a meeting to write and file case notes.
In these cases, you can add this buffer to your Availability request. Nylas returns booking time slots that meet your event's criteria and the requested buffer criteria. It's up to you to remember that you passed a buffer, and book the extra time you requested for the team member.
The buffer is in the availability_rules object, and you set it in minutes before and after the available time slot. You can set buffer time in increments of five minutes.
Troubleshooting Availability responses
When you work with Availability requests and modifiers, you might find a slot on a participant's calendar that looks like it should be available, but isn't returned as an available time slot. When this happens, you should check the following things:
- Have you set a buffer time around meetings? If so, how much?
- Are you setting open hours? Are they set to the correct timezone for the participant?
- Have you set an interval or any rounding?