The steps below explain how to update the options (i.e., the responses) available for a custom field arm.
| Step | Name | Endpoint | Details |
|---|---|---|---|
| List arms | POST /v3/companies/{companyId}/custom-fields/{customFieldId}/arms/list | List all the arms created for a custom field. URL path requires: companyId retrieved from the get company API, and customFieldId from Step 1 of the creating a custom field workflow.Request body: Use the optional searchText field to filter and find a specific arm.Response will contain: the list of arms along with information such as the id, name, audiences, action, and option group of each arm.Note: Inside an arm object the identifier property is called id, not armId. To find the optionGroupId, navigate to arms > action > userOptionSource. It is only present when userOptionSource > type is MANUAL. Arms with an AUTO action, and arms that source their options from a profile attribute, have no option group. You can also get the optionGroupId from Step 2 of the creating a custom field workflow.Other APIs will use: the id of the arm for which you need to update the options, and the optionGroupId. | |
| Get options for a custom field arm | POST /v3/companies/{companyId}/custom-fields/{customFieldId}/arms/{armId}/option-list | Get all the options for a custom field arm. URL path requires: companyId, customFieldId, and armId from Step 1.Request body requires: paginationParams to define the number of options displayed per API response, and fetchEffectiveAdditionalInfos. Both fields are mandatory. Within paginationParams, offset defaults to 0 and limit defaults to 100. You can also pass the optional nameSearchText field to return only the options whose name contains the text you supply.Response will contain: the name and description of each option added for the custom field arm, plus its additionalInfos. If the company has translations configured, each option additionally returns translatedName and translatedDescription.Note: Options that define their own additionalInfos always return them. Setting fetchEffectiveAdditionalInfos to true makes options that define none inherit the arm level additionalInfos instead, and setting it to false leaves those options with no additionalInfos. | |
| Update options for a specific options group | PATCH /v3/companies/{companyId}/custom-fields/{customFieldId}/option-groups/{optionGroupId} | Update the options for an arm. URL path requires: companyId, customFieldId, and optionGroupId from Step 1.Request body: Use the toUpdate field to update the name and description of the available options. If the name passed doesn't match with an existing option name, then a new option will be created. To delete existing options, use the toDelete field.Note: When one request contains both fields, the options named in toDelete are removed before the entries in toUpdate are applied. Options that appear in neither field are left unchanged. | |
| Upload file of options | POST /v3/companies/{companyId}/custom-fields/{customFieldId}/option-groups/{optionGroupId} | Upload a CSV file of options instead of listing them in the request body. This is useful when an option group holds a large number of options. URL path requires: companyId, customFieldId, and optionGroupId from Step 1.Request body requires: the CSV file sent as multipart/form-data in the file field.Note: The CSV file uses three columns. Action* is required and accepts Create, Update, or Delete. Response Option* is required and holds the option name used to match an existing option. Description is optional. |