Study Guide Reference

How to structure the studyGuide payload: blocks, question types, screening, concepts, conditional logic, and carry-forward

The studyGuide field of Create Study defines everything participants see: the questions, their order, screening, concept testing, and routing logic. It’s an array of blocks, and each block contains one or more items (questions).

Minimal study

{
  "title": "Coffee habits interview",
  "studyGuide": [
    {
      "type": "flat",
      "title": "Main questions",
      "items": [
        { "type": "open_ended", "text": "Walk me through your morning coffee routine." }
      ]
    }
  ]
}

Top-level request fields

title · string · required

Internal study title (shown in the dashboard).

externalTitle · string

Participant-facing title. Falls back to title when omitted.

background · string

Background context for the AI interviewer — what the study is about and who you’re talking to.

studyGoal · string

What you want to learn. Helps the AI interviewer probe in the right direction.

config · Config

Interview mode, languages, and platform targeting. See Config.

welcomeMessage · object

{ "title": "...", "message": "..." } shown to participants before the interview starts.

closingMessage · string

Message shown when the interview ends.

studyGuide · Block[] · required

The blocks described below. At least one.

Config

interviewMode · string

One of text, audio, audio_text, audio_screen, video, video_screen.

questionLanguage · string

Language code the questions are written in (e.g. en, de, fr, es, zh-TW, en-medical). See the complete language list.

availableLanguages · string[] | null

Translation target codes participants can switch to. null or omitted = English only.

targetPlatforms · string[]

Restrict which devices can take the study: any of ios, android, desktop.

Example config

{
  "config": {
    "interviewMode": "audio_text",
    "questionLanguage": "en",
    "availableLanguages": ["en", "de", "fr"],
    "targetPlatforms": ["desktop"]
  }
}

Blocks

Every block has a type, a title, and an items array (at least one item).

Type	Purpose
flat	A plain sequence of questions.
screening	Qualifies participants before the interview. At most one, and it must be the first block.
concept	Shows each participant one or more concepts (stimuli) and asks the block’s questions about them. Requires conceptSamplingConfig.

Screening blocks

Screening blocks may contain only multiple_choice items, and every option must carry a status:

• approve — selecting it qualifies the participant
• reject — selecting it screens the participant out
• neutral — doesn’t affect qualification

Screening block

{
  "type": "screening",
  "title": "Screener",
  "items": [
    {
      "externalId": "coffee-frequency",
      "type": "multiple_choice",
      "text": "How often do you drink coffee?",
      "options": [
        { "externalId": "opt-daily", "text": "Every day", "status": "approve" },
        { "text": "A few times a week", "status": "approve" },
        { "text": "Rarely or never", "status": "reject" }
      ]
    }
  ]
}

Outside screening blocks, status must be null or omitted.

Concept blocks

Concept blocks show stimuli — product ideas, ads, prototypes — and ask the block’s items about each one. They require a conceptSamplingConfig with at least one concept; other block types must omit it.

concepts · Concept[] · required

Each concept has a nickname (internal label) and content: a participant-facing title, optional description, optional media (images/videos), and an optional embed (e.g. a Figma prototype URL).

subsampleCount · integer | null

How many concepts each participant sees, randomly sampled. null = every participant sees all concepts.

Each concept can also carry a conditional, so it’s only shown to participants matching the criteria — e.g. gate each concept on a screener answer. selectedTemplateOptions criteria on a concept must reference an item in a block before the concept block.

Concept block

