https://api.us.nylas.com/v3/grants/{grant_id}/scheduling/configurations/{configuration_id}Update Configuration
Updates the specified Configuration object.
A PUT request merges your request body into the existing Configuration. Settings you leave out
keep their current values, including settings inside nested objects you include. A few fields are
replaced as a whole instead:
scheduler.additional_fields: include every field you want to keep, not only the one you're adding or changing.scheduler.notetaker_settings- Arrays, except
participants, whose entries are merged byemail.
Path parameters
ID of the grant to access. You can also use the email address associated with the grant, or use
/me/ to refer to the grant associated with an access token.
"[email protected]"appearanceanyAn object that defines the appearance settings for the Scheduling Page. This field
may be null if no appearance customization has been set.
your-keystringA key-value pair. For pre-defined keys for hosted Scheduling Pages, see Styling options for hosted Scheduling Pages.
interval_minutesintegerThe interval between meetings. Nylas checks from the nearest interval of the passed start_time. For example, you schedule 30-minute meetings (duration_minutes) with 15 minutes between them (interval_minutes). If you have a meeting starting at 9:59, the API returns times starting at 10:00 (10:00-10:30, 10:15-10:45).
round_tointegerNylas rounds each time slot to the nearest round_to value. For example, if a time slot starts at 9:05a.m. and round_to is set to 15, Nylas rounds it to 9:15a.m. Must be a multiple of 5 minutes.
15availability_rulesobjectAvailability rules for the scheduling configuration. These rules define how Nylas calculates availability for all participants.
availability_methodstringThe method that Nylas uses to calculate availability for all participants. For one-on-one
meetings, the availability_method is always collective.
The round-robin methods, max-fairness and max-availability, don't support
Agent Account participants. Use connected grants for
round-robin pools.
"collective"bufferobjectThe amount of buffer time to add around existing meetings, in minutes. For example, if an account has a meeting scheduled from 10–11a.m., and you set a buffer of 30 minutes, Nylas treats 9:30–11:30a.m. as busy.
beforeintegerThe amount of buffer time to add before meetings, in increments of five minutes. For example,
if an account has a meeting scheduled from 10:00–11:00a.m., and you set a before buffer of
30 minutes, Nylas treats 9:30–11:00a.m. as busy.
This value must be between 0 and 120, and must be divisible by 5.
0afterintegerThe amount of buffer time to add after meetings, in increments of five minutes. For example, if
an account has a meeting scheduled from 10:00–11:00a.m., and you set an after buffer of 15
minutes, Nylas treats 10:00–11:15a.m. as busy.
This value must be between 0 and 120, and must be divisible by 5.
0default_open_hoursarray<object>A default set of open hours to apply to participants that don't define participant-level open_hours. You can overwrite these open hours for individual participants by specifying open_hours on the participant object. In Scheduler configurations, set event_booking.timezone to control the timezone used when Scheduler evaluates default open hours.
daysarray<integer>The days of the week that the open hour settings are applied to. Sunday corresponds to 0, and Saturday corresponds to 6.
[0,1,2]startstringThe start time in 24-hour time format. Single-digit hours doesn't have a leading zero. The earliest start time is 0:00, and the latest start time is 23:49.
"10:00""14:00"timezonestringThe timezone for this open-hours block, as an IANA-formatted string.
For participant open_hours, this value applies only to the open-hours block where you define it and overrides the participant's timezone. If you omit it, Scheduler uses the participant's timezone, then event_booking.timezone.
For default_open_hours in Scheduler configurations, set event_booking.timezone to control the timezone that Scheduler uses when evaluating default open hours.
"America/Chicago"default_specific_time_availabilityarray<object>Default specific date and time availability that applies to ALL participants in this configuration. These are merged with participant-specific entries, with participant entries taking precedence for the same date. Use this to define organization-wide special hours (e.g., holidays, events).
only_specific_time_availabilitybooleanWhen true, ALL participants will ONLY be available at times defined in default_specific_time_availability
and their individual specific_time_availability entries. Regular open_hours and default_open_hours
are completely ignored.
This is useful for:
- Temporary availability windows (e.g., hiring events, special booking periods)
- Disabling all availability by setting to
truewith no specific dates defined
Note: When set at the config level, individual participants cannot override this to false.
falsetruebooking_typestringThe booking type. If set to booking, Scheduler follows the
standard booking flow.
If set to organizer-confirmation, Scheduler creates an event marked "Pending" in the organizer's
calendar and sends a confirmation request email to the organizer. The confirmation request email
includes a link to a page where the organizer can confirm or cancel the booking.
"booking""booking"conferencingobjectAn object that lets you automatically create a conference, or enter conferencing details manually.
You can't use autocreate and details in the same request. If you do, Nylas returns an error.
Nylas stores conference information in the event description. To remove conference details, set
conferencing to {} and remove the corresponding conference information from the description in
the same request.
provider*stringThe conferencing provider that Nylas uses to create the conference. Teams for Business is available for Microsoft grants only.
autocreate*objectWhen you include autocreate in your request, Nylas automatically creates the conference
for the event and appends the conferencing details to the event description.
If the provider is Zoom Meeting, your Zoom OAuth app must include the following
granular scopes
for Nylas to manage meetings on behalf of the user:
meeting:write:meeting— required to create Zoom meetings.meeting:update:meeting— required to update Zoom meetings (for example, when event time or title changes).meeting:delete:meeting— required to delete Zoom meetings (when events are removed).
If any of these scopes are missing, the Zoom API rejects the request. After adding scopes to your Zoom app, affected users must re-authenticate their grant so their access tokens include the new scopes.
conf_grant_idstringThe grant ID of the account that hosts the conference. The user that belongs to this grant acts as the conference host: they join the conference at the scheduled time and admit other participants during the meeting.
Include conf_grant_id when the conferencing provider isn't available on the user's
own account — for example, when the provider is Google Meet but the user
authenticated with a Microsoft account (cross-provider autocreation). When the
provider is Zoom Meeting, conf_grant_id is always required.
conf_settingsobjectOptional provider-specific settings that Nylas passes through when it creates the
conference. For Zoom Meeting, each key is sent as a top-level parameter to
Zoom's Create a Meeting API
— for example, agenda, password, or Zoom's own settings object. Nylas does not
validate these values. They can make your Zoom integration more accessible but
potentially less secure, so review your organization's security requirements.
disable_emailsbooleannullableWhen true, Nylas doesn't send email notifications when an event is booked, cancelled, or
rescheduled. When null, the default behavior applies (emails are sent).
falsefalsehide_participantsbooleannullableWhen true, Nylas creates the event with hide_participants=true, so the host can see who's on the event but the guests cannot. When null, the default behavior applies (participants are visible).
falsefalsenotify_participantsbooleannullableWhen true, the calendar provider sends notifications to participants when the
event is created, updated, or deleted. Microsoft grants ignore this flag and
always notify participants. This field may be null if not explicitly set on
the configuration; treat null the same as false (the default behavior).
falsetruetimezonestringThe timezone Nylas uses to display times in confirmation messages and reminders. This must be an IANA-formatted string.
"America/Chicago"participants*array<object>A list of participants to be included in the scheduled event.
Participants that provide availability (through an availability or booking block) must be
associated with a valid Nylas grant, or the request fails. Participants supplied by email only
don't require a grant. They're notification-only invitees who receive scheduling emails but don't
affect availability calculation and can't be selected as a round-robin host.
This field isn't accepted for group or round-robin configurations, which are anchored to the organizer's own grant and calendar instead.
availability*objectThe availability data for the participant. If omitted, the participant is considered to be available at all times. At least one participant must have availability data.
calendar_ids*array<string>A list of calendar IDs associated with the participant's email address. These calendars are used to check the participant's availability.
For an Agent Account participant, set this to
["primary"] or to the Agent Account's email address. Scheduler reads busy time from an Agent
Account's primary calendar only.
open_hoursarray<object>An array of objects for the participant's open hours. Nylas searches for free time slots within these open hours.
daysarray<integer>The days of the week that the open hour settings are applied to. Sunday corresponds to 0, and Saturday corresponds to 6.
[0,1,2]startstringThe start time in 24-hour time format. Single-digit hours doesn't have a leading zero. The earliest start time is 0:00, and the latest start time is 23:49.
"10:00""14:00"timezonestringThe timezone for this open-hours block, as an IANA-formatted string.
For participant open_hours, this value applies only to the open-hours block where you define it and overrides the participant's timezone. If you omit it, Scheduler uses the participant's timezone, then event_booking.timezone.
For default_open_hours in Scheduler configurations, set event_booking.timezone to control the timezone that Scheduler uses when evaluating default open hours.
"America/Chicago"booking*objectThe booking data for the participant. If omitted, the participant is not included in the booked event. At least one participant must have booking data.
calendar_id*stringThe calendar ID that the event is created in.
For an Agent Account participant, set this to
primary or the Agent Account's email address. Scheduler creates booking events on an Agent
Account's primary calendar only.
email*stringThe participant's email address.
If the participant provides an availability or booking block, this email address must be
associated with a valid Nylas grant, or the request fails. Participants supplied by email only
(no availability or booking block) don't require a grant. They're treated as notification-only
invitees: they still receive scheduling emails, but they don't affect availability or free-busy
calculation and can't be selected as a round-robin host.
"[email protected]"is_organizerbooleanWhen true, indicates that the participant is the organizer of the event.
For non-round-robin meetings, one of the participants must be specified as the organizer. For
round-robin meetings, remove the is_organizer key/value pair or set is_organizer to false
for all participants.
falsefalsespecific_time_availabilityarray<object>A specific date and time range when the participant is available. Use "00:00" for both start and end to explicitly mark a date as unavailable.
only_specific_time_availabilitybooleanWhen true, this participant will ONLY be available at times defined in their
specific_time_availability entries. Their regular open_hours are ignored.
If the config-level availability_rules.only_specific_time_availability is true,
this participant-level setting cannot override it to false.
Setting to true with an empty specific_time_availability array results in
zero availability for this participant (useful for temporarily disabling someone).
falsetruetimezonestringThe timezone in which the participant is located, as an IANA-formatted string. Nylas uses this when calculating the participant's open hours, and in email notifications.
If a participant open_hours block includes its own timezone, the open-hours timezone
overrides this participant timezone for that block. If participant open_hours doesn't include
a timezone, Scheduler uses this participant timezone, then event_booking.timezone.
"America/Toronto"requires_session_authbooleannullableWhen true, the scheduling Availability and
Bookings endpoints require a valid session ID to
authenticate requests using the specified Configuration. This field may be null
if not explicitly set on the configuration; treat null the same as false
(the default behavior).
falseavailable_days_in_futureintegerThe number of days in the future that Scheduler is available for scheduling events.
30min_booking_noticeintegernullableThe minimum number of minutes in the future that a user can make a new booking. This field may be null if not explicitly set on the configuration; treat null the same as 60 (the default behavior).
600hide_rescheduling_optionsbooleanIf true, the option to reschedule an event is hidden in booking confirmations and email notifications.
falsehide_cancellation_optionsbooleanIf true, the option to cancel an event is hidden in booking confirmations and email notifications.
falsehide_additional_guestsbooleanWhether to hide the Additional guests field on the Scheduling Page. If true, guests cannot invite additional guests to the event.
falsenotetaker_settingsobjectSettings for automatically adding a Notetaker bot to bookings created with this configuration.
When enabled, Notetaker joins the meeting to record, transcribe, and optionally generate
summaries and action items. Requires event_booking.conferencing to be configured.
enabledbooleanWhen true, automatically creates a Notetaker bot for bookings made with this configuration.
The bot joins the meeting at the scheduled time to record and transcribe.
falsetrueshow_ui_consent_messagebooleanWhen true, displays a consent message in the Scheduler UI informing guests that the
meeting will be recorded.
truetruenotetaker_namestringThe display name for the Notetaker bot that joins the meeting. Maximum 255 characters.
"Nylas Notetaker""Sales Recording Bot"action_itemsbooleanWhen true, Notetaker generates a list of action items from the meeting. If action_items is
true, video_recording, audio_recording, and transcription must also be true.
truetrueleave_after_silence_secondsintegerThe number of seconds of silence after which the Notetaker bot automatically leaves the meeting. This helps end recordings when meetings have concluded but participants haven't disconnected the call. Must be between 10 and 3600 seconds (1 hour).
300360summarybooleanWhen true, Notetaker generates a summary of the meeting. If summary is true,
video_recording, audio_recording, and transcription must also be true.
truetruetranscriptionbooleanWhen true, Notetaker transcribes the meeting's audio. If transcription is true,
video_recording and audio_recording must also be true.
truetruetranscription_settingsobjectnullableOptional settings that tune how Notetaker transcribes audio. transcription must be
true for these settings to take effect. Provide any combination of the fields below.
The fields fall into two independent groups:
- Language hints (
expected_languages,fallback_language) constrain automatic language detection. This declares the languages you expect; it does not translate transcripts or force the recording into a specific language. - Keyword hints (
keywords,use_speaker_names_as_keywords) bias recognition toward domain-specific terms such as names, acronyms, and product names.
Set on individual Notetakers, on calendar sync, or on event sync. When set on a calendar,
events inherit the value unless the event's own request overrides it. Send null or {}
to clear inherited settings and return to default transcription behavior.
See Set transcription languages for supported language codes and validation rules.
expected_languagesarray<string>Language codes the audio is expected to contain. Optional. When provided, it must
contain at least one supported code and cannot be null or empty. When omitted,
transcription considers all supported languages.
["en","es"]fallback_languagestringLanguage to use if Notetaker does not detect one of the expected_languages. Optional.
When expected_languages is set, the fallback must be one of those codes. When
expected_languages is omitted, transcription considers all supported languages and
the fallback may be any supported code. When fallback_language is omitted, the
transcriber auto-detects the language. The field is not stored, so responses do not
return it.
"en"keywordsarray<string>Domain-specific terms that bias transcription toward recognizing them correctly, such
as names, acronyms, and product names. Optional. Up to 200 terms; each term must be
1 to 200 characters and cannot contain control characters. Cannot be null.
["Nylas","AssemblyAI"]messagesobjectCustom announcements the Notetaker bot posts to the meeting chat. Use this to greet attendees when the bot joins, or to acknowledge new participants as they arrive. Messages are optional; when omitted, the bot only posts the default recording-and-transcription notice described in Using Nylas Notetaker.
Like other notetaker_settings fields, messages participates in the
configuration hierarchy and uses whole-object override semantics: the most
specific layer that sets messages completely replaces the parent's value
(there is no per-message merging). See Custom announcements
for the full inheritance model.
on_joinarray<object>Messages the bot sends shortly after it joins the meeting. Each message has its own configurable delay measured from the moment the bot joins. Up to 10 messages per trigger.
type*stringThe message format. Currently only text is supported. Plain-text content
is preferred; any HTML tags in content are stripped before the message
is sent.
"text"content*stringThe message text the bot posts to the meeting chat. After HTML tags are
stripped, the remaining text must be at least 1 character. Requests whose
content becomes empty after sanitization are rejected with a validation
error.
"👋 Hey team! I'm your AI notetaker — here to capture the key points."on_participant_joinarray<object>Messages the bot sends when a new participant joins the meeting. Each message uses a trailing debounce window — if another participant joins before the window expires, the timer resets and only one message is posted per burst of joins. Up to 10 messages per trigger.
type*stringThe message format. Currently only text is supported. Plain-text content
is preferred; any HTML tags in content are stripped before the message
is sent.
"text"content*stringThe message text the bot posts to the meeting chat. After HTML tags are
stripped, the remaining text must be at least 1 character. Requests whose
content becomes empty after sanitization are rejected with a validation
error.
"👋 Welcome! Recording and transcription are running."debounce_ms*integerTrailing debounce window in milliseconds. When a participant joins, the bot waits this long before posting the message. If another participant joins inside the window, the timer resets — the message is only posted once the window expires without another join event. This collapses a burst of nearly-simultaneous joins into a single announcement.
3000disable_emailsbooleannullableWhen true, Nylas doesn't send email notifications when an event is booked,
cancelled, or rescheduled. When null, the default behavior applies (emails are sent).
falsehide_participantsbooleannullableWhen true, Nylas creates the event with hide_participants=true, so the host can see who's on the event but the guests cannot. When null, the default behavior applies (participants are visible).
falsenotify_participantsbooleannullableWhen true, the calendar provider sends notifications to participants
when the event is created, updated, or deleted. Microsoft grants ignore
this flag and always notify participants. This field may be null if not
explicitly set on the configuration; treat null the same as false.
false"America/New York"["primary"]open_hoursarray<object>An array of objects representing the participant's open hours. Nylas searches for free time slots within these open hours.
daysarray<integer>The days of the week that the open hour settings are applied
to. Sunday corresponds to 0, and Saturday corresponds to 6.
[1,2,3,4,5]exdatesarray<string>A list of dates that are excluded from the participant's open
hours, in YYYY-MM-DD format.
["2025-01-18"]timezonestringThe participant's timezone as an IANA-formatted string. Nylas uses this when calculating the participant's open hours and in email notifications.
"America/New York""[email protected]"requires_session_authbooleannullableWhen true, the scheduling Availability and Bookings endpoints require a valid
session ID to authenticate requests using the Configuration. This field may be
null if not explicitly set; treat null the same as false.
falseavailable_days_in_futureintegerThe number of days in the future that Scheduler is available for scheduling events.
30Rate limited. The provider or Nylas throttled the request. If a provider throttles a request and
says how long to wait, the Retry-After header gives that number of seconds. When the header
is missing, retry with exponential backoff. See
429 rate limit errors by provider.