---
title: "Guests API"
description: "Put named guests on an event from your CRM or registration system through the API, or from a file, and give each one a personal link to choose their seats."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.seatlayer.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Guests API

A guest list makes an event invite-only, or adds named guests to an open
sale. Each guest gets a personal link that opens their own seat choice. You
fill the list by hand in the dashboard, from a spreadsheet, or from your CRM or
registration system through this API. The
dashboard's **Guests** tab uses these same routes, so your system can do
everything the tab does.

Every route on this page takes a matching `sk_test_…` or `sk_live_…` secret
key, and the event key in the path. Guest lists are REST and webhooks: the
server SDKs have no guest methods, so call these routes over HTTP.

Guest lists are on for every organization. Only when SeatLayer has turned
them off for yours do adding guests, importing a file (the check too), changing
a guest and giving a new link answer `403 module_not_enabled` with
`"module": "guest_lists"`. Reading and removing guests always work, and so does
a link a guest already has.

## What a guest seat costs

Each seat a guest gets uses one hosted ticket credit, the same as a seat sold
through SeatLayer checkout, whether the guest chooses it or your team gives it.
A seat that is released, or freed when the guest is removed, keeps its credit
spent. Moving a guest to other seats uses no credit.

## The same person is the same guest

A guest list never holds the same person twice:

- The same **email** (case and spaces ignored) is the same guest.
- The same **reference** (your own id for the person) is the same guest.

Sending a guest who is already on the list updates that guest, and never adds a
second one. A field you leave out keeps what the guest has. When an email
belongs to one guest and a reference to another, the row answers
`email_and_reference_differ` and nothing changes: SeatLayer never guesses which
person you meant.

Each guest's `source` says how they joined the list: `manual` (added in the
dashboard), `file` (an import), `api` (this API), or `partner` for a guest a
partner added. `POST …/guests` matches an email only among guests added in the
dashboard, from a file or by the API: an email that a partner's guest has
answers `email_from_source`.

## Add or update guests

**POST /v1/events/:key/guests**. Authentication: Secret key

Send one guest or up to 1,000:

```bash
curl https://api.seatlayer.io/v1/events/$EVENT_KEY/guests \
  -H "Authorization: Bearer $SEATLAYER_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: crm-sync-2027-02-01" \
  -d '{
    "guests": [
      { "name": "Sarah Mitchell", "email": "sarah.mitchell@example.com",
        "group": "Diamond Directors", "seatsAllowed": 2, "language": "ko",
        "reference": "CRM-48211", "extra": { "Country": "Korea" } }
    ]
  }'
```

The answer is `201` when at least one guest was added, else `200`. It holds
every guest added or updated, in request order, and a `problems` list for the
rows that changed nothing:

```json
{
  "guests": [{ "id": "gst_…", "status": "invited", "link": "https://app.seatlayer.io/e/ev_…/invite#gsl_…", "…": "…" }],
  "problems": [{ "index": 3, "error": "invalid_email", "field": "email" }]
}
```

| Field | Rule |
|---|---|
| `name`, `email` | Required. Name up to 200 characters, email up to 254 |
| `phone` | 6 to 20 characters: digits, spaces and `+ - ( )` |
| `group` | Up to 120 characters |
| `seatsAllowed` | 1 to 20. Left out, the group's seats each apply |
| `language` | A locale tag (`ko`, `pt-BR`, `zh-TW`); it becomes one of the booking page's 43 languages, and a tag for none of them answers `invalid_language` |
| `reference` | Up to 200 characters, unique within your source |
| `party` | Any text, up to 120 characters. Guests with the same text choose together, 2 to 20 people |
| `partyChooser` | `true` for the one guest who chooses for the party; else the first one listed |
| `extra` | Up to 10 text values; a list keeps at most 10 extra field names |

The `link` is the guest's personal link. Every read shows it again, so you can
send it from your own mail tool too. It opens the event's own invite address,
`/e/<event>/invite#gsl_…`; the part after `#` is the guest's key. Links sent
earlier in the `/a#gsl_…` shape keep working.

`send` decides whether SeatLayer emails the guests this call adds their link:
`email` or `none`. Leave it out and the event's `guestLinks.sender` decides:
`seatlayer` emails them, `organizer` doesn't. A guest the call only updates gets
nothing, unless it gives them another email: their new link then goes to the
new address the same way. The import takes the same `send`.

