This guide explains how to collect custom field responses during checkout.
Be sure to read custom field concepts to familiarize yourself with this feature before starting to use it.
The flow uses three calls:
- Get the custom fields applicable to the booking in progress.
- Get the list of options applicable to the custom fields from step 1.
- Submit the responses collected from the traveler with the booking request.
Call the get applicable custom fields endpoint. The request requires the userId of the traveler and a bookingContext.
The bookingContext requires a tripId and an itinerary object. For an air booking, set itineraryType to AIR and supply the searchId and the rateOptionId of the itinerary the traveler selected. See air booking workflow for more details regarding these identifiers. Use bookingFlowType to distinguish a new booking from a modification or a cancellation.
Here's a sample get applicable custom fields API request:
{
"userId": "8d2f6c14-5b73-4a19-9c0e-3f7a2b6d1e84",
"bookingContext": {
"tripId": "a1c9e70b-42d8-4f36-8b51-6d0c7e29af13",
"itinerary": {
"itineraryType": "AIR",
"searchId": "a3f1c8d29b6e4705",
"rateOptionId": "7c40e9b2-5d18-4af3-9016-8be2d7c5301f"
},
"bookingFlowType": "NEW_BOOKING",
"pnrCreationProcessType": "OBT"
}
}The response contains a customFields array with all the details regarding the applicable custom fields for the traveler and the booking flow.
Here's a sample get applicable custom fields API response:
{
"hasNewCustomFields": true,
"customFields": [
{
"id": "d18c4e73-2fa9-4b60-91cd-7e35a806f2b1",
"name": "Reason for the out of policy booking",
"armId": "6c9a2f84-b073-41de-a52f-38e1c7b094d6",
"action": {
"type": "AUTO",
"name": "LD",
"description": "Lower fare declined",
"hidden": false
}
},
{
"id": "9b57e2a4-13cd-4068-8fa1-2e6d09c745b8",
"name": "Which cost center should this trip be charged to?",
"armId": "27df906c-4b81-45ea-93f7-c0a85e1d62b3",
"action": {
"type": "USER",
"required": true,
"format": {
"type": "OPTION_LIST",
"optionListTypeFormat": {
"isMultiSelect": false,
"isPctType": false
},
"customValueFormat": {
"isCustomValueAllowed": false
}
},
"userOptionSource": {
"type": "MANUAL",
"optionGroupId": "e40a71b9-38c6-42fd-8b05-9a71cde264f7"
}
}
},
{
"id": "71e8b3d0-5c47-4a92-86fb-2d09e4a15c73",
"name": "Add a note for the travel desk",
"armId": "0f3d97a5-8e21-4cb6-b74d-15a6c0392e8f",
"action": {
"type": "USER",
"required": false,
"format": {
"type": "TEXT_INPUT",
"userInputFormat": {
"type": "NON_REGEX",
"allowedChars": "ALL",
"minLength": 1,
"maxLength": 120
}
}
}
}
]
}Use the get options for a custom field arm API to get the applicable options (e.g., answers for a question) for a custom field.
Here's a sample get options for a custom field arm API request:
{
"paginationParams": {
"offset": 0,
"limit": 50
},
"fetchEffectiveAdditionalInfos": true
}
A sample response for the above API call:
{
"paginationParams": {
"totalNumResults": 3
},
"options": [
{
"name": "CC-1000",
"description": "Engineering"
},
{
"name": "CC-2000",
"description": "Sales"
},
{
"name": "CC-3000",
"description": "Operations"
}
]
}See the options row in the custom field API parameters table for more information about custom field options.
Send the collected answers in the customFieldV3Responses array when making a new booking request. For example, in this scenario, update the customFieldV3Responses array in the create air PNR API request.
Here's a sample create air PNR API request:
// ... payload truncated for focus
{
"customFieldV3Responses": [
{
"fieldId": "d18c4e73-2fa9-4b60-91cd-7e35a806f2b1",
"armId": "6c9a2f84-b073-41de-a52f-38e1c7b094d6",
"selectedOptions": [
{
"name": "LD",
"description": "Lower fare declined"
}
]
},
{
"fieldId": "9b57e2a4-13cd-4068-8fa1-2e6d09c745b8",
"armId": "27df906c-4b81-45ea-93f7-c0a85e1d62b3",
"selectedOptions": [
{
"name": "CC-1000",
"description": "Engineering"
}
]
},
{
"fieldId": "71e8b3d0-5c47-4a92-86fb-2d09e4a15c73",
"armId": "0f3d97a5-8e21-4cb6-b74d-15a6c0392e8f",
"selectedOptions": [
{
"name": "Arriving a day early for an internal review",
"additionalUserInput": "Arriving a day early for an internal review"
}
]
}
]
}You'll find the same object in hotel, car, rail, and limo booking creation APIs as well. Send the custom field responses using the customFieldV3Responses object during the PNR creation.