Skip to main content
A Dropdown Place is a type of Place that allows recipients to select an option from a predefined list during the signing ceremony. Dropdown
Dropdown places are only available in envelopes with sequential signing.
You can position Dropdown Places inside a document using either fixed positions or placeholders.

​
Options

The options property defines the choices available in the dropdown. You can specify options in two ways:

​
Custom Options

Provide an array of objects, each containing a label and an optional value. The label is displayed to the user, while the value is captured when the option is selected. If value is omitted, the label is used as the captured value. 
{
  //...
  "options": [
    { "label": "Full-time", "value": "full_time" },
    { "label": "Part-time", "value": "part_time" },
    { "label": "Contract", "value": "contract" }
  ]
  //...
}

​
Predefined Options

For common use cases like country or state selection, you can use a predefined option set by specifying a string value:
Option SetDescriptionExample Values
world_countries_namesFull country names”United States”, “Canada”, “Germany”
world_countries_2_letter_codesISO 3166-1 alpha-2 codes”US”, “CA”, “DE”
world_countries_3_letter_codesISO 3166-1 alpha-3 codes”USA”, “CAN”, “DEU”
world_countries_numeric_codesISO 3166-1 numeric codes”840”, “124”, “276”
us_states_namesFull US state names”California”, “Texas”, “New York”
us_states_2_letter_codesUS state abbreviations”CA”, “TX”, “NY”
{
  //...
  "options": "world_countries_names"
  //...
}

​
Default Selection

Use the default property to pre-select an option when the dropdown is displayed. The value is matched first against the label, then against the value of each option. 
{
  //...
  "options": "us_states_names",
  "default": "California"
  //...
}

​
Behavior

The behavior property controls how the dropdown is rendered during the signing ceremony:
  • auto (default): Automatically selects the best behavior based on the number of options.
    • Uses select for 10 or fewer options
    • Uses combobox for more than 10 options
  • select: Displays a standard dropdown list. Users click to see all options and select one.
  • combobox: Displays a searchable dropdown with type-ahead filtering. Users can type to filter the list.
For predefined option sets like country lists, the auto behavior will use combobox since there are more than 10 options, making it easier for users to find their selection. 
{
  //...
  "options": "world_countries_names",
  "behavior": "combobox"
  //...
}

​
Hints and Prompts

You can use hint and prompt properties to guide recipients while making their selection:
  • Hint: A tooltip message displayed when the user hovers over or focuses on the dropdown. Set it using the hint property.
  • Prompt: A placeholder message shown inside the dropdown before a selection is made. Set it using the prompt property.
{
  //...
  "hint": "Select your country of residence",
  "prompt": "Choose a country..."
  //...
}

​
Size and Appearance

You can customize the size and appearance of dropdown places:

​
Width

The width property sets the width of the dropdown field in points (1/72 of an inch). Must be between 30 and 540. The default is 30.

​
Font Size

The font_size property controls the size of the text displayed within the dropdown, measured in points. Must be between 6 and 12. The default is 12.

​
Examples

The following examples show different ways to configure dropdown places. 
"documents":
[
  {
    //...
    "places": [
      {
        "key": "employment_type",
        "type": "dropdown",
        "recipient_key": "employee",
        "options": [
          { "label": "Full-time", "value": "full_time" },
          { "label": "Part-time", "value": "part_time" },
          { "label": "Contract", "value": "contract" },
          { "label": "Internship", "value": "internship" }
        ],
        "default": "Full-time",
        "capture_as": "employment_type",
        "prompt": "Select employment type",
        "hint": "Choose the type of employment",
        "requirement": "required",
        "width": 150,
        "font_size": 10
      }
    ]
    //...
  }
]

​
Parameters

​
type
enum
required
Specifies the type of place.For a dropdown place, the value must be dropdown.
​
key
string
required
A user-provided key that identifies a place within a document.It must be up to 32 characters long, using only lowercase letters, numbers, or underscores, and it must begin with a letter.
​
recipient_key
string
required
A user-provided key that identifies a recipient within an envelope.It must match one of the recipient.key values in the envelope’s recipient list.
​
options
array or enum
required
Specifies the list of options available in the dropdown.You can provide either custom options or a predefined option set.Custom options: An array of objects, each with a label (displayed to the user) and an optional value (captured when selected). If value is omitted, the label is used as the value.
"options": [
  { "label": "Option A", "value": "a" },
  { "label": "Option B", "value": "b" }
]
Predefined options: A string specifying a built-in option set:
ValueDescription
world_countries_namesCountry names (e.g., “United States”, “Canada”)
world_countries_2_letter_codesISO 3166-1 alpha-2 codes (e.g., “US”, “CA”)
world_countries_3_letter_codesISO 3166-1 alpha-3 codes (e.g., “USA”, “CAN”)
world_countries_numeric_codesISO 3166-1 numeric codes (e.g., “840”, “124”)
us_states_namesUS state names (e.g., “California”, “Texas”)
us_states_2_letter_codesUS state codes (e.g., “CA”, “TX”)
​
default
string
Specifies the option that is pre-selected when the dropdown is displayed.The value is first matched against the label of each option. If no match is found, it is matched against the value of each option. If no match is found, a validation error is returned.
​
behavior
enum
Specifies the behavior of the dropdown during the signing ceremony.Possible values:
  • auto (default): Automatically selects the best behavior based on the number of options. Uses select for 10 or fewer options, and combobox for more than 10 options.
  • select: Displays a standard dropdown list. Best for short lists where users can quickly scan all options.
  • combobox: Displays a searchable dropdown with type-ahead filtering. Best for long lists where users need to search for their selection.
​
requirement
enum
Specifies whether the recipient must select an option to complete the signing ceremony.Possible values are required or optional. The default is required.
​
prompt
string
A placeholder message shown inside the dropdown field during the signing ceremony.Maximum length is 100 characters.Learn more in Hints and Prompts.
​
hint
string
A tooltip message displayed when the user hovers over or focuses on the dropdown field during the signing ceremony.Maximum length is 100 characters.Learn more in Hints and Prompts.
​
capture_as
string
A user-defined identifier used to store the value entered by the recipient. This value will be included in the captures object of the Envelope.Must start with a lowercase letter and contain only lowercase letters, numbers, or underscores. Maximum length is 32.
​
font_size
number
The font size in .Must be between 6 and 12. The default is 12.
​
width
number
The width of the dropdown field in .Must be between 30 and 540. The default is 30.