DEV Community

Qasim
Qasim

Posted on

Find meeting times with the Nylas Availability API

#api #calendar #devtools #productivity

"What time works for everyone?" is a surprisingly hard question to answer in code. You have to read each person's calendar, line up the busy blocks, respect working hours and time zones, leave buffer time between meetings, and only then find the gaps everyone shares. The Nylas Availability API does all of that in one request: hand it a list of participants and a window, and it returns the time slots that actually work.

This post covers finding meeting times from two angles: the HTTP API for your backend, and the nylas CLI for the terminal. I work on the CLI, so the terminal commands below are the ones I reach for when I'm checking a calendar.

Availability versus Free/Busy

There are two endpoints here, and picking the right one saves you work. The Availability endpoint finds bookable slots across a group of participants, applying working hours, buffers, and meeting duration to return times you can actually book. Free/Busy is simpler: it returns the raw busy blocks for one or more email addresses over a window, leaving the slot math to you.

Reach for Availability when the question is "when can these people meet?" and you want the answer as a list of open slots. Reach for Free/Busy when you only need to see when calendars are busy, for example to gray out times in a custom UI. Availability is a POST /v3/calendars/availability, an application-level call that takes participants by email, while Free/Busy is grant-scoped at POST /v3/grants/{grant_id}/calendars/free-busy. This post focuses on Availability, since that's the one that answers the scheduling question directly.

Find a time across participants

The core request lists the participants and the window to search. Each participant is identified by email and must be associated with a valid Nylas grant, since the endpoint reads their calendars. You set start_time and end_time as Unix timestamps for the search window, duration_minutes for how long the meeting is, and interval_minutes for how the candidate start times are spaced.

curl --request POST \
  --url "https://api.us.nylas.com/v3/calendars/availability" \
  --header "Authorization: Bearer <NYLAS_API_KEY>" \
  --header "Content-Type: application/json" \
  --data '{
    "participants": [
      { "email": "alice@example.com" },
      { "email": "bob@example.com" }
    ],
    "start_time": 1744714800,
    "end_time": 1744801200,
    "duration_minutes": 30,
    "interval_minutes": 30
  }'
Enter fullscreen mode Exit fullscreen mode

The response is a list of time_slots, each with a start_time, an end_time, and the emails of the participants available then. From the terminal, nylas calendar find-time wraps this for the common case: pass participants and a duration, and it searches for a slot.

nylas calendar find-time \
  --participants alice@example.com,bob@example.com \
  --duration 1h
Enter fullscreen mode Exit fullscreen mode

The CLI defaults make it useful out of the box: it searches the next 7 days (--days), excludes weekends (--exclude-weekends, on by default), and assumes 9:00-to-17:00 working hours you can change with --working-start and --working-end. Pass --timezones aligned with the participant order to handle people in different zones.

Tune the granularity with interval and duration

Two fields control the shape of the slots you get back, and they do different jobs. duration_minutes is how long the meeting is; interval_minutes is how often a candidate slot can start. Set a 30-minute duration with a 15-minute interval and the API checks for half-hour openings starting at 10:00, 10:15, 10:30, and so on, rather than only on the half hour.

By default interval_minutes is 30, and the minimum is 5, so you can get fine-grained start times when you need them. The pairing matters for fit: a long duration with a coarse interval finds fewer slots, while a short interval surfaces more candidate start times for the same meeting length. There's also a round_to parameter that rounds returned slot start times to a clean boundary, so a meeting can be found at a 15-minute mark even when the interval search ran finer. If you don't need fine control, leaving interval_minutes at its default of 30 and matching it to a 30-minute duration_minutes is the simplest setup, and it's the one most scheduling flows start with.

Set working hours with open hours

A calendar being technically free at 3am doesn't mean anyone wants to meet then, which is what open hours are for. In the availability_rules object, default_open_hours sets the working window that applies to every participant: the days of the week, a time zone, and a start and end time. You can then override it per participant with an open_hours entry inside that participant's object, so someone in another time zone or on a different schedule is handled correctly.

curl --request POST \
  --url "https://api.us.nylas.com/v3/calendars/availability" \
  --header "Authorization: Bearer <NYLAS_API_KEY>" \
  --header "Content-Type: application/json" \
  --data '{
    "participants": [{ "email": "alice@example.com" }, { "email": "bob@example.com" }],
    "start_time": 1744714800,
    "end_time": 1744801200,
    "duration_minutes": 30,
    "availability_rules": {
      "default_open_hours": [{
        "days": [1, 2, 3, 4, 5],
        "timezone": "America/Chicago",
        "start": "9:00",
        "end": "17:00",
        "exdates": []
      }]
    }
  }'
Enter fullscreen mode Exit fullscreen mode

Open hours take an exdates array too, a list of dates to exclude entirely, which is how you keep the agent from booking on a company holiday or someone's day off. The CLI exposes the common parts of this directly: --working-start, --working-end, and --days on nylas calendar find-time set the same kind of window without writing the rules object by hand.

Collective meetings versus round-robin

The availability_method in availability_rules decides what "available" means across the participants. Set it to collective to find slots where every participant is free at once, which is what you want for a meeting everyone attends. The field defaults to max-availability, so you set collective explicitly whenever the whole group needs to be there.

