Skip to content
Skip to main content
POST
/v3/grants/{grant_id}/calendars/free-busy

Get free/busy schedule

(Not supported for iCloud) Returns the free/busy schedule for the specified list of email addresses.

Keep in mind

  • The grant ID included in the request must have access to view the provided email addresses' free/busy data. This is usually configured by the provider.
  • All specified email addresses must use the same provider.
  • This endpoint always returns 200 OK, even if one of the responses returns an error. Be sure to check for any errors in the list of responses.
  • Microsoft's availability calculation is limited to a maximum of 1,000 entries per time slot for each email address included in the request.
  • The free/busy response does not include all-day room resource bookings on Google or Microsoft.
  • You can include up to 20 email addresses for Microsoft Graph, and up to 50 email addresses for Google in a single request.
NYLAS API KEYACCESS TOKEN

Parameters

Path parameters

grant_id*string

ID of the grant to access. Use /me/ to refer to the grant associated with an access token.

Request body

start_time*integer

The start of a time block, in seconds using the Unix timestamp format. Nylas uses start_time and end_time to assess the specified account's free/busy schedule.

Example: 1690862400
end_time*integer

The end of a time block, in seconds using the Unix timestamp format. Nylas uses start_time and end_time to assess the specified account's free/busy schedule.

For Google and EWS accounts, Nylas can query a timespan of up to 3 months from the start_time.

For Microsoft Graph accounts, Nylas can query a timespan of up to 62 days from the start_time.

Example: 1691208000
emails*array<string>

A list of email addresses to check the free/busy schedules for.

tentative_as_busyboolean

When true, Nylas treats tentative events as busy.

Default: true

Responses

request_idstring

The request ID.

dataarray<object>

An array of free/busy schedules. Nylas returns one free/busy schedule for each email address specified in the request.

POSThttps://api.us.nylas.com/v3/grants/{grant_id}/calendars/free-busy

Find your API key in the Nylas Dashboard under API Keys in your application settings.

grant_idrequiredstring

ID of the grant to access. Use /me/ to refer to the grant associated with an access token.

Loading editor...

Autocomplete and validation come from this endpoint's request schema.