Create Configuration - Configurations - API Reference

POST

https://api.us.nylas.com/v3/grants/{grant_id}/scheduling/configurations

Creates a Configuration object that you use to define settings and preferences for a scheduling session.

Duplicate email notifications

If the organizer in a scheduling session is a Microsoft account user, both the organizer and all attendees might receive duplicate email notifications, including booking confirmations, rescheduling and cancellation notifications, and reminders. This is because of the way Microsoft handles email notifications. If you set notifications in Scheduler, Microsoft also sends its own notifications to the event organizer and attendees. Microsoft doesn't provide a way to disable these notifications.

Metadata as additional fields

You can add metadata fields (type: metadata) to your Configuration to store custom information about a booking. For example, you can add campaign tags, keywords, or a logo URL. Set the value in the field's default. Configurations don't have a top-level metadata object, and a metadata field isn't the same as the metadata object on events and messages. It's a hidden field on the booking form.

The Scheduler UI doesn't display metadata fields. When a guest books through the hosted scheduling page or the nylas-scheduling component, the page sends each metadata field's default with the booking. The component's bookingInfo.additionalFields property overrides the default.

The Bookings API doesn't read default, required, or pattern. If your own code creates bookings with POST /v3/scheduling/bookings, include the values in the request's additional_fields. The API checks only that each key exists in the Configuration, and returns Additional field '<key>' not found in configuration if it doesn't. Values are strings.

Booking webhook notifications (booking.created, booking.rescheduled, booking.cancelled, booking.pending, and booking.reminder) include your metadata fields in booking_info.additional_fields. For group events, booking.reminder sends additional_fields as null. Calendar event webhooks (for example, event.updated) do not include them. Scheduler's own email notifications don't display them, but workflow templates can read them.

Guests can read and change metadata field values in the browser, so don't use them for routing, pricing, or secrets.

To identify Scheduler-related changes in event webhooks instead, use the metadata that Scheduler stamps on the calendar events it creates. For more information, see the event.updated notification schema.

NYLAS API KEY

Parameters

Path parameters

grant_id*string

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.

Example: "[email protected]"

Request body

appearanceany

An object that defines the appearance settings for the Scheduling Page. This field may be null if no appearance customization has been set.

availability*object

The rules that determine the available time slots for the event.

duration_minutes*integer

The total number of minutes the event should last.

interval_minutesinteger

The 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_tointeger

Nylas 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.

Default: 15

availability_rulesobject

Availability rules for the scheduling configuration. These rules define how Nylas calculates availability for all participants.

availability_methodstring

The 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.

collectivemax-fairnessmax-availability

Default: "collective"

bufferobject

The 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.

default_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.

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_availabilityboolean

When 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 true with no specific dates defined

Note: When set at the config level, individual participants cannot override this to false.

Default: false

Example: true

event_booking*object

booking_typestring

The 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.

bookingorganizer-confirmation

Default: "booking"

Example: "booking"

conferencingobject

An 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.

descriptionstring

The description of the event.

Example: "Come ready to talk philosophy!"

disable_emailsbooleannullable

When true, Nylas doesn't send email notifications when an event is booked, cancelled, or rescheduled. When null, the default behavior applies (emails are sent).

Default: false

Example: false

hide_participantsbooleannullable

When 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).

Default: false

Example: false

locationstring

The location of the event.

Example: "Central Library, room 203"

notify_participantsbooleannullable

When 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).

Default: false

Example: true

remindersarray<object>

timezonestring

The timezone Nylas uses to display times in confirmation messages and reminders. This must be an IANA-formatted string.

Example: "America/Chicago"

minLength: 1

title*string

The title of the event.

Example: "Annual Philosophy Club Meeting"

namestring

The name of the Scheduling Page. If not defined, Nylas defaults to the organizer's name.

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.

Array items:

availability*object

The 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.

booking*object

The booking data for the participant. If omitted, the participant is not included in the booked event. At least one participant must have booking data.