{
  "type": "concept",
  "title": "Packaging concepts",
  "conceptSamplingConfig": {
    "subsampleCount": 2,
    "concepts": [
      {
        "nickname": "minimal",
        "content": {
          "title": "Minimal design",
          "description": "Clean white packaging with a single accent color.",
          "media": [
            { "name": "minimal.png", "url": "https://example.com/minimal.png", "type": "image" }
          ]
        }
      },
      {
        "nickname": "bold",
        "content": {
          "title": "Bold design",
          "embed": { "url": "https://www.figma.com/proto/..." }
        },
        "conditional": {
          "operator": "and",
          "criteria": [
            {
              "type": "selectedTemplateOptions",
              "questionId": "coffee-frequency",
              "matchingCriteria": "mustSelect",
              "choices": ["opt-daily"]
            }
          ]
        }
      }
    ]
  },
  "items": [
    { "type": "open_ended", "text": "What's your first impression of this design?" }
  ]
}

Question types

All items share a few common fields:

text · string · required

The question text.

type · string · required

One of open_ended, multiple_choice, ranking, matrix, max_diff, statement.

externalId · string

Stable identifier for the item, unique within the payload. Auto-generated when omitted — set it only when a conditional or carryForwardFrom needs to reference this item.

conditional · Conditional | null

Show this question only when the criteria match. See Conditional logic.

media · Media[] | null

Images or videos shown with the question: { "name", "url", "type": "image" | "video", "widthPercentage"?, "forceWatching"? }. forceWatching requires the participant to finish the video before answering.

embed · Embed | null

An embedded web page shown with the question: { "url", "proxyUrl"? }.

Open-ended

The AI interviewer asks the question conversationally and can probe with follow-ups.

followUp · string | null

Follow-up depth: none, light, medium, or heavy.

addInstructions · string | null

Extra instructions for the AI interviewer on how to probe this question.

preferredInput · string | null

text, voice, screenRecording, or none.

screenObservationEnabled · boolean | null

Lets the AI observe the participant’s screen while they answer. Only applies when preferredInput is screenRecording.

Open-ended

{
  "type": "open_ended",
  "text": "Tell me about the last time you switched coffee brands.",
  "followUp": "medium",
  "addInstructions": "Probe for what triggered the switch and what almost stopped them.",
  "preferredInput": "voice"
}

Multiple choice

options · Option[]

Required unless carryForwardFrom is set. Each option: { "text", "externalId"?, "status"?, "exclusiveOption"? }.

multiSelect · boolean | null

Allow selecting more than one option.

minSelect / maxSelect · integer | null

Bounds on how many options must be selected. Both must be set together (or both omitted), only valid when multiSelect is true, and minSelect ≤ maxSelect.

allowCustomOption · boolean | null

Adds an “Other” option with free-text input.

randomizeOptionOrder · boolean | null

Shuffle option order per participant.

pinnedFinalOption · boolean | null

Keep the last option in place when randomizing (e.g. “None of the above”).

carryForwardFrom · string | null

externalId of an earlier multi-select multiple choice item; this question shows only the options the participant selected there. See Carry-forward.

An option with exclusiveOption: true clears and locks the other selections when picked (e.g. “None of the above”). It’s only valid on the final option of a multi-select question.

Multiple choice

{
  "externalId": "brands-used",
  "type": "multiple_choice",
  "text": "Which coffee brands have you bought in the last 3 months?",
  "multiSelect": true,
  "minSelect": 1,
  "maxSelect": 4,
  "randomizeOptionOrder": true,
  "pinnedFinalOption": true,
  "options": [
    { "externalId": "opt-blue-bottle", "text": "Blue Bottle" },
    { "externalId": "opt-stumptown", "text": "Stumptown" },
    { "externalId": "opt-lavazza", "text": "Lavazza" },
    { "text": "None of the above", "exclusiveOption": true }
  ]
}

Ranking

Participants order the options. Supports randomizeOptionOrder and carryForwardFrom (rank only the options selected in an earlier multi-select question).

Ranking

{
  "type": "ranking",
  "text": "Rank these brands from most to least trusted.",
  "carryForwardFrom": "brands-used"
}

Matrix

A grid: each row is rated single-select across the options (columns).

Matrix

