Create a Scheduler booking config

You want a self-service booking page inside your own product. The page needs to know whose calendar to check, how long the meeting is, and what event to create when someone books. Building all of that by hand per page doesn’t scale.

A Scheduler configuration captures those rules once. You define the participants, their availability, and the event to book, and Nylas returns a configuration ID that powers a booking page or the Scheduler UI components.

How do I create a booking configuration?

Send a POST /v3/grants/{grant_id}/scheduling/configurations request. The body defines participants (with the organizer and the calendars to check), an availability block with the meeting duration_minutes, and an event_booking block describing the event to create. Nylas returns the configuration’s id, which you reuse as the configuration_id for every booking against this page. The example sets a 30 minute meeting.

Request

curl --compressed --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
    },
    "event_booking": {
      "title": "Testing Scheduler",
      "hide_participants": false,
      "conferencing": {
        "provider": "Zoom Meeting",
        "autocreate": {
          "conf_grant_id": "<NYLAS_GRANT_ID>",
          "conf_settings": {
            "settings": {
              "join_before_host": true,
              "waiting_room": false,
              "mute_upon_entry": false,
              "auto_recording": "none"
            }
          }
        }
      }
    }
  }'

What does a configuration define?

A configuration ties together 3 things: who, when, and what. The participants array lists the people whose calendars are checked for availability and where the booked event lands across all 4 providers, with one marked is_organizer. The availability block sets the meeting length and open hours, and event_booking defines the created event’s title and conferencing, including automatically creating a Zoom or Google Meet link.

Conferencing is the high-value part: set event_booking.conferencing.autocreate and every booking gets a fresh meeting link with no manual step, on Google Meet, Zoom, or Microsoft Teams.

Things to know about configurations

A configuration is reusable infrastructure, not a one-off. The single configuration_id drives both a hosted booking page and the Scheduler UI components you embed, so you create it once and reference it from your frontend. Set requires_session_auth to control whether booking needs an authenticated session, which matters for internal versus public pages.

Availability uses the same engine as the availability API, so a configuration checks each participant’s listed calendars across the 4 providers before offering a slot. See the Scheduler docs for the full configuration schema.

What’s next

• Create, reschedule, and cancel bookings against this configuration
• Scheduler overview for the full configuration schema and UI components
• Find open meeting times across calendars for the raw availability API
• Add scheduling with Notetaker to record booked meetings