The email goes once the guest's seat choice is open: the event is on sale and
their group's opening time (else the list's) has come. A guest added before then
gets it after it opens, and never once the change deadline has passed. An event
that is not on sale yet sends its waiting invitations after it goes on sale.
Invitations count toward your organization's
[daily email allowance](#the-daily-email-allowance): a list bigger than what is
left of the day goes out over the following days, oldest guest first, and the
call's answer never waits for the emails. `POST …/send` doesn't wait for a
group's opening time; it works once the event is on sale.

Guests you add through the API join the `API` source; guests someone adds while
signed in to the dashboard join "Added by you".

`seats` gives the guest seats your team chose: each a seat label (`J-12-9`) or
the seat as tickets print it (`Hall 1 · J · 12 · 9`). SeatLayer books them
under the guest's own order and emails the ticket, and the guest's page shows
them as chosen by your team. A seat the guest already has stays theirs, so
sending the same guest again changes nothing. A seat someone else has is never
moved: that row answers `seat_taken`, and its other details still apply. So do
`seat_not_on_chart` and `seats_over_allowed`. On an event that takes payment,
a row with `seats` answers `seat_placement_unavailable`.

## List and read guests

**GET /v1/events/:key/guests**. Authentication: Secret key
**GET /v1/events/:key/guests/:id**. Authentication: Secret key

Reading guests, one guest and a guest's history (below) shows every guest's
email and personal link, so it takes the same permission as the Guests file:
`event:orders:read`. A secret key reads as before; a dashboard member without
the Orders permission (a viewer) gets `403 missing_manage_capability`.

The list is sorted by name (any case), 50 at a time (up to 200 with `limit`),
with `nextCursor` for the next page. A guest added while you page never shifts
a page you haven't read. Filter it with:

- `status`: `invited`, `opened`, `chosen` or `cancelled`, or `not_chosen` for
  invited or opened;
- `group`, `source` (a `src_…` id or a kind such as `api`) and `party` (a
  `pty_…` id);
- `changed=1`: the seat changed at least once;
- `givenByTeam=1`: your team gave the seat (a Seat column, Box office or a
  move);
- `inParty=1`: in a party of two or more;
- `backInSource=pending`: no guest added in the dashboard, from a file, by the
  API or by a partner matches it, so it finds none;
- `q`: part of a name, an email or a reference, or a whole seat, written
  `H-14-22` or `H 14 22`;
- `partner`: a partner's id (`porg_…`), `any` for guests given to any partner,
  or `none` for your own.

A filter that isn't `1`, `0` or (for `backInSource`) `pending` answers
`422 invalid_filter` with the `field`.

## Count the list

**GET /v1/events/:key/guests/summary**. Authentication: Secret key

The counts the dashboard's Guests tab shows, in one call:

```json
{
  "total": 11582, "invited": 2204, "opened": 1020, "chosen": 8300, "cancelled": 58,
  "chosenLastHour": 412, "changedSeat": 612, "seatChanges": 731, "inParty": 642, "seatGivenByTeam": 214, "notBackInSource": 3,
  "seats": { "chosen": 8300, "toChoose": 3224 }, "lastReminderAt": 1798185600000,
  "sources": [
    { "id": "src_…", "kind": "file", "label": "File", "count": 86, "takesSeatsBack": false, "lastSyncAt": null, "back": 0, "retrying": 0 }
  ],
  "groups": [
    { "group": "Diamond Directors", "count": 318, "chosen": 301, "sources": [{ "id": "src_…", "kind": "file", "label": "File" }] }
  ],
  "linkHost": "app.seatlayer.io"
}
```

- Every count is of guests on the list now; `total` includes the cancelled
  ones.
- `changedSeat`, `inParty`, `seatGivenByTeam` and `notBackInSource` use the
  same rules as the `changed`, `inParty`, `givenByTeam` and `backInSource`
  filters, so each count matches the list its filter opens.
- No guest waits to go back to a source: `notBackInSource` is 0, and every
  source's `takesSeatsBack` is false.
- `groups` leaves out guests with no group. Each group's `sources` are the
  sources its guests came from (cancelled ones included, removed ones not), in
  the order of `sources`, labelled as each guest's `source` is.
- `seats` counts seats, not guests. `chosen` is the seats guests hold now.
  `toChoose` is the seats the guests who haven't chosen yet may still choose:
  each guest's own number, else their group's, else 1.
- `seatChanges` adds up every seat change; `changedSeat` is how many guests
  made them. Each group's `chosen` is its guests who have chosen.
- `lastReminderAt` is when SeatLayer last sent a reminder to any guest on the
  list, or null before the first. A guest gets at most one reminder a week.
- The summary also carries `linksWaiting`, `sendsWaiting`, `emailPace` and,
  after a send that ended early, `emailsNotSent`: see
  [The daily email allowance](#the-daily-email-allowance).
- Every source's `back` and `retrying` are 0, and its `lastSyncAt` is null.
- `linkHost` is the host guest links are built on today. It is there when the
  list is empty too.

## Download the guest list

**GET /v1/events/:key/guests.csv**. Authentication: Secret key

The Guests file: one row for each guest on the list, chosen or not, from every
source. Cancelled guests are in it; removed guests are not. The columns, in this
order:

`Source`, `Reference`, `Name`, `Email`, `Group`, `Seat choice`, `Party`,
`Chosen by`, `Seat given by`, `Hall`, `Block`, `Row`, `Seat`, `Chose on`,
`Changes`, `Back in source`, `Language`, `Personal link`, then one column for
each extra field, in the event's order.

- `Source` is the label the Guests tab shows: "Added by you", "File", "API",
  or the partner's name for a guest a partner added.
- On a list where any guest has a partner, `Partner` comes right after
  `Source`: the partner's name, or empty for your own guests. A list without
  partners has no `Partner` column, so its file reads exactly as before.
- `Seat choice` is "Chose", "Not yet" or "Cancelled".
- `Party` is the party's own text (a file's Party column) when it has one, else
  the name of the person who chooses for it.
- `Chosen by` names who chose the seats: the guest, or their party's chooser.
  It is empty for seats your team gave. `Seat given by` is set only then:
  "File · vip-seats.xlsx", "API", or "You" for the dashboard.
- A guest's seats next to each other read `7–8` in `Seat`. Seats in more than
  one row are listed row by row, separated by `; `.
- `Chose on` is `2027-02-22 09:03` in the event's time zone.
- `Back in source` is "–" for guests added by hand, from a file or by the API,
  and empty for a guest a partner added.
- `Personal link` is the guest's link, as the Guests tab copies it.

The file has every guest's email and link, so it takes the same permission as
the orders file (`event:orders:read` on a browser token). It answers
`403 module_not_enabled` only when SeatLayer has turned guest lists off for your
organization. It streams, so a list of any size
downloads in one go, with a UTF-8 BOM so spreadsheet apps read accents.

## Who can book

Create the event with `whoCanBook` on `POST /v1/events`:

- `anyone` (the default): today's event, with no guest list needed;
- `guests`: only the people on the guest list can choose seats, and the
  public booking page refuses holds with `403 guests_only`;
- `both`: guests choose first, then the booking page opens to everyone.

Anything but `anyone` needs guest lists on for your organization (they are,
unless SeatLayer has turned them off: `403 module_not_enabled`) and SeatLayer
checkout: send it with
`buyerCheckout: "seatlayer"` or `bookingMode: "free"`, else the create answers
`422 who_can_book_needs_seatlayer_checkout`. A guest's link opens only on a
SeatLayer-checkout event.

The event then reads `whoCanBook` in `GET /v1/events/:key` and the events
list. An event that is `anyone` leaves the field out. Copying an event, or
making an event series from it, never copies its guest list: every copy is
`anyone`.

## The guest settings on the event

`PATCH /v1/events/:key` takes the guest list's settings beside the event's
other fields, and `GET /v1/events/:key` reads them in `meta`, for every event
of an organization with guest lists and for any event that isn't `anyone`:

```json
{
  "whoCanBook": "guests",
  "whoCanBookLocked": false,
  "seatChoice": { "opensAt": 1771750800000, "changeDeadline": 1772442000000 },
  "guestLinks": { "sender": "seatlayer" },
  "parties": { "chooseTogether": true },
  "teamSeats": "fixed",
  "guestInstructions": { "en": "Bring your badge.", "ko": "배지를 지참하세요." }
}
```

- `whoCanBook` can change until the event's first order (a buyer paying
  included) or booked seat. After that it answers
  `409 who_can_book_locked`, and `whoCanBookLocked` is true.
