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
/v1/events/:key/guestsSecret keySend 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
/v1/events/:key/guestsSecret key/v1/events/:key/guests/:idSecret keyReading 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,chosenorcancelled, ornot_chosenfor invited or opened;group,source(asrc_…id or a kind such asapi) andparty(apty_…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, writtenH-14-22orH 14 22;partner: a partner’s id (porg_…),anyfor guests given to any partner, ornonefor your own.
A filter that isn’t 1, 0 or (for backInSource) pending answers
422 invalid_filter with the field.
Count the list
/v1/events/:key/guests/summarySecret keyThe 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;
totalincludes the cancelled ones. changedSeat,inParty,seatGivenByTeamandnotBackInSourceuse the same rules as thechanged,inParty,givenByTeamandbackInSourcefilters, so each count matches the list its filter opens.- No guest waits to go back to a source:
notBackInSourceis 0, and every source’stakesSeatsBackis false. groupsleaves out guests with no group. Each group’ssourcesare the sources its guests came from (cancelled ones included, removed ones not), in the order ofsources, labelled as each guest’ssourceis.seatscounts seats, not guests.chosenis the seats guests hold now.toChooseis the seats the guests who haven’t chosen yet may still choose: each guest’s own number, else their group’s, else 1.seatChangesadds up every seat change;changedSeatis how many guests made them. Each group’schosenis its guests who have chosen.lastReminderAtis 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,emailPaceand, after a send that ended early,emailsNotSent: see The daily email allowance. - Every source’s
backandretryingare 0, and itslastSyncAtis null. linkHostis the host guest links are built on today. It is there when the list is empty too.
Download the guest list
/v1/events/:key/guests.csvSecret keyThe 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.
Sourceis 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,
Partnercomes right afterSource: the partner’s name, or empty for your own guests. A list without partners has noPartnercolumn, so its file reads exactly as before. Seat choiceis “Chose”, “Not yet” or “Cancelled”.Partyis 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 bynames who chose the seats: the guest, or their party’s chooser. It is empty for seats your team gave.Seat given byis set only then: “File · vip-seats.xlsx”, “API”, or “You” for the dashboard.- A guest’s seats next to each other read
7–8inSeat. Seats in more than one row are listed row by row, separated by;. Chose onis2027-02-22 09:03in the event’s time zone.Back in sourceis “–” for guests added by hand, from a file or by the API, and empty for a guest a partner added.Personal linkis 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 with403 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": "배지를 지참하세요." }
}whoCanBookcan change until the event’s first order (a buyer paying included) or booked seat. After that it answers409 who_can_book_locked, andwhoCanBookLockedis true.- A change of
whoCanBookor the deadline reaches the booking page at once. Withboth, the public sale opens atchangeDeadline; without one it stays closed, so guests never lose their head start. seatChoicechanges only the keys you send;nullclears one. A deadline must come after the opening (422 deadline_before_opening).guestLinks.senderisseatlayerororganizer;teamSeatsisfixedorchangeable;parties.chooseTogetheris true or false.guestInstructionsholds one text per language, up to 600 characters, keyed by any of the 43 languages the guest page speaks (en,ko,zh-Hans, …). APATCHreplaces 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_enabledwhen SeatLayer has turned guest lists off for your organization, except settingwhoCanBookback toanyone. whoCanBookLockedonly reads; aPATCHignores it.
Where groups sit
/v1/events/:key/guest-groupsSecret key/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" }]
}PUTtakes{ "groups": [...] }and replaces every rule of the event in one write. A group it leaves out has no rule afterwards.groupmatches the guests’ group in any case. Listing a group twice answers422 group_twice.seatTypesare the event’s seat types (its chart categories); the answer lists them inseatTypes. A key the event doesn’t have answers422 unknown_seat_type. An empty list means any open seat, like a guest in no group.seatsEachis 1 to 20: what each guest of the group chooses, unless the guest has their ownseatsAllowed.opensAtis the group’s wave;nullwaits forseatChoice.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
/v1/events/:key/partiesSecret key/v1/events/:key/parties/:idSecret key/v1/events/:key/parties/:id/members/:guestIdSecret key/v1/events/:key/parties/:idSecret keyA 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.
POSTtakes{ "guestIds": [...], "chooserId": "gst_…" }and answers201 { "id", "chooserId", "guestIds" }. Sending the same party again answers it with200.- It refuses a guest who already chose a seat (
409 party_member_chose, withguestIds), is in another party (409 already_in_party) or was cancelled (409 guest_cancelled). Fewer than 2 or more than 20 guests answer422 party_too_smallorparty_too_large; a chooser outside the list,422 party_chooser_missing. PATCHtakes{ "chooserId" }: another person in the party chooses.DELETE …/members/:guestIdtakes one person out; they choose alone. When the chooser leaves, the next person chooses. A party left with one person ends.DELETE …/parties/:idends 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_enabledwhen 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
/v1/events/:key/guests/:idSecret key/v1/events/:key/guests/:idSecret key/v1/events/:key/guests/:id/linkSecret keyPATCH 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
/v1/events/:key/guests/sendSecret key/v1/events/:key/guests/remindersSecret keyBoth 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 }queuedis the guests emailed now.waitingis 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.skippedis the guests you asked for that get no email. WithguestIds, 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 afilter, 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 …/sendemails 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 …/remindersemails 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) andlastReminderAt. - Send an
Idempotency-Keyto retry safely: the same key answers the first call again and sends nothing more. - Both answer
403 module_not_enabledwhen 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 }
}perDayis the most guest emails your organization sends in one UTC day, andtodayLeftis what is left of it.dayis the start of that UTC day.- Emails go in passes: at most
perPasseverypassMsmilliseconds. Other senders share a pass, so read any finish time you work out as an estimate. startis when sending can start: now, or later when no email can go yet.paused: truemeans 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.
emailPaceis left out when it can’t be read. linksWaitingcounts guests whose link goes out by itself later: when their seat choice opens, or as the allowance allows.sendsWaitingcounts guests a send or a reminder still has to email who are not inlinksWaiting. 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 } }reasonischoice_closed(the change deadline passed),sales_closed(the event’s sales closed for good),lifetime(it was still waiting 35 days on) orcancelled_by_staff(SeatLayer support stopped it).kindislinkorreminder.countis 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
/v1/events/:key/guests/:id/releaseSecret key/v1/events/:key/guests/:id/moveSecret keyPOST …/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"] }seatsis 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
/v1/events/:key/guests/seatSecret key/v1/events/:key/guests/:id/seatsSecret keyPOST …/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_chosenis 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
nextis not null, call again with the same body and"cursor": next. reasonisnot_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) orseat_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
/v1/events/:key/guests/partnerSecret keyAgencies, 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:
partneron 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 warningpartner_not_found: the row is still written, and the guest stays yours. Left out or empty, nothing changes.partneronPATCH …/guests/:id: an id, a name, ornullto 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: truesays 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. nulltakes guests back. Giving answers403 module_not_enabledwhen 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.
guestDatesonPATCH /v1/events/:key(any date) is the list’s Dates card:attendanceisevery(everyone comes every date) orown(each guest’s own dates; none given means every date).seatiseach(a seat for each date) orsame(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.dateson a guest you add or change: each a date’s event key, or a dayYYYY-MM-DDwith one date that day. A name that is no date of the series isdate_not_in_series(ordate_ambiguousfor a day with two dates); null or[]is every date.- Each guest reads
dates,everyDate,seatsByDate(each date they come, with their seats there) anddatesChosen:all,someornone. A guest ischosenonly once every date they come has seats. GET …/gueststakesdatesChosen=all|some|noneanddate=(guests who come that date). The summary addsseries: each date with who comes and who has seats there, and thedatesChosencounts.- The guest’s link opens one date at a time: on SeatLayer’s guest page, the
link’s exchange (
POST /pub/guest-links/exchange) takesdate, and answersserieswith the dates the guest comes and their seats there. Witheach, each date is held and confirmed on its own key. Withsame, 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_unavailablewith thedatesthat refused). Either way each date gets its own order and ticket, andguest.seat_chosennames that date. - Removing a guest frees their seats on every date:
guest.releasedis 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_unavailableon a series. A file’s Seat column, orseatsonPOST …/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
/v1/events/:key/guests/:id/historySecret keyEverything 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"] }
] }kindisadded,link_sent,link_new,opened,chosen,changed,released,removedorgroup_changed.group_changedis a move to another group. It hasfromGroupandtoGroup, and either isnullwhen the guest had no group or has none now.link_sentis each time SeatLayer emailed the link. A reminder hasreminder: true.byisguest,party_chooser,team(someone signed in),api(a secret key) orfile(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 …/moveandDELETE …/guests/:idanswerguest_order_paidwith theorderId. A full refund puts the guest back to choosing, and sendsguest.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
/v1/events/:key/guests/importSecret keyYour 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 |
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). 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:
{
"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
}partyappears only for a party of two or more,extraonly when the guest has extra fields, andpartner({ "id": "porg_…", "name" }) only for a partner’s guest.guest.seat_chosenaddsseatsandchosenBy.guest.seat_changedaddsfrom,toandchangedBy.guest.releasedaddsseats.chosenByandchangedByareguest,party_chooserorteam.- Each seat is
{ "label", "display", "floor", "section", "row", "seat", "orderId", "orderNumber" }.labelis the seat’s label on the chart;displayis what tickets print.floorisnull, andorderNumberis the order’s number, ornullwhen it has none. - A table chair adds
table(“T22”), withseatthe chair’s number as buyers read it (“7”) androwempty: it reads “Table T22 · Seat 7”. A booth addsbooth(“B4”), withseatthe booth’s name.labelstays the chair’s or the booth’s label (“T22-7”). guest.removedaddsreason, which isremoved.
{ "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.