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).
Top-level request fields
titlestringrequiredInternal study title (shown in the dashboard).
externalTitlestringParticipant-facing title. Falls back to title when omitted.
backgroundstringBackground context for the AI interviewer: what the study is about and who you're talking to.
studyGoalstringWhat you want to learn. Helps the AI interviewer probe in the right direction.
configConfigInterview mode, languages, and platform targeting. See Config.
welcomeMessageobject{ "title": "...", "message": "..." } shown to participants before the interview starts.
closingMessagestringMessage shown when the interview ends.
studyGuideBlock[]requiredThe blocks described below. At least one.
Config
interviewModestringOne of text, audio, audio_text, audio_screen, video, video_screen.
questionLanguagestringLanguage code the questions are written in (e.g. en, de, fr, es, zh-TW, en-medical). See the complete language list.
availableLanguagesstring[] | nullTranslation 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.
Blocks
Every block has a type, a title, and an items array (at least one item).
typestringrequiredOne of flat, concept, or screening. See the table below.
titlestringrequiredThe block title.
externalIdstringStable identifier for the block, unique within the payload. Auto-generated when omitted.
conditionalConditional | nullSkips 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[]requiredThe 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 participantreject: selecting it screens the participant outneutral: doesn't affect qualification
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[]requiredEach 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 | nullHow 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.
Question types
All items share a few common fields:
textstringrequiredThe question text.
typestringrequiredOne of open_ended, multiple_choice, ranking, matrix, max_diff, statement.
externalIdstringStable 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 | nullShow this question only when the criteria match. See Conditional logic.
mediaMedia[] | nullImages 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 | nullAn 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 | nullFollow-up depth: none, light, medium, or heavy.
addInstructionsstring | nullExtra instructions for the AI interviewer on how to probe this question.
preferredInputstring | nulltext, voice, screenRecording, or none.
screenObservationEnabledboolean | nullLets the AI observe the participant's screen while they answer. Only applies when preferredInput is screenRecording.
taskTask | nullMakes 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.
Multiple choice
optionsOption[]Required unless carryForwardFrom is set. Each option: { "text", "externalId"?, "status"?, "exclusiveOption"? }.
multiSelectboolean | nullAllow selecting more than one option.
minSelect / maxSelectinteger | nullBounds 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 | nullAdds an "Other" option with free-text input.
randomizeOptionOrderboolean | nullShuffle option order per participant.
pinnedFinalOptionboolean | nullKeep the last option in place when randomizing (e.g. "None of the above").
carryForwardFromstring | nullexternalId 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.
Ranking
Participants order the options. Supports randomizeOptionOrder and carryForwardFrom (rank only the options selected in an earlier multi-select question).
Matrix
A grid: each row is rated single-select across the options (columns).
optionsOption[]requiredThe columns each row is rated across. At least one.
rowsobject[]requiredThe rows to rate. Each row is { "text" }. At least one.
displaystring | nullHow 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.
MaxDiff
Best/worst scaling across at least two options. See MaxDiff analysis for how results are reported.
optionsOption[]requiredThe items being compared (minimum 2).
metricstring | nullWhat participants judge the items on (e.g. "importance", "appeal").
itemsPerScreen3 | 4 | 5 | nullHow many items are shown per comparison screen.
Statement
Not a question. A statement shows text (and optional media/embed) with a continue button. Use it for instructions or section intros.
continueButtonTextstringCustom label for the continue button.
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.
Two criterion types:
selectedTemplateOptions: based on an answer to an earlier multiple_choice or matrix item.
questionIdstringrequiredexternalId 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.
matchingCriteriastringrequiredmustSelect or mustNotSelect.
choicesstring[]requiredOption externalIds (falls back to option text). For a matrix source, these are the columns.
matrixRowstring | nullRequired only for a matrix source: the exact row text the criterion applies to.
searchParam: based on a URL parameter passed into the study link.
parameterstringrequiredThe query parameter name, e.g. segment in https://listenlabs.ai/s/abc123?segment=pro.
valuestringrequiredThe 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_choiceitems, and every option in them must carry astatus. Outside screening blocks,statusmust be null or omitted. - Screening blocks can't have a
conditional. - Concept blocks require
conceptSamplingConfigwith at least one concept. Other block types must omit it. externalIds must be unique across blocks, items, and concepts.conditional.criteria[].questionIdandcarryForwardFrommust reference theexternalIdof an earlier item (of the right type).- A block's
conditionalmust reference an item in a block before that block. - A concept's
conditionalmust reference an item in a block before the concept block. minSelect/maxSelectmust both be set or both omitted, only whenmultiSelectis true, withminSelect≤maxSelect.exclusiveOptionis only valid on the final option of a multi-selectmultiple_choicequestion.