Question types

Flashpoint.AI supports twenty question types, from simple single-select to choice-based conjoint. Each type maps to a structured answer schema so downstream analysis works without custom parsers.

Every question lives inside a block (section). When adding questions via the API or the agent, you specify the type string exactly as shown below.

Choice questions

select (single)

Single-select: respondent picks exactly one option from a list. Use for mutually exclusive choices like gender, purchase intent scales, or yes/no gates.

Field	Required	Description
`type`	yes	`"select"`
`subtype`	yes	`"single"`
`text`	yes	Question prompt
`options`	yes	Array of options (min 2). Each: `{text, type?}`
`config.ui`	no	`"radio"` (default), `"dropdown"`
`config.randomize`	no	Shuffle option order per respondent

curl -X PATCH https://surveys.flashpoint.ai/api/v1/surveys/{survey_id} \
  -H "X-Service-Token: $TOKEN" \
  -H "X-Team-ID: $TEAM_ID" \
  -H "X-User-ID: $USER_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "document": {
      "blocks": [{
        "name": "Screener",
        "questions": [{
          "type": "select",
          "subtype": "single",
          "text": "How often do you purchase coffee?",
          "options": [
            {"text": "Daily"},
            {"text": "A few times a week"},
            {"text": "Weekly"},
            {"text": "Rarely"},
            {"text": "Never"}
          ]
        }]
      }]
    }
  }'

Agent prompt: "Add a single-select question asking how often they purchase coffee, with options Daily, A few times a week, Weekly, Rarely, Never"

select (multi)

Multi-select: respondent picks one or more options. Use for "select all that apply" questions.

Field	Required	Description
`type`	yes	`"select"`
`subtype`	yes	`"multi"`
`options`	yes	Array of options (min 2)
`config.maxSelections`	no	Cap on number of selections
`config.minSelections`	no	Minimum selections required

Special option types: set "type": "nota" for "None of the above" (exclusive — clears other selections) or "type": "other" for a write-in field.

Agent prompt: "Add a multi-select asking which streaming services they use: Netflix, Hulu, Disney+, HBO Max, Amazon Prime Video, None of the above"

Open-ended questions

text (single)

Single open-ended text input. Use for verbatim feedback, explanations, or follow-up probes.

Field	Required	Description
`type`	yes	`"text"`
`subtype`	no	`"single"` (default)
`text`	yes	Question prompt

No options are accepted. The respondent types a free-form answer.

Agent prompt: "Add an open-ended question asking what they liked most about the product"

text (multi)

Multiple labeled text inputs in a single question. Use when you need several short answers grouped together (e.g., "List three words that describe this brand").

Field	Required	Description
`type`	yes	`"text"`
`subtype`	yes	`"multi"`
`config.inputs`	yes	Array of `{label, helper}` objects (min 1)

{
  "type": "text",
  "subtype": "multi",
  "text": "List three words that describe this brand.",
  "config": {
    "inputs": [
      {"label": "Word 1", "helper": "First word"},
      {"label": "Word 2", "helper": "Second word"},
      {"label": "Word 3", "helper": "Third word"}
    ]
  }
}

Agent prompt: "Add a multi-text question asking them to list three words that describe the brand"

contact-form

Structured contact fields. Each input has a fixed label from the set: firstname, lastname, phone, email, company, title.

Field	Required	Description
`type`	yes	`"contact-form"`
`config.inputs`	yes	Array of `{label, helper}` where label is one of the six field names

Agent prompt: "Add a contact form collecting first name, last name, email, and company"

Numeric questions

number

General numeric input with optional range validation.

Field	Required	Description
`type`	yes	`"number"`
`config.datarange`	no	`[min, max]` — use `null` for unbounded. Default: `[null, null]`

Agent prompt: "Add a number question asking their household size, between 1 and 20"

percentage

Percentage input, defaulting to a 0-100 range.

Field	Required	Description
`type`	yes	`"percentage"`
`config.datarange`	no	Default: `[0, 100]`

Agent prompt: "Ask what percentage of their commute is by car"

year

Year input with a default minimum of 1900.

Field	Required	Description
`type`	yes	`"year"`
`config.datarange`	no	Default: `[1900, null]`

Agent prompt: "Ask what year they were born"

currency

Currency amount input with an ISO 4217 currency code.

Field	Required	Description
`type`	yes	`"currency"`
`config.currency`	no	3-letter ISO code. Default: `"USD"`

Agent prompt: "Ask how much they spent on groceries last week in USD"

zipcode

Postal code input with country-specific validation.

