How do Group Events work with Nylas Scheduler for fixed-time classes and workshops?

Group Events in Nylas Scheduler are designed for scenarios where multiple attendees book the same fixed time slot, such as classes, workshops, webinars, or retreats. Unlike standard scheduling that calculates availability, Group Events work with specific events that you either create directly or import from existing calendar events.

How Group Events Work

Group Events follow a two-step process:

1. Create a Group Configuration

    

2. Add Events - You can create group events from the Scheduler Editor or create or import existing calendar events using the Group Events endpoints.
    

Using the Scheduler Editor Component

When creating configurations through the Scheduler Editor component, you can enable Group Events by setting the enableEventTypes property. The Editor will show a Group Events tab where you can:

• Set default capacity for events
• Configure booking policies
• Create new events or import existing calendar events

• Manage recurring event patterns

   

  
   

User perspective when booking:


 

Using the Scheduler API Directly

Step 1: Create Group Configuration

Create a configuration with type: group:

curl --request POST \
  --url "https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/scheduling/configurations" \
  --header 'Accept: application/json, application/gzip' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Learn how to bind a book",
    "type": "group",
    "group_booking": {
      "booking_type": "booking",
      "disable_emails": false,
      "calendar_id": "primary",
      "reminders": [{
        "type": "email",
        "minutes_before_event": 30,
        "recipient": "guest"
      }]
    },
    "scheduler": {
      "available_days_in_future": 260,
      "hide_cancellation_options": false,
      "hide_reschedule_options": true,
      "min_booking_notice": 0,
      "min_cancellation_notice": 480
    }
  }'

Step 2A: Create New Group Events

Use the Group Events POST endpoint to create events directly:
Documentation

POST /grants/{grant_id}/scheduling/configurations/{configId}/group-events

This allows you to specify:

• title: Event name
• when: Start and end times
• capacity: Maximum attendees
• participants: Organizer information
• description and location: Event details

Step 2B: Import Existing Calendar Events

Alternatively, use the import endpoint to register existing calendar events:
Documentation

POST /scheduling/configurations/{configId}/import-group-events

This imports events that already exist on your calendar into the scheduler system.

How Bookings Work

When someone books into a group event:

1. They select from available time slots (which come from your created/imported events)
2. The system adds them as a participant to the existing calendar event
3. Capacity is tracked by counting participants vs. the event's capacity limit
4. The calendar event is updated with the new participant

Important Considerations

• Calendar Impact: Group events create actual events on your calendar that get updated with participants
• No Conflict Checking: Group events ignore your calendar's availability and can overlap with other appointments
• Manual Conflict Management: You must manage scheduling conflicts yourself
• Virtual Calendars: Consider using Virtual Calendars for maximum isolation from your personal calendar
• Capacity Limits: 5-500 attendees for standard configurations, with provider-specific maximums
• Double-booking Risk: Since there's no conflict detection, group events can overlap with personal appointments

Group events are designed for scenarios where you dedicate specific time blocks exclusively for group bookings. They're not suitable for calendars with frequent personal appointments or situations requiring conflict detection.

For complete technical details, see the Group Events API documentation.

Updated November 04, 2025 15:29