Form Field

Discriminated union of all field types that can appear on a form. The concrete variant is selected by type.

Short Text

Long Text

Radio

Checkbox

Dropdown

Number

Email

Phone

Date

Name

URL

Address

Rating

NPS

Upload

Cascade

Ranking

Matrix Input

Likert Scale

Time

Location

Signature

Grid Rating

Table

Product

Booking

Linked Form

Page Break

Description

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.

Show child attributes

answer_explanation · string | null

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