# Creating a custom field

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 |
|  --- | --- | --- | --- |
| 1. 
 | [Create a custom field](/openapi/customfieldapi/custom-field-v3/createcustomfieldv3) | `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. |
| 1. 
 | [Create a custom field arm](/openapi/customfieldapi/custom-field-v3/createarm) | `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`. |
| 1. 
 | [Update options](/openapi/customfieldapi/custom-field-v3/updatecustomfieldoptiongroupv3) | `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](/openapi/customfieldapi/custom-field-v3/bulkuploadoptions) API instead. |
| 1. 
 | [Update the custom field status](/openapi/customfieldapi/custom-field-v3/updatecustomfieldstatus) | `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. |