Skip to main content

Documentation Index

Fetch the complete documentation index at: https://formhug.ai/docs/llms.txt

Use this file to discover all available pages before exploring further.

One field on a form, as returned in a form detail response. Every field returns the shared keys (label, api_code, notes, private, required, ...) plus its type-specific configuration determined by type — see the per-type sections below. The type-specific keys on read mirror what the same field type accepts on create / update, so a fetched form can be sent straight back through create / update without losing any setting.

​
type
enum<string>
required

Field type identifier. Determines which type-specific keys are present on the field.

Available options:
short_text
Example:

"short_text"

​
label
string
required
Example:

"Name"

​
api_code
string
required

Stable identifier of the field; used as the key for this field's value in entry payloads.

Always present on read. On form create / update, api_code is optional in the request body:

  • Omit to add a new field — the server auto-generates an api_code (e.g. field_3).
  • Provide an existing api_code to target an existing field for update; fields whose api_code is absent from the request are dropped.

The same rule applies to every other api_code-bearing sub-object on a field (e.g. choices, and statements/dimensions/levels of matrix, likert, cascade).

Example:

"field_1"

​
notes
string | null
required
Example:

"Please use your real name"

​
private
boolean
required

Whether the field is private

Example:

false

​
required
boolean
required
Example:

true

​
customized_validation_message
string | null
required

Override the default validation error message (max 50 chars). Null when not set.

​
predefined_value
string | null

Default value pre-filled when the form opens.

​
placeholder
string | null

Greyed hint text shown when empty.

​
answers
object[]

Scoring answers for this field. Only meaningful when the parent form's scene is exam or evaluation and the field type is one of the scorable types (radio, checkbox, dropdown, short_text, long_text, number, likert, rating).

  • exam: exactly one answer entry per field. For checkbox the answer array may carry multiple choice indices; for the other choice / text / number types it carries a single value. likert and rating are not supported in exam scene.
  • evaluation: applies to choice-bearing fields, likert, and rating. The answers array must contain one entry per scoreable position:
    • choice-bearing (radio / checkbox / dropdown) and likert: one entry per element of choices, positionally aligned (entry i scores the i-th choice). On read the answer key is a single-element array [<0-based choice position>]. On write the answer key is ignored (positional alignment with choices).
    • rating: one entry per rating level (size must equal rating_max, default 5), positionally aligned with levels 1..rating_max. On read the answer key is a single-element array [<0-based position>] (level − 1). On write the answer key is ignored.
​
answer_explanation
string | null

Optional explanation shown to respondents after grading. Only honored in exam scene.

Last modified on May 14, 2026