Form Fields

The fields array contains objects that represent individual questions in the survey. Each object must include a display_type that determines how the input renders on the device.

Common Properties

These properties apply to all field types.

Property	Type	Required	Description
question	string	Yes	The label or question text shown to the user
display_type	string	Yes	How the input renders (see Display Types)
data_type	string	Yes	The data type of the value (see Data Types)
key	string	Yes	Unique identifier for the field, used in conditionals. Must be unique across all fields
required	boolean	Yes	Whether the field must be filled before submission
section	string	No	The id of the page this field appears on
hint	string	No	Helper text displayed beneath the field
placeholder	string	No	Placeholder text shown inside the input
entry_title	boolean	No	If true, this field's value is used as the display title for the collected entry
regex	string	No	A regular expression pattern the value must match. Backslashes must be double-escaped (e.g. \\d)
column_name	string	No	Column name to use for this field's value in exported data, instead of key
auto_populate	boolean	No	If true, the value is filled in automatically (e.g. the enumerator from the login, or the date on submission)

Data Types

Data Type	Used with	Description
text	Text inputs, drop_down, radio	A single string value
number	number, range	A numeric value
array	checkbox	A list of selected values
date	date	A calendar date
file	image	A captured file, such as a photo

Choice-Based Properties

Used with drop_down, radio, and checkbox fields.

Property	Type	Required	Description
choices	array | object	Yes	The selectable option values. Use an object to group choices
sub_key	string	With grouped choices	Key that stores the option chosen within a group
default_value	array	No	Pre-selected value(s). Must always be an array, even for single-select fields

{
  "question": "What is the type of house?",
  "display_type": "radio",
  "data_type": "text",
  "key": "type_of_house",
  "required": true,
  "hint": "Select the type of house",
  "default_value": ["BUNGALOW"],
  "choices": ["BUNGALOW", "APARTMENT", "DETACHED", "SEMI-DETACHED"],
  "entry_title": false
}

Grouped Choices

For long, two-level lists, choices can be an object. Each property name is a group, and its array holds the options in that group. The user first picks a group, then an option within it.

The group is saved under the field's key. The option chosen within the group is saved under sub_key, which must be unique across the survey like any other key.

{
  "key": "land_use",
  "sub_key": "detail_land_use",
  "question": "Primary Land Use",
  "display_type": "drop_down",
  "data_type": "text",
  "required": true,
  "choices": {
    "Residential": [
      "Low-density housing (detached / bungalow)",
      "Traditional / mud house",
      "Other"
    ],
    "Commercial": [
      "Retail shop / supermarket",
      "Open market / stalls",
      "Other"
    ]
  }
}

An entry with Commercial → Open market / stalls saves land_use as "Commercial" and detail_land_use as "Open market / stalls". Conditionals can test either key; see Grouped Choices in Conditionals.

Numeric & Text Properties

Used with text_field, text_area, and range fields.

Property	Type	Description
min_length	number	Minimum number of characters (text) or minimum value (range)
max_length	number	Maximum number of characters (text) or maximum value (range)
from	number	The starting value of a range input
to	number	The ending value of a range input
step	number	The increment between values in a range input

{
  "question": "What is your age?",
  "display_type": "range",
  "data_type": "number",
  "key": "age",
  "from": 1,
  "to": 100,
  "step": 1,
  "required": true
}

Display Types

The display_type property controls how the field renders in the mobile app.

Display Type	Description	Properties
text_field	Single-line text input	min_length, max_length, regex
text_area	Multi-line text input	min_length, max_length
drop_down	Single-select dropdown list	choices, default_value
radio	Single-select radio buttons	choices, default_value
checkbox	Multi-select checkboxes	choices, default_value
number	Numeric input with number keyboard	default_value
range	Numeric slider	from, to, step
date	Date picker	—
email	Email address input with keyboard optimization	regex
phone	Phone number input with numeric keyboard	regex
image	Image capture input	—