Custom API
Attendee details
Reference only. Not a decision unless cited in product/DECISIONS.md.
Attendee details
An organizer can require a name for every ticket. When the setting is on, the buyer gives a first and last name for each ticket before they pay. The organizer's guest list shows every name.
An email per ticket is optional. With an email, that person also gets their pass by email. Without one, the pass stays with the buyer under that person's name.
The setting is off by default. When it is off, checkout collects the purchaser only and nothing on this page applies.
Who this is for
Anyone who builds their own checkout on POST /v1/orders. Hosted checkout
and the Web SDK checkout collect these fields for you.
The setting
The key is attendee_details_mode. It is off or required.
- Independent event (one show): set on that event.
- Series: set on the series. Every show follows it unless that show sets its own value.
- Show in a series: follows the series, or sets its own value for that show only.
- Series pass types always follow the series value. On a single show, read
series_attendee_details_modeonGET /v1/events/{eventId}. It is null for an independent event.
How your client learns it
Read it before you draw the checkout form.
GET /v1/events/{eventId}returnsattendee_details_mode. This is the effective value: the show's own value, else the series value, elseoff.attendee_details_mode_overrideis the show's own value when it differs from following the series. It is null when the show follows the series, and always null for an independent event.GET /v1/productions/{productionId}returnsattendee_details_modefor the series. Use it for series pass types. Each entry ineventscarries that show's effectiveattendee_details_modeand itsattendee_details_mode_override.
A ticket needs an attendee when its show's effective value is required. A
pass needs one when the series value is required. Add-ons never need one.
Organizer writes:
POST /v1/eventsandPATCH /v1/events/{eventId}takeattendee_details_modeasoff,requiredor null. Null on a show in a series means follow the series. Null on an independent event means off.PATCH /v1/productions/{productionId}takesofforrequired.
What to send
Add attendees to the body of POST /v1/orders. Send one entry for every
ticket that needs one.
| Field | Rule |
|---|---|
ticket_tier_id | A ticket type in the order |
seat_id | Reserved seats only. A seat in the order. Else null |
first_name | 1 to 60 characters after trimming |
last_name | 1 to 60 characters after trimming |
email | Optional. A valid email, at most 254 characters |
Leave email out, or send null or a blank string, when the buyer gave none.
A blank email is never an error. An email that is sent must be valid. Emails
are stored trimmed and lower-cased.
Example: two ticket types
Two General tickets and one VIP ticket. Three tickets, so three entries. Sam has no email, so Sam's pass stays with the buyer.
{
"venue_id": "VENUE_ID",
"venue_event_id": "EVENT_ID",
"payment_method": "card",
"lines": [
{
"item_type": "ticket",
"ticket_tier_id": "GENERAL_TIER_ID",
"quantity": 2
},
{ "item_type": "ticket", "ticket_tier_id": "VIP_TIER_ID", "quantity": 1 }
],
"purchaser_email": "buyer@example.com",
"purchaser_name": "Ana Diaz",
"attendees": [
{
"ticket_tier_id": "GENERAL_TIER_ID",
"first_name": "Ana",
"last_name": "Diaz",
"email": "ana@example.com"
},
{
"ticket_tier_id": "GENERAL_TIER_ID",
"first_name": "Sam",
"last_name": "Lee"
},
{
"ticket_tier_id": "VIP_TIER_ID",
"first_name": "Kim",
"last_name": "Park",
"email": "kim@example.com"
}
]
}
Example: reserved seats
Each seat is its own line with quantity 1. Name the seat on the attendee
too. Ana gets her own pass email. Sam's pass stays with the buyer.
{
"venue_id": "VENUE_ID",
"venue_event_id": "EVENT_ID",
"payment_method": "card",
"seat_hold_owner": "HOLD_OWNER_ID",
"lines": [
{
"item_type": "ticket",
"ticket_tier_id": "TIER_ID",
"seat_id": "SEAT_A_ID",
"quantity": 1
},
{
"item_type": "ticket",
"ticket_tier_id": "TIER_ID",
"seat_id": "SEAT_B_ID",
"quantity": 1
}
],
"purchaser_email": "buyer@example.com",
"attendees": [
{
"ticket_tier_id": "TIER_ID",
"seat_id": "SEAT_A_ID",
"first_name": "Ana",
"last_name": "Diaz",
"email": "ana@example.com"
},
{
"ticket_tier_id": "TIER_ID",
"seat_id": "SEAT_B_ID",
"first_name": "Sam",
"last_name": "Lee"
}
]
}
A private-link order (POST /v1/orders/allocation) takes the same
attendees field. Send one entry per unit in quantity.
Matching rules
- Entries for the same
ticket_tier_idare matched in array order. The first entry is the first ticket of that type, the second entry is the second ticket, and so on. - A reserved-seat ticket is matched by
seat_id. - The count must be exact. Two tickets of a type need two entries for that type.
- Add-on lines never take attendees.
- A cart can mix shows. Send entries only for the tickets whose show requires them.
- If nothing in the order requires details,
attendeesis ignored and not stored. - Ids are matched case-insensitively.
- On an idempotent replay the entries are checked against the tickets the stored order holds.
Errors
Both are HTTP 400. No inventory is reserved. message is a sentence you can
show the buyer.
attendee_details_required: a ticket that needs an attendee has none, or
the count for a ticket type or seat is wrong.
{
"success": false,
"error": "attendee_details_required",
"message": "Enter a first and last name for every ticket.",
"details": [
{
"ticket_tier_id": "GENERAL_TIER_ID",
"seat_id": null,
"expected": 2,
"received": 1
}
]
}
attendee_details_invalid: a value is invalid, or an entry names a ticket
type or seat that is not in the order. index is the position in the
attendees array you sent. field is first_name, last_name, email,
ticket_tier_id or seat_id. email is reported only when an email was
sent and is not valid.
{
"success": false,
"error": "attendee_details_invalid",
"message": "Check the name and email entered for each ticket.",
"details": [
{
"index": 1,
"field": "email",
"ticket_tier_id": "GENERAL_TIER_ID",
"seat_id": null
}
]
}
After the buyer pays
- A ticket named with an email is issued to that person. They get their own pass email with a link to their Live Pass.
- A ticket named without an email stays with the buyer. It carries the attendee's name and is delivered in the buyer's email.
- The buyer's confirmation email always contains every pass of the order, each labelled with its attendee's name, plus the order totals. This includes passes that were also sent to other people. If the buyer mistyped an email, they can transfer that pass to the right person from their own email.
- Amounts are shown only to the buyer. An attendee's email does not show what was paid.
- The order read (
GET /v1/orders/{orderId}), the create response and the verify response returnattendeesto the buyer who owns the order. It is an empty array when the order collected none.emailis null on an entry that has none. - Pay at the door (cash at entry) orders name attendees at checkout too. The names go on the tickets when the door collects the cash.
- Send
purchaser_emailon any order that names attendees, private-link orders included. Without it the create is refused with HTTP 400purchaser_email_required_for_attendees, because the buyer's email holds every pass and only the buyer sees the amounts. - Cancellation and change notices go to the buyer only for now. The notice asks the buyer to pass it on to the people they bought for.
See Ticket delivery for what the emails look like.
Transfer
A person who accepts a transferred ticket must give their name when the event requires attendee details, or when the ticket carries a name the buyer gave at checkout (even if the organizer has since turned the setting off; Agent default pending ENG-733 Q-7). The guest list then always shows the person who holds the ticket.
GET /v1/ticket-transfer-claims/{tokenOrShareCode}returnsattendee_name_required.- When it is true, send both
guest_first_nameandguest_last_nameon the claim. - A claim without both is refused with HTTP 400
attendee_name_required. Nothing is claimed. Ask for the name and send the claim again. - A name sent on any claim replaces both parts of the previous holder's name. A part you leave out is cleared, never kept from the previous holder (Agent default pending ENG-733 Q-8).
See Transfer.
Tickets issued by staff
Tickets that staff issue are exempt. Comps, door sales and internal
operations orders do not ask for attendee details, even when the setting is
required.
Privacy
- Show this notice next to the fields that collect attendees:
Add an email to send someone their pass. Without one, the pass stays with you. The organizer sees these names and emails. - The buyer's marketing consent covers the buyer only. An attendee is never added to a marketing list because the buyer agreed to one.
- The
Ticketing by AXYN · Privacydisclosure from Headless API still applies.
Related
| Page | Role |
|---|---|
| Get started | First API sale |
| Ticket delivery | Buy vs see; email |
| Transfer | Send a pass / claim |
| Errors | Error body and codes |
| Full API list | Machine contract |