Booking questions and answers – Bókun developer documentation

During checkout, the customer may need to answer questions provided by the product supplier, the seller, and/or the payment provider. The JSON schema for questions and answers is described below.

Answers can optionally be saved for a shopping cart before checkout. But normally, the questions are retrieved with the checkout options, and answered in the checkout request.

What information is required at the time of booking?

This is very dependent on each product configuration. Note that you can always generate the list of questions dynamically at the time of booking. But if you need to know the questions before the time of booking (for example if you are setting this up when you are mapping products from your platform to Bokun), then you need to look at the product configuration.

In general, the information you may be asked to provide falls into the following categories:

Main contact may be required to provide answers to some "standard questions".

This is configured on the product level.

Have a look at the mainContactFields field on the product, which contains all the standard questions configured for the product. Each field in the list specifies whether answer is required.

You can specify answers in mainContactDetails

Each passenger/participant may be required to provide answers to some "standard questions".

This is configured on the product level.

Have a look at the passengerFields field on the product, which contains all the standard questions configured for the product. Each field in the list specifies whether answer is required.

You can specify answers in activityBooking.passengers[].passengerDetails

The product may define a set of "booking questions". These may be asked per booking, per passenger/participant, or per extra that is booked.

This is configured on the product level.

Booking questions may be triggered by what you book. They can be triggered by:

A certain pricing category being booked

A certain rate being booked

A certain extra being booked

Have a look at the bookingQuestions field on the product, which lists all possible questions that may be asked, along with what triggers each question.

If you book pick up, you will be required to specify where to pick up from. Some products allow free text entry, but most require you to select from a predefined list. Same applies for drop off.

For information about whether a product offers pick up, and whether it accepts free text / custom entry, see here: Pick up: selection & pricing

For information on how to book pick up, and provide pick up info, see here: Booking pick up

The "standard questions" mentioned above are following:

title,

firstName,

lastName,

personalIdNumber,

email,

phoneNumber,

nationality,

gender,

organization,

passportId,

passportExpiry,

address,

dateOfBirth

Questions schema

The questions schema has the following structure:

Note that there is a questions object for each product booking. Following is an example that shows the structure for activity bookings:

Further description of the structure:

mainContactDetails: Personal and contact details for the main contact of the booking

activityBookings: Container for questions per activity booking.

bookingId: The ID of the activity booking

questions: Any per-booking questions for the booking

pickupQuestions: Any questions relating to pick up (if booked). For example, if an airport was selected for pick up, we may ask about flight number.

dropoffQuestions: Any questions relating to drop off (if booked). For example, if an airport was selected for drop off, we may ask about terminal.

passengers: Container for questions per passenger booked.

bookingId: The ID of the pricing category booking.

passengerDetails: Personal details for the passenger.

questions: Any per-passenger questions for the booking.

extras: Container for questions per extra booking.

bookingId: The ID of the extra booking.

questions: Any per-extra questions for the booking.

accommodationBookings: Container for questions per accommodation booking

bookingId: The ID of the accommodation booking

questions: Any per-booking questions for the booking

rooms: Container for questions per room booked.

bookingId: The ID of the room booking.

guests: Container for questions per guest.

personId: The ID of the guest.

details: Personal details for the guest.

questions: Any per-room questions for the booking.

extras: Container for questions per extra booking.

bookingId: The ID of the extra booking.

questions: Any per-extra questions for the booking.

rentalBookings: Container for questions per rental booking.

bookingId: The ID of the rental booking

questions: Any per-booking questions for the booking

items: Container for questions per item booked.

bookingId: The ID of the item booking.

people: Container for questions per person.

personId: The ID of the person.

details: Personal details for the person.

questions: Any per-item questions for the booking.

extras: Container for questions per extra booking.

bookingId: The ID of the extra booking.

questions: Any per-extra questions for the booking.

