Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Form structure & conditional logic

A form is an ordered list of steps, each holding an ordered list of questions. This is the shape you send when creating or updating a form, and the same shape GET /v2/forms/{id} returns — one model, both directions.

The shape

{
  "steps": [
    {
      "type": "custom",
      "name": "Applicant",
      "segment": "before",
      "position": 2,
      "questions": [
        { "type": "short_text", "label": "Full name", "required": true, "field_mapping": "FullName" }
      ]
    }
  ]
}
Step field
Description

type

welcome, custom, carrier_select, or confirmation.

name

Display name for the step.

segment

Where the step sits relative to the (optional) carrier-connect flow: before, carrier, or after.

position

Order among the form's steps.

questions[]

The ordered questions in this step — see below.

Question fields

Field
Description

type

short_text, long_text, email, number, date, dropdown, single_choice, multi_choice, file_upload, address, data_table.

label, placeholder

Display text.

required

Whether an answer is mandatory.

options

Choices, for dropdown / single_choice / multi_choice.

field_mapping

Maps the answer to a known field InsurGrid recognizes: FullName, Email, Phone, ServiceType, EventDate.

validation

Per-question validation: { "min": 1, "max": 100 } or { "pattern": "^[0-9]{5}$" }.

column_schema

Column definitions, for a data_table question.

rules

Conditional logic — see below.

New term — field_mapping: tells InsurGrid a question's answer corresponds to a well-known field (like the respondent's email), independent of however you worded the question's label. Use it so downstream consumers — like ACORD generation — know which answer is "the email," even if you labeled the question "Best way to reach you."

Conditional logic (rules)

Any question can carry rules that show, hide, require, skip, or end the form based on an earlier answer.

Rule field
Description

condition_mode

all (AND) or any (OR) across the rule's conditions.

conditions[]

Each: { source_question_id, operator, value }.

operator

equals, notEquals, contains, notContains, isEmpty, isNotEmpty, greaterThan, lessThan, before, after.

action

show, hide, require, skip_to_step, end_form, continue.

target_question_id / target_step_id

Where the action applies — for example, which step to skip to.

Worked example: show a question only when an earlier answer equals a value

Say your form asks whether a policy is personal or commercial, and you only want to ask for a legal entity name when the answer is "Commercial":

Walking through it:

  1. "Policy kind" is a single_choice question with two options.

  2. "Legal entity name" starts hidden (initially_hidden: true).

  3. Its rules say: when question q-policy-kind's answer equals "Commercial", show this question.

  4. Pick "Personal" and the field stays hidden. Pick "Commercial" and it appears.

Combine multiple conditions with condition_mode: "any" to show a question when any one of several earlier answers matches, or chain skip_to_step rules to route respondents down different step sequences entirely.

Consistency across create, update, and read

The exact same steps / questions / rules shape is used in POST /v2/forms, PATCH /v2/forms/{id}, and the response from GET /v2/forms/{id}. Implement the model once — parse it, build a form from it, or render a preview — and it works in every direction.

Related

PreviousOwnership model (agency vs agent)
NextThe two embeds