# Integrating custom fields at checkout

This guide explains how to collect custom field responses during checkout.

Be sure to read [custom field concepts](/spotnana/basic_custom_field_concepts) to familiarize yourself with this feature before starting to use it.

The flow uses three calls:

1. Get the custom fields applicable to the booking in progress.
2. Get the list of options applicable to the custom fields from step 1.
3. Submit the responses collected from the traveler with the booking request.


## Getting the applicable custom fields

Call the [get applicable custom fields](/openapi/customfieldapi/custom-field-v3/getapplicablecustomfields) 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](/spotnana/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](/openapi/customfieldapi/custom-field-v3/getapplicablecustomfields) API request:


```json POST /v3/applicable-custom-fields
{
  "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](/openapi/customfieldapi/custom-field-v3/getapplicablecustomfields) API response:


```json POST /v3/applicable-custom-fields
{
  "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
          }
        }
      }
    }
  ]
}
```

## Fetching the options for the custom field

Use the [get options for a custom field arm](/openapi/customfieldapi/custom-field-v3/getcustomfieldv3optionlist) 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](/openapi/customfieldapi/custom-field-v3/getcustomfieldv3optionlist) API request:


```json POST /v3/companies/{companyId}/custom-fields/{customFieldId}/arms/{armId}/option-list
{
  "paginationParams": {
    "offset": 0,
    "limit": 50
  },
  "fetchEffectiveAdditionalInfos": true
}
```

A sample response for the above API call:


```json POST /v3/companies/{companyId}/custom-fields/{customFieldId}/arms/{armId}/option-list
{
  "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](/spotnana/basic_custom_field_concepts#custom-field-api-parameters) table for more information about custom field options.

## Submitting the responses

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](/openapi/airapi/air/aircreatepnr) API request.

Here's a sample [create air PNR](/openapi/airapi/air/aircreatepnr) API request:


```json POST /v2/air/create-pnr
// ... 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.