Study Guide Reference

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. All 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, options, 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.

​Top-level request fields

​Config

​Blocks

​Screening blocks

​Concept blocks

​Question types

​Open-ended

​Multiple choice

​Ranking

​Matrix

​MaxDiff

​Statement

​Conditional logic

​Carry-forward

​External IDs

​Validation rules

Top-level request fields

Config

Blocks

Screening blocks

Concept blocks

Question types

Open-ended

Multiple choice

Ranking

Matrix

MaxDiff

Statement

Conditional logic

Carry-forward

External IDs

Validation rules