Listen LabsDocs

    Getting Started

    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

    titlestringrequired

    Internal study title (shown in the dashboard).

    externalTitlestring

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

    backgroundstring

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

    studyGoalstring

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

    configConfig

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

    welcomeMessageobject

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

    closingMessagestring

    Message shown when the interview ends.

    studyGuideBlock[]required

    The blocks described below. At least one.

    Config

    interviewModestring

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

    questionLanguagestring

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

    availableLanguagesstring[] | null

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

    targetPlatformsstring[]

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

    typestringrequired

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

    titlestringrequired

    The block title.

    externalIdstring

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

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

    itemsItem[]required

    The questions in the block. At least one.

    TypePurpose
    flatA plain sequence of questions.
    screeningQualifies participants before the interview. At most one, and it must be the first block.
    conceptShows 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.

    conceptsConcept[]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).

    subsampleCountinteger | 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:

    textstringrequired

    The question text.

    typestringrequired

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

    externalIdstring

    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.

    conditionalConditional | null

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

    mediaMedia[] | 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.

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

    followUpstring | null

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

    addInstructionsstring | null

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

    preferredInputstring | null

    text, voice, screenRecording, or none.

    screenObservationEnabledboolean | null

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

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

    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

    optionsOption[]

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

    multiSelectboolean | null

    Allow selecting more than one option.

    minSelect / maxSelectinteger | 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.

    allowCustomOptionboolean | null

    Adds an "Other" option with free-text input.

    randomizeOptionOrderboolean | null

    Shuffle option order per participant.

    pinnedFinalOptionboolean | null

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

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

    optionsOption[]required

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

    rowsobject[]required

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

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

    optionsOption[]required

    The items being compared (minimum 2).

    metricstring | null

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

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

    continueButtonTextstring

    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.

    questionIdstringrequired

    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.

    matchingCriteriastringrequired

    mustSelect or mustNotSelect.

    choicesstring[]required

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

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

    parameterstringrequired

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

    valuestringrequired

    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.