API reference
Configurations
Return a Configuration

GET

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

Return a Configuration

Returns the specified Configuration object.

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]"

configuration_id*string

The ID of the Configuration object to access.

Responses

request_idstring

The request ID.

dataobject

appearanceobjectnullable

Example: null

availabilityobject

The rules that determine available time slots for the event.

availability_rulesobject

A list of availability rules that apply to all participants.

availability_methodstring

The method Nylas uses to calculate availability for all participants.

Example: "collective"

bufferobject

A list of rules that set buffer time around events for all participants.

afterinteger

The amount of buffer time to add after meetings. 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.

Example: 15

beforeinteger

The amount of buffer time to add before meetings. 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.

Example: 5

duration_minutesinteger

The total duration of the event, in minutes.

Example: 30

interval_minutesinteger

The interval between meetings, in minutes.

Example: 15

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.

Example: 5

event_bookingobject

An object containing details about the booking.

booking_typestring

The booking type.

Example: "booking"

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

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

Example: false

locationstring

The location of the event.

Example: "Conference room 104"

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.

Example: false

remindersarray<object>

A list of reminders for the event.

Array items:

minutes_before_eventinteger

The number of minutes before the event to send the reminder.

Example: 15

recipientstring

(Email reminders only) Who should receive the reminder.

Example: "all"

typestring

The reminder type.

Example: "email"

timezonestring

The event's timezone as an IANA-formatted string.

Example: "America/New York"

titlestring

The event title.

Example: "Weekly One-on-One"

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.

Array items:

availabilityobject

The availability settings for the participant.

calendar_idsarray<string>

A list of calendar IDs used to check the participant's availability.

Example: ["primary"]

open_hoursarray<object>

An array of objects representing the participant's open hours. Nylas searches for free time slots within these open hours.

Array items:

daysarray<integer>

The days of the week that the open hour settings are applied to. Sunday corresponds to 0, and Saturday corresponds to 6.

Example: [1,2,3,4,5]

endstring

The end time in 24-hour time format.

Example: "14:00"

exdatesarray<string>

A list of dates that are excluded from the participant's open hours, in YYYY-MM-DD format.

Example: ["2025-01-18"]

startstring

The start time in 24-hour time format.

Example: "10:00"

timezonestring

The participant's timezone as an IANA-formatted string. Nylas uses this when calculating the participant's open hours and in email notifications.

Example: "America/New York"

bookingobject

The participant's booking data.

calendar_idstring

The ID of the calendar the event was created on.

Example: "primary"

emailstring

The participant's email address.

Example: "[email protected]"

namestring

The participant's name.

Example: "Leyah Miller"

is_organizerboolean

When true, shows that the participant is the organizer of the event.

Example: true

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

additional_fieldsobject

An object containing additional custom fields.

example_fieldobject

labelstring

The text label to be displayed in the Scheduler UI.

Example: "Sample field"

orderinteger

The order in which the field is displayed in the Scheduler UI. Fields with lower order values are displayed first.

Example: 4

requiredboolean

When true, marks the field as required.

Example: false

typestring

The field type.

Example: "multi_line_text"

available_days_in_futureinteger

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

Example: 30

email_templateobject

Template settings for email notifications.

booking_confirmedobject

Template settings for confirmation notifications.

bodystring

The body text of the message.

Example: "Your weekly one-on-one with Nyla has been confirmed."

titlestring

The title of the message.

Example: "Confirmed: Weekly One-on-One"

organizer_localestring

The organizer's locale settings.

Example: "en"

min_booking_noticeintegernullable

The minimum number of minutes in the future that a user can schedule a new booking. This field may be null if not explicitly set; treat null the same as 60.

Example: 30

min_cancellation_noticeinteger

The minimum amount of time before a meeting that the booking can still be cancelled, in minutes.

Example: 30

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"

request_idstring

The request ID.

errorobject

The response error object.

typestring

The error type.

messagestring

The error message.

provider_errorobject

The error from the provider.

request_idstring

The request ID.

errorobject

The response error object.

typestring

The error type.

messagestring

The error message.

provider_errorobject

The error from the provider.

request_idstring

The request ID.

errorobject

The response error object.

typestring

The error type.

messagestring

The error message.

provider_errorobject

The raw error from the provider, if available

codestring

messagestring

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

request_idstring

The request ID.

errorobject

The response error object.

typestring

The error type.

messagestring

The error message.

provider_errorobject

The provider's own error, when the provider returned one.

request_idstring

The request ID.

errorobject

The response error object.

typestring

The error type.

messagestring

The error message.

GEThttps://api.us.nylas.com/v3/grants/nyla%40example.com/scheduling/configurations/{configuration_id}

API key

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

Server

Path parameters

grant_idrequiredstring

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.

configuration_idrequiredstring

The ID of the Configuration object to access.