Skip to content

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_mode on GET /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} returns attendee_details_mode. This is the effective value: the show's own value, else the series value, else off. attendee_details_mode_override is 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} returns attendee_details_mode for the series. Use it for series pass types. Each entry in events carries that show's effective attendee_details_mode and its attendee_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/events and PATCH /v1/events/{eventId} take attendee_details_mode as off, required or null. Null on a show in a series means follow the series. Null on an independent event means off.
  • PATCH /v1/productions/{productionId} takes off or required.

What to send

Add attendees to the body of POST /v1/orders. Send one entry for every ticket that needs one.

FieldRule
ticket_tier_idA ticket type in the order
seat_idReserved seats only. A seat in the order. Else null
first_name1 to 60 characters after trimming
last_name1 to 60 characters after trimming
emailOptional. 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_id are 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, attendees is 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 return attendees to the buyer who owns the order. It is an empty array when the order collected none. email is 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_email on any order that names attendees, private-link orders included. Without it the create is refused with HTTP 400 purchaser_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} returns attendee_name_required.
  • When it is true, send both guest_first_name and guest_last_name on 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 · Privacy disclosure from Headless API still applies.
PageRole
Get startedFirst API sale
Ticket deliveryBuy vs see; email
TransferSend a pass / claim
ErrorsError body and codes
Full API listMachine contract