Skip to main content

​
Reference data

Supported language codes for API localization.
CodeLanguage
ENEnglish
ESSpanish
FRFrench
ITItalian
DEGerman
PTPortuguese
NLDutch
PLPolish
KOKorean
JAJapanese
ZH_HANSChinese (Simplified)
ZH_HANTChinese (Traditional)
ARArabic
DADanish
NONorwegian
RORomanian
RURussian
SVSwedish
TRTurkish
If a translation is not available for the requested language, content falls back to English (EN).
Supported cities are returned dynamically by the City API. This list may change over time, so always handle cities dynamically rather than hardcoding values.See: List Cities · List Collections · List Categories · List Subcategories · List Products
Supported media types in product details.
TypeDescription
IMAGEImage media
VIDEOVideo media
PDFPDF document
See: List Products · Get Product
Supported product types within product details.
Type
TOUR
ACTIVITY
EVENT
ATTRACTION
TRANSFER
AIRPORT_TRANSFER
ADD_ON
See: List Products · Get Product
Pricing types used in product listings. The price type determines how inventory pricing is structured and how booking requests must be formed.
TypeDescription
PER_PERSONPrice is charged per individual. Inventory returns person types (e.g., ADULT, CHILD, SENIOR) each with their own price point. The booking request must include one guest object per person with a valid personType.
PER_GROUPA single price covers a group. Inventory returns pricing tiers by group size (e.g., 1-4 people = 100,5−7=100, 5-7 = 120, 8-10 = $150). The booking request does not require a personType per guest.
See: List Products · Get Product
Defines how a variant’s start time and duration are structured. This affects how startDateTime and endDateTime in inventory slots should be interpreted, and what kind of date/time picker to show the user.
TypeDescriptionExample
FIXED_START_FIXED_DURATIONStarts at a precise time and lasts a fixed duration. startDateTime = actual start, endDateTime = actual end.A Broadway show at 7:00 PM lasting 2.5 hours
FIXED_START_FLEXIBLE_DURATIONStarts at a fixed time but the customer stays as long as they wish. startDateTime = entry time, endDateTime = venue closing time.An observation deck visit with a timed entry slot
FLEXIBLE_START_FIXED_DURATIONCustomer can arrive any time during operating hours but the experience lasts a fixed duration once started. startDateTime = opening time, endDateTime = latest allowed entry.A hot-air balloon ride (1 hour) during a morning window
FLEXIBLE_START_FLEXIBLE_DURATIONOpen entry and open-ended duration — customer arrives and leaves whenever they want within the day. startDateTime = opening time, endDateTime = closing time.A theme park day pass
For FLEXIBLE_START_* types, startDateTime represents the opening time of the venue, not a specific entry time for the customer.
See: List Inventory
Availability status within inventory slots. Determines whether and how many bookings can still be made for a given slot.
StatusDescription
LIMITEDLimited spots remaining — check the remaining field for the exact count before booking.
UNLIMITEDNo cap on bookings — the slot can be booked any number of times.
CLOSEDThe slot is unavailable and cannot be booked.
See: List Inventory
Inventory selection types for booking interfaces.
TypeDescription
NORMALStandard selection interface
SEATMAPSeat map selection interface
See: List Inventory
Person types valid for booking variants.
Type
ADULT
CHILD
INFANT
SENIOR
GENERAL
STUDENT
YOUTH
Additional types such as RESIDENT, NON_EUR_CHILD, etc. may appear dynamically.
See: List Inventory · Create Booking · Get Booking — see Pax Types

​
Input fields

Input field types for variant-specific customer information.
FieldDescription
NAMECustomer name
EMAILEmail address
PHONEPhone number
ADDRESSAddress information
AGE_Age-related fields
COUNTRY_Country information
DATE_OF_BIRTH_Date of birth
DROP_OFF_LOCATION_Drop-off location
FULL_NAME_Full name fields
GENDER_Gender information
IDENTITY_DOCUMENT_DETAILS_ID document details
LANGUAGE_Language preference
NATIONALITY_Nationality
PASSPORT_DETAILS_Passport information
PHYSICAL_INFORMATION_-_HEIGHT_Physical characteristics
PICK_UP_DETAILS_Pickup information
PICKUP_LOCATIONPickup location
CUSTOM_*Custom dynamic fields provided by supply partners
Many more values may appear dynamically from supply partners. Always handle unknown values gracefully.
See: Get Product · List Inventory — see Input Fields
Data types an input field can have. Use this to drive form validation and rendering on your end.
Data TypeDescriptionValidation
STRINGFree-form text (e.g., John Doe)Apply regex, minLength, maxLength from the validation object if present
ENUMOne of a predefined set of string literals (e.g., MALE, FEMALE, OTHER)Value must be one of the entries in validation.values (always string[] for this type)
BOOLBoolean flag — submit as the string "true" or "false"—
INTWhole-number value (e.g., 25)Apply minValue, maxValue from validation if present
FLOATDecimal number (e.g., 25.50)Apply minValue, maxValue from validation if present
LOCATIONPickup or drop-off location. When validation.values is non-empty, items are predefined location objects (not strings) — the customer must select one. When validation.values is null, accept a free-form address string.See predefined location object shape below
There is no dedicated DATE dataType. Date and date-time fields (such as DATE_OF_BIRTH_*) are submitted as STRING, with the expected format enforced by validation.regex on the field.

​
validation.values — Polymorphic Field