{
  "externalId": "satisfaction-matrix",
  "type": "matrix",
  "text": "How satisfied are you with each of the following?",
  "options": [
    { "text": "Not satisfied" },
    { "text": "Somewhat satisfied" },
    { "text": "Very satisfied" }
  ],
  "rows": [
    { "text": "Taste" },
    { "text": "Price" },
    { "text": "Availability" }
  ]
}

MaxDiff

Best/worst scaling across at least two options. See MaxDiff analysis for how results are reported.

options · Option[] · required

The items being compared (minimum 2).

metric · string | null

What participants judge the items on (e.g. “importance”, “appeal”).

itemsPerScreen · 3 | 4 | 5 | null

How many items are shown per comparison screen.

MaxDiff

{
  "type": "max_diff",
  "text": "Which of these matters most and least when choosing a coffee?",
  "metric": "importance",
  "itemsPerScreen": 4,
  "options": [
    { "text": "Price" },
    { "text": "Origin" },
    { "text": "Roast level" },
    { "text": "Brand" },
    { "text": "Packaging" }
  ]
}

Statement

Not a question — shows text (and optional media/embed) with a continue button. Use it for instructions or section intros.

continueButtonText · string

Custom label for the continue button.

Statement

{
  "type": "statement",
  "text": "Next, we'll show you a few packaging designs. There are no right or wrong answers.",
  "continueButtonText": "Show me"
}

Conditional logic

Any item — and any concept in a concept block — can carry a conditional: it’s only shown when the criteria match. Criteria are combined with an operator (and / or).

Show only if they selected Blue Bottle

{
  "type": "open_ended",
  "text": "What keeps you coming back to Blue Bottle?",
  "conditional": {
    "operator": "and",
    "criteria": [
      {
        "type": "selectedTemplateOptions",
        "questionId": "brands-used",
        "matchingCriteria": "mustSelect",
        "choices": ["opt-blue-bottle"]
      }
    ]
  }
}

Two criterion types:

selectedTemplateOptions — based on an answer to an earlier multiple_choice or matrix item.

questionId · string · required

externalId of an earlier multiple_choice or matrix item. For a conditional on a concept, the item must live in a block before the concept block.

matchingCriteria · string · required

mustSelect or mustNotSelect.

choices · string[] · required

Option externalIds (falls back to option text). For a matrix source, these are the columns.

matrixRow · string | null

Required only for a matrix source: the exact row text the criterion applies to.

searchParam — based on a URL parameter passed into the study link.

parameter · string · required

The query parameter name, e.g. segment in https://listenlabs.ai/s/abc123?segment=pro.

value · string · required

The value it must equal.

See also Conditional logic for how this behaves in the interview.

Carry-forward

multiple_choice and ranking items can set carryForwardFrom to the externalId of an earlier multi-select multiple choice item. The question then only shows (or ranks) the options the participant actually selected there — so you can ask “which have you used?” followed by “which of those do you prefer?”. When carryForwardFrom is set, omit options; they’re inherited from the source question.

External IDs

externalIds are stable handles you assign to blocks, items, options, and concepts. They’re optional everywhere — the server auto-generates them when omitted — but you must set one on any item that a conditional (questionId) or carryForwardFrom references. Block, item, and concept externalIds must be unique across the entire payload.

Validation rules

Beyond field-level validation, the server enforces these cross-field rules, returning 400 with code: invalid_study_guide and a descriptive error message when violated:

• At most one screening block, and it must be the first block.
• Screening blocks may contain only multiple_choice items, and every option in them must carry a status; outside screening blocks, status must be null/omitted.
• Concept blocks require conceptSamplingConfig with at least one concept; other block types must omit it.
• externalIds must be unique across blocks, items, and concepts.
• conditional.criteria[].questionId and carryForwardFrom must reference the externalId of an earlier item (of the right type).
• A concept’s conditional must reference an item in a block before the concept block.
• minSelect/maxSelect must both be set or both omitted, only when multiSelect is true, with minSelect ≤ maxSelect.
• exclusiveOption is only valid on the final option of a multi-select multiple_choice question.