# Use Scheduler with Agent Accounts

Source: https://developer.nylas.com/docs/v3/scheduler/agent-accounts/

Scheduler works with [Agent Account](/docs/v3/agent-accounts/) grants. Point a Configuration at an Agent Account's `grant_id` and the agent becomes the organizer: guests book against the agent's own calendar, the confirmation email comes from the agent's own address, and the booking lands on the agent's primary calendar. No OAuth connection and no human mailbox involved.

That matters when the thing doing the scheduling isn't a person. A support agent that needs to book a callback, or a recruiting agent that owns its own interview slots, previously had to borrow a human's connected grant. Now it can hold the Configuration itself.

> **Info:** 
> **New to Agent Accounts?** Start with the [Agent Accounts quickstart](/docs/v3/getting-started/agent-accounts/) to provision an account, then come back here to give it a booking page.

## What works the same as a connected grant

Every Scheduler endpoint takes the same shape for an Agent Account as it does for a Google or Microsoft grant. You call `/v3/grants/{grant_id}/scheduling/configurations` with the Agent Account's grant ID, and the [Availability](/docs/reference/api/availability/), [Sessions](/docs/reference/api/sessions/), and [Bookings](/docs/reference/api/bookings/) endpoints behave identically. There's no separate client, URL prefix, or auth flow.

- **Configurations.** Create, read, update, and delete against the Agent Account grant.
- **Public and private Configurations.** `requires_session_auth` works either way, and sessions are created the same way.
- **Nylas-hosted and self-hosted Scheduling Pages.** A public Configuration with a slug still gets hosted under `book.nylas.com`.
- **Availability rules.** Open hours, buffers, and specific-time availability all apply, and `available_days_in_future` still defaults to 30 days.
- **Booking flow.** Both the `booking` and `organizer-confirmation` booking types work, including the confirmation email to the organizer.
- **Booking webhooks.** All five triggers fire: `booking.created`, `booking.pending`, `booking.rescheduled`, `booking.cancelled`, and `booking.reminder`.

Because the Agent Account has no OAuth token, you can skip the scopes tables in the [Configurations](/docs/reference/api/configurations/) and [Bookings](/docs/reference/api/bookings/) references. Those columns cover Google and Microsoft grants; an Agent Account authenticates with your API key alone.

## Create a Configuration for an Agent Account

The [Create Configuration](/docs/reference/api/configurations/post-configurations/) request below sets up a booking page owned by an Agent Account, with slots 30 minutes long. The `participants[].email` is the Agent Account's own address, and both `availability.calendar_ids` and `booking.calendar_id` are set to `primary` because that's the only calendar Scheduler reads for an Agent Account today.

```bash
curl --request POST \
  --url "https://api.us.nylas.com/v3/grants/<AGENT_ACCOUNT_GRANT_ID>/scheduling/configurations" \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Support callback",
    "slug": "support-callback",
    "requires_session_auth": false,
    "participants": [
      {
        "name": "Support Agent",
        "email": "support-agent@agents.example.com",
        "is_organizer": true,
        "availability": {
          "calendar_ids": ["primary"]
        },
        "booking": {
          "calendar_id": "primary"
        }
      }
    ],
    "availability": {
      "duration_minutes": 30
    },
    "event_booking": {
      "title": "Support callback",
      "booking_type": "booking"
    }
  }'
```

After the Configuration exists, the booking flow is unchanged: a guest picks a slot, [`POST /v3/scheduling/bookings`](/docs/reference/api/bookings/post-bookings/) creates the event on the agent's primary calendar, and the agent's mailbox receives the same calendar traffic a human organizer would. See [Retrieve booking IDs](/docs/v3/scheduler/retrieve-booking-ids/) for reading bookings back.

## Only primary calendars are supported

Scheduler reads and writes the Agent Account's **primary** calendar only. Set `availability.calendar_ids` to `["primary"]` and `booking.calendar_id` to `"primary"` on every Agent Account participant. Agent Accounts can hold [additional calendars](/docs/v3/agent-accounts/calendars/) up to your plan's cap, but Scheduler reads exactly 1 calendar per Agent Account participant and ignores any others for both availability lookups and event creation.

Two practical consequences:

