Skip to main content
API Partners: building your own voucher instead of using the Headout URL? The Voucher API deep dive walks through every section of the voucher response — what each field holds, when it is null, and how it renders — so you can reproduce the voucher in your own UI.

​
Voucher URL — key points

  • Acts as the single source of truth
  • Shows booking status, ticket state, and experience instructions
  • Can be Headout-branded or re-skinned by the partner by masking out the Headout logo and contact details
  • Guides users clearly for delayed ticket generation
The voucher URL should be treated as the authoritative post-booking artifact. It reflects the latest booking and ticket state, even when tickets are generated later or booking status changes. Voucher messaging automatically adapts for delayed tickets.

​
Default customer communication

By default, Headout sends customer-facing emails directly to the booking’s primary customer using Headout branding — booking confirmation, voucher link, and ticket delivery notifications. If you have your own customer communication flow ready and want Headout to stop sending these emails, this can be disabled on a per-partner basis. Contact your Headout SPOC to opt out. Do not flip this off until your own emails (or other channels) are wired up and tested end-to-end — once opt-out is active, customers will not receive any communication from Headout, so the entire ticket-handoff is your responsibility.

​
Ticket types

How you need to handle ticket types depends entirely on which voucher flow you have implemented:
  • Using the Headout voucher URL directly — no additional handling needed. All ticket types are rendered correctly out of the box.
  • Embedding the Headout voucher in an iframe — no additional handling needed. The voucher renders correctly inside your UI.
  • Taking a screenshot of the Headout voucher to generate your own branded PDF — ⚠️ you must handle this carefully. For PDF_URL and HTML_URL ticket types, the Headout voucher renders a download button rather than the ticket inline. A screenshot will only capture the button, not the ticket. You must extract the URL from the API response and handle the download and rendering yourself.
Tickets are returned in the booking response under tickets[] once status reaches COMPLETED. Each ticket object includes a type field:

​
Bookings with no tickets

tickets can be null or []. This isn’t an error, so don’t show the guest a missing-ticket message.
  • PENDING: tickets are still being generated. Fetch the booking again when the webhook reports COMPLETED. See Ticket generation.
  • COMPLETED: the guest follows the redemption instructions. If the instructions include steps to generate or collect tickets, the guest must complete them. If they don’t, no ticket is required and the guest presents the voucher at the venue.
The Headout voucher at voucherUrl already shows the redemption instructions. If you build your own voucher from the Voucher API, always render instructions, and leave out the tickets section when ticketSection is null.

​
Multiple tickets per booking

A booking can return more tickets than it has guests, and the tickets can be of different types. Show every ticket in tickets[] on the voucher you give the customer. Do not pick one.
Do not assume one ticket per guest, or one ticket type per booking. Some experiences need more than one code for the same guest. For example, a museum entry ticket with an included audio guide can return:
  • a BARCODE ticket, scanned at the entrance
  • a QRCODE ticket, used to unlock the audio guide
A single-guest booking for that experience can return two tickets, and the guest needs both. If your voucher shows only the first ticket, the guest may be refused entry. Using the Headout voucher URL shows every ticket automatically. publicId identifies a ticket for support and lookup. It is not the code the venue scans, so do not render it as a QR code or barcode. For QRCODE and BARCODE tickets, show the image at url.
API Partners: building your own voucher? The Voucher API returns every ticket with its scannable ticketCode and the url to render, including the code for TEXT tickets, which have no image.