---
title: "Dropdown Place"
description: "Add dropdown selection fields with predefined options for recipients to choose from"
canonical: "https://signatureapi.com/docs/api/resources/places/dropdown"
source: "https://signatureapi.com/docs/api/resources/places/dropdown.md"
last_verified_api_version: "1.18.0"
last_modified: "2026-11-18T11:48:11Z"
---

# Dropdown Place

Add dropdown selection fields with predefined options for recipients to choose from

_Last verified against API version 1.18.0._

A **dropdown place** marks a location in a document where a recipient selects one option from a predefined list during the signing ceremony.

![An open dropdown during signing with the hint Select language above it and the options English, Spanish, Portuguese and French](https://signatureapi.com/docs/images/dropdown.webp)

> **Note:** Dropdown places are only available in envelopes with sequential signing.

You can position dropdown places using either [placeholders](https://signatureapi.com/docs/api/resources/places/positioning/#placeholders) or [fixed positions](https://signatureapi.com/docs/api/resources/places/positioning/#fixed-positions).

## Options

The `options` property defines the choices available in the dropdown. You can provide either custom options or a predefined option set.

### Custom options

Supply an array of objects. Each object requires a `label` (displayed to the recipient) and accepts an optional `value` (stored when the option is selected). If `value` is omitted, `label` is used as the stored value.

```json
{
  "options": [
    { "label": "Full-time", "value": "full_time" },
    { "label": "Part-time", "value": "part_time" },
    { "label": "Contract", "value": "contract" }
  ]
}
```

### Predefined option sets

For common selections like countries or US states, use a predefined option set by specifying one of these string values:

| Value                            | Description              | Example values                       |
| -------------------------------- | ------------------------ | ------------------------------------ |
| `world_countries_names`          | Full country names       | "United States", "Canada", "Germany" |
| `world_countries_2_letter_codes` | ISO 3166-1 alpha-2 codes | "US", "CA", "DE"                     |
| `world_countries_3_letter_codes` | ISO 3166-1 alpha-3 codes | "USA", "CAN", "DEU"                  |
| `world_countries_numeric_codes`  | ISO 3166-1 numeric codes | "840", "124", "276"                  |
| `us_states_names`                | Full US state names      | "California", "Texas", "New York"    |
| `us_states_2_letter_codes`       | US state abbreviations   | "CA", "TX", "NY"                     |

```json
{
  "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` of each option, then against the `value`. If no match is found, a validation error is returned.

```json
{
  "options": "us_states_names",
  "default": "California"
}
```

## Behavior

The `behavior` property controls how the dropdown is rendered during the signing ceremony.

| Behavior         | Description                                                                                                    |
| ---------------- | -------------------------------------------------------------------------------------------------------------- |
| `auto` (default) | Renders as a standard dropdown for 10 or fewer options, and as a searchable combobox for more than 10 options. |
| `select`         | Always renders as a standard dropdown list.                                                                    |
| `combobox`       | Always renders as a searchable dropdown with type-ahead filtering.                                             |

For large option sets like country lists, the `auto` behavior uses `combobox` since there are more than 10 options.

```json
{
  "options": "world_countries_names",
  "behavior": "combobox"
}
```

## Hints and Prompts

Use `hint` and `prompt` to guide recipients while making their selection.

- **`hint`**: A tooltip shown when the recipient hovers over or focuses on the dropdown.
- **`prompt`**: Placeholder text shown inside the dropdown before a selection is made.

```json
{
  "hint": "Select your country of residence",
  "prompt": "Choose a country..."
}
```

## Capturing Input

Set `capture_as` to store the selected value in the envelope's `captures` object. After the envelope is completed, retrieve the value using the key you specified.

## Size and Appearance

- **`width`**: The width of the dropdown field in points (1/72 inch). Must be between 30 and 540. Defaults to 30.
- **`font_size`**: The text size inside the dropdown, in points. Must be between 6 and 12. Defaults to 12.

## Attributes

#### `type` (enum, required)

Specifies the type of place.

For a dropdown place, the value must be `dropdown`.

#### `key` (string, required)

A unique identifier for this place within the document. Use this key to match the place to its position, either through a `[[place_key]]` placeholder in the document or an entry in `fixed_positions`.

Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters.

#### `recipient_key` (string, required)

The key of the recipient assigned to this place. Must match one of the `key` values in the envelope's `recipients` array.

#### `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.

```json
"options": [
  { "label": "Option A", "value": "a" },
  { "label": "Option B", "value": "b" }
]
```

**Predefined options**: A string specifying a built-in option set:

| Value                            | Description                                     |
| -------------------------------- | ----------------------------------------------- |
| `world_countries_names`          | Country names (e.g., "United States", "Canada") |
| `world_countries_2_letter_codes` | ISO 3166-1 alpha-2 codes (e.g., "US", "CA")     |
| `world_countries_3_letter_codes` | ISO 3166-1 alpha-3 codes (e.g., "USA", "CAN")   |
| `world_countries_numeric_codes`  | ISO 3166-1 numeric codes (e.g., "840", "124")   |
| `us_states_names`                | US state names (e.g., "California", "Texas")    |
| `us_states_2_letter_codes`       | US 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](https://signatureapi.com/docs/api/resources/places/dropdown#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](https://signatureapi.com/docs/api/resources/places/dropdown#hints-and-prompts).

#### `capture_as` (string)

A key that stores the recipient's input in the envelope's `captures` object. When set, the value entered or selected by the recipient is saved under this key after the envelope is completed.

Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. Set to `null` to disable capture.

#### `font_size` (number)

The font size in points.

Must be between 6 and 12. The default is 12.

#### `width` (number)

The width of the dropdown field in points.

Must be between 30 and 540. The default is 30.

## Examples

#### Custom Options

```json
{
  "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
}
```

#### Country Selection

```json
{
  "key": "country_of_residence",
  "type": "dropdown",
  "recipient_key": "applicant",
  "options": "world_countries_names",
  "default": "United States",
  "behavior": "combobox",
  "capture_as": "country",
  "prompt": "Select your country",
  "hint": "Choose your country of residence",
  "requirement": "required",
  "width": 200,
  "font_size": 10
}
```

#### US State Selection

```json
{
  "key": "state_selection",
  "type": "dropdown",
  "recipient_key": "customer",
  "options": "us_states_2_letter_codes",
  "capture_as": "state",
  "prompt": "Select state",
  "requirement": "required",
  "width": 80,
  "font_size": 10
}
```
