Managing availability in Nylas Scheduler

You can manage availability in Scheduler by setting default open hours, participant-specific open hours, buffer times, and specific time availability for particular dates. This page explains how to configure each option.

How Scheduler applies timezones

Scheduler uses IANA-formatted timezone strings, like America/Chicago, to interpret open hours and display booking times. Timezone fields are local to the object where you define them, but Scheduler also uses fallbacks when a more specific timezone isn’t set.

For availability calculations, Scheduler applies timezones in the following order.

Scope	Applies to	Precedence and fallback
participants[].availability.open_hours[].timezone	The specific participant open-hours block where you define it.	Highest precedence for that open-hours block. It overrides participants[].timezone.
participants[].timezone	The participant’s availability and email notifications.	Used as the fallback for participant open_hours blocks that don’t include their own timezone.
event_booking.timezone	The Scheduler configuration’s event display timezone, confirmation messages, reminders, and default open hours.	Used as the fallback when a participant doesn’t have a timezone. Scheduler also uses this timezone when evaluating availability_rules.default_open_hours.
availability.availability_rules.default_open_hours[].timezone	The default open-hours block for participants that don’t define their own open_hours.	Used by the Calendar Availability API. In Scheduler configurations, set event_booking.timezone to control the timezone used for default open hours.

If a participant defines participants[].availability.open_hours, those participant open hours replace availability.availability_rules.default_open_hours for that participant. The timezone on a participant open-hours block applies only to that block, not to other participants or other open-hours blocks.

Set default open hours

Default open hours allow you to define standard working hours for your team at the Configuration level. You can override these settings on a per-participant level as needed.

Open hours cannot span multiple days. Each day’s availability is contained within that single day (00:00 to 23:59).

To set default open hours using the Scheduler API, make a Create Configuration or Update Configuration request that defines the default_open_hours and event_booking.timezone. The following example sets the default open hours to between 9:00a.m. and 5:00p.m. in the Chicago timezone, Monday through Friday.

curl --request PUT \
  --url "https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/scheduling/configurations/<CONFIGURATION_ID>" \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "availability": {
      "availability_rules": {
        "default_open_hours": [{
          "days": [1, 2, 3, 4, 5],
          "timezone": "America/Chicago",
          "start": "9:00",
          "end": "17:00"
        }]
      }
    },
    "event_booking": {
      "title": "Consultation",
      "timezone": "America/Chicago"
    }
  }'

If you’re using the Scheduler Editor, it renders the default open hours picker in the Availability tab. Under Default open hours, select the timezone and set the available hours. When you’re done, be sure to save your changes.

Set participant open hours

You can use participant open hours to override Configuration-level open hours settings on a per-participant basis. This is useful when a participant’s working hours differ from their team’s default, for example.

Open hours cannot span multiple days. Each day’s availability is contained within that single day (00:00 to 23:59).

If you’re using the Scheduler API, make a Create Configuration or Update Configuration request and set the open_hours for each participant’s availability. The following example sets a participant’s open_hours to between 10:00a.m. and 6:00p.m. in the Toronto timezone, on Monday, Tuesday, and Wednesday only. It also excludes August 15th, 2025 because the participant isn’t available that day.

curl --request PUT \
  --url "https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/scheduling/configurations/<SCHEDULER_CONFIGURATION_ID>" \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "participants": [{
      "name": "Leyah Miller",
      "email": "[email protected]",
      "is_organizer": false,
      "availability": {
        "calendar_ids": [
          "[email protected]",
          "en.usa#[email protected]"
        ],
        "open_hours": [{
          "days": [1, 2, 3],
          "timezone": "America/Toronto",
          "start": "10:00",
          "end": "18:00",
          "exdates": ["2025-08-15"]
        }]
      },
      "booking": {
        "calendar_id": "[email protected]"
      }
    }]
  }'

You can update a participant’s open hours in the Scheduler Editor by navigating to the Participants tab. Under Participant open hours, select the users that you want to set availability for. Select the timezone and available hours for each person, then save your changes.

Add buffer times to meetings

Nylas Scheduler allows you to add buffer times which ensure there’s space before or after a meeting. This avoids back-to-back meetings and gives participants time to prepare and recover.

You can add buffer times to meetings by including the buffer object in your Create Configuration or Update Configuration request. Specify the number of minutes before and after a meeting using before and after, respectively. The values can be from 0 - 120 minutes and in increments of five minutes.

curl --request POST \
  --url "https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/scheduling/configurations" \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "requires_session_auth": false,
    "participants": [{
      "name": "Nyla",
      "email": "[email protected]",
      "is_organizer": true,
      "availability": {
        "calendar_ids": ["primary"]
      },
      "booking": {
        "calendar_id": "primary"
      }
    }],
    "availability": {
      "duration_minutes": 30,
      "availability_rules": {
        "availability_method": "collective",
        "buffer": {
          "after": 15,
          "before": 5
        }
      }
    },
    "event_booking": {
      "title": "Testing Scheduler"
    }
  }'