The type of items in validation.values depends on the field’s dataType:
  • ENUM — validation.values is string[]. The submitted value must be an exact match. 
    "values": ["VEGETARIAN", "VEGAN", "GLUTEN_FREE", "NONE"]
  • LOCATION with predefined options — validation.values is an array of location objects. Render these as a dropdown and submit either the selected object’s id or its displayName as the field value. 
    "values": [
  {
    "id": 24698,
    "latitude": 36.112946,
    "longitude": -115.176507,
    "address": "3600 S Las Vegas Blvd, Las Vegas, NV 89109, USA",
    "displayName": "Bellagio",
    "timingConfig": {
      "startTime": "10:30",
      "endTime": "11:00",
      "minPeriod": null,
      "maxPeriod": null
    },
    "note": null
  }
]
  • All other types — validation.values is null.

​
Predefined location object fields

FieldTypeDescription
idintegerUnique identifier for this location. Submit this value or the location’s displayName as the field value when creating a booking.
latitudenumberLatitude of the pickup/drop-off point in decimal degrees.
longitudenumberLongitude of the pickup/drop-off point in decimal degrees.
addressstringFull street address of the location.
displayNamestringShort human-readable label for display in a dropdown (e.g., "Bellagio").
timingConfig.startTimestring | nullEarliest pickup time for this location (HH:mm format). Null if no restriction.
timingConfig.endTimestring | nullLatest pickup time for this location (HH:mm format). Null if no restriction.
timingConfig.minPeriodinteger | nullMinimum notice required for this pickup in minutes. Null if no restriction.
timingConfig.maxPeriodinteger | nullMaximum advance booking window in minutes. Null if no restriction.
noteobject | nullAdditional instruction for this pickup location. Null if no note. Contains content (string) and language (language code).
See: Get Product · List Inventory

​
Booking lifecycle

Cashback value types for promotional offers. The value field on the cashback object should be interpreted according to this type.
TypeDescriptionExample
ABSOLUTEFixed cashback amount in the product’s native currencyvalue: 10 → customer receives $10 cashback
PERCENTAGECashback as a percentage of the total variant pricevalue: 10 → customer receives 10% of the booking total as cashback
See: List Products · Get Product
Booking lifecycle statuses. PENDING and COMPLETED can still move to CANCELLED — e.g. customer cancellation within policy, or Headout-initiated cancellations like venue closures.
StatusDescription
UNCAPTUREDBooking entry has been created but payment has not been captured. Does not lock inventory or price. Never sent via webhook.
PENDINGPayment captured. Booking is confirmed with the supplier — show it to the customer as confirmed. Ticket generation may still be in progress.
COMPLETEDTicket has been generated and is available in the tickets array.
CANCELLEDBooking was cancelled — by the partner, customer, or Headout (e.g. venue closures). Reachable from PENDING or COMPLETED.
FAILEDCapture was attempted but rejected. The booking cannot move to any other status — create a new booking if the customer still wants to proceed.
CAPTURE_TIMEDOUTUNCAPTURED booking was not captured within 1 hour and can no longer be captured. The booking cannot move to any other status — create a new booking if the customer still wants to proceed.
Transitions
  • From UNCAPTURED: remains UNCAPTURED until captured, → PENDING on successful capture, → FAILED on rejected capture, → CAPTURE_TIMEDOUT if no capture within 1 hour.
  • From PENDING: → COMPLETED when the ticket is generated, → CANCELLED if cancelled before fulfilment.
  • From COMPLETED: → CANCELLED if cancelled after fulfilment (e.g. venue closure).
  • From FAILED or CAPTURE_TIMEDOUT: no further transitions.
See: Create Booking · List Bookings · Get Booking · Update Booking · Create Webhook
Ticket delivery formats returned in the tickets array of a booking.
TypeDescription
PDF_URLURL to a downloadable PDF ticket
HTML_URLURL to an HTML ticket page
QRCODEQR code data for scanning at the venue
BARCODEBarcode data for scanning at the venue
TEXTPlain text ticket information
APPLE_WALLET_URLURL to add ticket to Apple Wallet
GOOGLE_WALLET_URLURL to add ticket to Google Wallet
See: Get Booking
Defines who a given input field should be collected for. Use this to drive form rendering — only show and collect fields appropriate for each level.
LevelDescriptionTypical Fields
PRIMARY_CUSTOMERCollected once, from the lead guest only. There is always exactly one primary customer per booking. Submit inside the isPrimary: true customer’s inputFields.Name, email, phone, address
ALL_CUSTOMERCollected from every guest in the booking, including the primary customer. Submit inside every customer’s inputFields.Weight, height, meal preference, date of birth
BOOKINGApplies to the booking as a whole — not tied to any individual guest. Collected once regardless of pax count. Submit in the booking-level variantInputFields array, not inside any customer object.Language preference, group name on the reservation, special accessibility request
level (who you collect from) and dataType (what shape the value takes) are independent axes. A BOOKING-level field can be any dataType, and a LOCATION dataType field can be at any level.
See: Get Product · List Inventory
Permitted cancellation reasons for partner cancellation requests.
ValueDescription
TICKETS_NOT_RECEIVEDTickets or voucher not received by the customer
CHANGE_OF_TRAVEL_PLANSCustomer changed travel plans
MODIFY_EXISTING_RESERVATIONCustomer wants to modify an existing reservation
FOUND_CHEAPER_OPTION_ELSEWHERECustomer found a cheaper alternative
OTHEROther reason not listed above
See: Cancel Booking