Field Types

AgentForms supports 8 field types. Every field shares common properties and has type-specific config options.

Common Properties

All field types share these base properties:

Property	Type	Required	Description
`key`	string	Yes	Identifier used as the key in response `data`
`type`	string	Yes	One of the 8 types listed below
`label`	string	Yes	Display label shown to the user (max 255 chars)
`description`	string	No	Helper text shown below the label
`required`	boolean	No	Whether the field must be filled. Default: `false`
`config`	object	No	Type-specific configuration (see each type below)

text

text Single-line text input

Config Options

Key	Type	Description
`placeholder`	string	Placeholder text
`max_length`	integer	Maximum character count (enforced server-side)
`pattern`	string	Regex pattern (matched with Python `re.match()`)

Example

JSON

{
  "key": "full_name",
  "type": "text",
  "label": "Full Name",
  "required": true,
  "config": {
    "placeholder": "Jane Doe",
    "max_length": 100
  }
}

Response data: "full_name": "Jane Doe" (string)

textarea

textarea Multi-line text input

Config Options

Key	Type	Description
`placeholder`	string	Placeholder text
`max_length`	integer	Maximum character count
`rows`	integer	Display height in rows (default: 4)

Example

JSON

{
  "key": "bio",
  "type": "textarea",
  "label": "Tell us about yourself",
  "config": {
    "placeholder": "A few sentences...",
    "max_length": 500,
    "rows": 6
  }
}

Response data: "bio": "I'm a software engineer..." (string)

number

number Numeric input

Config Options

Key	Type	Description
`min`	number	Minimum allowed value
`max`	number	Maximum allowed value
`step`	number	Increment step

Example

JSON

{
  "key": "rating",
  "type": "number",
  "label": "Rating (1-10)",
  "required": true,
  "config": {
    "min": 1,
    "max": 10,
    "step": 1
  }
}

Response data: "rating": 8 (int if no decimal, float otherwise)

email

email Email address input

Config Options

Key	Type	Description
`placeholder`	string	Placeholder text

Validation: Server-side regex ^[^@\s]+@[^@\s]+\.[^@\s]+$.

Example

JSON

{
  "key": "email",
  "type": "email",
  "label": "Email Address",
  "required": true,
  "config": {
    "placeholder": "[email protected]"
  }
}

Response data: "email": "[email protected]" (string)

select

select Single-choice dropdown

Config Options

Key	Type	Required	Description
`options`	array of strings	Yes	Allowed values for the dropdown

Validation: The submitted value must be one of the listed options.

Example

JSON

{
  "key": "department",
  "type": "select",
  "label": "Department",
  "required": true,
  "config": {
    "options": ["Engineering", "Design", "Marketing", "Sales"]
  }
}

Response data: "department": "Engineering" (string)

multi_select

multi_select Multiple-choice selection

Config Options

Key	Type	Required	Description
`options`	array of strings	Yes	Allowed values

Validation: Every selected value must be in the options list.

Example

JSON

{
  "key": "skills",
  "type": "multi_select",
  "label": "Skills",
  "config": {
    "options": ["Python", "JavaScript", "Rust", "Go"]
  }
}

Response data: "skills": ["Python", "Rust"] (array of strings)

date

date Date picker

Config Options

Key	Type	Description
`min_date`	string	Earliest allowed date (`YYYY-MM-DD`)
`max_date`	string	Latest allowed date (`YYYY-MM-DD`)

Validation: Must match YYYY-MM-DD format and be a valid calendar date. Bounds checked server-side.

Example

JSON

{
  "key": "start_date",
  "type": "date",
  "label": "Start Date",
  "required": true,
  "config": {
    "min_date": "2026-01-01",
    "max_date": "2026-12-31"
  }
}

Response data: "start_date": "2026-06-15" (string, YYYY-MM-DD)

checkbox

checkbox Boolean checkbox

Config Options

No type-specific config options. The config object can be empty or omitted.

Aliases: You can also use "boolean" or "bool" as the type — the API normalizes them to "checkbox".

Validation: When required: true, the box must be checked. Values "on", "true", "1" are coerced to true. Unchecked or absent is false.

Example

JSON

{
  "key": "agree_tos",
  "type": "checkbox",
  "label": "I agree to the Terms of Service",
  "required": true
}

Response data: "agree_tos": true (boolean)

Complete Example

A form using every field type in a single API call:

JSON

{
  "title": "Full Demo Form",
  "fields": [
    {"key": "name", "type": "text", "label": "Name", "required": true, "config": {"max_length": 100}},
    {"key": "bio", "type": "textarea", "label": "Bio", "config": {"rows": 6}},
    {"key": "age", "type": "number", "label": "Age", "config": {"min": 0, "max": 150}},
    {"key": "email", "type": "email", "label": "Email", "required": true},
    {"key": "dept", "type": "select", "label": "Dept", "config": {"options": ["Eng", "Sales"]}},
    {"key": "tags", "type": "multi_select", "label": "Tags", "config": {"options": ["A", "B", "C"]}},
    {"key": "dob", "type": "date", "label": "DOB", "config": {"min_date": "1900-01-01"}},
    {"key": "agree", "type": "checkbox", "label": "I agree", "required": true}
  ]
}