If you’re using the Scheduler Editor, the nylas-buffer-time element is automatically included in the main NylasSchedulerEditor component. Organizers can set buffer times by navigating to the Availability tab and configuring the buffer time settings.

Set specific time availability

Specific time availability settings let you define one-off availability windows on particular dates (for example, holidays or extended hours) without changing your regular open hours. These settings temporarily override existing availability rules and expire after the date passes, so users can’t book outdated time slots.

Set specific time availability for a participant

If you’re using the Scheduler API, make a Create Configuration or Update Configuration request and set specific_time_availability on the participant.

Times are in 24-hour format. If no timezone is specified, the participant’s timezone is used.

curl --request PUT \
  --url "https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/scheduling/configurations/<CONFIGURATION_ID>" \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "participants": [{
      "email": "[email protected]",
      "is_organizer": true,
        "specific_time_availability": [
          {
            "date": "2025-08-21",
            "start": "09:00",
            "end": "13:00"
          },
          {
            "date": "2025-08-22",
            "start": "10:00",
            "end": "16:00"
          }
      ],
      "availability": { "calendar_ids": ["primary"] },
      "booking": { "calendar_id": "primary" }
    }]
  }'

Set default specific time availability for all participants

You can define specific dates that apply to all participants using default_specific_time_availability in the availability_rules object. This is useful for organization-wide events like holidays or special booking periods.

Participant-specific entries override config-level defaults for the same date.

When using default_specific_time_availability with timezones, you must also set event_booking.timezone to ensure proper timezone conversion across participants.

curl --request PUT \
  --url "https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/scheduling/configurations/<CONFIGURATION_ID>" \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "availability": {
      "duration_minutes": 30,
      "availability_rules": {
        "default_specific_time_availability": [
          {
            "date": "2025-12-24",
            "start": "09:00",
            "end": "12:00",
            "timezone": "America/Toronto"
          },
          {
            "date": "2025-12-31",
            "start": "10:00",
            "end": "14:00",
            "timezone": "America/Toronto"
          }
        ]
      }
    },
    "event_booking": {
      "title": "Holiday Meeting",
      "timezone": "America/Toronto"
    }
  }'

Use only specific time availability

When you want participants to only be available at specific times (ignoring their regular open hours), set only_specific_time_availability to true.

This is useful for:

• Temporary booking windows - Only allow bookings during a specific event or period
• Disabling availability - Set to true with no specific dates to temporarily block all bookings

At the participant level

curl --request PUT \
  --url "https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/scheduling/configurations/<CONFIGURATION_ID>" \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "participants": [{
      "email": "[email protected]",
      "is_organizer": true,
      "only_specific_time_availability": true,
      "specific_time_availability": [
        { "date": "2025-09-15", "start": "14:00", "end": "18:00" }
      ],
      "availability": {
        "calendar_ids": ["primary"],
        "open_hours": [{ "days": [1,2,3,4,5], "start": "09:00", "end": "17:00", "timezone": "UTC" }]
      },
      "booking": { "calendar_id": "primary" }
    }]
  }'

In this example, even though open_hours defines Mon-Fri 9am-5pm, the participant is only available on September 15th from 2pm-6pm because only_specific_time_availability is true.

At the configuration level

Setting only_specific_time_availability at the availability_rules level applies to all participants and cannot be overridden by individual participants.

curl --request PUT \
  --url "https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/scheduling/configurations/<CONFIGURATION_ID>" \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "availability": {
      "duration_minutes": 30,
      "availability_rules": {
        "only_specific_time_availability": true,
        "default_specific_time_availability": [
          { "date": "2025-09-15", "start": "09:00", "end": "17:00", "timezone": "America/Toronto" }
        ]
      }
    },
    "event_booking": {
      "title": "Special Event Booking",
      "timezone": "America/Toronto"
    }
  }'

Mark specific dates as unavailable

To explicitly mark a date as having no availability (closed), set both start and end to "00:00":

{
  "specific_time_availability": [
    {
      "date": "2025-12-25",
      "start": "00:00",
      "end": "00:00"
    }
  ]
}

This is useful when you want to override config-level defaults to close a specific participant’s availability on a particular date.

Specific time availability reference

Field	Type	Required	Description
date	string	Yes	Date in YYYY-MM-DD format
start	string	Yes	Start time in HH:MM (24-hour). Use “00:00” with end “00:00” for closed.
end	string	Yes	End time in HH:MM (24-hour)
timezone	string	No	IANA timezone. Required for default_specific_time_availability.

How merging works

When both config-level default_specific_time_availability and participant-level specific_time_availability are defined:

1. Participant-specific entries take precedence for the same date
2. Config defaults are added for dates not specified by the participant
3. The effective only_specific_time_availability is true if EITHER config OR participant level is true

If you’re using the Scheduler Editor, it displays specific time availability settings in the Participants tab. Scroll down to the participant whose availability you want to modify and click Specific date availability > Add specific date, then set the date and time you want to create an availability window during. When you’re done, save your changes.