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

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: POST /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	List of options to add or update

Specified values

Field	Type	Required	Description
`id`	text	No	If you omit this, a new value will be added
`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 POST \
  --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": 
      [
        {"id":"69fb07a5db49006f46c54a21","value":"High changed","conditional_color":"#48B220"},
        {"value":"Medium"}
      ]
      }'
  }'

Response properties

A successful request returns the full updated 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 changed",
                    "ConditionalColor": "#48B220"
                },
                {
                    "Id": "6a045fc7fb49c8dc991ee487",
                    "Value": "Medium",
                    "ConditionalColor": "#E27172"
                }
            ],
            "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": ""
        }
    ]
}