Check a calendar for availability in Nylas v2
The Nylas APIs include multiple ways to get availability information for your end users, so you can book meetings or run other time-based operations. First, you use the Free/Busy or Availability APIs to find a "time slot" when the participants are free, then use that information to create an event and send the booking.
This page introduces the Availability endpoint.
When to use what
Not sure which option to use?
Use Free/busy when...
- You only need to check one email address.
- You only need to know if someone is busy, and don’t need to compare their schedule with another.
- When you know that the calendar belongs to an account in your provider organization. (Free/Busy can only check accounts within your organization.)
Use the Availability endpoint when...
- You need to check availability for multiple participants and organize itineraries.
- Some participants are outside your organization, and you need to know when they are busy.
- You need to check for specific event duration and intervals.
- You want to set additional unavailable times that are not on the calendar.
How the Availability endpoints work
You can use the Availability endpoints to find space in an end user's primary calendar that will fit a meeting with specific and detailed criteria. These endpoints also allow you to query for availability among a group of participants so you can book collective meetings, or you can book a meeting with one person from the group 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 participant met the criteria.
Each Availability request has a few main components:
- The top-level meeting information.
- Open hours and availability rules.
- Free-Busy information (v2 only).
For more complex examples, see the Group booking documentation. 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 (the emails object). Nylas checks the participants' availability during the specified time period. The order in which the participants' email addresses are added to the request 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 and include the information Nylas returns in the free_busy object.
⚠️ 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, keep your list of participants small.
You can also specify interval_minutes, 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:00, then at 10:15, 10:30, 10:45, and so on. In v2, interval_minutes is required and defaults to 30 minutes.
The JSON sample below shows an example of basic top-level meeting information.
{
"duration_minutes": 30,
"start_time": 1600890568,
"end_time": 1600999200,
"interval_minutes": 10,
"emails": [
"tom@example.com",
"jane@example.com"
],
...
} Open hours and availability rules
Open hours let you combine a calendar's technical availability with a participant's preferred availability (for example, to limit availability requests to a participant's working hours in their time zone).
Open hours are optional. In v2, open hours is an object at the top level of the Availability request, and you can set it only once per group of participants.
The example below shows an open_hours object which sets the hours for two different email addresses as 10am to 2pm Chicago time, on Sundays only.
...
"open_hours": [{
"emails": [
"jane.doe@example.com",
"aristotle@example.com"
],
"days": ["0"],
"timezone": "America/Chicago",
"start": "10:00",
"end": "14:00",
"object_type": "open_hours"
}] Free-Busy information in Availability requests
The v2 Availability endpoint can read calendars for email addresses within your organization only. You can manually add information about participants outside of your organization by adding the times when they're not available to the free_busy array. The array works like the Free/Busy endpoint: you need to know the times when the participant is busy, and you input them as the start and end times for each time slot.
Each participant's email address and time slot is an independent object. This means that, if you want to add multiple busy times for a single end user, you must add a few Free-Busy objects for that email address, each representing a busy slot.
🔍 The Free-Busy object does not call the Free/Busy endpoint. It's named free_busy because its data represents the same information, in the same format.
You don't need to include Free-Busy information in calls to the /calendar/availability endpoint, but you must include the top-level empty array when it's not in use.
The following JSON snippet shows a free_busy array.
...
"free_busy": [
{
"email": "marie@example.com",
"object": "free_busy",
"time_slots": [{
"start_time": 1601042400,
"end_time": 1601044200,
"object": "time_slot",
"status": "busy"
}]
},
{
"email": "lamarr@example.com",
"object": "free_busy",
"time_slots": [{
"start_time": 1601042400,
"end_time": 1601044200,
"object": "time_slot",
"status": "busy"
}]
},
{
"email": "lamarr@example.com",
"object": "free_busy",
"time_slots": [{
"start_time": 1601047800,
"end_time": 1601051400,
"object": "time_slot",
"status": "busy"
}]
}
]
... Availability responses
When you make a POST request to the Availability endpoint, Nylas returns the availability information as entries in the time_slots array. Each entry represents a time slot where all participants are available. You can then use those time slots to book your meeting.
The following JSON snippets show responses to Availability requests.
{
"object": "availability",
"time_slots": [
{
"end": 1605803400,
"object": "time_slot",
"start": 1605801600,
"status": "free"
},
{
"end": 1605804600,
"object": "time_slot",
"start": 1605802800,
"status": "free"
},
{
"end": 1605805200,
"object": "time_slot",
"start": 1605803400,
"status": "free"
}
]
} Availability request modifiers
The Nylas Availability endpoint returns a list of time slots that meet your event's needs, but you can also adjust the times returned to meet the needs of the participants.
Specifying open hours
You can specify open hours as part of your Availability request. This allows you to specify when a participant or group of participants is categorically available for booking. 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.
In v2.x, you add the open_hours array to your Availability request, containing the open hours settings for each participant by email address. You can apply each open hours setting to multiple email addresses.
Adjusting calendar granularity
The interval_minutes parameter allows you to set the granularity of the time slots Nylas considers when calculating availability. The minimum interval setting is 5 (five minutes). When evaluating a time slot, Nylas first rounds the time up to the nearest increment. For example, if your calendar shows you're available starting at the very strange time of 10:11 and your interval is set to 5, Nylas starts looking for time slots starting at 10:15, 10:20, 10:25, 10:30, and so on.
The Availability endpoint uses the interval_minutes parameter together with a round_start boolean parameter. When you set round_start to true, Nylas modifies the start_time of your meeting to match the interval increment.
Adding buffer time
In some cases, you want to allow an attendee to book a meeting, but you also want to block out time before or after the meeting for your team member to perform 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 time as buffer time to your Availability request. Nylas returns booking time slots that meet your event criteria, but that also meet the buffer criteria you requested. It's up to you to remember that you passed a buffer, and book the extra time you requested for the team member.
You set the buffer parameter in minutes at the top level of the Availability request, and Nylas applies a buffer both before and after the available time slot.
External participants
The v2 Availability endpoint can check only the calendars it has access to within the same domain or organization. There are times, though, when you might need to include participants outside of your organization when calculating availability. In this case, you can pass an array of free_busy objects that block out times when these external participants are not available. Assuming you have access, you can use the Free/Busy endpoint to get this information.
Virtual calendars and Free-Busy information
You can use Nylas' Availability endpoints with virtual calendars. To do so, pass in any events, busy time slots, or times that you don't want booked to the free_busy object. For more information, see Virtual calendar availability.
Create an availability request
Putting it all together, you can create a simple availability request for a one-on-one meeting.
{
"duration_minutes": 30,
"start_time": 1605794400,
"end_time": 1605826800,
"interval_minutes": 10,
"emails": [
"jane.doe@example.com"
],
"free_busy": [{
"email": "lamarr@example.com",
"object": "free/busy",
"time_slots": [{
"start_time": 1601042400,
"end_time": 1601044200,
"object": "time_slot",
"status": "busy"
}]
}],
"open_hours": [{
"emails": [
"jane.doe@example.com"
],
"days": [
"1, 2, 3, 4, 5"
],
"timezone": "America/Chicago",
"start": "10:00",
"end": "14:00",
"object_type": "open_hours"
}]
} 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 buffer time around meetings, and if so, how much?
- Are you setting open hours, and are they set to the correct time zone for the participant?
- Have you set an interval, or any rounding?
- Are you manually passing any Free-Busy information for external participants that could conflict with the potentially open time slot?