Field	Required	Description
`type`	yes	`"zipcode"`
`config.country`	no	2-letter ISO 3166-1 alpha-2 code. Default: `"US"`

Agent prompt: "Add a zipcode question for their home address"

Allocation questions

percent-sum

Respondent allocates percentages across items that must total 100. Use for budget allocation, time split, or preference distribution.

Field	Required	Description
`type`	yes	`"percent-sum"`
`config.inputs`	yes	Array of `{label, helper}` (min 2). Each becomes a percentage input

{
  "type": "percent-sum",
  "text": "How do you split your work time across these activities?",
  "config": {
    "inputs": [
      {"label": "Meetings", "helper": "Meetings"},
      {"label": "Deep work", "helper": "Deep work"},
      {"label": "Email", "helper": "Email"},
      {"label": "Admin", "helper": "Admin"}
    ]
  }
}

Agent prompt: "Add a percent-sum question asking how they split their work time across Meetings, Deep work, Email, and Admin"

multi-percentage

Multiple independent percentage inputs (they do not need to sum to 100). Use when you need several percentage estimates that are unrelated.

Field	Required	Description
`type`	yes	`"multi-percentage"`
`config.inputs`	yes	Array of `{label, helper}` (min 2)

Agent prompt: "Add a multi-percentage question asking the likelihood of purchasing each product"

Ranking

ranking

Drag-to-rank: respondent orders items by preference. Use for priority rankings, feature importance, or brand preference.

Field	Required	Description
`type`	yes	`"ranking"`
`options`	yes	Array of options to rank (min 2)

Agent prompt: "Add a ranking question asking them to rank these features by importance: Battery life, Camera quality, Screen size, Price, Durability"

Grid / matrix

grid (single)

Matrix question with single-select per row. Rows are the items being rated; columns are the rating scale.

Field	Required	Description
`type`	yes	`"grid"`
`subtype`	no	`""` (default) for single-select per row
`options`	yes	Object: `{vertical: [{text}], horizontal: [{text}]}`

{
  "type": "grid",
  "subtype": "",
  "text": "Rate each brand on the following attributes.",
  "options": {
    "vertical": [
      {"text": "Nike"},
      {"text": "Adidas"},
      {"text": "New Balance"}
    ],
    "horizontal": [
      {"text": "Quality"},
      {"text": "Style"},
      {"text": "Value"},
      {"text": "Innovation"}
    ]
  }
}

Agent prompt: "Add a grid question rating Nike, Adidas, and New Balance on Quality, Style, Value, and Innovation"

grid (multi)

Matrix with multi-select per row. Same structure, but respondents can pick multiple columns per row.

Field	Required	Description
`type`	yes	`"grid"`
`subtype`	yes	`"multi"`
`options`	yes	Same nested structure as single grid

Agent prompt: "Add a multi-select grid asking which features each product has"

Advanced research types

nps

Net Promoter Score. Pre-configured 0-10 scale with Detractor/Passive/Promoter classification. No config or options needed — the scale is built in.

Field	Required	Description
`type`	yes	`"nps"`
`text`	yes	Question prompt (conventionally "How likely are you to recommend...")

Agent prompt: "Add an NPS question for our customer service team"

maxdiff

Best-worst scaling exercise. Respondents see subsets of items and pick the best and worst in each set. The experimental design (which items appear in which sets) is auto-generated.

Field	Required	Description
`type`	yes	`"maxdiff"`
`options`	yes	Full list of items (min 4)
`config.sets`	yes	Number of choice sets shown per respondent
`config.designs`	yes	Number of randomized design variants (typically 5-10)
`config.features`	yes	Items shown per set (typically 3-5)
`config.lowerText`	no	Label for "worst" pole. Default: `"Least Important"`
`config.upperText`	no	Label for "best" pole. Default: `"Most Important"`

The config.ranking array (the experimental design) is auto-generated from the parameters. Do not set it manually.

{
  "type": "maxdiff",
  "text": "Which product features are most and least important to you?",
  "options": [
    {"text": "Battery life"},
    {"text": "Camera quality"},
    {"text": "Screen size"},
    {"text": "Storage capacity"},
    {"text": "Water resistance"},
    {"text": "Processor speed"}
  ],
  "config": {
    "sets": 4,
    "designs": 5,
    "features": 3,
    "lowerText": "Least Important",
    "upperText": "Most Important"
  }
}

Agent prompt: "Add a maxdiff with 6 phone features: Battery life, Camera quality, Screen size, Storage, Water resistance, Processor speed. Show 3 per set, 4 sets, 5 designs."

conjoint

Choice-based conjoint analysis. Respondents choose between product profiles defined by combinations of attribute levels. The experimental design is auto-generated.

