Skip to main content
The Choices field allows users to select a single option from a predefined list. This field type displays as radio buttons or a dropdown menu, ensuring users choose exactly one option from the available choices. Use Choices fields when you need to collect a single selection from a fixed set of possibilities — country, priority, status, category, or any scenario where only one option should be selected.

​
When to Use

Use Choices fields for:
  • Country or region selection
  • Priority levels (low, medium, high)
  • Categories or types
  • Status indicators
  • Gender or salutation
  • Yes/No questions with additional options
  • Industry or sector
  • Payment methods
  • Communication preferences
  • Urgency levels
Consider alternatives:
  • Use Multiple Choice for selecting multiple items
  • Use Checkbox for simple yes/no only
  • Use Text for free-form input

​
Configuration Options

OptionDescriptionTypeDefaultExample
keyUnique identifierStringRequiredcountry
nameDisplay labelStringRequired”Country”
descriptionHelp text for usersStringOptional”Select your country”
ai_descriptionHint for IntelligenceStringOptional”The country of residence”
optionsArray of available optionsArrayRequiredSee below
requiredMust select an optionBooleanfalsetrue
defaultDefault selected valueStringNonebelgium
visibilityDisplay settingStringalways-visiblehide-when-empty
sectionSection this field belongs toStringNoneSection UUID

​
Options Configuration

Each option in the options array:
PropertyDescriptionTypeRequiredExample
valueInternal value storedStringYesbelgium
labelDisplay text shown to userStringYes”Belgium”

​
Examples

​
Country Selection

Select a single country: 
{
  "key": "country",
  "type": "choices",
  "name": "Country",
  "description": "Select your country of residence",
  "required": true,
  "options": [
    {"value": "belgium", "label": "Belgium"},
    {"value": "france", "label": "France"},
    {"value": "germany", "label": "Germany"},
    {"value": "netherlands", "label": "Netherlands"},
    {"value": "luxembourg", "label": "Luxembourg"},
    {"value": "other", "label": "Other"}
  ],
  "ai_description": "The country where the person resides or where the company is registered, typically found in address sections or registration documents"
}

​
Priority Level

Set case priority: 
{
  "key": "priority",
  "type": "choices",
  "name": "Priority",
  "description": "How urgent is this request?",
  "default": "medium",
  "options": [
    {"value": "low", "label": "Low - Routine"},
    {"value": "medium", "label": "Medium - Normal"},
    {"value": "high", "label": "High - Urgent"},
    {"value": "critical", "label": "Critical - Immediate"}
  ],
  "ai_description": "The urgency or priority level assigned to this case or request"
}

​
Industry Sector

Select industry: 
{
  "key": "industry",
  "type": "choices",
  "name": "Industry Sector",
  "description": "Primary business sector",
  "required": true,
  "options": [
    {"value": "finance", "label": "Financial Services"},
    {"value": "healthcare", "label": "Healthcare"},
    {"value": "technology", "label": "Technology"},
    {"value": "manufacturing", "label": "Manufacturing"},
    {"value": "retail", "label": "Retail"},
    {"value": "real_estate", "label": "Real Estate"},
    {"value": "other", "label": "Other"}
  ],
  "ai_description": "The primary industry sector or business category of the company"
}

​
Yes/No/Maybe

Three-option choice: 
{
  "key": "renewal_intention",
  "type": "choices",
  "name": "Do you intend to renew?",
  "description": "Let us know your renewal plans",
  "options": [
    {"value": "yes", "label": "Yes, I will renew"},
    {"value": "no", "label": "No, I will not renew"},
    {"value": "undecided", "label": "Not sure yet"}
  ],
  "ai_description": "Whether the customer intends to renew their policy or contract"
}

​
Validation

Choices fields enforce single-selection validation:

​
Required Validation

  • If required: true, user must select an option
  • Empty selection not allowed
  • Useful for essential categorization

​
Option Validation

  • User can only select from predefined options
  • No free-form input
  • Ensures data consistency and enables automation logic

​
Stored Values

Choices fields store a single string value: Example stored data: 
{
  "country": "belgium"
}
Empty state: 
{
  "country": null
}
The stored value is the value from the selected option, not the label.

​
AI Descriptions

AI descriptions help Intelligence extract single selections from documents. For Choices fields: Be specific about:
  • What the choice represents
  • Where it typically appears in documents
  • Format (dropdown, checkbox, written text)
  • Common values or labels used
Good AI descriptions for Choices fields:
FieldAI Description
country”The country where the person resides or company is registered, typically found in address sections as a country name or two-letter code”
priority”The urgency or priority level (low, medium, high, critical) assigned to this case or request, often indicated in the subject line or header”
industry”The primary industry sector or business category (e.g., finance, healthcare, technology), typically found in company information sections”
payment_method”The selected payment method (bank transfer, credit card, direct debit), usually found in payment preferences or billing information”
claim_type”The type or category of claim being filed (property damage, liability, health, etc.), typically stated in the claim header or category field”
Mention common variations:
  • “Country name or two-letter code (BE, FR, DE)”
  • “Priority as text (high, urgent) or numeric (1-5)”
  • Include synonyms Intelligence might encounter
If documents might use different labels than your option labels, mention those variations in the AI description.

​
Choices in Automations

Choices fields enable powerful conditional workflows: Check for specific value: 
{
  "condition": {":eq": "{data.country}", "belgium"}
}
Check if value in set: 
{
  "condition": {":in": "{data.priority}", ["high", "critical"]}
}
Route based on selection:
  • Assign to country-specific team based on country
  • Escalate high-priority cases automatically
  • Show industry-specific steps based on industry
  • Apply different pricing based on category
Status transitions:
  • Move to “Urgent Queue” when priority is high
  • Route to specialist when specific industry selected
  • Apply different SLAs based on priority
Learn more about Automations →

​
Best Practices

Keep option lists manageable:
  • 3-12 options is ideal
  • More than 20 options: consider search functionality or text input
  • Group logically (alphabetically or by frequency)
Use clear, distinct labels:
  • Each option should be clearly different
  • Avoid similar or overlapping choices
  • Use consistent terminology
Always include “Other” when appropriate:
  • Provides escape hatch for unlisted options
  • Prevents forcing users into wrong category
  • Can trigger follow-up for details
Value vs Label clarity:
  • Values: short, technical, consistent (e.g., belgium)
  • Labels: friendly, readable (e.g., “Belgium”)
  • Values don’t change, labels can be updated
Order options logically:
  • Alphabetical for countries and names
  • Most common first for frequency-based
  • Logical progression for priority/urgency
  • Group related options together
Set defaults carefully:
  • Only set default if there’s a clear common choice
  • Don’t default to first option (users may not notice)
  • Leave blank when user should actively choose
Required vs Optional:
  • Mark required when choice is essential
  • Leave optional when “prefer not to say” is valid
  • Consider if “no selection” is a valid state

Multiple Choice

Use for selecting multiple options

Checkbox

Use for simple yes/no only

Text

Use when predefined options aren’t suitable

Data Schema Overview

Back to Data Schema overview