The steps below explain how to create a new custom field, add an arm with its audiences and action, define the responses that travelers can select, and enable the field for the company.
| Step | Name | Endpoint | Details |
|---|---|---|---|
| Create a custom field | POST /v3/companies/{companyId}/custom-fields | Create a new custom field. URL path requires: companyId.Query parameter requires: companyRole, which describes the role of the company in the URL path and therefore sets the level at which the custom field is defined. Use ORG when a company administrator creates a field for their own company, or TMC or PARTNER_TMC when a TMC creates a field at the TMC level.Request body requires: name. You can optionally provide description, includeLocations, managementTags, and respondOnlyOnceLevel.Response will contain: the custom field id.Note: Custom field names must be unique for a company (unique per companyId). If you submit a name that is already in use, the request fails with a duplicate name error.Note: If respondOnlyOnceLevel is set to TRIP, then the travelers only have to respond to the custom field once per trip. For example, if they've responded during an air booking workflow, then they don't have to respond again when booking a car or hotel for the same trip. | |
| Create a custom field arm | POST /v3/companies/{companyId}/custom-fields/{customFieldId}/arms | Create an arm for the custom field. The arm creation process also includes creating an audience and an option group. URL path requires: companyId and customFieldId from Step 1.Request body requires: the arm name and action. The audiences field is optional and defaults to an empty array. An arm with no audiences applies to every user, which makes it useful as a default arm, but remember that such an arm takes precedence over all other arms.Response will contain: armId. It also contains an optionGroupId when the arm uses a manually defined option list, which means action > type is USER and action > userOptionSource > type is MANUAL. Arms with an AUTO action, and arms that obtain their options from a profile attribute, have no option group and return no optionGroupId.Note: You can create as many arms as needed for a custom field. But each arm can only contain one option group. Other APIs will use: armId and optionGroupId. | |
| Update options | PATCH /v3/companies/{companyId}/custom-fields/{customFieldId}/option-groups/{optionGroupId} | Update the options (i.e., the custom field responses) for an arm. URL path requires: companyId, customFieldId from Step 1, and optionGroupId from Step 2.Request body requires: a toUpdate array. Each entry needs a name, which is the response shown to the traveler, and can also carry a description and option level additionalInfos.Note: You can also use the toDelete field in this endpoint to delete an option from the list. The two fields (toDelete and toUpdate) are applied in a fixed order. The options named in toDelete are removed first, then the entries in toUpdate are inserted or updated by matching on name. The request does not replace the whole option group, so options you do not mention are left untouched.Note: If you have the list of options to be updated in a CSV file, you can use the upload file of options API instead. | |
| Update the custom field status | PATCH /v3/companies/{companyId}/custom-fields/update-status | Enable or disable a custom field. Each new custom field is disabled by default, so you'll have to enable it using this endpoint once it's configured and ready. URL path requires: companyId.Query parameter requires: companyRole, which sets the level at which the status is stored. This endpoint accepts ORG or TMC only.Request body requires: a fieldsToUpdate array. Each entry takes the custom field id from Step 1 and the enabled field set to either true or false.Note: You can set the enabled field to false to disable an active custom field later if needed. |