- A change of `whoCanBook` or the deadline reaches the booking page at once.
  With `both`, the public sale opens at `changeDeadline`; without one it stays
  closed, so guests never lose their head start.
- `seatChoice` changes only the keys you send; `null` clears one. A deadline
  must come after the opening (`422 deadline_before_opening`).
- `guestLinks.sender` is `seatlayer` or `organizer`; `teamSeats` is `fixed`
  or `changeable`; `parties.chooseTogether` is true or false.
- `guestInstructions` holds one text per language, up to 600 characters,
  keyed by any of the 43 languages the guest page speaks (`en`, `ko`,
  `zh-Hans`, …). A `PATCH` replaces every language; an empty text removes
  one. The guest page shows the guest's language, else the event's, else
  English.
- Everything here answers `403 module_not_enabled` when SeatLayer has turned
  guest lists off for your organization, except setting `whoCanBook` back to
  `anyone`.
- `whoCanBookLocked` only reads; a `PATCH` ignores it.

## Where groups sit

**GET /v1/events/:key/guest-groups**. Authentication: Secret key
**PUT /v1/events/:key/guest-groups**. Authentication: Secret key

```json
{
  "groups": [
    { "group": "Diamond Directors", "seatTypes": ["vip"], "seatsEach": 2, "opensAt": 1771747200000 },
    { "group": "Associates", "seatTypes": ["std"], "seatsEach": 1, "opensAt": null }
  ],
  "seatTypes": [{ "key": "std", "name": "Standard" }, { "key": "vip", "name": "VIP" }]
}
```

- `PUT` takes `{ "groups": [...] }` and replaces every rule of the event in one
  write. A group it leaves out has no rule afterwards.
- `group` matches the guests' group in any case. Listing a group twice
  answers `422 group_twice`.
- `seatTypes` are the event's seat types (its chart categories); the answer
  lists them in `seatTypes`. A key the event doesn't have answers
  `422 unknown_seat_type`. An empty list means any open seat, like a guest
  in no group.
- `seatsEach` is 1 to 20: what each guest of the group chooses, unless the
  guest has their own `seatsAllowed`.
- `opensAt` is the group's wave; `null` waits for `seatChoice.opensAt`.
- A guest gets the new rule when they next open their link. A page already
  open keeps the rule it opened with until it ends.

## Parties

**POST /v1/events/:key/parties**. Authentication: Secret key
**PATCH /v1/events/:key/parties/:id**. Authentication: Secret key
**DELETE /v1/events/:key/parties/:id/members/:guestId**. Authentication: Secret key
**DELETE /v1/events/:key/parties/:id**. Authentication: Secret key

A party is 2 to 20 guests who choose together: one person, the chooser,
picks everyone's seats on their own link, where their own group may sit. Each
person still gets their own seat and ticket.

- `POST` takes `{ "guestIds": [...], "chooserId": "gst_…" }` and answers
  `201 { "id", "chooserId", "guestIds" }`. Sending the same party again
  answers it with `200`.
- It refuses a guest who already chose a seat (`409 party_member_chose`, with
  `guestIds`), is in another party (`409 already_in_party`) or was cancelled
  (`409 guest_cancelled`). Fewer than 2 or more than 20 guests answer
  `422 party_too_small` or `party_too_large`; a chooser outside the list,
  `422 party_chooser_missing`.
- `PATCH` takes `{ "chooserId" }`: another person in the party chooses.
- `DELETE …/members/:guestId` takes one person out; they choose alone. When
  the chooser leaves, the next person chooses. A party left with one person
  ends.
- `DELETE …/parties/:id` ends the party: each person chooses alone, and seats
  already chosen stay.
- Each change signs everyone in the party out of a page they have open, so
  they see the party as it now is when they open their link again.
- Making a party and changing its chooser answer `403 module_not_enabled`
  when SeatLayer has turned guest lists off for your organization. Taking
  people out and ending a party always work.

## Change, remove, or give a new link

**PATCH /v1/events/:key/guests/:id**. Authentication: Secret key
**DELETE /v1/events/:key/guests/:id**. Authentication: Secret key
**POST /v1/events/:key/guests/:id/link**. Authentication: Secret key

`PATCH` changes only the fields you send; in `extra`, `null` removes a field.
An email another guest of the list already has answers `email_taken`. A new
email gives the guest a new link: the old link and anyone choosing on it stop,
and the guest's open orders move to the new address. When `guestLinks.sender`
is `seatlayer`, the new link goes to the new address as an invitation would.

`DELETE` frees the guest's seats, then removes the guest and stops their link
at once. An order with a ticket already used at the door stays as it is. The
same person can be added again later, as a new guest.

`POST …/link` gives the guest a new link. The old one then answers as not
recognised, and anyone still choosing on it is signed out.

## Email guests their links

**POST /v1/events/:key/guests/send**. Authentication: Secret key
**POST /v1/events/:key/guests/reminders**. Authentication: Secret key

Both take some guests by id, or every guest a list filter finds (the same
filters as `GET …/guests`; `{}` is the whole list). Send one of the two:

{/* sample-guard: skip two alternative request bodies, one per line */}
```json
{ "guestIds": ["gst_…", "gst_…"] }
{ "filter": { "status": "not_chosen", "group": "Diamond Directors" } }
```

`guestIds` takes 1 to 1,000 ids. A body with both, with neither, or with ids
that are not a list of 1 to 1,000 answers `422 invalid_send_target`.

Both answer `202`:

```json
{ "queued": 100, "skipped": 3, "waiting": 309 }
```

