Skip to main content
A static picklist is a hand-authored list of options that one or more dropdown fields point at. You type the values once, and every dropdown that references the list offers the same choices. It is the most common kind of picklist, and the building block for hierarchical lists too.

​
When to use it

  • You own a bounded vocabulary: goals, regions, product lines, priorities, UTM mediums.
  • The values change rarely, or any change should be reviewed before it ships.
  • You want to attach a readable label to each stored value, not just a raw list of strings.
Do not use a static picklist when the options already live as approved records in another taxonomy. Use an automated picklist so the list stays in sync. If you need cascading choices, you still use static picklists, just linked into a parent and child pair. See Hierarchical.

​
How it works

A static picklist is a named list. Each option has:
  • A code: the value saved on the record. Codes are unique within the picklist (and unique among children of the same parent in a hierarchy).
  • An optional label (the option’s description): the text shown in the dropdown. When absent, the code is shown as its own label.
  • A position: the order the options appear in. You set it by dragging rows in the editor.
When a dropdown uses the picklist, the submitter sees the labels and the record stores the chosen code. If you turn on “Allow new values”, a submitter can also type a value that is not in the list yet, and that value becomes a real option when the submission is approved.

​
Building and editing options

You edit options in a spreadsheet-style grid with a code column and a label column. You can:
  • Add rows one at a time, or paste a block of rows straight from a spreadsheet.
  • Reorder options by dragging.
  • Convert a flat list into a hierarchical one when you need cascading choices.
There are two ways to reach the editor. Open the full Picklists area of the governance model and add a new static list, or create one inline from a dropdown field’s settings without leaving the field editor (this inline path builds a flat list). Editing a list applies everywhere that list is used.
You cannot add or change options one at a time through the API. Options are managed as a set inside the picklist itself, or proposed by submitters and created on approval. There is no per-option “add” endpoint.

​
Allow new values (allow_additions)

When “Allow new values” is on (allow_additions: true), a submitter filling in a form can type a value that is not in the list. It appears as an “Add new …” choice and, once selected, is marked as a new value on that submission only. It is not visible to other submissions. When the submission is approved, any new values are added to the picklist as real options. The check uses the published version of the governance model that the submission was filled against, not the live toggle. So turning the switch on after a submission was started does not retroactively let that submission add values, and turning it off does not strip values from a submission filled while it was on. See Letting submitters add options.

​
Settings reference

SettingRequiredDefaultDescription
idYesNoneStable identifier, unique within the governance model.
nameYesNoneHuman-readable name, unique per governance model.
typeYesstaticMust be the literal string static.
optionsYesNoneArray of { code, description?, ancestor_path? }. Must hold at least one option unless allow_additions: true.
allow_additionsNofalseWhen true, submitters can propose new values while filling in a submission.
parent_idNoNoneWhen set, links this list to a parent static picklist and makes it the child side of a hierarchy. Every option must then carry an ancestor_path. See Hierarchical.
Option shape:
Option fieldRequiredDescription
codeYesNon-empty string, up to 100 characters. The value saved on records.
descriptionNoThe label shown in the dropdown. Safe to rename at any time.
ancestor_pathOnly on childrenOrdered array of parent option codes from root to immediate parent. Required on every option once parent_id is set.

​
Example

A flat UTM Sources picklist for the Campaign URL Builder: 
id: utm-sources
name: UTM Sources
type: static
allow_additions: true
options:
  - { code: newsletter, description: Newsletter }
  - { code: facebook,   description: Facebook }
  - { code: google,     description: Google }
Referenced from the utm_source dropdown field: 
name: utm_source
type: dropdown
required: true
settings:
  picklist_id: utm-sources
A submission with utm_source=facebook saves facebook on the record while the form shows the label Facebook. Because allow_additions is on, a submitter could also type reddit. It is held as a new value on that submission and becomes a real option on UTM Sources once the submission is approved.

​
Gotchas

  • Codes cannot be changed safely. Records hold the code, not an internal id. Renaming a code (say facebook to fb) leaves every record that used the old code without a matching option, so those values no longer show a label. Rename the label freely, treat codes as fixed.
  • Codes are unique per picklist, and per parent. Two top-level options cannot share a code, and neither can two children of the same parent. But two children under different parents can share a code, for example other under both email and social.
  • An empty list is allowed only with “Allow new values” on. Without allow_additions: true, a static picklist needs at least one option. With it on, you can ship an empty list and let submitters populate it.
  • New values are added on approval, gated by the published version. A proposed value becomes a real option only when its submission is approved, and only if the version the submission was filled against allowed additions. Toggling the switch after the fact does not change in-flight submissions.
  • Removing an option in the editor deletes it. When you remove an option through the editor and save, it is gone from the list. A value that was already selected on past records but is no longer an option counts as invalid for new submissions. Re-adding an option with the same code makes it valid again.
  • Renaming the picklist itself is safe. name is only a display label. The id is the stable reference that dropdowns and child picklists rely on.