Field	Required	Description
`type`	yes	`"conjoint"`
`config.sets`	yes	Choice sets per respondent
`config.designs`	yes	Number of design variants
`config.features`	yes	Profiles per choice set (typically 2-4)
`config.attributes`	yes	Array of attributes, each with `text` and `levels: [{text}]` (min 2 attributes, min 2 levels each)

{
  "type": "conjoint",
  "text": "Which laptop would you prefer?",
  "config": {
    "sets": 6,
    "designs": 8,
    "features": 3,
    "attributes": [
      {
        "text": "Brand",
        "levels": [{"text": "Apple"}, {"text": "Dell"}, {"text": "Lenovo"}]
      },
      {
        "text": "Price",
        "levels": [{"text": "$999"}, {"text": "$1,299"}, {"text": "$1,599"}]
      },
      {
        "text": "Screen Size",
        "levels": [{"text": "13 inch"}, {"text": "15 inch"}]
      }
    ]
  }
}

Agent prompt: "Create a conjoint for laptops with attributes Brand (Apple, Dell, Lenovo), Price ($999, $1299, $1599), and Screen Size (13in, 15in). 6 sets, 8 designs, 3 profiles per set."

van-westendorp

Price Sensitivity Meter. Four price questions that together reveal acceptable price ranges. The four inputs must map to: too cheap, bargain, expensive, too expensive.

Field	Required	Description
`type`	yes	`"van-westendorp"`
`config.inputs`	yes	Exactly 4 inputs, each with `label` (short id) and `helper` (displayed question text)
`config.currency`	no	ISO 4217 currency code. Default: `"USD"`

{
  "type": "van-westendorp",
  "text": "Thinking about this product, at what price would you say...",
  "config": {
    "currency": "USD",
    "inputs": [
      {"label": "1", "helper": "It is so cheap that you would question its quality?"},
      {"label": "2", "helper": "It is a bargain -- a great buy for the money?"},
      {"label": "3", "helper": "It is starting to get expensive but you would still consider it?"},
      {"label": "4", "helper": "It is too expensive to consider?"}
    ]
  }
}

Agent prompt: "Add a van-westendorp price sensitivity question for our new product"

Structural types

transition

Display-only screen with text or instructions between sections. No answer is collected. Use to introduce a new topic or provide context.

Field	Required	Description
`type`	yes	`"transition"`
`text`	yes	Content to display

Agent prompt: "Add a transition screen introducing the product evaluation section"

terminate

Ends the survey immediately. Used as a routing destination for disqualification logic. Auto-labels as S1, S2, etc.

Field	Required	Description
`type`	yes	`"terminate"`
`text`	yes	Message shown on termination (e.g., "Thank you for your time.")

Agent prompt: "Add a terminate screen that says 'Thank you for your interest, but you do not qualify for this survey.'"

variable

Hidden computed field. Stores a DSL expression that is evaluated at runtime from other question answers. Not shown to respondents. Used for computed routing, scoring, or downstream data enrichment.

Field	Required	Description
`type`	yes	`"variable"`
`text`	yes	Internal description of what the variable computes

Variables are typically added after all questions exist, since their definitions reference other question labels.

Agent prompt: "Add a variable that computes a satisfaction score from Q3 and Q5"

ai-chat

Conversational AI follow-up. Opens a freeform chat interface where the AI probes deeper based on prior answers. Use for qualitative depth on key topics.

Field	Required	Description
`type`	yes	`"ai-chat"`
`text`	yes	The AI's opening prompt

Agent prompt: "Add an AI chat follow-up asking them to elaborate on their product experience"

Common configuration

These fields apply across all question types.

Field	Type	Default	Description
`label`	string	Auto (`Q1`, `Q2`...)	Stable identifier used in skip logic and data exports
`config.required`	bool	`true`	Whether the question must be answered
`config.randomize`	bool	`false`	Shuffle option order per respondent
`optout`	object	none	`{allowed: true, text: "Prefer not to say"}` adds a skip button
`condition`	string	none	DSL display condition — see Skip logic
`skips`	array	`[]`	Skip/branch rules — see Skip logic

Option types

Options in choice-based questions support a type field:

Type	Behavior
`"user"`	Standard option (default)
`"other"`	Write-in: shows a text input when selected
`"nota"`	"None of the above": exclusive — deselects all others when chosen
`"dontknow"`	"Don't know" option
`"optout"`	Opt-out option
`"notapplicable"`	"Not applicable" option

Next steps

Add branching and screening: Skip logic & conditions
Control sample composition: Quotas
Build surveys conversationally: Agent