# Managing availability in Nylas Scheduler Source: https://developer.nylas.com/docs/v3/scheduler/managing-availability/ 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. > **Info:** > **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](/docs/reference/api/configurations/post-configurations/) or [Update Configuration](/docs/reference/api/configurations/put-configurations-id/) 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. ```bash {9,17-20} curl --request PUT \ --url "https://api.us.nylas.com/v3/grants//scheduling/configurations/" \ --header 'Accept: application/json' \ --header 'Authorization: Bearer ' \ --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. The Scheduler Editor UI displaying the Availability tab. The Default Open Hours section is shown, and availability is defined for Monday, Tuesday, and Wednesday. ## 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. > **Info:** > **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](/docs/reference/api/configurations/post-configurations/) or [Update Configuration](/docs/reference/api/configurations/put-configurations-id/) 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. ```bash {16-22} curl --request PUT \ --url "https://api.us.nylas.com/v3/grants//scheduling/configurations/" \ --header 'Accept: application/json' \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "participants": [{ "name": "Leyah Miller", "email": "leyah@example.com", "is_organizer": false, "availability": { "calendar_ids": [ "leyah@example.com", "en.usa#holiday@group.v.calendar.example.com" ], "open_hours": [{ "days": [1, 2, 3], "timezone": "America/Toronto", "start": "10:00", "end": "18:00", "exdates": ["2025-08-15"] }] }, "booking": { "calendar_id": "leyah@example.com" } }] }' ``` 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. The Scheduler Editor UI displaying the Participants tab. A participant is selected, and their availability is defined for Monday, Tuesday, Wednesday, and Thursday. ## 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](/docs/reference/api/configurations/post-configurations/) or [Update Configuration](/docs/reference/api/configurations/put-configurations-id/) 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. ```bash {23-26} curl --request POST \ --url "https://api.us.nylas.com/v3/grants//scheduling/configurations" \ --header 'Accept: application/json' \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "requires_session_auth": false, "participants": [{ "name": "Nyla", "email": "nyla@example.com", "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](/docs/reference/ui/buffer-time/) 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](/docs/reference/api/configurations/post-configurations/) or [Update Configuration](/docs/reference/api/configurations/put-configurations-id/) request and set `specific_time_availability` on the participant. > **Info:** > **Times are in 24-hour format.** If no timezone is specified, the participant's timezone is used. ```bash {9-19} curl --request PUT \ --url "https://api.us.nylas.com/v3/grants//scheduling/configurations/" \ --header 'Accept: application/json' \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "participants": [{ "email": "nyla@example.com", "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. > **Warn:** > **When using `default_specific_time_availability` with timezones**, you must also set `event_booking.timezone` to ensure proper timezone conversion across participants. ```bash {8-20} curl --request PUT \ --url "https://api.us.nylas.com/v3/grants//scheduling/configurations/" \ --header 'Accept: application/json' \ --header 'Authorization: Bearer ' \ --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 ```bash {10} curl --request PUT \ --url "https://api.us.nylas.com/v3/grants//scheduling/configurations/" \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "participants": [{ "email": "nyla@example.com", "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. ```bash {9} curl --request PUT \ --url "https://api.us.nylas.com/v3/grants//scheduling/configurations/" \ --header 'Authorization: Bearer ' \ --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"`: ```json { "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. The Scheduler Editor UI displaying the Participants tab. The Open Hours settings are shown for a participant, and a Specific Date Availability slot is defined from 7:30a.m. to 8:00a.m. on August 15, 2025.