Booking Questions (v1.3)

v1.3

Some products require specific guest information before a booking can be confirmed. The Booking Questions capability provides a structured, typed mechanism for collecting this data - with localized question text, dependency rules, PII flags, and clearly defined phases for when answers must be submitted.

Where Questions Come From

Booking Questions are returned as part of the Rate object. To retrieve Booking Questions, you must use the bookingQuestions=true query parameter.

If the Rate has associated questions, the response includes a bookingQuestions[] array. Always check for this array when building checkout flows. Questions can be added to a Rate by the Supplier at any time, so do not assume a Rate has no questions based on past behavior.

Filtering by Language

Add the locale= parameter to return only text in specific languages. Accepts a comma-separated list of BCP 47 language tags:

xxxxxxxxxx

GET /v1.3/suppliers/{id}/products/{id}bookingQuestions=true&locale=en-US,es-ES,de-DE

If locale= is omitted, all available language variants are returned.

LocalizedTextSet

Content fields use the LocalizedTextSet pattern to support multi-lingual and multi-format content.

LocalizedText

Represents a single text entry in a specific language and format. If a supplier provides this object, all its internal fields (text, format, and locale) are mandatory.

LocalizedTextSet

A collection of LocalizedText objects. While a set can contain multiple entries to accommodate various locales and formats, each locale + format combination must be unique within a single LocalizedTextSet. The system will reject duplicate combinations from the Supplier side.

xxxxxxxxxx

"description": [

  {

    "text": "Join us for a 3-hour kayaking tour around the Barcelona coastline.",

    "locale": "en",

    "format": "plain"

  },

  {

    "text": "Únete a nosotros para un recorrido en kayak de 3 horas por la costa de Barcelona.",

    "locale": "es",

    "format": "plain"

  }

]

Booking Questions Object Field

Answer Types

For choice and multiple_choice types, use the answer value from the matching AnswerOption - not the display label. The label is for rendering to the guest; the answer is what you submit.

Scope

scope defines who an answer applies to:

For scope guest, collect a separate answer for each traveler in the booking and submit them individually. A common example is dietary requirements or passport details, which differ per guest.

Phase

phase defines when an answer must be submitted:

hold-phase questions are typically used when the answer affects what inventory is reserved, for example, a meal choice that determines which catering block is allocated. booking-phase questions are for information that only needs to be finalized at the time of purchase, for example, a transfer preference or a language selection.

Conditional Questions

A question may carry a dependency field that makes it conditional on another question's answer. Only render and submit a dependent question when its condition is satisfied.

xxxxxxxxxx

"dependency": {

  "questionId": "q_001",

  "answer": true

}

This means: only show this question if question q_001 has been answered with true. If the condition is not met, do not include the question's questionId in the answers array.

Dependencies only reference one level - a question depends on at most one other question. Check whether the referenced question is itself conditional before assuming it will always be present.

PII Handling

Questions with pii: true collect Personally Identifiable Information, for example, passport numbers, birth dates, physical measurements, or health data. Apply the following when handling PII answers:

• Do not log PII values in application or server logs
• Do not cache PII answers beyond what is operationally required to complete the booking
• Store PII in compliance with your applicable data privacy regulations (GDPR, CCPA, or equivalent)
• Treat PII fields in your internal data model with appropriate access controls

Submitting Answers

Answers are submitted as an answers[] array, a list of { questionId, answer } pairs. Include this array in the Hold or Booking request body, depending on each question's phase.

In the Hold Request (phase: hold)

xxxxxxxxxx

POST /v1.3/holds

{

  "hold": {

    "id": "f7393cf6-097d-443a-919a-ae3ca518e040",

    "partnerId": "your-partner-id",

    "items": [...],

    "answers": [

      { "questionId": "q_123", "answer": "Window seat" },

      { "questionId": "q_456", "answer": true },

      { "questionId": "q_789", "answer": "2026-06-20" }

    ]

  }

}

Required hold-phase questions (required: true) will cause the Hold request to fail if omitted.

Optional questions (required: false) should still be rendered and offered to the guest - omit them from the payload only if the guest left them blank.

In the Booking Request (phase: booking)

xxxxxxxxxx

POST /v1.3/bookings

{

  "booking": {

    "holdId": "f7393cf6-097d-443a-919a-ae3ca518e040",

    "customer": {...},

    "items": [...],

    "answers": [

      { "questionId": "q_101", "answer": "Gluten-free" },

      { "questionId": "q_102", "answer": "Spanish" }

    ]

  }

}

Required booking-phase questions will cause the Booking request to fail if omitted.

Guest-Scoped Answers (scope: guest)

For questions with scope: guest, submit one answer per traveler. The exact structure for guest-scoped answers depends on the Supplier integration - refer to the API Reference for the traveler-level answer placement specific to your Supplier's configuration.

Full Example Flow

1. GET /rates/{id} → Rate response includes bookingQuestions[]

2. Review questions:

• q_001: scope=booking, phase=hold, type=boolean, required=true

  • text: "Do you require a vegetarian meal?"

• q_002: scope=booking, phase=hold, type=choice, required=false

  • text: "If yes, which preference?"
  • dependency: { questionId: "q_001", answer: true }
  • options:
    • { label: "Vegan", answer: "vegan" },
    • { label: "Lacto-vegetarian", answer: "lacto" }

• q_003: scope=guest, phase=booking, type=text, required=true, pii=true

  • text: "Passport number"

3. POST /holds → answers:

• { questionId: "q_001", answer: true },
• { questionId: "q_002", answer: "vegan" } (q_003 is phase=booking, so omit from Hold)

4. POST /bookings → answers:

• { questionId: "q_003", answer: "AB1234567" } (per traveler, if scope=guest)