Skip to content
Skip to main content

Checking free/busy information

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. The simplest way to do so is using the Free/Busy endpoint, which returns simple information about blocks of time when they’re booked on their primary calendar and not available.

Which calendar availability tool to use

All three read your users' calendars. Free/Busy tells you when people are busy, Availability tells you when a meeting fits, and Scheduler adds a ready-made booking page on top. To show meeting times in your own UI, use Availability.
Diagram as text
  • Your app: Decide what you need: Raw busy times to work with yourself, ready-to-offer meeting times, or a complete booking page for guests.
  • Ends in one of:
    • Only busy times → Free/Busy: Returns the busy blocks on each person's calendar, one list per person. You work out the free times yourself. Up to 20 people on Microsoft or 50 on Google, all on the same provider. Not available for iCloud. Request: POST /v3/grants/{grant_id}/calendars/free-busy with a list of emails.
    • Meeting times in your UI (recommended) → Availability: Returns times when a meeting fits, with the people free at each time. Nylas applies working hours and breaks between meetings for you. Works for meetings everyone attends and for round robin, where any one person can host. Every person must have connected their calendar (a grant). Request: POST /v3/calendars/availability.
    • A ready-made booking page → Scheduler: Gives guests a booking page where they pick a time and Nylas books it. You set the rules once in a Configuration, in the Dashboard or with POST /v3/grants/{grant_id}/scheduling/configurations. Guests book on a Nylas-hosted page or on the Scheduling Component in your app, which call GET /v3/scheduling/availability and POST /v3/scheduling/bookings.

How the Free/Busy endpoint works

Section titled “How the Free/Busy endpoint works”

When you make a request to the Free/Busy endpoint, Nylas returns a simple list of time slots during which the user’s primary calendar is booked, and they’re not available.

When a user hasn’t accepted an event on their calendar (for example, an event that’s automatically added from an email invitation), providers handle it differently. Google marks that calendar as busy during that time span, while Microsoft marks it as free.

If you’re querying a user within your organization, free/busy information is usually public. If you’re querying a user outside of your organization, they must have published or made their calendar’s free/busy information public.

The time_slots array lists busy blocks only. If the user has no busy time in the requested range, Nylas returns an empty time_slots array.

[
  {
    "email": "[email protected]",
    "object": "free_busy",
    "time_slots": []
  }
]

Nylas recommends you use the Free/Busy endpoint when you need to know the times when a user’s calendar is booked. If you need to do any of the following tasks, Nylas recommends you use the Availability endpoint instead:

  • Compare users’ schedules.
  • Check the status of room resources.

For more information, see Check calendar availability.

You can use the Free/Busy endpoint to check multiple users’ calendars in the same call, but Nylas returns their individual busy data and does not compare or combine it.

Request busy data for a user

Section titled “Request busy data for a user”

The following code snippet fetches a single user’s busy data.

curl --compressed --request POST \
  --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/calendars/free-busy' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "start_time": 1682467200,
    "end_time": 1682550000,
    "emails": ["[email protected]"]
  }'

Request busy data for multiple users

Section titled “Request busy data for multiple users”

The following example fetches busy data for multiple users and shows the type of response you can expect from Nylas. You can use this request to view shared time slots for individuals using different providers, across multiple accounts and calendars.