Question types

Flashpoint.AI supports twenty-four question types, from simple single-select to choice-based conjoint and image-based stimuli. 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"

Picture-based choices? When the options are images rather than text, use image carousel or image hotspot — see Image questions.

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"

Rating images? To rate a set of images on a scale, use image rating — a grid whose rows are pictures. See Image questions.

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."

Comparing images? For a MaxDiff over pictures (including simple A‑vs‑B pairs), use image comparison — see Image questions.

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"

Image questions

Image questions use pictures as the stimulus instead of text. Under the hood they are subtypes of the choice, grid, and MaxDiff families, so they share the same answer schema and analysis as their parent type — they just render images and require an image on every stimulus.

Add the images in the builder (upload, AI‑generate, or pick a stock photo). Each image is normalized and hosted on the Flashpoint CDN, and referenced by its URL: media_url on an option (the picture for that choice), or config.image_url for a single base image. If any required image is missing, the survey will not validate.

image carousel

Single‑ (or multi‑) select where each option is an image, shown in a swipeable carousel. Use for pack tests, ad/creative selection, or "pick the design you prefer."

Field	Required	Description
`type`	yes	`"select"`
`subtype`	yes	`"image_carousel"`
`text`	yes	Question prompt
`options`	yes	Array (min 2). Each: `{text, media_url}`. Every option requires `media_url` (the image); `text` is the caption
`config.selection`	no	`"single"` (default) or `"multi"`
`config.show_captions`	no	Show each option's `text` as a caption. Default `true`
`config.allow_zoom`	no	Allow tap/click to zoom an image. Default `true`

{
  "type": "select",
  "subtype": "image_carousel",
  "text": "Which packaging design do you prefer?",
  "options": [
    {"text": "Design A", "media_url": "https://cdn.flashpoint.ai/.../design-a.webp"},
    {"text": "Design B", "media_url": "https://cdn.flashpoint.ai/.../design-b.webp"},
    {"text": "Design C", "media_url": "https://cdn.flashpoint.ai/.../design-c.webp"}
  ],
  "config": {"selection": "single", "show_captions": true, "allow_zoom": true}
}

Agent prompt: "Add an image carousel asking which of three packaging designs they prefer." (Then upload or generate the image for each option.)

image hotspot

Respondents click one or more regions on a single base image. Use for "tap what catches your eye," shelf/planogram tests, or pointing at parts of a design.

Field	Required	Description
`type`	yes	`"select"`
`subtype`	yes	`"image_hotspot"`
`text`	yes	Question prompt
`config.image_url`	yes	URL of the base image the regions sit on
`options`	yes	One per clickable region. Each: `{text, coords}` where `coords` is `{x, y, w, h}` as percentages (0–100) of the base image
`config.selection`	no	`"single"` (default) or `"multi"`

{
  "type": "select",
  "subtype": "image_hotspot",
  "text": "Tap the area of the shelf you would reach for first.",
  "config": {
    "image_url": "https://cdn.flashpoint.ai/.../shelf.webp",
    "selection": "single"
  },
  "options": [
    {"text": "Top shelf", "coords": {"x": 5, "y": 4, "w": 90, "h": 28}},
    {"text": "Middle shelf", "coords": {"x": 5, "y": 36, "w": 90, "h": 28}},
    {"text": "Bottom shelf", "coords": {"x": 5, "y": 68, "w": 90, "h": 28}}
  ]
}

The builder includes a visual region editor — draw rectangles on the base image and the coordinates are filled in for you.

Agent prompt: "Add an image hotspot on the shelf photo asking which area they would reach for first." (Then upload the base image and draw the regions.)

image rating

A grid whose rows are images and columns are a rating scale. Use to rate a set of creatives, products, or logos on the same scale.

Field	Required	Description
`type`	yes	`"grid"`
`subtype`	yes	`"image_rating"`
`text`	yes	Question prompt
`options`	yes	`{vertical: [...rows], horizontal: [...columns]}`. Every `vertical` row requires `media_url`; `horizontal` columns are the rating labels

{
  "type": "grid",
  "subtype": "image_rating",
  "text": "Rate each ad on how appealing it is.",
  "options": {
    "vertical": [
      {"text": "Ad 1", "media_url": "https://cdn.flashpoint.ai/.../ad-1.webp"},
      {"text": "Ad 2", "media_url": "https://cdn.flashpoint.ai/.../ad-2.webp"}
    ],
    "horizontal": [
      {"text": "Not at all appealing"},
      {"text": "Somewhat appealing"},
      {"text": "Very appealing"}
    ]
  }
}

Agent prompt: "Add an image rating grid to rate each of these ads on a 3-point appeal scale." (Then upload an image for each row.)

image comparison

A MaxDiff where the items are images. With two images per set it is a simple A‑vs‑B pairwise comparison; with more, it is best‑worst scaling over images. Use for preference testing across many creatives.

Field	Required	Description
`type`	yes	`"maxdiff"`
`subtype`	yes	`"image_compare"`
`options`	yes	Full list of image items (min 4). Each: `{text, media_url}`. Every item requires `media_url`
`config.sets`	yes	Choice sets shown per respondent
`config.designs`	yes	Number of randomized design variants
`config.features`	yes	Images per set — use `2` for A‑vs‑B pairwise

{
  "type": "maxdiff",
  "subtype": "image_compare",
  "text": "In each pair, which image do you prefer?",
  "options": [
    {"text": "Image 1", "media_url": "https://cdn.flashpoint.ai/.../1.webp"},
    {"text": "Image 2", "media_url": "https://cdn.flashpoint.ai/.../2.webp"},
    {"text": "Image 3", "media_url": "https://cdn.flashpoint.ai/.../3.webp"},
    {"text": "Image 4", "media_url": "https://cdn.flashpoint.ai/.../4.webp"}
  ],
  "config": {"sets": 6, "designs": 5, "features": 2}
}

Agent prompt: "Add an image comparison over these 6 creatives, shown 2 at a time, 6 sets, 5 designs." (Then upload an image for each item.)

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