- `queued` is the guests emailed now.
- `waiting` is the guests this send emails later, as your
  [daily email allowance](#the-daily-email-allowance) allows: oldest guest
  first, each one once. You don't call again for them.
- `skipped` is the guests you asked for that get no email. With `guestIds`,
  that is every id not emailed: a cancelled or removed guest, a party member
  whose chooser chooses for them, or, for a reminder, a guest who has chosen or
  was reminded in the last 7 days. With a `filter`, it counts only the guests a
  reminder holds back for those 7 days.

Both refuse when an email could not lead to a seat: `409 event_not_on_sale`
before the event is on sale, and `409 guest_choice_closed` once the change
deadline has passed.

- `POST …/send` emails each guest their link: the invitation, or the party
  email to a party's chooser. Every guest but a cancelled one can get it. A
  guest who chooses while the send is still waiting gets none.
- Making a party, or choosing another chooser, emails the chooser the party
  email only if they haven't had their link already.
- `POST …/reminders` emails only guests who haven't chosen yet, and each guest
  at most one reminder a week. A guest reminded in the last 7 days is skipped.
- While parties choose together, the people a chooser chooses for get nothing:
  their own link chooses no seat.
- The emails go out in the organizer's name, with your email sender name and
  reply-to when you set them, in each guest's language (else your
  organization's, else English), with your guest instructions on top.
- Every guest shows `linkSentAt` (when SeatLayer last emailed the link) and
  `lastReminderAt`.
- Send an `Idempotency-Key` to retry safely: the same key answers the first
  call again and sends nothing more.
- Both answer `403 module_not_enabled` when SeatLayer has turned guest lists off
  for your organization.

SeatLayer also emails a party's chooser when you make the party or change who
chooses, when SeatLayer sends the event's links.

When a guest confirms, their seat confirmation is the order confirmation with
their tickets, in their language, with a line to their guest page. In a party,
each person gets their own when the chooser confirms.

## The daily email allowance

Each organization has a daily allowance of guest emails, and SeatLayer sends
them in passes through the day. The invitation, the party email, the reminder
and every `POST …/send` count toward it. A guest's own seat confirmation and the
email about a moved seat don't: they go at once.

What doesn't fit today waits and goes by itself, oldest guest first, each guest
once. No call fails because of the allowance.

A new organization starts with a smaller allowance. If your guest lists need
more, contact support and we can raise it.

`GET …/guests/summary` reports the allowance as `emailPace`:

```json
{
  "linksWaiting": 120, "sendsWaiting": 309,
  "emailPace": { "now": 1793698200000, "paused": false, "start": 1793698200000,
    "day": 1793664000000, "todayLeft": 412, "perDay": 600, "perPass": 100, "passMs": 900000 }
}
```

- `perDay` is the most guest emails your organization sends in one UTC day, and
  `todayLeft` is what is left of it. `day` is the start of that UTC day.
- Emails go in passes: at most `perPass` every `passMs` milliseconds. Other
  senders share a pass, so read any finish time you work out as an estimate.
- `start` is when sending can start: now, or later when no email can go yet.
- `paused: true` means no guest email is going out for now. What waits goes
  when sending is back.
- The numbers are your organization's own and can change. Read them from the
  summary; don't keep a copy in your code. `emailPace` is left out when it
  can't be read.
- `linksWaiting` counts guests whose link goes out by itself later: when their
  seat choice opens, or as the allowance allows. `sendsWaiting` counts guests a
  send or a reminder still has to email who are not in `linksWaiting`. The two
  together are the guests still to be emailed, each counted once.

When your team gives seats to several guests in one call, the seats are theirs
at once and their confirmations go out at the same pace.

A send that is still waiting ends, with the rest unsent, when emailing them
would no longer help. The summary then has `emailsNotSent`:

```json
{ "emailsNotSent": { "count": 180, "reason": "choice_closed", "kind": "link", "endedAt": 1793750400000 } }
```

- `reason` is `choice_closed` (the change deadline passed), `sales_closed` (the
  event's sales closed for good), `lifetime` (it was still waiting 35 days on)
  or `cancelled_by_staff` (SeatLayer support stopped it).
- `kind` is `link` or `reminder`. `count` is the guests it had not emailed.
- It is there for the latest such send, until a later send of that kind
  finishes or 35 days pass.

To reach a large list before a close date, send the links yourself: add the
guests with `send: "none"` (or set `guestLinks.sender` to `organizer`) and mail
each guest's `link` from your own tool. Those emails are yours and use none of
the allowance.

## Free or move a guest's seats

**POST /v1/events/:key/guests/:id/release**. Authentication: Secret key
**POST /v1/events/:key/guests/:id/move**. Authentication: Secret key

`POST …/release` frees every seat the guest has. Their bookings are cancelled
and their tickets stop working, and the guest is told. Their link stays, so they
choose again while seat choice is open. A ticket already used at the door
answers `tickets_already_used` with its `labels`, and nothing changes.

`POST …/move` moves the guest to other seats in one step:

```json
{ "seats": ["H-14-25", "H-14-26"] }
```

- `seats` is the guest's whole new set, as many seats as they have now. Each is
  a seat label or what tickets print.
- The new seats are booked before the old ones are freed, so the guest is never
  left without a seat. A seat someone else has answers `seat_taken`, and
  nothing changes.
- Your team moves a guest to any seat type, at any time. The guest's own number
  of seats still holds.
- A moved seat counts as one your team gave (`seatGivenByTeam`), and the guest
  gets a new ticket for it: they are told of the move, and their tickets are
  emailed again, only the ones that work. The old ticket stops scanning; door
  phones get the change when they next refresh their list. A move uses no
  credit.

## Give guests seats

**POST /v1/events/:key/guests/seat**. Authentication: Secret key
**POST /v1/events/:key/guests/:id/seats**. Authentication: Secret key

`POST …/guests/seat` gives the best seats to guests who have none, for example
when seat choice has closed. Send some guests by id, or a list filter (the same
filters as `GET …/guests`):

```json
{ "filter": { "status": "not_chosen", "group": "Diamond Directors" } }
```

- Each guest gets the best seats left in their seat types, as many as they may
  have. A group with no seat types may sit anywhere.
- A party that chooses together sits side by side, where its chooser's group
  may sit. People of the party who have seats already are sat beside.
- It never takes a seat someone has, and leaves seats set aside for a sales
  channel alone.
- Your team places the seats: each guest gets a free booking, their tickets and
  the confirmation, and `guest.seat_chosen` is sent.

The answer says what one call did:

```json
{ "seated": 48, "seatsPlaced": 61, "next": "WyJrYW…",
  "notSeated": [{ "guestId": "gst_…", "reason": "not_enough_together" }] }
```

- One call works through 50 guests at most, and stops sooner when a page takes
  long (each guest is a booking, tickets and an email). While `next` is not
  null, call again with the same body and `"cursor": next`.
- `reason` is `not_enough_seats` (none left in their seat types),
  `not_enough_together` (seats are left, but not side by side for the party),
  `has_seats` (they have seats, or took some themselves while the call ran),
  `guest_cancelled`, `guest_not_found`, `no_seats_allowed`,
  `insufficient_hosted_credits` (your organization is out of hosted ticket
  credits) or `seat_placement_unavailable` (the booking could not be made; try
  again).

`POST …/guests/:id/seats` gives one guest the seats you name, as a file's Seat
column does:

```json
{ "seats": ["H-14-25", "H-14-26"] }
```

It answers the guest. A seat someone has answers `seat_taken`; more seats than
the guest may have answers `seats_over_allowed`. Seats the guest has already are
kept. To give a guest other seats instead, move them (`POST …/move`).

Both work on free events only: on an event that takes payment they answer
`422 seat_placement_unavailable`. Both answer `403 module_not_enabled` when
SeatLayer has turned guest lists off for your organization.

## Partners' guests

**POST /v1/events/:key/guests/partner**. Authentication: Secret key

Agencies, sponsors, exhibitors and other partners with access to the event
(Channels › Partner access) can have guests of their own. A partner's guests
choose only from that partner's seats: the channels its access covers. Each
guest reads its partner as `partner: { "id": "porg_…", "name" }`, or `null`
for your own.

Give guests to a partner in any of these ways:

- `partner` on a guest you add (`POST …/guests`) or in an import row: the
  partner's id or its name, in any case. A name no partner has is the warning
  `partner_not_found`: the row is still written, and the guest stays yours.
  Left out or empty, nothing changes.
- `partner` on `PATCH …/guests/:id`: an id, a name, or `null` to take the guest
  back.
- `POST …/guests/partner`, for many guests at once:

```json
{ "guestIds": ["gst_…", "gst_…"], "partner": "Brightwell Korea", "dryRun": true }
```

```json
{ "given": 24, "unchanged": 0, "seatsKept": 19,
  "freed": [{ "guestId": "gst_…", "seats": [{ "label": "H-14-22" }] }], "notGiven": [] }
```

- A guest who has seats keeps them only when every one is in the new partner's
  seats (or, taken back, in Public sale). Otherwise their seats are freed, the
  way Release frees them, and they choose again. `dryRun: true` says what would
  happen and changes nothing.
- A party moves together: giving one person gives their whole party. A party
  can't be made of two partners' guests (`party_mixed_partners`).
- Your team places a partner's guest only in that partner's seats: another seat
  answers `seat_outside_partner_seats`.
- `null` takes guests back. Giving answers `403 module_not_enabled` when
  SeatLayer has turned guest lists off for your organization; taking guests
  back always works.

The summary's `partners` lists each partner with its guests (`count`, `chosen`),
its seats and `seatsLeft`: its seats less those its guests hold or may still
choose.

## Several dates: one list for an event series

Each date of an event series is its own event, and every date shares one guest
list: one row and one link per guest. Every guest route takes the key of any
date; adding, listing, counting, changing and removing act on the whole list.
Orders, tickets, door scans and Performance stay per date.

- `guestDates` on `PATCH /v1/events/:key` (any date) is the list's Dates card:
  `attendance` is `every` (everyone comes every date) or `own` (each guest's
  own dates; none given means every date). `seat` is `each` (a seat for each
  date) or `same` (the same seat every date). It is fixed once a guest has a
  seat on any date
  (`409 guest_dates_locked`). Who can book, set on any date, is set on every
  date.
- `dates` on a guest you add or change: each a date's event key, or a day
  `YYYY-MM-DD` with one date that day. A name that is no date of the series is
  `date_not_in_series` (or `date_ambiguous` for a day with two dates); null or
  `[]` is every date.
- Each guest reads `dates`, `everyDate`, `seatsByDate` (each date they come,
  with their seats there) and `datesChosen`: `all`, `some` or `none`. A guest is
  `chosen` only once every date they come has seats.
- `GET …/guests` takes `datesChosen=all|some|none` and `date=` (guests who come
  that date). The summary adds `series`: each date with who comes and who has
  seats there, and the `datesChosen` counts.
- The guest's link opens one date at a time: on SeatLayer's guest page, the
  link's exchange (`POST /pub/guest-links/exchange`) takes `date`, and answers
  `series` with the dates the guest comes and their seats there. With `each`, each date is held and confirmed on its own key.
  With `same`, the guest holds seats on the date the map draws, and one
  confirm books those seats on every date they come, or on none
  (`409 seats_unavailable` with the `dates` that refused). Either way each
  date gets its own order and ticket, and `guest.seat_chosen` names that date.
- Removing a guest frees their seats on every date: `guest.released` is sent
  once for each date they had seats on, naming that date, with that date's
  seats.
- The team's seat routes and a guest's Change seat answer
  `409 series_seats_unavailable` on a series. A file's Seat column, or
  `seats` on `POST …/guests`, is refused the same way on each row that has
  seats (`series_seats_unavailable`); the guest is still added, without the
  seat.
- A list covers a series of up to 31 dates (`422 series_too_long`).

## A guest's history

**GET /v1/events/:key/guests/:id/history**. Authentication: Secret key

Everything that happened to a guest, oldest first, and who did it. It takes
the same permission as reading guests (`event:orders:read`):

```json
{ "history": [
  { "at": 1793664000000, "kind": "added", "by": "file" },
  { "at": 1793667600000, "kind": "opened", "by": "guest" },
  { "at": 1793667900000, "kind": "chosen", "by": "guest", "seats": ["H-14-22"] },
  { "at": 1793750400000, "kind": "changed", "by": "team", "from": ["H-14-22"], "to": ["H-14-25"] }
] }
```

- `kind` is `added`, `link_sent`, `link_new`, `opened`, `chosen`, `changed`,
  `released`, `removed` or `group_changed`.
- `group_changed` is a move to another group. It has `fromGroup` and `toGroup`,
  and either is `null` when the guest had no group or has none now.
- `link_sent` is each time SeatLayer emailed the link. A reminder has
  `reminder: true`.
- `by` is `guest`, `party_chooser`, `team` (someone signed in), `api` (a secret
  key) or `file` (an import).
- A removed guest's history stays readable.

## The guest's own page

A guest opens their link on SeatLayer's guest page. The page trades the link
for a short session that belongs to that guest alone, and the guest chooses on
the seat map with it.

- **Seats.** A guest chooses up to their `seatsAllowed`, else their group's
  seats each, else one. Seats they have held and seats they have booked count
  together, from every phone or browser they open the link on.
- **Where.** Only the seat types their group may sit in. A guest in no group,
  or in a group that has no seat types yet, may choose any open seat.
- **When.** From their group's opening time (else when seat choice opens) until
  the change deadline.
- **Only people you invite.** On an event only for its guests, the seat map
  refuses everyone else's holds and best-available with `guests_only`. On an event for both, guests
  choose first and everyone else can book once the guests' deadline passes.

When a guest confirms their seats, SeatLayer books them under the guest's own
order, emails the ticket to the guest's address, and sends `guest.seat_chosen`.
The guest's seats then show in `seats` on the guest.

**On an event that takes payment**, a guest pays for their seats on the
event's own payment page, as any buyer on the booking page does: the seat's
normal price and the booking fee, through the gateway the event uses, with no
discount code. The order is in the guest's name and email, and the payment
page sends the guest back to a page that shows how the payment went. Once the
payment settles, the seats are booked, the ticket is emailed, and
`guest.seat_chosen` is sent, as for a free seat. A payment that never completes
leaves the guest choosing; the seat is held for 30 minutes while they pay.

- A party that chooses together can't pay online: its chooser's confirm
  answers `guest_party_payment_unavailable`. Turn off "Parties choose together"
  so each person chooses and pays on their own link.
- A paid seat is changed or refunded in Orders, never from the guest list:
  `POST …/release`, `POST …/move` and `DELETE …/guests/:id` answer
  `guest_order_paid` with the `orderId`. A full refund puts the guest back to
  choosing, and sends `guest.released`.
- While a guest is paying, a change to their email answers
  `guest_payment_pending`. Change it once the payment ends.

Until the change deadline, a guest can change their seat on the same page, in
one step and where their group may sit. A seat your team gave them stays
fixed, unless the event's `teamSeats` is `changeable`.

**Parties.** People in a party choose together on the chooser's link, where the
chooser's group may sit, up to all their seats together. The others' links show
the party and wait for the chooser. The chooser's confirm books every person's
seat in one step, or none: each person gets their own order, ticket and
`guest.seat_chosen`.

## Check and import a file

**POST /v1/events/:key/guests/import**. Authentication: Secret key

Your code reads the file and sends its rows, with the columns mapped, up to
20,000 rows. Send `dryRun: true` first: the answer says what the rows would do,
and nothing changes.

```json
{ "counts": { "new": 412, "updated": 18, "removed": 0, "removedWithSeats": 0, "seatsPlaced": 0, "parties": 38, "problems": 3 },
  "problems": [{ "row": 14, "error": "invalid_email", "field": "email" }] }
```

`row` counts from 1 within `rows`. `seatsPlaced` counts the seats a Seat column
places (see `seats` above); a seat it cannot place is a problem on its row. Then
send the same rows without `dryRun`, with an `Idempotency-Key`, to apply them.

A file matches guests by reference, else by email, in every source of the
event. A reference that belongs to a guest of another source (the API, the
dashboard) matches only when the row has that guest's email too; otherwise the
row answers `email_and_reference_differ` and the file's other rows still apply.
It changes the details only of guests that files added. For a guest
added any other way (by hand, by the API or by a partner), a row is only a
match.
`removeMissing: true` removes every guest an earlier file of this event added,
whatever that file was called, that this one leaves out, and no others. Their seats are freed first: `removedWithSeats`
counts those guests (at most 200 in one file). Send `fileName` with the rows,
and each seat the file places says so (`placedFile`).

A file that places many seats, or frees many, is applied over several calls.
A call stops once it has worked for a while and says what is left:

```json
{ "counts": { "new": 412, "updated": 0, "removed": 0, "removedWithSeats": 0, "seatsPlaced": 23, "parties": 38, "problems": 0 },
  "problems": [], "pending": { "seats": 177, "removals": 0 } }
```

While `pending` is there, send the same rows again with a new `Idempotency-Key`.
Each call matches the same guests, keeps the seats they have, and places or
frees more: `counts` says what that call did. A guest the file removes stays on
the list until their seats are freed. If a call leaves as much as the one
before, wait a minute and send the file again. `POST …/guests` answers
`pending` the same way when its `seats` take long.

## Errors

A refusal is JSON with its code in `error`, often with a `field` or another
detail beside it. The codes every route shares are on
[Errors](/server-api/errors/): `401 unauthorized`, `403 forbidden`,
`403 mode_mismatch`, `403 module_not_enabled` (here with
`"module": "guest_lists"`), `404 not_found` for the event, and the
`Idempotency-Key` codes. The guest list's own follow.

### Any guest route

| Status | Code | When |
|---|---|---|
| `404` | `guest_not_found` | No guest with that id is on the list |
| `409` | `series_seats_unavailable` | Free, move or give seats on an event series |
| `422` | `series_too_long` | The series has more than 31 dates (`max`) |
| `503` | `guest_links_unavailable` | Guest links can't be made or shown right now. Try again later |

### Add guests, import a file

| Status | Code | When |
|---|---|---|
| `400` | `idempotency_key_required` | An import without `dryRun` and without an `Idempotency-Key` |
| `422` | `invalid_request` | `guests` is not a list of at least one guest, `rows` is not a list, `removeMissing` is not true or false, or `fileName` is over 200 characters |
| `422` | `too_many_guests` | More than 1,000 guests in a call, or 20,000 rows in an import (`max`) |
| `422` | `invalid_send` | `send` is not `email` or `none` |
| `422` | `too_many_seats_to_free` | `removeMissing` would free the seats of more than 200 guests (`max`, `removedWithSeats`). Nothing is written |

A row that can't be applied is listed in `problems` with its `error` and
`field`, and the call still answers `200` or `201`.

These rows are not written:

| Code | Field | When |
|---|---|---|
| `missing_name`, `missing_email` | `name`, `email` | Left out or empty |
| `invalid_email`, `invalid_phone`, `invalid_language` | `email`, `phone`, `language` | Not an email, a phone or a language the guest page has |
| `value_too_long` | `name`, `group`, `reference`, `party`, `partner` | Over the field's length |
| `seats_allowed_out_of_range` | `seatsAllowed` | Not a whole number from 1 to 20 |
| `extra_value_too_long` | `extra` | Not an object of text, a name over 60 characters or a value over 200 |
| `too_many_extra_fields` | `extra` | More than 10 extra fields in the row, or on the list with this row's new ones |
| `invalid_dates` | `dates` | Not a list of up to 31 dates |
| `seat_twice_in_request` | `seats` | The same seat twice in the row |
| `seats_over_allowed` | `seats` | More seats than the row's own `seatsAllowed` |
| `seat_placement_unavailable` | `seats` | The row has `seats` and the event takes payment |
| `email_twice_in_request`, `reference_twice_in_request` | `email`, `reference` | The same person again in one call or file. The first row is kept |
| `email_and_reference_differ` | `reference` | The email is one guest's and the reference another's |
| `email_from_source` | `email` | The email belongs to a guest a partner added, and the row can't be matched to them |
| `party_too_large` | `party` | The party would have more than 20 people |
| `party_chooser_twice` | `partyChooser` | Two guests of one party are marked as its chooser |

These rows are written, and only the named part is left out:

| Code | Field | When |
|---|---|---|
| `seat_not_on_chart`, `seat_taken`, `seats_over_allowed` | `seats` | The seat isn't on the chart, someone has it, or it is more than the guest may have |
| `seat_outside_partner_seats` | `seats` | A partner's guest, and the seat is not one of that partner's |
| `insufficient_hosted_credits` | `seats` | Your organization is out of hosted ticket credits. This row's seats and every later row's are not placed |
| `seat_placement_unavailable` | `seats` | The booking could not be made. Send the row again |
| `series_seats_unavailable` | `seats` | `seats` on an event series |
| `not_a_series` | `dates` | `dates` on an event that is not part of a series |
| `date_not_in_series`, `date_ambiguous` | `dates` | No date of the series has that name, or two dates share that day |
| `partner_not_found` | `partner` | No partner has that id or name. The guest stays yours |
| `party_mixed_partners` | `partner` | The party's people have different partners. The row takes the chooser's |

### List, read and change a guest

| Status | Code | When |
|---|---|---|
| `422` | `invalid_status` | `status` is not one of the five values |
| `422` | `invalid_filter` | A filter can't be read (`field`), or `datesChosen` or `date` on an event that is not part of a series |
| `422` | `invalid_request` | The `PATCH` body is not an object, or has a field a guest doesn't have |
| `409` | `source_owned` | The name, email or language of a guest whose source keeps those details. No source on the list does: guests added in the dashboard, from a file, by the API or by a partner never answer it |
| `409` | `email_taken` | Another guest of the list has that email (`field`) |
| `422` | `partner_not_found` | No partner has that id or name (`field`) |
| `422` | `not_a_series`, `invalid_dates`, `date_not_in_series`, `date_ambiguous` | `dates` that can't be used (`field`) |
| `422` | A row code above | The change fails a row's own checks: the first one is in `error`, each one in `problems` |
| `409` | `guest_cancelled` | A new link for a cancelled guest |

### Groups and parties

| Status | Code | When |
|---|---|---|
| `422` | `invalid_groups` | A rule can't be read (`index`, `field`) |
| `422` | `group_twice` | A group is listed twice (`index`, `firstIndex`) |
| `422` | `unknown_seat_type` | The event has no such seat type (`seatType`) |
| `422` | `invalid_request` | The party's body can't be read |
| `422` | `party_too_small`, `party_too_large` | Fewer than 2 guests, or more than 20 |
| `422` | `party_chooser_missing` | The chooser is not one of the party (`field`) |
| `422` | `party_mixed_partners` | The guests don't all have the same partner |
| `404` | `guest_not_found`, `party_not_found` | A guest (`guestId`) or the party isn't on the list |
| `409` | `guest_cancelled` | One of the guests was cancelled (`guestId`) |
| `409` | `already_in_party` | One of them is in another party (`guestId`, `partyId`) |
| `409` | `party_member_chose` | One of them already chose seats (`guestIds`) |
| `409` | `party_changed` | One of them changed while the call ran. Read the list and try again |

### Email links and reminders

| Status | Code | When |
|---|---|---|
| `422` | `invalid_send_target` | Not exactly one of `guestIds` (1 to 1,000 ids) and `filter` |
| `422` | `invalid_filter`, `invalid_status` | A filter value can't be read (`field`) |
| `409` | `event_not_on_sale` | The event is not on sale yet, or its sales have closed |
| `409` | `guest_choice_closed` | The change deadline has passed |

### Free, move and give seats

| Status | Code | When |
|---|---|---|
| `409` | `tickets_already_used` | A ticket was used at the door (`labels`). Nothing changes |
| `409` | `guest_order_not_free` | Free: one of the guest's orders is not a free booking (`orderId`) |
| `409` | `order_not_movable` | Move: one of the guest's orders can't be moved (`orderId`) |
| `409` | `order_edit_in_progress`, `order_changed`, `order_not_cancellable`, `not_found`, `used_tickets_acknowledgement_required` | The guest's order changed while the call ran (`orderId`). Read the guest and try again |
| `409` | `guest_cancelled` | The guest was cancelled |
| `409` | `guest_has_no_seats` | Move: the guest has no seats to move |
| `409` | `seat_taken` | Someone else has one of the seats (`seats`) |
| `409` | `move_busy` | Other seat changes for the event are still finishing. Nothing moved; send it again |
| `409` | `move_expired` | The move ran out before it finished, and nothing moved. Send it again |
| `403` | `channel_access_denied` | Move: a seat belongs to a sales channel this guest can't book from (`seats`) |
| `422` | `invalid_seats` | Move: `seats` is not a list of 1 to 20 seats |
| `422` | `invalid_request` | Give seats to one guest: `seats` is not a list of 1 to 20 seats (`field`) |
| `422` | `seat_not_on_chart` | A seat isn't on the chart |
| `422` | `seat_count_differs` | Move: not as many seats as the guest has now |
| `422` | `seat_size_differs` | Move: a whole table and a single seat can't swap (`seats`) |
| `422` | `seats_over_allowed` | More seats than the guest may have |
| `422` | `seat_outside_partner_seats` | A partner's guest, and the seat is not one of that partner's |
| `422` | `insufficient_hosted_credits` | Give seats: your organization is out of hosted ticket credits |
| `422` | `seat_placement_unavailable` | Give seats: the event takes payment, or the booking could not be made |
| `422` | `invalid_seat_target`, `invalid_cursor` | Give best seats: not exactly one of `guestIds` and `filter`, or a `cursor` that is not text |

Removing a guest frees their seats first, so `DELETE …/guests/:id` can answer
the same `409` codes as freeing them. A used ticket doesn't stop a removal: that
order is kept. Give best seats doesn't refuse for one guest: it names each guest
it could not seat in `notSeated`, with a `reason`.

### Give guests to a partner

| Status | Code | When |
|---|---|---|
| `422` | `invalid_give_target` | `guestIds` is not a list of 1 to 1,000 ids, `partner` is left out, or `dryRun` is not true or false (`field`) |
| `422` | `partner_not_found` | No partner has that id or name (`field`) |

The answer's `notGiven` names each guest left as they were, with a `reason`:
`guest_not_found`, `guest_cancelled`, `seats_not_freed` or
`tickets_already_used`.

### Who can book and the guest settings

| Status | Code | When |
|---|---|---|
| `422` | `invalid_who_can_book` | `whoCanBook` is not `anyone`, `guests` or `both` |
| `422` | `who_can_book_needs_seatlayer_checkout` | The event is not on SeatLayer checkout |
| `409` | `who_can_book_locked` | The event has an order or a booked seat (`orders`, `bookedSeats`) |
| `422` | `invalid_guest_settings` | A setting can't be read (`field`) |
| `422` | `deadline_before_opening` | The change deadline is not after the opening |
| `422` | `invalid_language`, `instructions_too_long` | `guestInstructions` has a language the guest page doesn't speak, or a text over 600 characters (`language`) |
| `422` | `not_a_series` | `guestDates` on an event that is not part of a series |
| `409` | `guest_dates_locked` | `guestDates` after a guest has a seat (`bookedSeats`) |

### The guest's page

The guest page is SeatLayer's own, so you don't call its routes. The link's
exchange, `POST /pub/guest-links/exchange`, is for that page only. A session
opened from any other site gets the guest's confirm and Change seat answers
with no `orderId` and no `confirmationUrl`.

These are the codes worth knowing, for a guest who writes to you or for your
own seat map on a guest event:

| Status | Code | When |
|---|---|---|
| `401` | `guest_link_invalid` | The link is not recognised: it was replaced, or the guest was removed |
| `403` | `guest_cancelled` | The guest was cancelled |
| `403` | `guests_only` | A hold by someone who is not a guest, while the event is only for guests or guests still choose first |
| `409` | `guest_choice_closed` | The guest's choice is not open yet, or the change deadline has passed |
| `409` | `event_closed` | The event is not on sale |
| `409` | `guest_payment_unavailable` | A seat with a price on an event that takes payment |
| `409` | `seats_unavailable` | The seats could not be booked. On a series with the same seat every date, `dates` names the dates that refused |
| `409` | `seat_given_by_team` | The guest tried to change a seat your team gave, and `teamSeats` is `fixed` |
| `409` | `insufficient_hosted_credits` | Your organization is out of hosted ticket credits |
| `422` | `seats_over_allowed` | More seats than the guest, or the party, may have |
| `422` | `date_not_coming` | The link was opened for a date of the series the guest doesn't come to |

## Webhooks

Five events follow a guest list. Subscribe to them by name, like any other
event ([Manage subscriptions](/webhooks/manage-subscriptions/)). Each delivery
uses the usual signed envelope ([Webhook events](/webhooks/events/)).

| Event | Sent when |
|---|---|
| `guest.added` | A guest is added: through the API, from a file, by hand, or by a partner |
| `guest.seat_chosen` | A guest's seats are confirmed |
| `guest.seat_changed` | A guest's seats are moved |
| `guest.released` | A guest's seats are freed, and the guest can choose again |
| `guest.removed` | A guest is removed |

Updating a guest, or giving them a new link, sends no event.
`guest.seat_chosen` is sent when a guest confirms their seats, or your team
places them. `guest.seat_changed` is sent when the guest or your team moves
them, and `guest.released` when they are freed (also before a removal).

Every payload names the event, the event series the date belongs to (or
`null`), and the guest as the change left them:

```json title="guest.added"
{
  "eventKey": "ev_9f3a",
  "seriesKey": null,
  "guest": {
    "id": "gst_…",
    "reference": "CRM-48211",
    "source": { "kind": "api", "label": "API" },
    "name": "Sarah Mitchell",
    "email": "sarah.mitchell@example.com",
    "party": { "id": "pty_…", "chooser": true },
    "extra": { "Country": "Korea" }
  },
  "at": 1793664000000,
  "livemode": true
}
```

- `party` appears only for a party of two or more, `extra` only when the
  guest has extra fields, and `partner` (`{ "id": "porg_…", "name" }`) only for
  a partner's guest.
- `guest.seat_chosen` adds `seats` and `chosenBy`. `guest.seat_changed` adds
  `from`, `to` and `changedBy`. `guest.released` adds `seats`.
- `chosenBy` and `changedBy` are `guest`, `party_chooser` or `team`.
- Each seat is `{ "label", "display", "floor", "section", "row", "seat", "orderId", "orderNumber" }`.
  `label` is the seat's label on the chart; `display` is what tickets print.
  `floor` is `null`, and `orderNumber` is the order's number, or
  `null` when it has none.
- A table chair adds `table` ("T22"), with `seat` the chair's number as buyers
  read it ("7") and `row` empty: it reads "Table T22 · Seat 7". A booth adds
  `booth` ("B4"), with `seat` the booth's name. `label` stays the chair's or the
  booth's label ("T22-7").
- `guest.removed` adds `reason`, which is `removed`.

```json title="guest.removed"
{ "eventKey": "ev_9f3a", "seriesKey": null, "guest": { "id": "gst_…", "reference": null, "source": { "kind": "file", "label": "File" }, "name": "Ali Khan", "email": "ali@example.com" }, "reason": "removed", "at": 1793664000000, "livemode": true }
```

Each event is sent at least once: dedupe by `occurrenceId`. SeatLayer records
the event together with the change, so no guest is added or removed without
its event. A call you send again (with the same `Idempotency-Key`, or the same
guest again) sends no second event. If a send fails, it goes again within the
hour. A file of 20,000 new guests sends 20,000 `guest.added` events. `at` is
when the change happened, not when the event was sent.

Source: https://docs.seatlayer.io/server-api/guests/index.mdx
