NYnylas
Configurations

Create Configuration

Changed on

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.

post/v3/grants/{grant_id}/scheduling/configurations

Request

  • Base URL
    https://api.us.nylas.com
  • Auth
    HTTP bearer

Request body

OR

Example request

{
  "availability": {
    "availability_rules": {
      "default_open_hours": [
        {
          "days": [
            0,
            1,
            2
          ],
          "start": "10:00",
          "end": "14:00",
          "timezone": "America/Chicago",
          "exdates": [
            "2006-01-18"
          ]
        }
      ],
      "default_specific_time_availability": [
        {
          "date": "2025-12-25",
          "start": "09:00",
          "end": "13:00",
          "timezone": "America/Toronto"
        }
      ],
      "only_specific_time_availability": true
    }
  },
  "event_booking": {
    "booking_type": "booking",
    "description": "Come ready to talk philosophy!",
    "location": "Central Library, room 203",
    "notify_participants": true,
    "reminders": [
      {
        "email_subject": "Reminder: Annual Philosophy Club Meeting",
        "minutes_before_event": 30,
        "recipient": "host",
        "type": "email"
      }
    ],
    "timezone": "America/Chicago",
    "title": "Annual Philosophy Club Meeting"
  },
  "participants": [
    {
      "availability": {
        "open_hours": [
          {
            "days": [
              0,
              1,
              2
            ],
            "start": "10:00",
            "end": "14:00",
            "timezone": "America/Chicago",
            "exdates": [
              "2006-01-18"
            ]
          }
        ]
      },
      "email": "nyla@example.com",
      "name": "Nyla",
      "specific_time_availability": [
        {
          "date": "2025-08-21",
          "start": "09:00",
          "end": "17:00",
          "timezone": "America/Toronto"
        }
      ],
      "only_specific_time_availability": true,
      "timezone": "America/Toronto"
    }
  ],
  "scheduler": {
    "notetaker_settings": {
      "enabled": true,
      "show_ui_consent_message": true,
      "notetaker_name": "Sales Recording Bot",
      "meeting_settings": {
        "action_items": true,
        "action_items_settings": {
          "custom_instructions": "Only return the 5 most important action items."
        },
        "audio_recording": true,
        "leave_after_silence_seconds": 360,
        "summary": true,
        "summary_settings": {
          "custom_instructions": "Return this summary in the MEDPIC sales methodology."
        },
        "transcription": true,
        "video_recording": true,
        "transcription_settings": {
          "expected_languages": [
            "en",
            "es"
          ],
          "fallback_language": "en",
          "keywords": [
            "Nylas",
            "AssemblyAI"
          ],
          "use_speaker_names_as_keywords": true
        },
        "messages": {
          "on_join": [
            {
              "type": "text",
              "content": "👋 Hey team! I'm your AI notetaker — here to capture the key points.",
              "send_after_ms": 5000
            }
          ],
          "on_participant_join": [
            {
              "type": "text",
              "content": "👋 Welcome! Recording and transcription are running.",
              "debounce_ms": 3000
            }
          ]
        }
      }
    }
  }
}

Response

Configuration returned

OR

Example response

{
  "request_id": "5fa64c92-e840-4357-86b9-2aa364d35b88"
}

Changes

  • 0e71ff80a4ceRevision changes
    • info

      the request property default value Nylas Notetaker was removed

    • info

      the request property default value Nylas Notetaker was removed

  • a669a04b02baRevision changes
    • breaking

      the request property //// became required

    • breaking

      the request property //// became required

    • breaking

      the //// request property's min was increased to 5.00

    • breaking

      removed subschema #1: Auto-conferencing subschema #2: Google Meet subschema #3: Zoom Meeting subschema #4: Microsoft Teams subschema #5: Teams for Business subschema #6: Skype for Consumer subschema #7: Skype for Business subschema #8: WebEx subschema #9: GoToMeeting from the // request property oneOf list

    • info

      added subschema #1: Auto-conferencing subschema #2: Google Meet subschema #3: Zoom Meeting subschema #4: Microsoft Teams subschema #5: Teams for Business subschema #6: Skype for Consumer subschema #7: Skype for Business subschema #8: WebEx subschema #9: GoToMeeting subschema #10: Remove conferencing to the // request property anyOf list