email*string

The 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.

Example: "[email protected]"

grant_idstring

The participant's grant ID.

is_organizerboolean

When 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.

Default: false

Example: false

namestring

The participant's name.

Example: "Nyla"

specific_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_availabilityboolean

When 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).

Default: false

Example: true

timezonestring

The 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.

Example: "America/Toronto"

requires_session_authbooleannullable

When 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).

Default: false

schedulerobject

additional_fieldsobject

available_days_in_futureinteger

The number of days in the future that Scheduler is available for scheduling events.

Default: 30

min_booking_noticeintegernullable

The 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).

Default: 60

min_cancellation_noticeinteger

The minimum number of minutes before a booking can be cancelled.

Default: 0

cancellation_policystring

A message about the cancellation policy to display to users when booking an event.

rescheduling_urlstring

The URL used to reschedule bookings. This URL is included in confirmation messages.

cancellation_urlstring

The URL used to cancel bookings. This URL is included in confirmation messages.

organizer_confirmation_urlstring

The URL used to confirm or cancel pending bookings. This URL is included in booking request messages.

confirmation_redirect_urlstring

The URL that Nylas redirects the user to when the booking is confirmed.

hide_rescheduling_optionsboolean

If true, the option to reschedule an event is hidden in booking confirmations and email notifications.

Default: false

hide_cancellation_optionsboolean

If true, the option to cancel an event is hidden in booking confirmations and email notifications.

Default: false

hide_additional_guestsboolean

Whether to hide the Additional guests field on the Scheduling Page. If true, guests cannot invite additional guests to the event.

Default: false

notetaker_settingsobject

Settings 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.

enabledboolean

When 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.

Default: false

Example: true

show_ui_consent_messageboolean

When true, displays a consent message in the Scheduler UI informing guests that the meeting will be recorded.

Default: true

Example: true

notetaker_namestring

The display name for the Notetaker bot that joins the meeting. Maximum 255 characters.

Default: "Nylas Notetaker"

Example: "Sales Recording Bot"

meeting_settingsobject

A collection of settings for the Notetaker bot.

action_itemsboolean

When 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.

Default: true

Example: true

action_items_settingsobject

audio_recordingboolean

When true, Notetaker records the meeting's audio.

Default: true

Example: true

leave_after_silence_secondsinteger

The 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).

Default: 300

Example: 360

min: 10max: 3600

summaryboolean

When true, Notetaker generates a summary of the meeting. If summary is true, video_recording, audio_recording, and transcription must also be true.

Default: true

Example: true

summary_settingsobject

transcriptionboolean

When true, Notetaker transcribes the meeting's audio. If transcription is true, video_recording and audio_recording must also be true.

Default: true

Example: true

video_recordingboolean

When true, Notetaker records the meeting's video.

Default: true

Example: true

transcription_settingsobjectnullable

Optional 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.

messagesobject

Custom 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.

maxItems: 10

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.

maxItems: 10

email_templateobject

Configurable settings for booking emails.

slugstringnullable

The slug for the Configuration object. This is an optional, unique identifier. You can use the slug instead of the configuration_id when making requests to the Nylas Scheduling endpoints. Slugs are unique to each Nylas application. This field may be null if no slug has been set.

Responses

request_idstring

The request ID.

dataobject

appearanceobjectnullable

Example: null

availabilityobject

The rules that determine available time slots for the event.

event_bookingobject

An object containing details about the booking.

idstring

The Configuration ID.

Example: "26e98405-3b48-47d2-898a-7254f1fad8d7"

namestring

The name of the Scheduling Page.

Example: "Leyah & Nyla Weekly One-on-One"

participantsarray<object>

A list of participants included in the scheduled event.

requires_session_authbooleannullable

When 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.

Example: false

schedulerobject

slugstringnullable

The Configuration slug. You can use this instead of the configuration_id when making requests to other Scheduling endpoints. This field may be null if no slug has been set.

Example: "xyz-en"