Skip to content
Skip to main content

Checking calendar availability

Last updated:

The Nylas APIs offer multiple ways to get information about 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

Section titled “How the Availability endpoint works”

You can use the Availability endpoint to find space in a 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.

How Nylas turns an Availability request into time slots

Nylas reads each person's calendar, applies their working hours and breaks, and returns the times a meeting fits. Use collective when everyone must attend. Use a round-robin method when any one person can take the meeting: max-availability (the default) offers every time someone is free, and max-fairness spreads meetings to whoever was booked least recently.
Diagram as text
  • Your app: Ask when a meeting fits: Your app tells Nylas who should attend, the date range to search, and how long the meeting is. Each person must have connected their calendar to your app (a grant).
    • Request details: POST /v3/calendars/availability with participants, start_time, end_time, and duration_minutes.
    • Request details: participants[].calendar_ids: the calendars to check. Without it, Nylas uses the participant's primary calendar.
    • Request details: availability_rules.default_open_hours: working hours for everyone. A participant's own open_hours replace them.
    • Request details: availability_rules.buffer: before and after minutes to keep free around existing events, 0 to 120 in steps of 5.
    • Request details: interval_minutes: how often a slot can start. Defaults to duration_minutes.
    • Request details: round_to: rounds slot start times, in minutes. Defaults to 15.
    • Request details: availability_rules.availability_method: collective, max-fairness, or max-availability (default).
    • Request details: availability_rules.round_robin_group_id: for round robin, Nylas ranks participants by events whose metadata key5 has this value.
  • Nylas: Find when each person is busy: Nylas reads the events on each person's calendars in the date range you asked about (start_time to end_time).
  • Nylas: Block out off-hours and breaks: Time outside a person's working hours (open hours), or on a day off you listed (exdates), counts as busy. Nylas also keeps a break free before and after each existing meeting (the buffer).
  • One of these paths (Depends on who must attend, set by availability_method):
    • Everyone attends (collective)
      • Nylas: Keep only times everyone shares: A time counts only when every person is free. Use it for meetings that everyone attends.
    • Any one person hosts (max-availability, round robin)
      • Nylas: Offer every time someone is free: A time counts when any one person is free. Nylas lines people up so whoever was booked least recently is first (round robin). It counts bookings in the round_robin_group_id group.
    • Spread meetings evenly (max-fairness, round robin)
      • Nylas: Offer times for whoever is due next: Nylas lines people up the same way, then checks only those booked least recently. If they have no free time, Nylas falls back to max-availability.
  • Nylas: Return the times that work: Nylas returns a list of meeting times (time_slots), each the length you asked for, with the people free at that time (emails). Round-robin results also include order: who is next in line to host.
    • Response details: Each slot is duration_minutes long, and slots start every interval_minutes.
  • Your app: Book the chosen time: Your app creates the meeting on the calendar. For round robin, pick the host from the people free at that time, following order. Request: POST /v3/grants/{grant_id}/events.

Each Availability request has a few main components:

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

Section titled “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": "[email protected]",
      "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 participants’ email addresses doesn’t matter, but they must be associated with valid Nylas grants, and should be unique within their application.

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, interval_minutes is the same as duration_minutes. 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

Section titled “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_hours object 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_hours item that overrides the default_open_hours and 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 responses

Section titled “Availability responses”

When you make a POST request to the Availability endpoint, Nylas returns the availability information as entries in a time_slots array. For collective requests, each entry represents a time slot where all participants are available. For round-robin requests (max-availability or max-fairness), each entry’s emails array lists the participants who are free during that slot, and the response includes an order array. You can then use the time slots to book your meeting.

The following JSON snippets show example responses to Availability requests.

Add buffer time

Section titled “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

Section titled “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?