Skip to content

Guests API

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.

Updated View as Markdown

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/guestsSecret key

Send one guest or up to 1,000:

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:

{
  "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: 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/guestsSecret key
GET/v1/events/:key/guests/:idSecret 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/summarySecret key

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

{
  "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.
  • 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.csvSecret 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:

{
  "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-groupsSecret key
PUT/v1/events/:key/guest-groupsSecret key
{
  "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/partiesSecret key
PATCH/v1/events/:key/parties/:idSecret key
DELETE/v1/events/:key/parties/:id/members/:guestIdSecret key
DELETE/v1/events/:key/parties/:idSecret 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.
PATCH/v1/events/:key/guests/:idSecret key
DELETE/v1/events/:key/guests/:idSecret key
POST/v1/events/:key/guests/:id/linkSecret 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.

POST/v1/events/:key/guests/sendSecret key
POST/v1/events/:key/guests/remindersSecret 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:

{ "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:

{ "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 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:

{
  "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:

{ "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/releaseSecret key
POST/v1/events/:key/guests/:id/moveSecret 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:

{ "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/seatSecret key
POST/v1/events/:key/guests/:id/seatsSecret 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):

{ "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:

{ "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:

{ "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/partnerSecret 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:
{ "guestIds": ["gst_…", "gst_…"], "partner": "Brightwell Korea", "dryRun": true }
{ "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/historySecret key

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

{ "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/importSecret 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.

{ "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:

{ "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: 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
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). Each delivery uses the usual signed envelope (Webhook 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:

guest.addedjson
{
  "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.
guest.removedjson
{ "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.

Navigation

Type to search…

↑↓ navigate↵ selectEsc close