- **Everything on the primary calendar counts toward busy time.** If the agent also creates events directly through the [Events API](/docs/reference/api/events/), those events block booking slots. Keep operational or placeholder events off the primary calendar, or accept that they narrow availability.
- **You can't split booking types across calendars.** A pattern like "demos on the `sales` calendar, callbacks on the `support` calendar" needs one Agent Account per booking type rather than one account with two calendars.

Connected Google and Microsoft grants are unaffected. If a Configuration mixes an Agent Account organizer with connected-grant participants, only the Agent Account participant is restricted to `primary`.

## Round-robin meetings aren't supported

Agent Accounts can't participate in round-robin Configurations. Both distribution methods, `max-fairness` and `max-availability`, require the `availability_method` field in `availability_rules`, and neither works when an Agent Account is in the `participants` array. Use connected grants for round-robin pools, where Nylas recommends capping the participant list at 10 users for performance.

The other three [meeting types](/docs/v3/scheduler/meeting-types/) work: one-on-one, collective, and group. One-on-one is the natural fit, since an Agent Account represents a single identity rather than a team. Collective meetings work when the agent is one of several required attendees, and group Configurations work for classes or webinars the agent hosts.

If you need round-robin distribution across a pool of agents, do the rotation in your own code: keep one Configuration per Agent Account and pick which booking link to hand out. You lose the `key5` fairness bookkeeping that [max-fairness](/docs/v3/scheduler/meeting-types/#max-fairness-round-robin-meetings) does for you, so track the last-booked agent yourself.

## Booking notifications

Scheduler emits 5 booking triggers, and all of them fire for Agent Account organizers exactly as they do for connected grants, with the same payload shape. Subscribe with [`POST /v3/webhooks`](/docs/reference/api/webhook-notifications/post-webhook-destinations/) and read the [Scheduler notification schemas](/docs/reference/notifications/scheduler/) for the full field list.

| Trigger | What it fires on |
| --- | --- |
| [`booking.created`](/docs/reference/notifications/scheduler/booking-created/) | A guest confirms a slot on the agent's Scheduling Page. |
| [`booking.pending`](/docs/reference/notifications/scheduler/booking-pending/) | A guest books an `organizer-confirmation` slot and the agent hasn't confirmed yet. |
| [`booking.rescheduled`](/docs/reference/notifications/scheduler/booking-rescheduled/) | A guest moves an existing booking. |
| [`booking.cancelled`](/docs/reference/notifications/scheduler/booking-cancelled/) | A guest cancels. |
| [`booking.reminder`](/docs/reference/notifications/scheduler/booking-reminder/) | The reminder window before the event start time is reached. |

Booking webhooks arrive alongside the Agent Account's own [`event.created`](/docs/reference/notifications/events/event-created/) and [`message.created`](/docs/reference/notifications/messages/message-created/) triggers for the same booking, because the event lands on the agent's calendar and the confirmation email lands in its mailbox. Pick one trigger to drive your logic. `booking.created` carries the `booking_id` and `booking_ref` you need for reschedule and cancel links, so it's usually the right one.

## Send limits apply to booking email

Booking confirmations, reschedule notices, cancellations, and reminders all send from the Agent Account's address, so each one counts against the account's [daily send quota](/docs/v3/agent-accounts/send-limits/#sending-limits). A booking page with reminders turned on generates at least 2 messages per booking: the confirmation, then the reminder, plus anything the guest triggers by rescheduling or cancelling.

If the account is over quota, the event still saves but the email is skipped silently, and the guest sees a confirmed slot with no confirmation in their inbox. Check the quota before you point a high-traffic Scheduling Page at a new Agent Account, and set `disable_emails` on the Configuration if you'd rather send confirmations from your own system.

## What's next

- [Meeting types in Nylas Scheduler](/docs/v3/scheduler/meeting-types/) for the one-on-one, collective, and group Configurations that work with Agent Accounts
- [Managing availability](/docs/v3/scheduler/managing-availability/) for open hours, buffers, and specific-time availability rules
- [How Agent Account calendars work](/docs/v3/agent-accounts/calendars/) for the Events API surface behind a booking
- [Supported endpoints for Agent Accounts](/docs/v3/agent-accounts/supported-endpoints/) for the full Agent Account API surface
- [Scheduling agent with a dedicated identity](/docs/cookbook/use-cases/act/scheduling-agent-with-dedicated-identity/) for an end-to-end tutorial
- [Configurations API reference](/docs/reference/api/configurations/) for request and response schemas