# Custom field concepts

Custom fields allow you to capture additional information during the booking process that can be useful for analyzing your processes and creating reports. These fields can be customized and presented to travelers during checkout to prompt them to select an answer or enter a relevant response before booking. For example, a custom field could be a question (e.g., cost center or reason for travel) with 10 (or more) answers a traveler could select from. A custom field can also be made mandatory (i.e., the traveler must select or enter a value before proceeding with the booking). In the [update arm](/openapi/customfieldapi/custom-field-v3/updatearm) API request, the `action` > `required` field must be set to `true` if the traveler response is mandatory.

The legacy custom field V2 operations are now deprecated and will be sunset after 1 July 2027. If you're currently using the V2 endpoints, we recommend you to migrate to the [custom fields V3](/openapi/customfieldapi/custom-field-v3) APIs.

The creating and managing custom fields require atleast one of the following [permissions](/spotnana/basic_rbac_concepts#available-permissions):

| Permission  | Context |
|  --- | --- |
| `COMPANY_MANAGEMENT` (read, write, and delete) | Allows the user to create and manage custom fields for the specific companies they manage. |
| `TMC_MANAGEMENT` (read, write, and delete) | Allows the user to create and manage custom fields for all the companies under a specific TMC. |


To create a more granular permission (e.g., an agent with read-only access to the custom fields), see [RBAC concepts](/spotnana/basic_rbac_concepts) and [RBAC workflows](/spotnana/rbac_workflows_intro).

## Sample use cases

The following use cases demonstrate how you might utilize custom fields within a booking workflow.

### Use case 1

An administrator wants to gather the information about whether the bookings made by their travelers are for business purposes or for leisure. A custom field could be used to create the question **What's the purpose of your booking?** and provide that question with two responses (i.e., *business* and *leisure*) to choose from. The traveler would be presented with this question at the time of booking and the answer they select will be recorded.

### Use case 2

A company invites all its employees to create a round trip air booking for their annual offsite happening in Dubai. Some employees may plan to stay beyond the actual event dates at their own expense to explore the country. The company would like to know if they are extending their stay and want to collect their emergency contact. The administrator can configure the first custom field to ask the question **Are you planning to extend your stay?** along with two responses **Yes** and **No**. If the traveler selects **Yes**, a second custom field asking the traveler to **Enter your emergency contact number** is displayed. This custom field can have a simple text box that accepts numerical values as a response. If they select **No** as their response to the first custom field, they can simply continue to checkout (since they are not traveling beyond the dates of the company event).

To restrict the response to numerical values, set the `action` > `format` > `userInputFormat` > `allowedChars` field to `NUMERIC` in the [creating a custom field arm](/openapi/customfieldapi/custom-field-v3/createarm) API. To make the second custom field appear only when the traveler answers **Yes**, use the [create custom field arm](/openapi/customfieldapi/custom-field-v3/createarm) API to set the `audiences` > `predicates` > `type` field to `CUSTOM_FIELD_RESPONSE` and add reference to the first custom field's `id` and expected `values`. See the [action](#action) and [audiences](#audiences) rows in the custom field API parameters table for the full set of options.

## Where are custom fields used?

The custom fields can be enabled for [standard trips](/spotnana/trip_concepts_intro), [individual bookings](/spotnana/basic_trip_concepts#pnr) within trips (i.e., PNR creation), [event templates](/spotnana/spd_concepts_intro), and [Specialty Desk (SPD) trips or events](/spotnana/spd_concepts_intro). In the APIs referred to in this document, the `customFieldV3Responses` array will be used to capture the custom field information and its subsequent responses selected by the travelers or added automatically based on the configuration.

For example, in the [create air PNR](/openapi/airapi/air/aircreatepnr) API, the request contains a `customFieldV3Responses` array which holds all the information about the custom fields related to the PNR. This also includes the responses selected by the traveler in the `customFieldV3Responses` > `selectedOptions` field.

For [SPD trips](/spotnana/spd_concepts_intro) and [SPD events](/spotnana/spd_concepts_intro), the event coordinator can enable a custom field that will then appear for travelers during checkout. However, the coordinator can only select from a list of custom fields that were already created and enabled by the administrators.

## Custom field API parameters

The section provides more detailed information about specific API parameters used when working with [custom field](/openapi/customfieldapi) APIs.

| API parameter | Context |
|  --- | --- |
| `name`
 | The name of the custom field. This is the text (or question) displayed to the traveler during the checkout flow whenever the field is shown.
For example, some typical names of custom fields might be:
- What's the reason for choosing an out of policy booking?
- What's the purpose of your trip?
- Select the countries where this trip has a layover.

The custom field name will be displayed on the **Checkout** page, along with the responses the traveler can select from (alternately, the traveler may be prompted to type a response into a text field).
 |
| `arms`
 | Arms indicate the different response sets configured for a custom field.
For example, assume a company has five subsidiaries and all the company employees are invited to attend an event. You wish to capture the legal entity (i.e., the company subsidiary) of the person making the booking. This is because employees who make their own booking can pay using the company's central card but if an agent makes the booking on behalf of an employee, then the agent has to pay for it and send an invoice to the company's legal entity.
In this scenario:
- A custom field is set to ask **Select the legal entity you work for**.
- Two arms are created for the custom field and configured as follows:
  - **Arm 1:** A menu with a list of the five company subsidiary names from which the user can select only one option. This set of responses is displayed to all users initiating a booking (except agents).
  - **Arm 2:** An auto selected response containing the name of the agent's legal entity which has partnered with the company to provide agent services. The response is recorded whenever an agent user initiates a booking. By default the auto selected response is also displayed to the user at checkout as a read only value. Set `hidden` to `true` on the [arm creation](/openapi/customfieldapi/custom-field-v3/createarm) API if you do not want it displayed at all.
A custom field can have as many arms as needed and each arm has its own unique arm `id` and `audiences`.
If a user making the booking falls under the audiences of more than one arm (i.e., they satisfy both arm 1 and arm 2 conditions), then the arm that was created first is selected.

 |
| `audiences`
 | Audiences are the group of users to whom the custom field will be displayed. Audiences can be grouped by any conditions set by the administrators when they're creating a custom field (e.g., travelers making an air booking).
When [creating an arm](/openapi/customfieldapi/custom-field-v3/createarm) you can use the conditional logic of the `audiences` > `predicates` > `type` field to define an audience. For example, if
- the `type` is set to `BOOKING_TYPE`,
- the `comparator` is set to `EQ`, and
- the `bookingTypes` is set to `AIR`,

then the custom field will be displayed to any user who makes an air booking.
The `type` field allows more values (such as `BOOKING_INITIATOR_TYPE`, `ORIGIN_CITY`, etc) which can be used to create a more focused set of audiences (e.g., show the custom field to an agent where the booking's origin city is New York).
 |
| `action`
 | The action object is used to configure the type of responses displayed to the traveler on the **Checkout** page.
When [creating an arm](/openapi/customfieldapi/custom-field-v3/createarm), the `action` > `type` field can have one of the following values:
- `AUTO`: Indicates that the response for a custom field is auto selected and the traveler doesn’t have to respond to it. The `hidden` field is set to `false` by default, so the custom field and the auto-selected response are still displayed to the traveler as a read-only value. Set `hidden` to `true` to hide the custom field and the response from traveler.
- `USER`: Indicates that the system expects the traveler to make a selection for the custom field displayed at checkout.
If you've set the `action` > `type` field to `USER`, then you must also set `action` > `format` > `type` to define the format of the response options displayed:
  - `OPTION_LIST`: A list of options displayed for a custom field from which the traveler can make one or more selections, based on whether `action` > `format` > `optionListTypeFormat` > `isMultiSelect` is set to `false` or `true`.
  - `TEXT_INPUT`: A text box which allows the traveler to enter a response for the custom field.

 |
| `options`
 | Options are the responses displayed for a custom field arm. Based on the action configured, the responses are either auto selected or chosen manually by the traveler.
For example, a custom field question **Are you planning to extend your stay?** can have the options of **Yes** and **No**. In this scenario, the `action` > `format` > `type` field will be set to `OPTION_LIST` and `action` > `format` > `optionListTypeFormat` > `isMultiSelect` will be set to `false`, since only one response needs to be selected.
Use the [update options](/openapi/customfieldapi/custom-field-v3/updatecustomfieldoptiongroupv3) API endpoint to add options for a custom field arm. The `toUpdate` > `name` field indicates the name of the options (e.g., Yes and No) which will be displayed to the traveler.
Each option also accepts an optional `description`, which gives the traveler more context about the option. If the company has translations configured on the platform, the API additionally returns `translatedName` and `translatedDescription` matching the traveler's preferred language. These translated values are read only and cannot be set through the [update options](/openapi/customfieldapi/custom-field-v3/updatecustomfieldoptiongroupv3) endpoint.
An option group indicates a list of options that are grouped together using an `optionGroupId`. An arm can only contain one `optionGroupId`.
 |
| `additionalInfos`
 | The `additionalInfos` field can be used to display any additional details for an arm and for an option.
Each entry in `additionalInfos` is one of two types.
- A `VARIABLE` entry references a system value through its `name` field, which accepts `PUBLISHED_FARE`, `LLF` (the lowest logical fare), `ADD_COLLECT_AMOUNT`, `SELECTED_FARE`, or `SPLIT_PAYMENT_FARE`.
- An `EXPRESSION` entry supplies a `formatExpression` template of the form `<any_text> ${expression} <any_text>`, which can combine those variables with the math operations `add`, `mul`, `div`, `sub`, `min`, and `max` (e.g., `math.<math_op>(arg1, arg2)`). All keywords must be lowercase.

The `additionalInfos` values are stored against a booking, and returned by the trip APIs and in company reports. They are not displayed to the traveler.
For example, a custom field capturing the reason for an out of policy booking can set `additionalInfos` on the arm with two `VARIABLE` entries, `LLF` and `SELECTED_FARE`, and one `EXPRESSION` entry with a `formatExpression` of `Extra cost: ${math.sub(SELECTED_FARE,LLF)}`. When the traveler picks a reason, the platform resolves these into values and stores them with the response, so a report not only shows why a booking was out of policy but how much more it cost.
 |


The following illustrations explain some of the custom field API parameters explained above:


 ***Fig:** Image explaining the custom field name and options with an example.* 




 ***Fig:** Image explaining the custom field arms and audiences with an example.*