transportBookings: Container for questions per transport booking.The question specification which is referenced above is the basic construct which describes what type of question should be asked: Here is a brief description of the fields in the question specification:

bookingId: The ID of the transport route booking

questions: Any per-booking questions for the booking

pickupQuestions: Any questions relating to pick up (if booked). For example, if an airport was selected for pick up, we may ask about flight number.

dropoffQuestions: Any questions relating to drop off (if booked). For example, if an airport was selected for drop off, we may ask about terminal.

passengers: Container for questions per passenger booked.

bookingId: The ID of the pricing category booking.

passengerDetails: Personal details for the passenger.

questions: Any per-passenger questions for the booking.

The question specification which is referenced above is the basic construct which describes what type of question should be asked:

Here is a brief description of the fields in the question specification:

questionId: The ID of the question - you will need to supply this when you submit the answers.

questionCode: Optional code for the question, only specified if this is a custom question and the supplier has specified code.

label: This should be used as a label for the question.

help: Optional help text for the question

placeholder: Optional placeholder for the question

dataType: The data type expected for the answer.

dataFormat: Optional data format which can apply some validation constraints to the answer.

pattern: If the dataFormat is PATTERN, then this field will contain regular expression pattern that should be used for validation of the answer.

required: Specifies whether the answer is required.

defaultValue: Optional default value for the answer.

flags: Any custom flags that the supplier has provided.

selectFromOptions: Specifies whether the user must select from a list of predefined options.

selectMultiple: Specifies whether the user can supply more than one answer to the question.

answerOptions: If selectFromOptions is true, then the options to select from will be listed here.

label: The display label for this option

value: The value for the option. This should be submitted as the answer if this option is selected.

Answers Schema

The answers schema has the following structure:

Note that there is an answers object for each product booking. Following is an example that shows the structure for activity bookings:

The schema matches the questions schema, and should therefore be self explanatory. Just a note regarding the answer object:

Here, the questionId must match that of the question being answered. Values are specified as an array. If the question allows only one answer, then the answer array should contain a maximum of one value.

Get questions for a Shopping Cart

Use case : Get a list of all the questions that need to be answered when checking out, for a whole shopping cart.

GET /question.json/shopping-cart/{cartUUID}

The response will be of the schema described under "Questions schema".

Save answers for a Shopping Cart

Use case : Save answers for the shopping cart. This is useful if you want to capture answers as soon as items are added to the shopping cart. The customer can then return later, and check out without having to enter the answers again. Note that you can also submit answers during the checkout process.

POST /question.json/shopping-cart/{cartUUID}

The request body should contain data on the following schema: BookingAnswersDto. Answers will be validated. If they are valid, then the answers are saved. If not, you will get a bad request response with information about the invalid or missing answers.

Get questions for an existing Booking

Use case : Get a list of all questions for an existing booking. If they have been previously answered, you will also get the answers.

GET /question.json/booking/{bookingId}

The response will be of the schema described under "Questions schema".

Save answers for an existing Booking

Use case : Save answers for a booking. This is useful if you want to update answers for an existing booking.

POST /question.json/booking/{bookingId}

The request body should contain data on the following schema: BookingAnswersDto.

Answers will be validated. If they are valid, then the answers are saved. If not, you will get a bad request response with information about the invalid or missing answers.

Get questions for an individual Activity Booking

Use case : Get a list of all questions for an individual activity booking. If they have been previously answered, you will also get the answers.

GET /question.json/activity-booking/{bookingId}

The response will be of type ActivityBookingQuestionsDto as described in the "Questions schema".

Save answers for an individual Activity Booking

Use case : Save answers for an individual activity booking. This is useful if you want to update answers for an existing booking.

POST /question.json/activity-booking

The request body should contain data of the type ActivityBookingAnswersDto as described in the following schema: BookingAnswersDto. Answers will be validated. If they are valid, then the answers are saved. If not, you will get a bad request response with information about the invalid or missing answers.