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

string

required

Internal study title (shown in the dashboard).

string

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

string

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

string

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

Config

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

object

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

string

Message shown when the interview ends.

Block[]

required

The blocks described below. At least one.

Config

string

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

string

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

string[] | null

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

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

string

required

One of flat, concept, or screening. See the table below.

string

required

The block title.

string

Stable identifier for the block, unique within the payload. Auto-generated when omitted.

Conditional | null

Skips the whole block unless the criteria match. Each questionId must reference an item in an earlier block. Not allowed on screening blocks. See Conditional logic.

Item[]

required

The questions in the block. At least one.

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. Screening blocks can’t have a conditional.

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.

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

integer | null

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

Each concept can also carry a conditional, so it’s only shown to participants matching the criteria. For example, 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:

string

required

The question text.

string

required

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

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 | null

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

Media[] | null

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

Embed | null

An embedded web page shown with the question: { "url" }. proxyUrl is accepted but ignored. The proxy URL is set automatically after the study is saved.

Open-ended

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

string | null

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

string | null

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

string | null

text, voice, screenRecording, or none.

boolean | null

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

Task | null

Makes this an open-ended task. Tasks can’t be skipped, can’t show media or embeds, and can’t appear in a screening block. Omit it or set it to null for an ordinary open-ended question.

Show Task fields

string

Optional http or https destination. Defaults to the concept URL in concept blocks. A bare domain uses https.

boolean

Opens the task in a floating window on supported desktop browsers. Needs voice-first input with a required microphone. Defaults to false.

string

Where the task page comes from: concept, previous, or custom. Omit it to use the default rules.

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

Option[]

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

boolean | null

Allow selecting more than one option.

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.

boolean | null

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

boolean | null

Shuffle option order per participant.

boolean | null

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

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

Option[]

required

The columns each row is rated across. At least one.

object[]

required

The rows to rate. Each row is { "text" }. At least one.

string | null

How the participant answers. grid (default) shows a row-by-column grid. card_sort shows the rows as cards that the participant sorts into the options as groups. card_sort is always single-select.

Matrix

{
  "externalId": "satisfaction-matrix",
  "type": "matrix",
  "text": "How satisfied are you with each of the following?",
  "display": "grid",
  "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.

Option[]

required

The items being compared (minimum 2).

string | null

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

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. A statement shows text (and optional media/embed) with a continue button. Use it for instructions or section intros.

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, any concept in a concept block, and any block can carry a conditional. It’s only shown when the criteria match. Criteria are combined with an operator (and / or). A block conditional can’t be used on a screening block.

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.

string

required

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

string

required

mustSelect or mustNotSelect.

string[]

required

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

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.

string

required

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

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. For example, 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. 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. It returns 400 with code: invalid_study_guide and a descriptive error message when a rule fails:

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 or omitted.
Screening blocks can’t have a conditional.
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 block’s conditional must reference an item in a block before that block.
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