Use this endpoint to replace the option list of an existing dropdown or multi-select dropdown field in a questionnaire.

NOTE: This endpoint replaces the entire list of values. To add new values, include both the existing values and the new values in the request.

HTTP responses

HTTP response status code	Interpretation
200 OK	The field values were updated successfully
400 Bad Request	The field type does not support dropdown values, the body is invalid, or the repository update fails
401 Unauthorized	The API key is invalid
403 Forbidden	The caller is not an administrator
404 Not Found	The questionnaire does not exist, or the field was not found

Prerequisites

This endpoint only updates specified_values for one field. It does not update other field properties.

Endpoint: PUT /v1/questionnaires/{id}/fields/{fieldId}/dropdown-values
The header for your API request
Parameters, which must include:

Path parameters

Parameter	Required	Type	Description
`id`	Yes	String	Questionnaire ID
`fieldId`	Yes	String	ID of the dropdown or multi-select dropdown field

Request Body

The request body, which must include:

Field	Type	Required	Description
`specified_values`	array	Yes	New option list for the field. Use an empty array to clear all options. This list replaces the existing list.

Specified values

Field	Type	Required	Description
`value`	text	Yes	Label/value of the option
`conditional_color`	Hex color code	No	Hex color value of the color for the conditional layout

NOTE: There is a limit of 7500 values that can be set in this call.

Curl example:

curl --request PUT \
 --url 'https://<base-url>/v1/questionnaires/<questionnaire-id>/fields/<field-id>/dropdown-values' \
  --header 'X-Api-Key: <api-key>' \
  --header 'tenant: <tenant-name>' \
  --header 'Content-Type: application/json' \
  --data '{
    "specified_values": [
      { "value": "High", "conditional_color": "#48B220" },
      { "value": "Medium", "conditional_color": "#ED1C24" },
      { "value": "Low", "conditional_color": "#854F44" }
    ]
  }'

Response properties

A successful request returns the complete questionnaire, not just the modified field, with a 200 OK HTTP status code and the following response body:

{
    "id": "69f9e06b87476064c2e98d2b",
    "library_template_id": "000000000000000000000000",
    "builtin": false,
    "version": 0,
    "name": "Test API",
    "template_type": "BOEM_Form",
    "target": 0,
    "fields": [
        {
            "id": "f63393cd-81dc-448a-99d7-a33a9a00822c",
            "name": "Text",
            "built_in": false,
            "position": 0,
            "field_type": "text",
            "default_value": null,
            "description": "",
            "is_required": false,
            "share_with_library": true,
            "show_in_official_views": false,
            "completeness_item": false,
            "contains_sensitive_information": false,
            "read_only": false,
            "is_sensitive": false,
            "conditional_color_true": "",
            "conditional_color_false": "",
            "conditional_color_not_set": "",
            "currency_symbol": "USD",
            "number_of_decimals": 0,
            "open_in_new_window": false,
            "number_of_lines": 0,
            "is_lookup": false,
            "lookup_collection": "",
            "lookup_display_field": "",
            "specified_values": [],
            "object_definition_name": "",
            "selected_relationship": "",
            "relationship_remark": "",
            "max_length": 50,
            "multiple_values_allowed": false,
            "create_new_object_allowed": false,
            "object_definition_category_internal": "",
            "selected_mode": "",
            "selection_filter": ""
        },
        {
            "id": "9e306f94-305f-4087-85a5-661b177ac497",
            "name": "Dropdown",
            "built_in": false,
            "position": 1,
            "field_type": "dropdown",
            "default_value": "",
            "description": "",
            "is_required": false,
            "share_with_library": true,
            "show_in_official_views": false,
            "completeness_item": false,
            "contains_sensitive_information": false,
            "read_only": false,
            "is_sensitive": false,
            "conditional_color_true": "",
            "conditional_color_false": "",
            "conditional_color_not_set": "",
            "currency_symbol": "USD",
            "number_of_decimals": 0,
            "open_in_new_window": false,
            "number_of_lines": 0,
            "is_lookup": false,
            "lookup_collection": "",
            "lookup_display_field": "",
            "specified_values": [
                {
                    "Id": "69fb07a5db49006f46c54a21",
                    "Value": "High",
                    "ConditionalColor": "#48B220"
                },
                {
                    "Id": "69fb07a5db49006f46c54a23",
                    "Value": "Medium",
                    "ConditionalColor": "#ED1C24"
                },
                {
                    "Id": "69fb07a5db49006f46c54a25",
                    "Value": "Low",
                    "ConditionalColor": "#854F44"
                }
            ],
            "object_definition_name": "",
            "selected_relationship": "",
            "relationship_remark": "",
            "max_length": 0,
            "multiple_values_allowed": false,
            "create_new_object_allowed": false,
            "object_definition_category_internal": "",
            "selected_mode": "",
            "selection_filter": ""
        },
        {
            "id": "b9c75810-b727-47dc-82a4-260f6fe99ff4",
            "name": "Multi Dropdown",
            "built_in": false,
            "position": 2,
            "field_type": "multiselect",
            "default_value": "",
            "description": "",
            "is_required": false,
            "share_with_library": true,
            "show_in_official_views": false,
            "completeness_item": false,
            "contains_sensitive_information": false,
            "read_only": false,
            "is_sensitive": false,
            "conditional_color_true": "",
            "conditional_color_false": "",
            "conditional_color_not_set": "",
            "currency_symbol": "USD",
            "number_of_decimals": 0,
            "open_in_new_window": false,
            "number_of_lines": 0,
            "is_lookup": false,
            "lookup_collection": "",
            "lookup_display_field": "",
            "specified_values": [
                {
                    "Id": "69f9e080ecc89277672c4fad",
                    "Value": "One",
                    "ConditionalColor": "#AF756F"
                },
                {
                    "Id": "69f9e0808447a4f54de450d5",
                    "Value": "Two",
                    "ConditionalColor": "#00B6C5"
                },
                {
                    "Id": "69f9e080873fe97280395a2f",
                    "Value": "Three",
                    "ConditionalColor": "#FF913F"
                }
            ],
            "object_definition_name": "",
            "selected_relationship": "",
            "relationship_remark": "",
            "max_length": 0,
            "multiple_values_allowed": false,
            "create_new_object_allowed": false,
            "object_definition_category_internal": "",
            "selected_mode": "",
            "selection_filter": ""
        }
    ]
}