The other two methods solve a different problem: finding any one participant who's free, which is how round-robin scheduling works. max-availability, the default, prioritizes whoever has the most open time, while max-fairness distributes meetings evenly across a pool of people. You'd use these for a "talk to a sales rep" flow where the meeting is with one person from a team, not the whole team. So pick collective when everyone must attend, and a round-robin method when any one of several people will do.

Add buffers between meetings

Back-to-back meetings with no breathing room are their own problem, and the buffer setting prevents them. In availability_rules, a buffer with before and after values in minutes reserves padding around each candidate slot, so a slot only counts as available if the participant is also free for the buffer on each side. Set a 15-minute buffer and a slot that butts up against an existing meeting won't be offered.

This matters most for people who book heavily. Without a buffer, the API will happily propose a slot that starts the instant another meeting ends, which is technically free but practically miserable. A buffer makes the returned slots respect the gaps real people need, and it's set once in the rules rather than filtered out afterward. Combined with open hours, it's the difference between technically-free time and time someone would actually accept.

Book the slot you found

Finding a slot is half the job; booking it is the other half. The Availability response gives you time_slots, each with a start_time and end_time, and you turn one of those into a meeting by creating an event with POST /v3/grants/{grant_id}/events. Pass the slot's times as the event's when, add the participants, and set notify_participants=true so everyone gets the invite.

curl --request POST \
  --url "https://api.us.nylas.com/v3/grants/<GRANT_ID>/events?calendar_id=primary&notify_participants=true" \
  --header "Authorization: Bearer <NYLAS_API_KEY>" \
  --header "Content-Type: application/json" \
  --data '{
    "title": "Project sync",
    "when": { "start_time": 1744714800, "end_time": 1744716600 },
    "participants": [{ "email": "alice@example.com" }, { "email": "bob@example.com" }]
  }'
Enter fullscreen mode Exit fullscreen mode

That's the full loop: query Availability for a slot that fits everyone, then create the event at that slot to send the invites. A returned slot is not a hold on the calendar, so nothing is reserved until you create the event, and two requests racing for the same slot can both see it as free. For anything beyond a single booking, where you want participants to pick from proposed times themselves, Scheduler builds that round-trip on top of the same availability engine.

Work across participant time zones

Time zones are where naive scheduling breaks, and the Availability API handles them through open hours rather than the raw search window. Each open_hours entry, default or per-participant, carries its own timezone, so "09:00 to 17:00" means 9-to-5 in each person's local zone, not a single server zone applied to everyone. A meeting between someone in Chicago and someone in Toronto respects both local working days and hours at once.

The CLI mirrors this with --timezones, a comma-separated list aligned to the --participants order, so the first time zone applies to the first participant and so on. Get the alignment right and nylas calendar find-time returns slots that fall inside everyone's working day, which is exactly the slot a human scheduler would land on. Mismatch the order and you'll get slots that look valid but land at 6am for someone, so keep the two lists in lockstep.

Check busy times with Free/Busy

When you only need raw busy times rather than computed slots, Free/Busy is the lighter call. POST /v3/grants/{grant_id}/calendars/free-busy returns busy blocks for the email addresses you pass over a time range, with the grant authorizing access, which you'd use to render people's schedules or do your own slot math. From the terminal, nylas calendar availability check covers this case, defaulting to the grant's own calendar for the next 24 hours, or several people with --emails:

nylas calendar availability check \
  --emails alice@example.com,bob@example.com \
  --start "tomorrow 9am" \
  --end "tomorrow 5pm"
Enter fullscreen mode Exit fullscreen mode

The --emails flag checks several people at once, and --duration (for example --duration 7d) sets how far out to look. The response is a set of busy blocks per email, each with a start and end time, with no working hours or buffers applied. That rawness is the point: Free/Busy hands you the underlying schedule without imposing a meeting model, which is what you want when you're building your own availability logic or visualizing a calendar. When you'd rather have the bookable slots computed for you, that's when you move up to the Availability endpoint.

Things to keep in mind

A few details make an availability integration behave the way you expect.

  • Participants must be valid grants. The endpoint reads each participant's calendar, so every email has to map to a connected Nylas account.
  • Keep the participant list small. You can pass up to 50 emails, but a large list slows responses and can hit provider rate limits.
  • Set open hours, not just a window. A free calendar at 3am is still free; default_open_hours keeps slots inside working time and time zones.
  • Use a buffer for heavy calendars. It stops the API from offering slots that start the second another meeting ends.
  • Pick the method deliberately. collective for meetings everyone attends, max-fairness or max-availability for round-robin to one person.
  • Book by creating an event. A returned slot isn't a hold; create an event at its start_time/end_time to actually reserve the time and send invites.
  • Align --timezones with --participants. The lists are positional, so a mismatch produces slots outside someone's working day.

Wrapping up

The Availability API turns "find a time that works" into a single request: list the participants, set a duration and a window, layer on working hours and buffers, and get back the slots that fit. Free/Busy stays the lower-level tool for reading raw busy blocks, and the nylas calendar find-time and availability check commands cover both from the terminal. The fields that earn their place are open hours, buffers, and the availability method, since those are what separate a technically-free slot from one a person would actually accept.

Where to go next:

Top comments (0)