# Voicepanel study reference: one feedback engine for every research method

> The complete Voicepanel study schema. Snap together question types, tasks, assets, recording, logic, audience targeting, screeners, and quotas to run usability tests, surveys, concept tests, and interviews on one mixed-method research platform.

Voicepanel is a set of building blocks that snap together into any study design you want. Put the tasks of a usability test, the logic of a survey, and the depth of an interview into one study. Then send it to exactly the people you need to hear from.

HTML version: https://www.voicepanel.com/docs/study-reference

## Overview

Voicepanel is a mixed-method research platform. One study can hold survey questions, usability tasks, prototype and media tests, and interview-style open questions. Respondents answer by voice, by text, or with taps and clicks, and Voicepanel can record their voice, webcam, and screen while they do.

AI is a feature of specific blocks, not the whole session. Turn on AI probing for an open-ended question, and Voicepanel asks follow-up questions based on the answer. Add an AI conversation step for a short, timed interview. Every other block works the way a survey or a usability test works.

Every study has two parts:

- **Part 1: Design.** What feedback do you collect? The design is the study itself: the plan, and the settings around it. Stack sections, fill each one with questions, tasks, and assets, and choose what to record.
- **Part 2: Distribution.** Who gives the feedback? A distribution decides who takes the study and how they reach it. Pick a channel, target an audience, screen each person, and balance the sample with quotas.

Let an AI assistant write a study through the MCP server (https://www.voicepanel.com/docs/mcp), send it to the REST API (https://app.voicepanel.co/api/docs), or build it in the Voicepanel app. All three accept the schema on this page.

## Anatomy of a study

A study has a design and one or more distributions. The design is the plan plus the study settings. A plan is a stack of sections. Each section holds its steps. A section can also hold one asset (`stimulus`), one recording mode (`recording`), and one display condition (`conditionalBranch`), and all three apply to every step in the section. A distribution holds a channel, an audience, a screener, and quotas.

The example is a product feedback study that mixes four methods. Section 1 asks foundational questions about how the team uses the app. Section 2 is a usability task on a Figma prototype, with the screen and voice recorded. Section 3 loops through three feature ideas, one at a time, with the webcam and voice recorded, and names each feature with `{{stimulus.metadata.feature}}`. Section 4 is a reflection: an NPS question and a short AI conversation, with the voice recorded.

### Design

Build, from section 1 down:

- Plan: [Desktop only]
- Section 1, Foundations: [Single choice] [Multiple choice] [Open-ended]
- Section 2, Usability task (on [Prototype: New project setup], [Record: screen + voice]): [Task] [Rating scale: 1–5]
- Section 3, Feature loop (on [Group: loops through all 3 images, one at a time + Metadata], [Record: webcam + voice]): [Rating scale: 1–7] [Open-ended + AI probing]
- Section 4, Reflection ([Record: voice]): [Rating scale: 0–10] [AI conversation: 2 min]

```json
{
  "version": "2025_04",
  "device": "desktop",
  "randomizations": [],
  "sections": [
    {
      "intro": "First, a few questions about how your team uses Planly.",
      "stimulus": null,
      "recording": null,
      "conditionalBranch": null,
      "steps": [
        {
          "type": "single_select",
          "question": "How often do you use Planly?",
          "options": [
            {
              "value": "Every day"
            },
            {
              "value": "A few times a week"
            },
            {
              "value": "A few times a month"
            },
            {
              "value": "Less often"
            }
          ]
        },
        {
          "type": "multi_select",
          "question": "Which parts of Planly does your team use?",
          "options": [
            {
              "value": "Boards"
            },
            {
              "value": "Calendar"
            },
            {
              "value": "Reports"
            },
            {
              "value": "Automations"
            }
          ],
          "shuffle_options": true
        },
        {
          "type": "long_question",
          "question": "What is the main job that your team uses Planly for?",
          "probing_type": "none",
          "response_format": "audio"
        }
      ]
    },
    {
      "intro": "Next, you will try a new way to set up a project. Please think out loud.",
      "stimulus": {
        "type": "prototype",
        "url": "https://www.figma.com/proto/abc123/Project-setup",
        "name": "New project setup"
      },
      "recording": {
        "audio": true,
        "video": false,
        "screen": true,
        "mobile_screen": false
      },
      "conditionalBranch": null,
      "steps": [
        {
          "type": "task",
          "question": "Create a project for a product launch and invite two teammates.",
          "task_type": "generic_instruction",
          "expected_duration_seconds": 180
        },
        {
          "type": "rating_scale",
          "question": "How easy was it to set up the project?",
          "options": [
            {
              "value": "1"
            },
            {
              "value": "2"
            },
            {
              "value": "3"
            },
            {
              "value": "4"
            },
            {
              "value": "5"
            }
          ],
          "lowest_rating_label": "Very difficult",
          "highest_rating_label": "Very easy"
        }
      ]
    },
    {
      "intro": "Now you will see three feature ideas, one at a time.",
      "stimulus": {
        "type": "group",
        "showCount": 3,
        "stimuli": [
          {
            "type": "image",
            "url": "https://cdn.example.com/planly/smart-scheduling.png",
            "name": "Smart scheduling",
            "metadata": {
              "feature": "smart scheduling"
            }
          },
          {
            "type": "image",
            "url": "https://cdn.example.com/planly/workload-view.png",
            "name": "Workload view",
            "metadata": {
              "feature": "a workload view"
            }
          },
          {
            "type": "image",
            "url": "https://cdn.example.com/planly/ai-summaries.png",
            "name": "AI summaries",
            "metadata": {
              "feature": "AI project summaries"
            }
          }
        ]
      },
      "recording": {
        "audio": true,
        "video": true,
        "screen": false,
        "mobile_screen": false
      },
      "conditionalBranch": null,
      "steps": [
        {
          "type": "rating_scale",
          "question": "How useful would {{stimulus.metadata.feature}} be for your team?",
          "options": [
            {
              "value": "1"
            },
            {
              "value": "2"
            },
            {
              "value": "3"
            },
            {
              "value": "4"
            },
            {
              "value": "5"
            },
            {
              "value": "6"
            },
            {
              "value": "7"
            }
          ],
          "lowest_rating_label": "Not at all useful",
          "highest_rating_label": "Extremely useful"
        },
        {
          "type": "long_question",
          "question": "When would you use this, and what would it replace?",
          "probing_type": "light"
        }
      ]
    },
    {
      "intro": "Last, look back on everything that you saw today.",
      "stimulus": null,
      "recording": {
        "audio": true,
        "video": false,
        "screen": false,
        "mobile_screen": false
      },
      "conditionalBranch": null,
      "steps": [
        {
          "type": "rating_scale",
          "question": "How likely are you to recommend Planly to a colleague?",
          "options": [
            {
              "value": "0"
            },
            {
              "value": "1"
            },
            {
              "value": "2"
            },
            {
              "value": "3"
            },
            {
              "value": "4"
            },
            {
              "value": "5"
            },
            {
              "value": "6"
            },
            {
              "value": "7"
            },
            {
              "value": "8"
            },
            {
              "value": "9"
            },
            {
              "value": "10"
            }
          ],
          "lowest_rating_label": "Not at all likely",
          "highest_rating_label": "Extremely likely"
        },
        {
          "type": "conversation",
          "question": "If you could change one thing about Planly tomorrow, what would it be?",
          "time_limit_seconds": 120,
          "conversation_mode": "no-guide"
        }
      ]
    }
  ]
}
```

### Distribution

- Channel: Link
- Quota: 40 responses, lifetime
- Language: en-US
- Email: Collected before the study

```json
{
  "name": "Active Planly customers",
  "type": "link",
  "collect_email": true,
  "quota_limit": 40,
  "quota_frequency": "lifetime",
  "default_response_language": "en-US"
}
```

## Quick start

### With your own AI assistant

Connect an MCP client to the Voicepanel MCP server, then describe the study and the audience. The assistant writes the plan with `create_study` or `generate_study`, sets up the distribution, and `review_study` scores the plan before you launch.

```text
Create a Voicepanel study that tests our new checkout prototype at https://www.figma.com/proto/abc123. Record the screen, ask respondents to buy two items, follow up with anyone who can't finish, and end with an NPS question. Then recruit 15 US adults who shop online at least once a month from a panel.
```

### With the REST API

Send the plan as the `plan` field of `POST /api/v1/studies`. Then create a distribution with `POST /api/v1/distributions` and publish it with `POST /api/v1/distributions/{id}/publish`.

```bash
# 1. Create the study (the design)
curl -X POST https://app.voicepanel.co/api/v1/studies \
  -H "Authorization: Bearer $VOICEPANEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": "YOUR_ACCOUNT_ID",
    "display_name": "Checkout feedback",
    "objective": "Find out where buyers get stuck in checkout.",
    "plan": {
      "version": "2025_04",
      "randomizations": [],
      "sections": [
        {
          "intro": null,
          "steps": [
            { "type": "long_question", "question": "What almost stopped you from buying today?" }
          ]
        }
      ]
    }
  }'

# 2. Create a distribution (who answers)
curl -X POST https://app.voicepanel.co/api/v1/distributions \
  -H "Authorization: Bearer $VOICEPANEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "study_id": "STUDY_ID", "name": "Recent buyers", "type": "link", "quota_limit": 100 }'

# 3. Publish it
curl -X POST https://app.voicepanel.co/api/v1/distributions/DISTRIBUTION_ID/publish \
  -H "Authorization: Bearer $VOICEPANEL_API_KEY"
```

### In the Voicepanel app

When you create a new study in the Voicepanel app, you can start from scratch or start with AI. From scratch, you add the sections, assets, recording modes, and blocks yourself in the study editor. With AI, you describe your research goal to the built-in AI setup assistant, and it drafts the full plan for you to review. In both cases, you can add, remove, and reorder blocks at any time. Then set up each distribution on the Distribute tab.

![Sections 2 and 3 of the Planly product feedback study in the Voicepanel study editor. Section 2 has a Figma prototype, screen recording, a task, and a rating scale. Section 3 loops through three feature images with webcam recording.](https://www.voicepanel.com/images/study-editor-planly.png)

Part 3, "What you can build", near the end of this file, has 20 complete example studies, from usability tests to AI answer evaluations.

## Part 1: Design. What feedback do you collect?

The design is the study itself: the plan, and the settings around it. Stack sections, fill each one with questions, tasks, and assets, and choose what to record.

One design can hold a survey, a usability test, and an interview at the same time.

### Plan and sections

A study plan is a JSON object. It holds an ordered list of sections. Each section holds an ordered list of steps, and can add one asset, one recording mode, and one display condition.

The respondent moves through the sections in order, unless a randomization group shuffles them or a condition hides one.

#### Plan (`plan`)

The root object. Every study has exactly one plan.

| Field | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `version` | `string` | yes |  | The schema version. Use "2025_04". |
| `sections` | `Section[]` | yes |  | The sections, in authored order. |
| `randomizations` | `Randomization[]` | yes |  | Groups of sections to shuffle for each respondent. Use [] for none. |
| `device` | `"any" \| "desktop" \| "mobile" \| "ios" \| "android"` | no |  | The device respondents must use. If you omit it on create, Voicepanel derives it from the recording modes and assets. See Device restriction. |

Example

```json
{
  "version": "2025_04",
  "sections": [
    {
      "intro": null,
      "steps": [
        {
          "type": "long_question",
          "question": "What is the hardest part of your workday?"
        }
      ]
    }
  ],
  "randomizations": []
}
```

#### Section (`section`)

A group of steps that share one asset, one recording mode, and one display condition.

Put steps in the same section when the respondent should see the same asset for all of them. Start a new section when the asset, the recording mode, or the audience changes.

| Field | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `intro` | `string \| null` | no | `null` | Text that introduces the section before its first step. With text-to-speech on, Voicepanel reads it aloud. |
| `steps` | `Step[]` | yes |  | The questions and tasks, in order. |
| `stimulus` | `Asset \| null` | no |  | The asset the respondent sees or uses for the whole section. See Assets and Asset layouts. |
| `recording` | `Recording \| null` | no |  | What Voicepanel records for the whole section: audio, webcam, desktop screen, or mobile screen. See Recording. |
| `conditionalBranch` | `ConditionalBranch \| null` | no |  | Show the section only when a condition is true. See Logic. |

Example

```json
{
  "intro": "Next, you will look at our new homepage.",
  "stimulus": {
    "type": "website",
    "url": "https://example.com",
    "name": "Homepage"
  },
  "recording": {
    "audio": true,
    "video": false,
    "screen": true,
    "mobile_screen": false
  },
  "conditionalBranch": null,
  "steps": [
    {
      "type": "task",
      "question": "Find the pricing for the team plan. Think out loud as you go.",
      "task_type": "generic_instruction"
    },
    {
      "type": "long_question",
      "question": "What did you expect to find, and what did you find?",
      "probing_type": "light"
    }
  ]
}
```

### Question types

A step is one question or one task. Every step has a "question" (the text the respondent sees and hears) and a "type". The other fields depend on the type.

Mix closed questions, which give countable results, with open-ended questions, which give the reasons. AI is a feature of two blocks: AI probing adds follow-up questions to an open-ended question, and an AI conversation runs a short interview inside the study.

#### Open-ended question (`long_question`)

A free answer, spoken or typed. Turn on AI probing, and Voicepanel asks follow-up questions based on what the respondent said.

Use it for:

- Reasons, stories, and first reactions
- Expectations before a task and reflections after it
- Any question where you want to hear the respondent's own words

| Field | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `probing_type` | `"none" \| "light" \| "custom"` | no | `"light"` | AI probing. "none" asks no follow-up questions. "light" lets the AI decide when a follow-up adds depth. "custom" follows up on the topics in probing_areas. |
| `probing_areas` | `string \| null` | no | `null` | The topics to probe when probing_type is "custom". Write them as plain instructions for the AI. |
| `response_format` | `"audio" \| "audio_only" \| "chat" \| "chat_only"` | no | `"audio"` | How the respondent answers: by voice, by typing, or either. See Answer modes. |

Example: Custom probing

```json
{
  "type": "long_question",
  "question": "Tell me about the last time you switched banks.",
  "probing_type": "custom",
  "probing_areas": "What triggered the switch, which alternatives they considered, and what almost stopped them.",
  "response_format": "audio"
}
```

Notes:

- Turn on probing for the two or three questions that need depth. Probing every question makes the session long.

#### Single choice (`single_select`)

The respondent picks exactly one option.

Use it for:

- Frequency, category, and yes/no questions
- The source question for a conditional section

| Field | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `options` | `Option[]` | yes |  | The choices, in display order. Each option is { value, anchor, exclusive }. value is the text the respondent sees, and conditional sections match on it exactly. anchor and exclusive are optional. See "Option order and exclusivity" under Logic. |
| `shuffle_options` | `boolean \| null` | no | `null` | Shuffle the options for each respondent to remove position bias. Options with anchor: true keep their position. |
| `vertically_align_choices` | `boolean \| null` | no | `null` | Stack the choices in one column. |

Example

```json
{
  "type": "single_select",
  "question": "Which plan are you on today?",
  "options": [
    {
      "value": "Free"
    },
    {
      "value": "Pro"
    },
    {
      "value": "Business"
    },
    {
      "value": "I'm not sure",
      "anchor": true
    }
  ],
  "shuffle_options": false
}
```

#### Multiple choice (`multi_select`)

The respondent picks any number of options.

Use it for:

- Awareness, usage, and consideration sets
- Feature usage and pain point checklists

| Field | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `options` | `Option[]` | yes |  | The choices, in display order. Each option is { value, anchor, exclusive }. value is the text the respondent sees, and conditional sections match on it exactly. anchor and exclusive are optional. See "Option order and exclusivity" under Logic. |
| `shuffle_options` | `boolean \| null` | no | `null` | Shuffle the options for each respondent to remove position bias. Options with anchor: true keep their position. |
| `vertically_align_choices` | `boolean \| null` | no | `null` | Stack the choices in one column. |

Example

```json
{
  "type": "multi_select",
  "question": "Which of these tools have you used in the past month?",
  "options": [
    {
      "value": "Notion"
    },
    {
      "value": "Asana"
    },
    {
      "value": "Linear"
    },
    {
      "value": "Jira"
    },
    {
      "value": "None of these",
      "anchor": true,
      "exclusive": true
    }
  ],
  "shuffle_options": true
}
```

#### Rating scale (`rating_scale`)

A numeric scale with labeled end points. Use it for NPS, CSAT, ease, clarity, and appeal.

Use it for:

- Net Promoter Score (0–10)
- Satisfaction, ease, and likelihood scores (1–5, 1–7, 1–10)
- The source question for a conditional section, such as a follow-up for low scores

| Field | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `options` | `Option[]` | yes |  | Consecutive integers as strings. Use exactly one of these ranges: 1–5, 1–7, 1–10, or 0–10. Example: [{ "value": "1" }, ..., { "value": "5" }]. |
| `lowest_rating_label` | `string \| null` | no | `null` | The label under the lowest value. |
| `highest_rating_label` | `string \| null` | no | `null` | The label under the highest value. |

Example: Net Promoter Score

```json
{
  "type": "rating_scale",
  "question": "How likely are you to recommend us to a friend or colleague?",
  "options": [
    {
      "value": "0"
    },
    {
      "value": "1"
    },
    {
      "value": "2"
    },
    {
      "value": "3"
    },
    {
      "value": "4"
    },
    {
      "value": "5"
    },
    {
      "value": "6"
    },
    {
      "value": "7"
    },
    {
      "value": "8"
    },
    {
      "value": "9"
    },
    {
      "value": "10"
    }
  ],
  "lowest_rating_label": "Not at all likely",
  "highest_rating_label": "Extremely likely"
}
```

Example: Five-point ease score

```json
{
  "type": "rating_scale",
  "question": "How easy was it to find what you needed?",
  "options": [
    {
      "value": "1"
    },
    {
      "value": "2"
    },
    {
      "value": "3"
    },
    {
      "value": "4"
    },
    {
      "value": "5"
    }
  ],
  "lowest_rating_label": "Very difficult",
  "highest_rating_label": "Very easy"
}
```

Notes:

- A rating scale has two labels only. There is no midpoint label.
- Rating scales keep their order. shuffle_options does not apply.

#### Ranking (`ranking`)

The respondent puts the options in order.

Use it for:

- Feature and roadmap prioritization
- Ordering messages, names, or benefits by appeal

| Field | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `options` | `Option[]` | yes |  | The choices, in display order. Each option is { value, anchor, exclusive }. value is the text the respondent sees, and conditional sections match on it exactly. anchor and exclusive are optional. See "Option order and exclusivity" under Logic. |
| `shuffle_options` | `boolean \| null` | no | `null` | Shuffle the options for each respondent to remove position bias. Options with anchor: true keep their position. |

Example

```json
{
  "type": "ranking",
  "question": "Rank these features from most to least important to you.",
  "options": [
    {
      "value": "Offline mode"
    },
    {
      "value": "Shared workspaces"
    },
    {
      "value": "Calendar sync"
    },
    {
      "value": "Custom templates"
    }
  ],
  "shuffle_options": true
}
```

#### Task (`task`)

An instruction the respondent carries out, such as a usability task. The respondent reports whether they completed it.

Pair a task with an asset on the same section: a website, a prototype, or a mobile app. Add recording to capture what the respondent says and does during the task. Use the completion result to show a follow-up section only to the respondents who did not finish.

Use it for:

- Usability tasks on websites, prototypes, and apps
- Instructions for physical products and in-home tests

| Field | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `task_type` | `"generic_instruction" \| "visit_website" \| "download_app" \| "open_app" \| "watch_video"` | yes |  | Use "generic_instruction". The section asset tells the respondent where to go. The MCP server and the AI editor store every task with this value. |
| `expected_duration_seconds` | `number` | no | `60` | The time you expect the task to take. Voicepanel uses it for the estimated study length only. |

Example

```json
{
  "type": "task",
  "question": "Using the site above, book a table for two this Friday at 7pm. Think out loud as you go.",
  "task_type": "generic_instruction",
  "expected_duration_seconds": 180
}
```

Notes:

- Do not add a task that tells respondents to watch a video or listen to audio. The video, youtube, and audio assets already do this.

#### AI conversation (`conversation`)

A timed, free-form AI conversation with the respondent, about the topics so far or about a guide you write. Use it to put an interview inside a survey or a usability test.

Use it for:

- A short wrap-up that catches what your questions missed
- Semi-structured interview blocks with a discussion guide

| Field | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `time_limit_seconds` | `number` | yes |  | The length of the conversation, in seconds. |
| `conversation_mode` | `"no-guide" \| "guide"` | yes |  | "no-guide" lets the AI follow the respondent. "guide" follows conversation_guide. |
| `conversation_guide` | `string \| null` | no | `null` | The discussion guide, used when conversation_mode is "guide". |
| `response_format` | `"audio" \| "audio_only" \| "chat" \| "chat_only"` | no | `"audio"` | How the respondent answers: by voice, by typing, or either. See Answer modes. |

Example: Guided interview block

```json
{
  "type": "conversation",
  "question": "Let's talk about how your team plans its work.",
  "time_limit_seconds": 300,
  "conversation_mode": "guide",
  "conversation_guide": "Cover: who owns planning, which tools they use, where handoffs break, and one thing they would change.",
  "response_format": "audio"
}
```

Example: Open wrap-up

```json
{
  "type": "conversation",
  "question": "Is there anything else you want to tell us?",
  "time_limit_seconds": 60,
  "conversation_mode": "no-guide"
}
```

### Answer modes

Respondents answer open-ended questions and conversations by voice by default. Set response_format on each step to allow typing, or to require one mode.

Choice, rating, and ranking steps take taps or clicks. To read every question aloud, turn on text-to-speech in the study settings.

#### Response format (`response_format`)

Voice, text, or both, for each long_question and conversation step.

| Value | Behavior |
| --- | --- |
| `audio` | Voice by default. The respondent can switch to typing. |
| `audio_only` | Voice only. |
| `chat` | Typing by default. The respondent can switch to voice. |
| `chat_only` | Typing only. |

Example: A typed answer for a sensitive question

```json
{
  "type": "long_question",
  "question": "Is there anything about your finances you'd prefer to type rather than say?",
  "probing_type": "none",
  "response_format": "chat_only"
}
```

### Recording

Recording captures a whole section, from its first step to its last. Use it for think-aloud usability tests, facial reactions, and screen capture. Set it on the section as { "audio", "video", "screen", "mobile_screen" }.

Voice answers to open-ended questions do not need a recording block. Set recording to null for a section that records nothing.

#### Audio (think-aloud) (`recording.audio`)

Record the respondent's voice for the whole section, for example while they use a website.

Example

```json
{
  "audio": true,
  "video": false,
  "screen": false,
  "mobile_screen": false
}
```

#### Webcam video (`recording.video`)

Record the respondent's camera. Use it for facial reactions to ads and for physical product tests.

Example

```json
{
  "audio": true,
  "video": true,
  "screen": false,
  "mobile_screen": false
}
```

Notes:

- Webcam recording also needs audio: true.

#### Desktop screen (`recording.screen`)

Record the respondent's desktop screen. Use it for website, web app, and prototype tests.

Example

```json
{
  "audio": true,
  "video": false,
  "screen": true,
  "mobile_screen": false
}
```

Notes:

- Screen recording needs audio: true and device "desktop".
- A study cannot use both screen and mobile_screen.

#### Mobile screen (`recording.mobile_screen`)

Record the respondent's phone screen through the Voicepanel iPhone app. Use it for mobile app and mobile web tests.

Example

```json
{
  "audio": true,
  "video": false,
  "screen": false,
  "mobile_screen": true
}
```

Notes:

- Mobile screen recording needs audio: true and device "ios".
- If the section asset is a mobile_app or a website, the respondent leaves the Voicepanel app for the task, so Voicepanel turns off webcam video for that section.

### Asset types

An asset (called a "stimulus" in the JSON) is the thing respondents react to: a website, a prototype, an app, an image, a video, a piece of copy, or a physical product. Set one asset on a section with the stimulus field. The respondent sees it for every step in that section.

To show several assets, use a group or a side-by-side layout. See Asset layouts. Media must be at a public URL. The MCP server can create an upload link for files on the user's device.

#### Common asset fields (`stimulus`)

The fields every single asset accepts.

| Field | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `type` | `string` | yes |  | One of the asset types below. |
| `url` | `string` | yes |  | A public URL. Required for every type except "text". Template variables resolve here, for example a link query parameter. |
| `content` | `string` | yes |  | The text to show, for "text" assets only. Markdown renders here. |
| `name` | `string \| null` | no |  | A name for the asset. Respondents do not see it. Analysis uses it. |
| `metadata` | `object` | no |  | Your own attributes for analysis, such as { "price": "low" }. See Asset metadata. |
| `placement` | `"throughout" \| "at-start"` | no | `"throughout"` | Show the asset next to every step, or once, full screen, before the steps. See Display settings. |
| `displaySeconds` | `number \| null` | no |  | Show the asset for this many seconds, then hide it. See Display settings. |
| `sizing` | `"fit" \| "fit-width" \| "fit-height"` | no |  | How an image or page fits the frame. Not available on text assets. |

#### Website (`website`)

A live website. The respondent opens it and uses it while they answer the section's questions.

Use it for:

- Usability tests and task-based journeys
- Competitive and benchmark reviews

Example

```json
{
  "type": "website",
  "url": "https://example.com/pricing",
  "name": "Pricing page"
}
```

#### Prototype (`prototype`)

An interactive prototype, such as a Figma prototype link. It shows inline, next to the questions.

Use it for:

- Testing designs before you build them
- Comparing flows early in design

Example

```json
{
  "type": "prototype",
  "url": "https://www.figma.com/proto/abc123/Onboarding",
  "name": "Onboarding v2"
}
```

#### Mobile app (`mobile_app`)

A native app, linked from the App Store, TestFlight, or Google Play. The respondent installs or opens it on their phone.

Use it for:

- Mobile usability tests
- Beta and TestFlight feedback

Example

```json
{
  "type": "mobile_app",
  "url": "https://apps.apple.com/us/app/example/id123456789",
  "name": "Example for iOS"
}
```

Notes:

- A mobile_app asset needs device "ios" or "android". An App Store or TestFlight link means "ios". A Google Play link means "android". One study uses links for one platform.

#### Image (`image`)

A static image: a design, an ad, packaging, a screenshot, or a concept board.

Use it for:

- Concept and packaging tests
- Five-second tests and first impressions
- Side-by-side design comparisons

Example

```json
{
  "type": "image",
  "url": "https://cdn.example.com/concepts/label-a.png",
  "name": "Label A",
  "sizing": "fit"
}
```

#### Video (`video`)

A hosted video file. The respondent watches it in the study.

Use it for:

- Ad and trailer tests
- Product demos and explainer videos

Example

```json
{
  "type": "video",
  "url": "https://cdn.example.com/ads/spring-30s.mp4",
  "name": "Spring campaign, 30s"
}
```

#### YouTube video (`youtube`)

A YouTube video, embedded in the study.

Example

```json
{
  "type": "youtube",
  "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
  "name": "Launch video"
}
```

#### Audio (`audio`)

An audio file: a podcast clip, a radio spot, a voice assistant reply, or a sonic logo.

Example

```json
{
  "type": "audio",
  "url": "https://cdn.example.com/audio/radio-spot.mp3",
  "name": "Radio spot"
}
```

#### Text (`text`)

Copy that you write in the plan: a message, a value proposition, a product description, or a scenario. Markdown renders here.

Use it for:

- Message and claims testing
- Scenarios and concept descriptions
- Evaluating AI-written answers

Example

```json
{
  "type": "text",
  "name": "Value proposition B",
  "content": "**Close your books in a day.** Automatic reconciliation for teams that are tired of month-end."
}
```

Notes:

- A text asset has "content" instead of "url", and has no sizing field.

#### HTML page (`html`)

A self-contained HTML page, shown inline in a sandboxed frame. Use it for interactive mockups and rendered AI outputs.

Example

```json
{
  "type": "html",
  "url": "https://cdn.example.com/outputs/answer-a.html",
  "name": "Answer A"
}
```

#### Offline (physical) (`offline`)

Something physical in front of the respondent: a product, a package, a printed page, or a store shelf.

Use it for:

- In-home use tests
- Unboxing and packaging tests

Example

```json
{
  "type": "offline",
  "url": "",
  "name": "Sample kit"
}
```

Notes:

- An offline asset has no media. Set url to "". Pair it with webcam recording to see the product in use.

#### None (`none`)

An explicit marker for a section with no asset. It is the same as stimulus: null.

Example

```json
{
  "type": "none",
  "url": ""
}
```

### Asset layouts

A section shows one asset, a rotation of assets, or a side-by-side set. These three layouts are how you build monadic, sequential monadic, and comparative designs without copying sections.

#### Single asset (`stimulus`)

One asset for the whole section. Most sections use this.

Example

```json
{
  "stimulus": {
    "type": "image",
    "url": "https://cdn.example.com/home-v3.png",
    "name": "Homepage v3"
  },
  "steps": [
    {
      "type": "long_question",
      "question": "What is this page offering you?"
    }
  ]
}
```

#### Group (rotation) (`group`)

A pool of assets. The section repeats once for each asset shown, and each respondent sees showCount assets, picked at random.

A group gives you monadic designs (showCount: 1) and sequential monadic designs (showCount of 2 or more) with the questions written once. Voicepanel picks the members at random for each respondent, and analysis reports each iteration separately.

Use it for:

- Concept tests with many concepts
- Ad, message, and packaging rotations
- AI output evaluations across many samples

| Field | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `type` | `"group"` | yes |  | Marks the asset as a group. |
| `stimuli` | `Asset[]` | yes |  | The pool. Members can be any single asset type, or side-by-side sets. |
| `showCount` | `number` | yes |  | How many members each respondent sees. The section repeats once for each. |
| `displaySeconds` | `number \| null` | no |  | Show each member for this many seconds, then hide it. |
| `sizing` | `"fit" \| "fit-width" \| "fit-height"` | no |  | How each member fits the frame. |

Example: Sequential monadic: each respondent sees 2 of 4 concepts

```json
{
  "type": "group",
  "showCount": 2,
  "stimuli": [
    {
      "type": "image",
      "url": "https://cdn.example.com/concepts/a.png",
      "name": "Concept A"
    },
    {
      "type": "image",
      "url": "https://cdn.example.com/concepts/b.png",
      "name": "Concept B"
    },
    {
      "type": "image",
      "url": "https://cdn.example.com/concepts/c.png",
      "name": "Concept C"
    },
    {
      "type": "image",
      "url": "https://cdn.example.com/concepts/d.png",
      "name": "Concept D"
    }
  ]
}
```

Notes:

- Do not follow a group with a "Which one did you prefer?" section. The order is random and respondents may see only some members. Compare the members in analysis, or use a side-by-side set.

#### Side by side (`side_by_side`)

Up to 4 images or HTML pages on screen at the same time, for direct comparison.

Voicepanel gives each member a random 3-digit label, such as "482", and shows it on screen. Respondents say the label to name a design. Questions can name a position with template variables such as {{stimulus.first.label}}.

| Field | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `type` | `"side_by_side"` | yes |  | Marks the asset as a side-by-side set. |
| `stimuli` | `Asset[]` | yes |  | Two to four members of type "image" or "html". Do not set a label. Voicepanel assigns one when you save. |
| `displaySeconds` | `number \| null` | no |  | Show the set for this many seconds, then hide it. |
| `sizing` | `"fit" \| "fit-width" \| "fit-height"` | no |  | How each member fits its frame. |

Example

```json
{
  "type": "side_by_side",
  "stimuli": [
    {
      "type": "image",
      "url": "https://cdn.example.com/checkout-a.png",
      "name": "Checkout A"
    },
    {
      "type": "image",
      "url": "https://cdn.example.com/checkout-b.png",
      "name": "Checkout B"
    }
  ],
  "sizing": "fit"
}
```

Notes:

- A side-by-side set needs device "desktop" or "any". On a phone, Voicepanel shows the members one after another.
- A group can hold side-by-side sets, so each respondent compares a different random pair.

#### Display settings (`placement / displaySeconds / sizing`)

Control when and how long an asset is visible. Build five-second tests, first-impression tests, and memory tests.

| Field | Values | Effect |
| --- | --- | --- |
| `placement` | "throughout" (default), "at-start" | "throughout" keeps the asset next to every step. "at-start" shows it once, full screen, before the steps. |
| `displaySeconds` | number | Show the asset for N seconds, then hide it. A value above 0 also means "at-start". |
| `sizing` | "fit", "fit-width", "fit-height" | Fit the whole asset, the width, or the height into the frame. |

Example: Five-second test

```json
{
  "type": "image",
  "url": "https://cdn.example.com/landing.png",
  "name": "Landing page",
  "placement": "at-start",
  "displaySeconds": 5
}
```

Notes:

- "at-start" applies to image and text assets.
- Image, prototype, text, HTML, and audio assets show inline, next to the questions. Websites, apps, and videos open in a full-screen view with the instructions.

#### Asset metadata (`metadata`)

Tag each asset with your own attributes, such as price tier, model, or variant. Analysis groups and compares results by them.

Metadata is a flat object. A key maps to a string, a number, a boolean, or a list of strings and numbers. Nested objects become dotted keys: { "pricing": { "tier": "pro" } } is stored as { "pricing.tier": "pro" }.

Set metadata in the plan, through PUT /api/v1/stimuli/{stimulus_id}/metadata, or with the set_stimulus_metadata MCP tool. A plan that does not name metadata leaves the stored attributes unchanged.

Example

```json
{
  "type": "text",
  "name": "Answer from model A",
  "content": "Here are three ways to lower your energy bill...",
  "metadata": {
    "model": "model-a",
    "temperature": 0.2,
    "grounded": true,
    "tags": [
      "energy",
      "tips"
    ]
  }
}
```

Notes:

- Questions can read metadata with template variables, such as {{stimulus.metadata.price}}. See Template variables.

### Logic

Logic changes the path for each respondent. Show a section only to the people it applies to, shuffle sections and options, and pipe earlier answers into later questions.

Conditional sections use 0-based indexes. Answer piping uses 1-based numbers. Keep this difference in mind when you write both in one plan.

#### Show a section based on an answer (`conditionalBranch (question)`)

Show a section only when an earlier single choice, multiple choice, or rating scale answer matches one of the trigger values.

| Field | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `sourceType` | `"question"` | no | `"question"` | Optional for this branch type. |
| `sourceSectionIndex` | `number` | yes |  | The 0-based index of the section that holds the source question. It must be an earlier section. |
| `sourceStepIndex` | `number` | yes |  | The 0-based index of the source step in that section. |
| `triggerValues` | `string[]` | yes |  | The option values that show the section. They must match the option values exactly. For multiple choice, the section shows if the answer includes any of them. For a rating scale, use the numbers as strings, such as "0". |

Example: Detractor follow-up

```json
{
  "sourceType": "question",
  "sourceSectionIndex": 0,
  "sourceStepIndex": 0,
  "triggerValues": [
    "0",
    "1",
    "2",
    "3",
    "4",
    "5",
    "6"
  ]
}
```

#### Show a section based on a task result (`conditionalBranch (task)`)

Show a section only to respondents who completed, or did not complete, an earlier task.

| Field | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `sourceType` | `"task"` | yes |  | Marks a task-based branch. |
| `sourceSectionIndex` | `number` | yes |  | The 0-based index of the section that holds the task. |
| `sourceStepIndex` | `number` | yes |  | The 0-based index of the task step. |
| `triggerValues` | `("completed" \| "not_completed")[]` | yes |  | The task results that show the section. |

Example

```json
{
  "sourceType": "task",
  "sourceSectionIndex": 1,
  "sourceStepIndex": 0,
  "triggerValues": [
    "not_completed"
  ]
}
```

#### Show a section based on a segment (`conditionalBranch (segment)`)

Show a section only to respondents in a segment, such as a plan tier or a persona, that a segmentation assigns.

| Field | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `sourceType` | `"segment"` | yes |  | Marks a segment-based branch. |
| `segmentationKey` | `string` | yes |  | The key of an existing segmentation on the study. The list_segmentations MCP tool returns the keys. |
| `triggerValues` | `string[]` | yes |  | The segment values that show the section. |

Example

```json
{
  "sourceType": "segment",
  "segmentationKey": "plan_tier",
  "triggerValues": [
    "enterprise"
  ]
}
```

#### Section randomization (`randomizations`)

Shuffle the order of a group of sections for each respondent, to remove order bias.

| Field | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `sectionIndices` | `number[]` | yes |  | The 0-based indexes of the sections to shuffle. A plan can have more than one group. |

Example: Shuffle sections 2, 3, and 4

```json
{
  "sectionIndices": [
    1,
    2,
    3
  ]
}
```

Notes:

- Keep intro and wrap-up sections out of randomization groups.
- Answer piping uses the authored section number, so randomization does not change it.

#### Option order and exclusivity (`shuffle_options / anchor / exclusive`)

Shuffle options per respondent, pin catch-all options in place, and make an option clear the others.

| Field | Where | Effect |
| --- | --- | --- |
| `shuffle_options` | single_select, multi_select, ranking | Shuffle the options for each respondent. |
| `anchor` | One option | Keep this option in its position while the others shuffle. Use it for "None of the above" and "Other", and put them last. |
| `exclusive` | One option, multi_select only | Selecting this option clears all other selections. |

Example: A catch-all option

```json
{
  "value": "None of the above",
  "anchor": true,
  "exclusive": true
}
```

Notes:

- Shuffle unordered lists, such as brands, features, and reasons. Do not shuffle ordered lists, such as frequencies, price bands, and agreement levels.

#### Template variables (`{{ }}`)

Insert earlier answers, link parameters, response IDs, and asset attributes into question text and asset URLs.

Write a variable in double curly braces. Variables resolve in question text, option text, rating scale labels, and asset URLs. An unknown variable renders as an empty string.

| Variable | Resolves to |
| --- | --- |
| `{{<section>.<step>}}` | An earlier answer. Both numbers are 1-based: {{1.2}} is the answer to step 2 of section 1. A probed step gives its most recent answer. |
| `{{<query_param>}}` | Any query parameter on the link the respondent opened. ?plan=Pro makes {{plan}} render as Pro. |
| `{{response_id}}` | The unique ID of the response. |
| `{{voicepanelResponseId}}` | The same value as {{response_id}}. |
| `{{response_number}}` | The respondent's sequence number in the study. |
| `{{stimulus.metadata.<key>}}` | A metadata value of the asset on screen, when the section shows one asset at a time (a single asset, or one iteration of a group). Not available in asset URLs. |
| `{{stimulus.first.label}}` | The on-screen label of the first side-by-side member. Positions are first to tenth. |
| `{{stimulus.first.metadata.<key>}}` | A metadata value of the member in that side-by-side position. |
| `{{asset.…}}` | The same values as {{stimulus.…}}. |
| `{{segment_<key>}}` | A segment value. Resolves in distribution redirect URLs only. |

Example: Pipe an earlier answer

```json
{
  "type": "long_question",
  "question": "You said you use {{1.2}} most often. What keeps you there?",
  "probing_type": "light"
}
```

Example: Personalize an asset URL with a link parameter

```json
{
  "type": "website",
  "url": "https://example.com/onboarding?account={{account}}&rid={{response_id}}",
  "name": "Onboarding"
}
```

### Study settings

Study settings apply to the whole study and to every distribution of it. The device is a field of the plan. The other settings are fields on the study, next to plan, when you create or update it.

#### Device restriction (`device`)

Restrict the study to any browser, a desktop, a phone, an iPhone, or an Android phone.

Pick the narrowest device the study needs, and use "any" when nothing forces one. Distributions inherit the device, so an "ios" study is offered to iPhone respondents only.

| Value | Meaning | Required by |
| --- | --- | --- |
| `any` | A phone or desktop browser. The default. | — |
| `desktop` | A desktop browser. | recording.screen, side-by-side sets (or any) |
| `mobile` | A phone browser on iOS or Android. | — |
| `ios` | An iPhone. Mobile screen recording uses the Voicepanel iPhone app. | recording.mobile_screen, App Store and TestFlight links |
| `android` | An Android phone. | Google Play links |

Example: An iPhone-only app test

```json
{
  "version": "2025_04",
  "device": "ios",
  "randomizations": [],
  "sections": [
    {
      "intro": "Open our app on your iPhone.",
      "stimulus": {
        "type": "mobile_app",
        "url": "https://apps.apple.com/us/app/example/id123456789",
        "name": "Example for iOS"
      },
      "recording": {
        "audio": true,
        "video": false,
        "screen": false,
        "mobile_screen": true
      },
      "steps": [
        {
          "type": "task",
          "question": "Find the settings page and turn on reminders.",
          "task_type": "generic_instruction",
          "expected_duration_seconds": 120
        }
      ]
    }
  ]
}
```

Notes:

- If you omit device when you create a study, Voicepanel derives it from the recording modes and assets. If you omit it on an edit, the study keeps its device.
- The API and the MCP server reject a plan that its device cannot run, and name the section that conflicts.

#### Study language (`written_in_language`)

Write the study in one language. Respondents take it in any of 37 languages.

Set written_in_language to the language of your plan. Voicepanel translates the intros, questions, and options into the language of each respondent, and accepts voice and text answers in that language.

Each distribution chooses the language a respondent sees first, and can pretranslate the study for review. See Languages and pretranslation in the Distribution part.

| Field | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `written_in_language` | `string` | no | `"en"` | The language code of the plan, such as "en" or "de". |

Example

```json
{
  "display_name": "Einkaufsgewohnheiten",
  "written_in_language": "de"
}
```

#### Welcome page and branding (`show_welcome_page`)

Greet respondents with your study name, your logo, and a welcome message.

| Field | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `display_name` | `string` | no |  | The study name that respondents see. |
| `show_welcome_page` | `boolean` | no |  | Show a welcome page before the first section. |
| `welcome_text` | `string` | no |  | The text on the welcome page. |
| `brand_logo_url` | `string` | no |  | A logo to show during the study. |

Example

```json
{
  "display_name": "Checkout feedback",
  "show_welcome_page": true,
  "welcome_text": "Thanks for helping us improve our checkout. There are no wrong answers.",
  "brand_logo_url": "https://cdn.example.com/acme-logo.png"
}
```

#### Read-aloud voice (`enable_tts_default`)

Read every question aloud with a natural text-to-speech voice, for a spoken, interview-like experience.

| Field | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `enable_tts_default` | `boolean` | no |  | Read every question aloud with text-to-speech. |
| `tts_voice_id` | `string` | no |  | The text-to-speech voice. See the table below. |

| Voice | Accent | tts_voice_id |
| --- | --- | --- |
| `Sarah (default)` | American, female | EXAVITQu4vr4xnSDxMaL |
| `Lily` | British, female | pFZP5JQG7iQjIQuC4Bku |
| `Katie` | Irish, female | sgk995upfe3tYLvoGcBN |
| `Nora` | Danish, female | ONFS8Q3TuiPLQCXXa4dy |
| `Adam` | American, male | pNInz6obpgDQGcFmaJgB |
| `Daniel` | British, male | onwK4e9ZLuTAKqWW03F9 |
| `Charlie` | Australian, male | IKne3meq5aSn9XLyUdCD |
| `Michael` | German, male | 42I57fNB7wi2PIYWo0Xr |

Example

```json
{
  "enable_tts_default": true,
  "tts_voice_id": "onwK4e9ZLuTAKqWW03F9"
}
```

#### Research context (`objective`)

Tell Voicepanel what the study must find out and what your product is. AI probing, AI conversations, and the analysis all use this context.

| Field | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `internal_name` | `string` | no |  | A name for your team only. |
| `objective` | `string` | no |  | What the study must find out. AI follow-up questions and the analysis focus on it. |
| `context` | `string` | no |  | Background on your brand or product, so AI follow-up questions are informed. |
| `target_length_min` | `number` | no |  | The target length of a session, in minutes. |
| `brand_words` | `string[]` | no |  | Brand names and jargon. They improve transcription accuracy. |

Example

```json
{
  "internal_name": "Q3 checkout study",
  "objective": "Find out where first-time buyers get stuck in the new checkout, and why.",
  "context": "Acme sells refurbished electronics online. The new checkout adds a trade-in step.",
  "target_length_min": 10,
  "brand_words": [
    "Acme",
    "TradeIn+"
  ]
}
```

## Part 2: Distribution. Who gives the feedback?

A distribution decides who takes the study and how they reach it. Pick a channel, target an audience, screen each person, and balance the sample with quotas.

One design can have many distributions at once. Send the same study to a panel in three countries and to your own customers, each with its own screener, quota, and language.

### Channels

A distribution sends the study to people. Set the channel with type. One study can have many distributions at the same time, and each one has its own audience, screener, quota, and language.

Create a distribution with POST /api/v1/distributions and the study_id. Every distribution starts as a draft. See Lifecycle.

#### Link (`link`)

A shareable link that you send to your own customers, users, or community.

Use it for:

- Customer lists, newsletters, and CRM campaigns
- Community, social, and forum posts
- A button in your product, your help center, or an email signature
- A hand-off from another survey tool or a partner panel, with redirects back

Example

```json
{
  "name": "Newsletter readers",
  "type": "link",
  "quota_limit": 300,
  "quota_frequency": "lifetime",
  "collect_email": true,
  "default_response_language": "en-US",
  "complete_redirect_url": "https://example.com/thanks"
}
```

Notes:

- When you publish a link distribution, Voicepanel returns share_url, the public link to send.
- Add query parameters to the link to pass data into the study. See Link parameters.

#### Panel recruitment (`panel`)

Voicepanel recruits participants from research panels that match your audience, consumers or professionals.

Describe who you need and how many. Voicepanel posts the study to the panel, screens each applicant, and invites the people who qualify. You do not need your own list of participants.

| Field | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `config.targetMarketType` | `"b2c" \| "b2b"` | no |  | Consumers (b2c), or professionals targeted by job, industry, and company (b2b). |
| `config.targetNumberOfParticipants` | `number` | no |  | How many participants to recruit. |
| `quota_limit` | `number` | no |  | The number of completed responses to collect. Usually the same as the number of participants. |
| `automatic_invites` | `boolean` | no | `true` | Invite applicants as soon as they pass the screener. Set it to false to approve each applicant by hand. |

Example

```json
{
  "name": "US finance managers",
  "type": "panel",
  "config": {
    "targetMarketType": "b2b",
    "targetNumberOfParticipants": 12
  },
  "quota_limit": 12,
  "automatic_invites": false
}
```

Notes:

- The panel filters are stored in config. Voicepanel generates them from a plain-text audience description. See Panel audience.

#### Intercept (`website`)

Invite the visitors of your own website or web app while they use it, through the Voicepanel snippet.

Install the snippet once. Then each intercept distribution decides which visitors see the study, with a targeting condition and a traffic sample. The Voicepanel app shows this channel as Intercept, and the API stores it as type "website".

| Field | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `key` | `string` | no |  | The snippet key. Your code can also open the study directly with this key. |
| `targeting_condition` | `Condition` | no |  | Which visitors see the study. See Intercept targeting. |
| `traffic_threshold` | `number` | no |  | The share of matching visitors who see the study, out of 1,000,000. See Traffic sampling. |

Example

```json
{
  "name": "Post-purchase intercept",
  "type": "website",
  "key": "post-purchase",
  "targeting_condition": {
    "op": "EQUALS",
    "args": [
      {
        "type": "property",
        "value": "eventName"
      },
      {
        "type": "constant",
        "value": "order_completed"
      }
    ]
  },
  "traffic_threshold": 100000,
  "quota_limit": 50,
  "quota_frequency": "weekly"
}
```

Notes:

- By default, a visitor sees the same intercept at most once in 90 days.
- A study that records the phone screen cannot run as an intercept.

### Audience targeting

Targeting decides who is offered the study. A screener then confirms that each person qualifies, and quotas balance the final sample.

The plan device targets too. An "ios" study is offered only to people on an iPhone.

#### Panel audience (`config`)

Target panel participants by demographic and professional attributes, or describe the audience in plain text.

Describe the audience in plain text, such as "US enterprise IT admins who manage Okta" or "parents in Mexico who shop for groceries online". Voicepanel turns the description into panel filters and a screener. In the dashboard, use Create with AI. Over the MCP server, pass audience to create_panel_distribution.

You can also set the filters by hand. The available attributes depend on the panel. These are the common ones:

| Attribute | Audience | Examples |
| --- | --- | --- |
| `Country and region` | b2c and b2b | United States; Ontario, Canada |
| `Age` | b2c and b2b | 25 to 44 |
| `Gender` | b2c and b2b | Women |
| `Household income` | b2c | $75,000 to $150,000 |
| `Education` | b2c | Bachelor's degree or higher |
| `Ethnicity` | b2c | Hispanic or Latino |
| `Job title and occupation` | b2b | Product manager; nurse |
| `Industry` | b2b | Financial services; healthcare |
| `Company size` | b2b | 1,000 employees or more |
| `Skills` | b2b | Salesforce; Kubernetes |

Notes:

- Use targeting for what the panel knows about a person, and a screener for everything else: behaviors, products used, and purchase intent.

#### Intercept targeting (`targeting_condition`)

A condition tree that decides which visitors of your site or app see an intercept.

A condition node is { op, args }. A value node is { type: "property", value } or { type: "constant", value }. Nest AND, OR, and NOT to combine rules.

Set targeting_condition through the REST API. When your app sends an event to the snippet, Voicepanel checks each intercept against the page and the event. The properties are url, path, search, hash, eventName, userId, and every custom property that you send with the event, such as plan or country.

| op | Arguments | True when |
| --- | --- | --- |
| `EQUALS` | A property and a constant | The property equals the constant. |
| `REGEXP_MATCH` | A property, then a constant | The property matches the regular expression. |
| `AND` | Two or more conditions | Every condition is true. |
| `OR` | Two or more conditions | At least one condition is true. |
| `NOT` | One condition | The condition is false. |

Example: Enterprise users who export a report

```json
{
  "name": "Reporting feedback",
  "type": "website",
  "key": "reporting-feedback",
  "targeting_condition": {
    "op": "AND",
    "args": [
      {
        "op": "EQUALS",
        "args": [
          {
            "type": "property",
            "value": "eventName"
          },
          {
            "type": "constant",
            "value": "report_exported"
          }
        ]
      },
      {
        "op": "EQUALS",
        "args": [
          {
            "type": "property",
            "value": "plan"
          },
          {
            "type": "constant",
            "value": "enterprise"
          }
        ]
      },
      {
        "op": "REGEXP_MATCH",
        "args": [
          {
            "type": "property",
            "value": "path"
          },
          {
            "type": "constant",
            "value": "^/reports"
          }
        ]
      }
    ]
  }
}
```

#### Traffic sampling (`traffic_threshold`)

Show an intercept to a share of the matching visitors, so a busy page does not ask everyone.

| traffic_threshold | Share of matching visitors |
| --- | --- |
| `1000000` | All of them |
| `100000` | 10% |
| `10000` | 1% |
| `1000` | 0.1% |

Notes:

- The sample uses a stable ID for each visitor, so a visitor gets the same result on every visit.

#### Email allow-list (`screen_email`)

Let only the people on your email list take a link study, such as beta testers or one customer segment.

The respondent enters an email address before the study. Voicepanel checks the address against the list and screens out everyone else.

| Field | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `screen_email` | `boolean` | no |  | Screen respondents against an email list. |
| `email_list_id` | `string` | no |  | The email list to check against. |

Example

```json
{
  "name": "Beta customers",
  "type": "link",
  "collect_email": true,
  "screen_email": true,
  "email_list_id": "list_beta_customers"
}
```

### Screeners

A screener is a short set of questions before the study. Each answer carries a qualification rule, so Voicepanel admits or screens out each respondent automatically.

Screeners belong to the distribution, not to the plan. The same study can use a different screener for each audience. Write the questions by hand, or describe the audience and Voicepanel writes them.

Link and panel distributions run screeners. An intercept targets visitors with its targeting condition instead.

#### Screener question (`screener_questions`)

Single choice, multiple choice, AI-evaluated open answers, and matrix grids.

| Field | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `text` | `string` | yes |  | The question. |
| `type` | `"radio" \| "checkbox" \| "open_ended" \| "matrix_radio" \| "matrix_checkbox"` | yes |  | Single choice, multiple choice, an open answer, or a grid with one or many answers for each row. |
| `isRequired` | `boolean` | yes |  | The respondent must answer. |
| `earlyScreenout` | `boolean` | no |  | Screen out as soon as this answer fails, before the next question. Use it for hard requirements only. |
| `randomizeOptions` | `boolean \| null` | no |  | Shuffle the options, so their order does not bias the answers. |
| `options` | `{ text, qualification, anchor, exclusive }[]` | no |  | The choices for radio and checkbox questions. See Choice rules. |
| `signals` | `{ text, qualifyLogic }[]` | no |  | What AI looks for in an open answer. See AI-evaluated open answer. |
| `columns, rows` | `{ text }[], { text, cells }[]` | no |  | The grid of a matrix question. See Matrix question. |

Example

```json
{
  "text": "Which of these have you done in the past three months?",
  "type": "checkbox",
  "isRequired": true,
  "earlyScreenout": false,
  "randomizeOptions": true,
  "options": [
    {
      "text": "Booked a flight online",
      "qualification": "must_one_of"
    },
    {
      "text": "Booked a hotel online",
      "qualification": "must_one_of"
    },
    {
      "text": "Rented a car online",
      "qualification": "may_select"
    },
    {
      "text": "None of these",
      "qualification": "disqualify",
      "anchor": true,
      "exclusive": true
    }
  ]
}
```

Notes:

- Ask broad questions first and narrow questions last.

#### Choice rules (`qualification`)

Each option of a radio or checkbox question carries one qualification rule.

| qualification | Question type | Meaning |
| --- | --- | --- |
| `qualify` | radio | Choosing this option passes the question. |
| `disqualify` | radio, checkbox | Choosing this option screens the respondent out. |
| `must_select` | checkbox | The respondent must choose this option. |
| `must_one_of` | checkbox | The respondent must choose at least one of the options with this rule. |
| `may_select` | checkbox | This option neither passes nor fails the question. |

Example

```json
{
  "text": "What is your role in buying software for your team?",
  "type": "radio",
  "isRequired": true,
  "earlyScreenout": true,
  "randomizeOptions": false,
  "options": [
    {
      "text": "I make the final decision",
      "qualification": "qualify"
    },
    {
      "text": "I recommend options",
      "qualification": "qualify"
    },
    {
      "text": "I am not involved",
      "qualification": "disqualify"
    }
  ]
}
```

Notes:

- anchor: true keeps an option in place when the options shuffle. exclusive: true clears the other selections of a checkbox question.

#### AI-evaluated open answer (`open_ended`)

The respondent answers in their own words, and AI checks the answer for the signals you define.

Use an open answer to check experience in the respondent's own words, such as the tool they use or the last time they bought something.

| qualifyLogic | Meaning |
| --- | --- |
| `must` | The answer must show this signal to pass. |
| `must_not` | An answer that shows this signal screens out. |
| `may` | Record the signal without screening on it. |

Example

```json
{
  "text": "Describe the last time you reconciled expenses for your team. Which tool did you use?",
  "type": "open_ended",
  "isRequired": true,
  "earlyScreenout": false,
  "signals": [
    {
      "text": "Describes a specific, recent expense process",
      "qualifyLogic": "must"
    },
    {
      "text": "Names an expense or accounting tool",
      "qualifyLogic": "may"
    },
    {
      "text": "Handles only personal expenses",
      "qualifyLogic": "must_not"
    }
  ]
}
```

#### Matrix question (`matrix_radio`)

A grid of rows and columns, with a qualification rule in each cell. Use matrix_checkbox to allow several answers in each row.

Example

```json
{
  "text": "How often do you use each of these apps?",
  "type": "matrix_radio",
  "isRequired": true,
  "earlyScreenout": false,
  "randomizeOptions": true,
  "columns": [
    {
      "text": "Weekly"
    },
    {
      "text": "Monthly"
    },
    {
      "text": "Never"
    }
  ],
  "rows": [
    {
      "text": "Spotify",
      "cells": [
        {
          "qualification": "qualify"
        },
        {
          "qualification": "qualify"
        },
        {
          "qualification": "disqualify"
        }
      ]
    },
    {
      "text": "Apple Music",
      "cells": [
        {
          "qualification": "qualify"
        },
        {
          "qualification": "qualify"
        },
        {
          "qualification": "qualify"
        }
      ]
    }
  ]
}
```

### Quotas

Quotas control how many people complete the study, and the mix of those people. Only completed responses count toward a quota.

When a quota is full, Voicepanel stops admitting respondents to it and sends them to quota_full_redirect_url, if you set one.

#### Response quota (`quota_limit`)

Cap the number of completed responses, once or on a repeating schedule.

| Field | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `quota_limit` | `number \| null` | no |  | The maximum number of completed responses. null means no limit. |
| `quota_frequency` | `"lifetime" \| "monthly" \| "weekly" \| "daily"` | no | `"lifetime"` | How often the count resets. Use a repeating quota for an always-on link or intercept. A panel distribution uses "lifetime". |

Example: An always-on survey

```json
{
  "name": "Always-on NPS",
  "type": "link",
  "quota_limit": 50,
  "quota_frequency": "weekly"
}
```

#### Segment quotas (`segment_quotas`)

Set a quota for each segment, and nest segments for interlocking quotas.

A segment sorts respondents by a screener answer, a link query parameter, or a panel profile field. Name the segment with segment_key, then give a quota for each value.

To interlock two segments, give a value its own segment_key and values. The example collects 50 respondents for each combination of country and age group.

| Field | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `segment_key` | `string` | yes |  | The segment to split on. |
| `values` | `Record<string, { quota, segment_key?, values? }>` | yes |  | A quota for each segment value. Add segment_key and values inside a value to nest another segment. |

Example: Interlocking quotas

```json
{
  "name": "US and UK shoppers",
  "type": "panel",
  "config": {
    "targetMarketType": "b2c",
    "targetNumberOfParticipants": 200
  },
  "quota_limit": 200,
  "segment_quotas": {
    "segment_key": "country",
    "values": {
      "US": {
        "quota": 100,
        "segment_key": "age_group",
        "values": {
          "18-34": {
            "quota": 50
          },
          "35+": {
            "quota": 50
          }
        }
      },
      "UK": {
        "quota": 100,
        "segment_key": "age_group",
        "values": {
          "18-34": {
            "quota": 50
          },
          "35+": {
            "quota": 50
          }
        }
      }
    }
  }
}
```

Notes:

- A respondent who matches none of the values at a level is screened out, so list every value that you want to admit.

### Languages and pretranslation

Write the study once. Each respondent takes it in their own language, from 37 supported languages, and Voicepanel accepts voice and text answers in that language.

#### Response language (`default_response_language`)

Choose the language that a respondent sees first.

Voicepanel picks the first language that it finds in this order:

| Order | Source | Example |
| --- | --- | --- |
| `1` | The lang query parameter on the link | ?lang=es |
| `2` | default_response_language on the distribution | "es-MX" |
| `3` | The language of the respondent's browser | fr-FR |

Example

```json
{
  "name": "Mexico shoppers",
  "type": "panel",
  "config": {
    "targetMarketType": "b2c",
    "targetNumberOfParticipants": 30
  },
  "quota_limit": 30,
  "default_response_language": "es-MX"
}
```

#### Pretranslation (`translations`)

Translate the study into the locales you choose before launch, so your team can review each translation.

By default, Voicepanel translates the study when each session starts. With pretranslation, Voicepanel translates the study once for each locale that you choose, such as fr-FR or es-MX, and stores the result on the distribution.

A pretranslation covers the intros, questions, options, rating labels, welcome text, and study name. For a link distribution, it also covers the screener and the incentive text.

Choose the locales on the distribution form in the dashboard. Voicepanel translates the study when you open the distribution to review it. A string without a pretranslation falls back to live translation.

### Links, tracking, and redirects

Connect a distribution to the rest of your stack. Pass data in on the link, identify each participant, collect an email, reward respondents, and send them on when they finish.

#### Link parameters (`?name=value`)

Add query parameters to a link to pass data about each respondent into the study.

Voicepanel saves every query parameter on the response. Use a parameter in a question as a template variable, in a segment for quotas and conditional sections, and in a redirect URL.

| Parameter | Meaning |
| --- | --- |
| `cid` | A participant ID from your system. Required when the study sets uniqueness_constraint. |
| `lang` | The respondent language, such as es or fr-FR. |
| `complete_redirect_uri` | Overrides complete_redirect_url for this link. screen_out_redirect_uri and quota_full_redirect_uri work the same way. |
| `Any other name` | Saved on the response, for example ?plan=pro&source=newsletter. |

#### Unique participants (`uniqueness_constraint`)

Require a participant ID on every link, and optionally allow one submission for each ID.

| Field | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `uniqueness_constraint` | `"custom_id_required" \| "custom_id_required_single_submission" \| null` | no |  | A study field. custom_id_required rejects a link without cid. custom_id_required_single_submission also rejects a cid that already has a response. Set it on update or through the MCP server. |

#### Redirects (`complete_redirect_url`)

Send respondents to your site, a panel, or another survey at the end of the study.

| Field | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `complete_redirect_url` | `string` | no |  | Where respondents go when they complete the study. |
| `screen_out_redirect_url` | `string` | no |  | Where respondents go when they fail the screener. |
| `quota_full_redirect_url` | `string` | no |  | Where respondents go when the quota is full. |

Example: Hand respondents back to a partner panel

```json
{
  "name": "Partner panel",
  "type": "link",
  "complete_redirect_url": "https://partner.example.com/done?pid={{pid}}&status=complete",
  "screen_out_redirect_url": "https://partner.example.com/done?pid={{pid}}&status=screenout",
  "quota_full_redirect_url": "https://partner.example.com/done?pid={{pid}}&status=full"
}
```

Notes:

- A redirect URL resolves template variables: each link query parameter by name, such as {{pid}}, each segment as {{segment_<key>}}, and {{response_id}}.

#### Email collection (`collect_email`)

Ask each respondent for an email address before the study, to send an incentive or follow up later.

| Field | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `collect_email` | `boolean` | no |  | Ask for an email address before the study. |

#### Incentive (`incentive`)

Reward link respondents when they finish, with a promo code, a unique code from a list, a claim link, or a gift card. Panels reward their own participants.

| type | What the respondent gets | Extra fields |
| --- | --- | --- |
| `promo_code` | One code, the same for everyone. | code |
| `promo_code_from_list` | A unique code from a list that you upload. | promo_code_list_id |
| `promo_code_url` | A button that opens a claim link. | claim_url, claim_text |
| `gift_card` | A gift card. | — |

Example

```json
{
  "name": "Community members",
  "type": "link",
  "collect_email": true,
  "incentive": {
    "type": "promo_code",
    "title": "Thank you!",
    "description": "Use this code for a discount on your next order.",
    "code": "THANKYOU"
  }
}
```

### Lifecycle

Every distribution moves through a set of statuses. Launch, pause, and close each one without changes to the study.

#### Status and publishing (`status`)

A distribution starts as a draft and goes live when you publish it.

| status | Meaning |
| --- | --- |
| `draft` | Set up, not yet live. Every distribution starts here. |
| `in_review` | Waiting for review before it goes live. |
| `published` | Live. Respondents can take the study. |
| `paused` | Temporarily closed to new respondents. |
| `completed` | Closed. The quota is full, or you ended it. |

Notes:

- Publish with POST /api/v1/distributions/{id}/publish.
- When you publish, Voicepanel freezes a copy of the plan and the device into the distribution. Every respondent of that distribution sees the same version of the study.

## Part 3: What you can build. Which studies can you run?

Teams usually split these methods across a usability testing tool, a survey tool, and an interview tool. In Voicepanel, each one is a study made of the same blocks.

Every example is a complete study that you can copy, change, and send to the API. Most studies have several sections.

| Method | Example | Sections |
| --- | --- | --- |
| Mixed-method product feedback | Product feedback study for a team planning app | 4 |
| Unmoderated usability test | Website usability test with think-aloud | 4 |
| Competitive usability benchmark | Home insurance quote: your site against a competitor | 4 |
| Mobile app test | iPhone app onboarding test | 4 |
| Five-second test and first impressions | Five-second test of a landing page | 3 |
| Concept test (monadic or sequential monadic) | Sequential monadic concept test | 4 |
| Design preference and A/B comparison | Side-by-side checkout preference test | 3 |
| NPS, CSAT, and satisfaction surveys | NPS survey with detractor and promoter follow-ups | 4 |
| In-product intercept survey | In-product intercept after a report export | 3 |
| Customer discovery and in-depth interviews | Customer discovery interview | 3 |
| Video ad and creative testing | Video ad test with facial reactions | 3 |
| Message, copy, and claims testing | Value proposition test | 3 |
| Audio testing (podcasts, voice assistants, sonic branding) | Radio spot and brand voice test | 4 |
| Packaging, in-home use, and physical product tests | In-home product test | 3 |
| AI output and model evaluation | AI answer evaluation | 3 |
| Feature prioritization and pricing research | Roadmap and pricing survey | 4 |
| Brand perception and awareness | Brand awareness and perception tracker | 6 |
| Global and multi-country studies | Multi-country app launch study | 3 |
| Personalized and segmented studies | Personalized dashboard test for each account | 4 |
| Customer panels and beta programs | Beta program check-in | 4 |

Each design is listed from section 1 down. "on [Asset]" means that the asset spans the whole section, and every step of the section uses it.

### Product feedback study for a team planning app

Method: Mixed-method product feedback. Usually run in: A survey tool, a usability testing tool, and an interview tool, used together.

Foundational questions about how the team uses the app. Then a usability task on a prototype, a loop through three feature ideas, and a reflection section. The study records the screen, then the webcam, then the voice.

#### Design

Build, from section 1 down:

- Plan: [Desktop only]
- Section 1, Foundations: [Single choice] [Multiple choice] [Open-ended]
- Section 2, Usability task (on [Prototype: New project setup], [Record: screen + voice]): [Task] [Rating scale: 1–5]
- Section 3, Feature loop (on [Group: loops through all 3 images, one at a time + Metadata], [Record: webcam + voice]): [Rating scale: 1–7] [Open-ended + AI probing]
- Section 4, Reflection ([Record: voice]): [Rating scale: 0–10] [AI conversation: 2 min]

```json
{
  "version": "2025_04",
  "device": "desktop",
  "randomizations": [],
  "sections": [
    {
      "intro": "First, a few questions about how your team uses Planly.",
      "stimulus": null,
      "recording": null,
      "conditionalBranch": null,
      "steps": [
        {
          "type": "single_select",
          "question": "How often do you use Planly?",
          "options": [
            {
              "value": "Every day"
            },
            {
              "value": "A few times a week"
            },
            {
              "value": "A few times a month"
            },
            {
              "value": "Less often"
            }
          ]
        },
        {
          "type": "multi_select",
          "question": "Which parts of Planly does your team use?",
          "options": [
            {
              "value": "Boards"
            },
            {
              "value": "Calendar"
            },
            {
              "value": "Reports"
            },
            {
              "value": "Automations"
            }
          ],
          "shuffle_options": true
        },
        {
          "type": "long_question",
          "question": "What is the main job that your team uses Planly for?",
          "probing_type": "none",
          "response_format": "audio"
        }
      ]
    },
    {
      "intro": "Next, you will try a new way to set up a project. Please think out loud.",
      "stimulus": {
        "type": "prototype",
        "url": "https://www.figma.com/proto/abc123/Project-setup",
        "name": "New project setup"
      },
      "recording": {
        "audio": true,
        "video": false,
        "screen": true,
        "mobile_screen": false
      },
      "conditionalBranch": null,
      "steps": [
        {
          "type": "task",
          "question": "Create a project for a product launch and invite two teammates.",
          "task_type": "generic_instruction",
          "expected_duration_seconds": 180
        },
        {
          "type": "rating_scale",
          "question": "How easy was it to set up the project?",
          "options": [
            {
              "value": "1"
            },
            {
              "value": "2"
            },
            {
              "value": "3"
            },
            {
              "value": "4"
            },
            {
              "value": "5"
            }
          ],
          "lowest_rating_label": "Very difficult",
          "highest_rating_label": "Very easy"
        }
      ]
    },
    {
      "intro": "Now you will see three feature ideas, one at a time.",
      "stimulus": {
        "type": "group",
        "showCount": 3,
        "stimuli": [
          {
            "type": "image",
            "url": "https://cdn.example.com/planly/smart-scheduling.png",
            "name": "Smart scheduling",
            "metadata": {
              "feature": "smart scheduling"
            }
          },
          {
            "type": "image",
            "url": "https://cdn.example.com/planly/workload-view.png",
            "name": "Workload view",
            "metadata": {
              "feature": "a workload view"
            }
          },
          {
            "type": "image",
            "url": "https://cdn.example.com/planly/ai-summaries.png",
            "name": "AI summaries",
            "metadata": {
              "feature": "AI project summaries"
            }
          }
        ]
      },
      "recording": {
        "audio": true,
        "video": true,
        "screen": false,
        "mobile_screen": false
      },
      "conditionalBranch": null,
      "steps": [
        {
          "type": "rating_scale",
          "question": "How useful would {{stimulus.metadata.feature}} be for your team?",
          "options": [
            {
              "value": "1"
            },
            {
              "value": "2"
            },
            {
              "value": "3"
            },
            {
              "value": "4"
            },
            {
              "value": "5"
            },
            {
              "value": "6"
            },
            {
              "value": "7"
            }
          ],
          "lowest_rating_label": "Not at all useful",
          "highest_rating_label": "Extremely useful"
        },
        {
          "type": "long_question",
          "question": "When would you use this, and what would it replace?",
          "probing_type": "light"
        }
      ]
    },
    {
      "intro": "Last, look back on everything that you saw today.",
      "stimulus": null,
      "recording": {
        "audio": true,
        "video": false,
        "screen": false,
        "mobile_screen": false
      },
      "conditionalBranch": null,
      "steps": [
        {
          "type": "rating_scale",
          "question": "How likely are you to recommend Planly to a colleague?",
          "options": [
            {
              "value": "0"
            },
            {
              "value": "1"
            },
            {
              "value": "2"
            },
            {
              "value": "3"
            },
            {
              "value": "4"
            },
            {
              "value": "5"
            },
            {
              "value": "6"
            },
            {
              "value": "7"
            },
            {
              "value": "8"
            },
            {
              "value": "9"
            },
            {
              "value": "10"
            }
          ],
          "lowest_rating_label": "Not at all likely",
          "highest_rating_label": "Extremely likely"
        },
        {
          "type": "conversation",
          "question": "If you could change one thing about Planly tomorrow, what would it be?",
          "time_limit_seconds": 120,
          "conversation_mode": "no-guide"
        }
      ]
    }
  ]
}
```

#### Distribution

Send a link to 40 active customers. Voicepanel asks each respondent for their email, so you can match answers to accounts.

- Channel: Link
- Quota: 40 responses, lifetime
- Language: en-US
- Email: Collected before the study

```json
{
  "name": "Active Planly customers",
  "type": "link",
  "collect_email": true,
  "quota_limit": 40,
  "quota_frequency": "lifetime",
  "default_response_language": "en-US"
}
```

### Website usability test with think-aloud

Method: Unmoderated usability test. Usually run in: Usability testing tools.

Record the screen and voice while respondents book a hotel. A follow-up section appears only for the people who could not finish, and a short AI conversation closes the study.

#### Design

Build, from section 1 down:

- Plan: [Desktop only]
- Section 1, Background: [Single choice]
- Section 2, Booking task (on [Website: Travel site], [Record: screen + voice]): [Task] [Rating scale: 1–5] [Open-ended]
- Section 3, Follow-up if stuck ([Show if: task 2.1 not completed]): [Open-ended + AI probing]
- Section 4, Wrap-up: [AI conversation: 1 min]

```json
{
  "version": "2025_04",
  "device": "desktop",
  "randomizations": [],
  "sections": [
    {
      "intro": "First, a little about you.",
      "steps": [
        {
          "type": "single_select",
          "question": "How often do you book travel online?",
          "options": [
            {
              "value": "Every month"
            },
            {
              "value": "A few times a year"
            },
            {
              "value": "Once a year or less"
            }
          ]
        }
      ]
    },
    {
      "intro": "Next, you will use a travel website. Please think out loud the whole time.",
      "stimulus": {
        "type": "website",
        "url": "https://example-travel.com",
        "name": "Travel site"
      },
      "recording": {
        "audio": true,
        "video": false,
        "screen": true,
        "mobile_screen": false
      },
      "steps": [
        {
          "type": "task",
          "question": "Find a hotel in Lisbon for two adults next weekend, under $200 a night, and go as far as the payment page.",
          "task_type": "generic_instruction",
          "expected_duration_seconds": 240
        },
        {
          "type": "rating_scale",
          "question": "How easy was that task?",
          "options": [
            {
              "value": "1"
            },
            {
              "value": "2"
            },
            {
              "value": "3"
            },
            {
              "value": "4"
            },
            {
              "value": "5"
            }
          ],
          "lowest_rating_label": "Very difficult",
          "highest_rating_label": "Very easy"
        },
        {
          "type": "long_question",
          "question": "What, if anything, slowed you down?",
          "probing_type": "none"
        }
      ]
    },
    {
      "intro": "You mentioned that you could not finish the task.",
      "conditionalBranch": {
        "sourceType": "task",
        "sourceSectionIndex": 1,
        "sourceStepIndex": 0,
        "triggerValues": [
          "not_completed"
        ]
      },
      "steps": [
        {
          "type": "long_question",
          "question": "Where did you get stuck, and what did you expect to happen?",
          "probing_type": "custom",
          "probing_areas": "The exact page and control, what they tried, and what would have helped."
        }
      ]
    },
    {
      "intro": null,
      "steps": [
        {
          "type": "conversation",
          "question": "Is there anything else about the site you want to share?",
          "time_limit_seconds": 60,
          "conversation_mode": "no-guide"
        }
      ]
    }
  ]
}
```

#### Distribution

Recruit 15 people from a panel who book travel online, and screen out people who do not.

- Channel: Recruited panel of consumers
- Screener: 1 question
- Quota: 15 responses, lifetime

```json
{
  "name": "Online travel bookers",
  "type": "panel",
  "config": {
    "targetMarketType": "b2c",
    "targetNumberOfParticipants": 15
  },
  "quota_limit": 15,
  "screener_questions": [
    {
      "text": "How did you book your most recent hotel stay?",
      "type": "radio",
      "isRequired": true,
      "earlyScreenout": true,
      "randomizeOptions": true,
      "options": [
        {
          "text": "On a travel website or app",
          "qualification": "qualify"
        },
        {
          "text": "On the hotel's website",
          "qualification": "qualify"
        },
        {
          "text": "By phone or through an agent",
          "qualification": "disqualify"
        },
        {
          "text": "I have not stayed in a hotel",
          "qualification": "disqualify"
        }
      ]
    }
  ]
}
```

### Home insurance quote: your site against a competitor

Method: Competitive usability benchmark. Usually run in: Usability testing tools and benchmarking agencies.

Each respondent gets a quote on your site and on a competitor's site, with the screen and voice recorded. The two site sections come in random order to balance order effects. A final section asks which site they would buy from, and why.

#### Design

Build, from section 1 down:

- Plan: [Desktop only] [Shuffle: sections 2 or 3]
- Section 1, Background: [Single choice]
- Section 2, Your site (on [Website: Shieldly (your site)], [Record: screen + voice]): [Task] [Rating scale: 1–5] [Open-ended]
- Section 3, Competitor site (on [Website: CoverCo (competitor)], [Record: screen + voice]): [Task] [Rating scale: 1–5] [Open-ended]
- Section 4, Head-to-head: [Single choice] [Open-ended + AI probing]

```json
{
  "version": "2025_04",
  "device": "desktop",
  "randomizations": [
    {
      "sectionIndices": [
        1,
        2
      ]
    }
  ],
  "sections": [
    {
      "intro": "First, a little about how you buy insurance.",
      "steps": [
        {
          "type": "single_select",
          "question": "How did you buy your current home or renters policy?",
          "options": [
            {
              "value": "On the insurer's website"
            },
            {
              "value": "On a comparison site"
            },
            {
              "value": "Through an agent"
            },
            {
              "value": "I don't have a policy"
            }
          ]
        }
      ]
    },
    {
      "intro": "You will now use an insurance website. Please think out loud.",
      "stimulus": {
        "type": "website",
        "url": "https://shieldly.example.com",
        "name": "Shieldly (your site)"
      },
      "recording": {
        "audio": true,
        "video": false,
        "screen": true,
        "mobile_screen": false
      },
      "steps": [
        {
          "type": "task",
          "question": "Get a quote for renters insurance for a two-bedroom apartment. Stop when you see a price.",
          "task_type": "generic_instruction",
          "expected_duration_seconds": 240
        },
        {
          "type": "rating_scale",
          "question": "How easy was it to get a quote on Shieldly?",
          "options": [
            {
              "value": "1"
            },
            {
              "value": "2"
            },
            {
              "value": "3"
            },
            {
              "value": "4"
            },
            {
              "value": "5"
            }
          ],
          "lowest_rating_label": "Very difficult",
          "highest_rating_label": "Very easy"
        },
        {
          "type": "long_question",
          "question": "What, if anything, was confusing on Shieldly?",
          "probing_type": "none"
        }
      ]
    },
    {
      "intro": "You will now use a different insurance website. Please think out loud.",
      "stimulus": {
        "type": "website",
        "url": "https://coverco.example.com",
        "name": "CoverCo (competitor)"
      },
      "recording": {
        "audio": true,
        "video": false,
        "screen": true,
        "mobile_screen": false
      },
      "steps": [
        {
          "type": "task",
          "question": "Get a quote for renters insurance for a two-bedroom apartment. Stop when you see a price.",
          "task_type": "generic_instruction",
          "expected_duration_seconds": 240
        },
        {
          "type": "rating_scale",
          "question": "How easy was it to get a quote on CoverCo?",
          "options": [
            {
              "value": "1"
            },
            {
              "value": "2"
            },
            {
              "value": "3"
            },
            {
              "value": "4"
            },
            {
              "value": "5"
            }
          ],
          "lowest_rating_label": "Very difficult",
          "highest_rating_label": "Very easy"
        },
        {
          "type": "long_question",
          "question": "What, if anything, was confusing on CoverCo?",
          "probing_type": "none"
        }
      ]
    },
    {
      "intro": "Last, compare the two sites.",
      "steps": [
        {
          "type": "single_select",
          "question": "Which site would you buy renters insurance from?",
          "options": [
            {
              "value": "Shieldly"
            },
            {
              "value": "CoverCo"
            },
            {
              "value": "Neither"
            }
          ]
        },
        {
          "type": "long_question",
          "question": "Why would you choose that site?",
          "probing_type": "custom",
          "probing_areas": "Trust, price clarity, speed, and the moment that decided it."
        }
      ]
    }
  ]
}
```

#### Distribution

Recruit 30 people from a panel who plan to buy or renew home or renters insurance in the next 12 months.

- Channel: Recruited panel of consumers
- Screener: 1 question
- Quota: 30 responses, lifetime

```json
{
  "name": "Insurance shoppers",
  "type": "panel",
  "config": {
    "targetMarketType": "b2c",
    "targetNumberOfParticipants": 30
  },
  "quota_limit": 30,
  "screener_questions": [
    {
      "text": "Do you plan to buy or renew home or renters insurance in the next 12 months?",
      "type": "radio",
      "isRequired": true,
      "earlyScreenout": true,
      "randomizeOptions": false,
      "options": [
        {
          "text": "Yes",
          "qualification": "qualify"
        },
        {
          "text": "No",
          "qualification": "disqualify"
        },
        {
          "text": "I'm not sure",
          "qualification": "disqualify"
        }
      ]
    }
  ]
}
```

### iPhone app onboarding test

Method: Mobile app test. Usually run in: Usability testing tools.

Respondents install a budgeting app and set up their first budget. People who get stuck explain why, and everyone rates the experience.

#### Design

Build, from section 1 down:

- Plan: [iPhone only]
- Section 1, Background: [Single choice]
- Section 2, Onboarding task (on [Mobile app: Example Budget for iOS]): [Task] [Rating scale: 1–5]
- Section 3, Follow-up if stuck ([Show if: task 2.1 not completed]): [Open-ended]
- Section 4, App rating: [Open-ended] [Rating scale: 1–5]

```json
{
  "version": "2025_04",
  "device": "ios",
  "randomizations": [],
  "sections": [
    {
      "intro": "First, a little about how you manage money.",
      "steps": [
        {
          "type": "single_select",
          "question": "How do you keep track of your spending today?",
          "options": [
            {
              "value": "A budgeting app"
            },
            {
              "value": "A spreadsheet"
            },
            {
              "value": "My bank's app"
            },
            {
              "value": "I don't track it",
              "anchor": true
            }
          ],
          "shuffle_options": true
        }
      ]
    },
    {
      "intro": "Now install our app, if you don't have it yet, and open it.",
      "stimulus": {
        "type": "mobile_app",
        "url": "https://apps.apple.com/us/app/example/id123456789",
        "name": "Example Budget for iOS"
      },
      "steps": [
        {
          "type": "task",
          "question": "Create an account and set up your first monthly budget.",
          "task_type": "generic_instruction",
          "expected_duration_seconds": 300
        },
        {
          "type": "rating_scale",
          "question": "How easy was it to set up a budget?",
          "options": [
            {
              "value": "1"
            },
            {
              "value": "2"
            },
            {
              "value": "3"
            },
            {
              "value": "4"
            },
            {
              "value": "5"
            }
          ],
          "lowest_rating_label": "Very difficult",
          "highest_rating_label": "Very easy"
        }
      ]
    },
    {
      "intro": "You said that you could not finish the setup.",
      "conditionalBranch": {
        "sourceType": "task",
        "sourceSectionIndex": 1,
        "sourceStepIndex": 0,
        "triggerValues": [
          "not_completed"
        ]
      },
      "steps": [
        {
          "type": "long_question",
          "question": "What stopped you from finishing the setup?",
          "probing_type": "none"
        }
      ]
    },
    {
      "intro": "Last, a few questions about the app.",
      "steps": [
        {
          "type": "long_question",
          "question": "What was the most confusing part of the app?",
          "probing_type": "none"
        },
        {
          "type": "rating_scale",
          "question": "How likely are you to keep using the app?",
          "options": [
            {
              "value": "1"
            },
            {
              "value": "2"
            },
            {
              "value": "3"
            },
            {
              "value": "4"
            },
            {
              "value": "5"
            }
          ],
          "lowest_rating_label": "Not at all likely",
          "highest_rating_label": "Very likely"
        }
      ]
    }
  ]
}
```

#### Distribution

Recruit 12 people from a panel. The plan device is "ios", so only iPhone users can take the study.

- Channel: Recruited panel of consumers
- Quota: 12 responses, lifetime

```json
{
  "name": "iPhone budgeters",
  "type": "panel",
  "config": {
    "targetMarketType": "b2c",
    "targetNumberOfParticipants": 12
  },
  "quota_limit": 12
}
```

### Five-second test of a landing page

Method: Five-second test and first impressions. Usually run in: Usability testing tools.

Show a landing page for five seconds and measure what respondents remember. Then show it again with no time limit to test clarity and the first click.

#### Design

Build, from section 1 down:

- Section 1, Five-second view (on [Image: Landing page · shown 5s]): [Open-ended] [Single choice]
- Section 2, Second look (on [Image: Landing page]): [Rating scale: 1–5] [Open-ended]
- Section 3, Company size: [Single choice]

```json
{
  "version": "2025_04",
  "randomizations": [],
  "sections": [
    {
      "intro": "You will see a web page for five seconds. Look at it as you normally would.",
      "stimulus": {
        "type": "image",
        "url": "https://cdn.example.com/landing.png",
        "name": "Landing page",
        "placement": "at-start",
        "displaySeconds": 5
      },
      "steps": [
        {
          "type": "long_question",
          "question": "What do you remember about the page?",
          "probing_type": "none"
        },
        {
          "type": "single_select",
          "question": "What do you think this company sells?",
          "options": [
            {
              "value": "Accounting software"
            },
            {
              "value": "Banking services"
            },
            {
              "value": "Payroll services"
            },
            {
              "value": "I'm not sure",
              "anchor": true
            }
          ],
          "shuffle_options": true
        }
      ]
    },
    {
      "intro": "Here is the page again. Take as long as you like.",
      "stimulus": {
        "type": "image",
        "url": "https://cdn.example.com/landing.png",
        "name": "Landing page"
      },
      "steps": [
        {
          "type": "rating_scale",
          "question": "How clear is it what this company offers?",
          "options": [
            {
              "value": "1"
            },
            {
              "value": "2"
            },
            {
              "value": "3"
            },
            {
              "value": "4"
            },
            {
              "value": "5"
            }
          ],
          "lowest_rating_label": "Not at all clear",
          "highest_rating_label": "Very clear"
        },
        {
          "type": "long_question",
          "question": "What would you click first, and why?",
          "probing_type": "none"
        }
      ]
    },
    {
      "intro": "Last, a question about your business.",
      "steps": [
        {
          "type": "single_select",
          "question": "How many people work at your company?",
          "options": [
            {
              "value": "Just me"
            },
            {
              "value": "2–10"
            },
            {
              "value": "11–50"
            },
            {
              "value": "More than 50"
            }
          ]
        }
      ]
    }
  ]
}
```

#### Distribution

Collect 50 first impressions from a panel of small business owners.

- Channel: Recruited panel of professionals
- Quota: 50 responses, lifetime

```json
{
  "name": "Small business owners",
  "type": "panel",
  "config": {
    "targetMarketType": "b2b",
    "targetNumberOfParticipants": 50
  },
  "quota_limit": 50
}
```

### Sequential monadic concept test

Method: Concept test (monadic or sequential monadic). Usually run in: Survey tools.

Each respondent sees two of four meal-kit concepts in random order and answers the same questions about each. Metadata tags each concept with its price and format, so analysis can compare them.

#### Design

Build, from section 1 down:

- Section 1, Eating habits: [Multiple choice] [Single choice]
- Section 2, Concept loop (on [Group: loops through 2 of 4 images, one at a time + Metadata]): [Open-ended] [Rating scale: 1–5] [Open-ended]
- Section 3, Final choice: [Open-ended]
- Section 4, Household: [Single choice]

```json
{
  "version": "2025_04",
  "randomizations": [],
  "sections": [
    {
      "intro": "First, a few questions about how you eat during the week.",
      "steps": [
        {
          "type": "multi_select",
          "question": "Which of these have you bought in the past month?",
          "options": [
            {
              "value": "Meal kits"
            },
            {
              "value": "Ready-made meals"
            },
            {
              "value": "Grocery delivery"
            },
            {
              "value": "Restaurant delivery"
            },
            {
              "value": "None of these",
              "anchor": true,
              "exclusive": true
            }
          ],
          "shuffle_options": true
        },
        {
          "type": "single_select",
          "question": "How many nights a week do you cook dinner at home?",
          "options": [
            {
              "value": "0–1"
            },
            {
              "value": "2–3"
            },
            {
              "value": "4–5"
            },
            {
              "value": "6–7"
            }
          ]
        }
      ]
    },
    {
      "intro": "Now you will see a few new product ideas, one at a time.",
      "stimulus": {
        "type": "group",
        "showCount": 2,
        "stimuli": [
          {
            "type": "image",
            "url": "https://cdn.example.com/concepts/a.png",
            "name": "Concept A",
            "metadata": {
              "price": "low",
              "format": "subscription"
            }
          },
          {
            "type": "image",
            "url": "https://cdn.example.com/concepts/b.png",
            "name": "Concept B",
            "metadata": {
              "price": "high",
              "format": "subscription"
            }
          },
          {
            "type": "image",
            "url": "https://cdn.example.com/concepts/c.png",
            "name": "Concept C",
            "metadata": {
              "price": "low",
              "format": "one-time"
            }
          },
          {
            "type": "image",
            "url": "https://cdn.example.com/concepts/d.png",
            "name": "Concept D",
            "metadata": {
              "price": "high",
              "format": "one-time"
            }
          }
        ]
      },
      "steps": [
        {
          "type": "long_question",
          "question": "In your own words, what is this product?",
          "probing_type": "none"
        },
        {
          "type": "rating_scale",
          "question": "How appealing is this idea to you?",
          "options": [
            {
              "value": "1"
            },
            {
              "value": "2"
            },
            {
              "value": "3"
            },
            {
              "value": "4"
            },
            {
              "value": "5"
            }
          ],
          "lowest_rating_label": "Not at all appealing",
          "highest_rating_label": "Extremely appealing"
        },
        {
          "type": "long_question",
          "question": "This idea is sold as a {{stimulus.metadata.format}}. How does that affect whether you would buy it?",
          "probing_type": "none"
        }
      ]
    },
    {
      "intro": "You have now seen both ideas.",
      "steps": [
        {
          "type": "long_question",
          "question": "Which of the two ideas would you buy, and why?",
          "probing_type": "none"
        }
      ]
    },
    {
      "intro": "Last, a question about your household.",
      "steps": [
        {
          "type": "single_select",
          "question": "Who do you usually cook for?",
          "options": [
            {
              "value": "Just me"
            },
            {
              "value": "Me and a partner"
            },
            {
              "value": "A family with children"
            },
            {
              "value": "Housemates"
            }
          ]
        }
      ]
    }
  ]
}
```

#### Distribution

Recruit 200 consumers, with an even split across two age groups, so each concept gets about 100 ratings.

- Channel: Recruited panel of consumers
- Quota: 200 responses, lifetime
- Segment quotas: By age_group

```json
{
  "name": "Concept test sample",
  "type": "panel",
  "config": {
    "targetMarketType": "b2c",
    "targetNumberOfParticipants": 200
  },
  "quota_limit": 200,
  "segment_quotas": {
    "segment_key": "age_group",
    "values": {
      "18-34": {
        "quota": 100
      },
      "35+": {
        "quota": 100
      }
    }
  }
}
```

### Side-by-side checkout preference test

Method: Design preference and A/B comparison. Usually run in: Usability testing tools.

Show two checkout designs at the same time. Respondents pick the one they trust more, explain the choice, and finish with a short AI conversation.

#### Design

Build, from section 1 down:

- Plan: [Desktop only]
- Section 1, Background: [Single choice]
- Section 2, Checkout A vs. B (on [Side by side: 2 images at once]): [Single choice] [Open-ended] [Open-ended]
- Section 3, Wrap-up: [AI conversation: 1 min]

```json
{
  "version": "2025_04",
  "device": "desktop",
  "randomizations": [],
  "sections": [
    {
      "intro": "First, a question about how you shop online.",
      "steps": [
        {
          "type": "single_select",
          "question": "How often do you buy things online?",
          "options": [
            {
              "value": "Every week"
            },
            {
              "value": "Every month"
            },
            {
              "value": "A few times a year"
            },
            {
              "value": "Rarely"
            }
          ]
        }
      ]
    },
    {
      "intro": "You will see two versions of a checkout page.",
      "stimulus": {
        "type": "side_by_side",
        "stimuli": [
          {
            "type": "image",
            "url": "https://cdn.example.com/checkout-a.png",
            "name": "Checkout A"
          },
          {
            "type": "image",
            "url": "https://cdn.example.com/checkout-b.png",
            "name": "Checkout B"
          }
        ]
      },
      "steps": [
        {
          "type": "single_select",
          "question": "Which version looks more trustworthy?",
          "options": [
            {
              "value": "{{stimulus.first.label}}"
            },
            {
              "value": "{{stimulus.second.label}}"
            },
            {
              "value": "No difference",
              "anchor": true
            }
          ]
        },
        {
          "type": "long_question",
          "question": "Which version would you rather use, {{stimulus.first.label}} or {{stimulus.second.label}}? Why?",
          "probing_type": "none"
        },
        {
          "type": "long_question",
          "question": "What would you change about the version you did not pick?",
          "probing_type": "none"
        }
      ]
    },
    {
      "intro": null,
      "steps": [
        {
          "type": "conversation",
          "question": "Is there anything else about checking out online that you want to share?",
          "time_limit_seconds": 60,
          "conversation_mode": "no-guide"
        }
      ]
    }
  ]
}
```

#### Distribution

Share a link with your own customers and stop at 100 completed responses.

- Channel: Link
- Quota: 100 responses, lifetime

```json
{
  "name": "Customer link",
  "type": "link",
  "quota_limit": 100,
  "quota_frequency": "lifetime"
}
```

### NPS survey with detractor and promoter follow-ups

Method: NPS, CSAT, and satisfaction surveys. Usually run in: Survey tools.

A 0–10 recommendation score and a reason for everyone. Scores of 6 and below get a section about what went wrong, and scores of 9 and 10 get a section about referrals.

#### Design

Build, from section 1 down:

- Section 1, NPS score: [Rating scale: 0–10] [Open-ended + AI probing]
- Section 2, Detractor follow-up ([Show if: answer 1.1 is 0–6]): [Multiple choice] [Open-ended]
- Section 3, Promoter follow-up ([Show if: answer 1.1 is 9 or 10]): [Open-ended] [Single choice]
- Section 4, Tenure: [Single choice]

```json
{
  "version": "2025_04",
  "randomizations": [],
  "sections": [
    {
      "intro": null,
      "steps": [
        {
          "type": "rating_scale",
          "question": "How likely are you to recommend us to a friend or colleague?",
          "options": [
            {
              "value": "0"
            },
            {
              "value": "1"
            },
            {
              "value": "2"
            },
            {
              "value": "3"
            },
            {
              "value": "4"
            },
            {
              "value": "5"
            },
            {
              "value": "6"
            },
            {
              "value": "7"
            },
            {
              "value": "8"
            },
            {
              "value": "9"
            },
            {
              "value": "10"
            }
          ],
          "lowest_rating_label": "Not at all likely",
          "highest_rating_label": "Extremely likely"
        },
        {
          "type": "long_question",
          "question": "You gave a score of {{1.1}}. What is the main reason?",
          "probing_type": "light"
        }
      ]
    },
    {
      "intro": "Thanks for being honest. We want to fix this.",
      "conditionalBranch": {
        "sourceType": "question",
        "sourceSectionIndex": 0,
        "sourceStepIndex": 0,
        "triggerValues": [
          "0",
          "1",
          "2",
          "3",
          "4",
          "5",
          "6"
        ]
      },
      "steps": [
        {
          "type": "multi_select",
          "question": "Which of these have frustrated you?",
          "options": [
            {
              "value": "Price"
            },
            {
              "value": "Reliability"
            },
            {
              "value": "Customer support"
            },
            {
              "value": "Missing features"
            },
            {
              "value": "Something else",
              "anchor": true
            }
          ],
          "shuffle_options": true
        },
        {
          "type": "long_question",
          "question": "If you could change one thing, what would it be?",
          "probing_type": "none"
        }
      ]
    },
    {
      "intro": "Thank you! We are glad you like it.",
      "conditionalBranch": {
        "sourceType": "question",
        "sourceSectionIndex": 0,
        "sourceStepIndex": 0,
        "triggerValues": [
          "9",
          "10"
        ]
      },
      "steps": [
        {
          "type": "long_question",
          "question": "What would you tell a friend about us?",
          "probing_type": "none"
        },
        {
          "type": "single_select",
          "question": "Would you write a public review for us?",
          "options": [
            {
              "value": "Yes"
            },
            {
              "value": "Maybe later"
            },
            {
              "value": "No"
            }
          ]
        }
      ]
    },
    {
      "intro": "One last question.",
      "steps": [
        {
          "type": "single_select",
          "question": "How long have you been a customer?",
          "options": [
            {
              "value": "Less than 6 months"
            },
            {
              "value": "6–12 months"
            },
            {
              "value": "1–3 years"
            },
            {
              "value": "More than 3 years"
            }
          ]
        }
      ]
    }
  ]
}
```

#### Distribution

An always-on link in your customer emails. The cid parameter identifies the customer, and the quota resets each month.

- Channel: Link
- Quota: 500 responses, monthly
- Redirects: 1 URL

```json
{
  "name": "Monthly customer NPS",
  "type": "link",
  "quota_limit": 500,
  "quota_frequency": "monthly",
  "complete_redirect_url": "https://example.com/thanks?customer={{cid}}"
}
```

### In-product intercept after a report export

Method: In-product intercept survey. Usually run in: In-app feedback tools.

Ask enterprise users about a report right after they export it. An extra question appears only for people who pick "Something else".

#### Design

Build, from section 1 down:

- Section 1, Report use: [Single choice]
- Section 2, Follow-up if other ([Show if: answer 1.1 is Something else]): [Open-ended]
- Section 3, Report experience: [Rating scale: 1–5] [Open-ended]

```json
{
  "version": "2025_04",
  "randomizations": [],
  "sections": [
    {
      "intro": "You just exported a report. Can we ask about it?",
      "steps": [
        {
          "type": "single_select",
          "question": "What will you do with this report?",
          "options": [
            {
              "value": "Share it with my team"
            },
            {
              "value": "Present it to leadership"
            },
            {
              "value": "Analyze it in a spreadsheet"
            },
            {
              "value": "Something else",
              "anchor": true
            }
          ],
          "shuffle_options": true
        }
      ]
    },
    {
      "intro": null,
      "conditionalBranch": {
        "sourceType": "question",
        "sourceSectionIndex": 0,
        "sourceStepIndex": 0,
        "triggerValues": [
          "Something else"
        ]
      },
      "steps": [
        {
          "type": "long_question",
          "question": "What will you use this report for?",
          "probing_type": "none"
        }
      ]
    },
    {
      "intro": null,
      "steps": [
        {
          "type": "rating_scale",
          "question": "How easy was it to build this report?",
          "options": [
            {
              "value": "1"
            },
            {
              "value": "2"
            },
            {
              "value": "3"
            },
            {
              "value": "4"
            },
            {
              "value": "5"
            }
          ],
          "lowest_rating_label": "Very difficult",
          "highest_rating_label": "Very easy"
        },
        {
          "type": "long_question",
          "question": "What did you have to do outside our product to get this report ready?",
          "probing_type": "none"
        }
      ]
    }
  ]
}
```

#### Distribution

An intercept on your own web app. The targeting condition matches the report_exported event for enterprise users, and the traffic sample shows the study to 10% of them, up to 30 answers each week.

- Channel: In-product intercept
- Show when: eventName is report_exported, and plan is enterprise
- Sample: 10% of matching visitors
- Quota: 30 responses, weekly

```json
{
  "name": "Report export intercept",
  "type": "website",
  "key": "report-export",
  "targeting_condition": {
    "op": "AND",
    "args": [
      {
        "op": "EQUALS",
        "args": [
          {
            "type": "property",
            "value": "eventName"
          },
          {
            "type": "constant",
            "value": "report_exported"
          }
        ]
      },
      {
        "op": "EQUALS",
        "args": [
          {
            "type": "property",
            "value": "plan"
          },
          {
            "type": "constant",
            "value": "enterprise"
          }
        ]
      }
    ]
  },
  "traffic_threshold": 100000,
  "quota_limit": 30,
  "quota_frequency": "weekly"
}
```

### Customer discovery interview

Method: Customer discovery and in-depth interviews. Usually run in: Interview tools, or a researcher on a video call.

Profile questions, then open-ended questions with targeted AI probing, then a guided AI conversation that works like a semi-structured interview.

#### Design

Build, from section 1 down:

- Section 1, Background: [Single choice] [Single choice]
- Section 2, Current process: [Open-ended + AI probing] [Open-ended]
- Section 3, Ideal process: [AI conversation: 4 min]

```json
{
  "version": "2025_04",
  "randomizations": [],
  "sections": [
    {
      "intro": "First, a little about your role.",
      "steps": [
        {
          "type": "single_select",
          "question": "Which best describes your role?",
          "options": [
            {
              "value": "Finance manager"
            },
            {
              "value": "Controller"
            },
            {
              "value": "CFO"
            },
            {
              "value": "Operations manager"
            },
            {
              "value": "Other",
              "anchor": true
            }
          ]
        },
        {
          "type": "single_select",
          "question": "How many people on your team submit expenses?",
          "options": [
            {
              "value": "1–10"
            },
            {
              "value": "11–50"
            },
            {
              "value": "51–200"
            },
            {
              "value": "More than 200"
            }
          ]
        }
      ]
    },
    {
      "intro": "I'd like to learn how you manage your team's expenses today.",
      "steps": [
        {
          "type": "long_question",
          "question": "Walk me through what happens after someone on your team buys something for work.",
          "probing_type": "custom",
          "probing_areas": "Tools used, who approves, how long it takes, and the most annoying step."
        },
        {
          "type": "long_question",
          "question": "Tell me about the last time an expense caused a problem.",
          "probing_type": "none"
        }
      ]
    },
    {
      "intro": null,
      "steps": [
        {
          "type": "conversation",
          "question": "Let's talk about what an ideal process would look like.",
          "time_limit_seconds": 240,
          "conversation_mode": "guide",
          "conversation_guide": "Explore what they would automate, what they would keep manual, what they would pay to fix, and who else would need to agree."
        }
      ]
    }
  ]
}
```

#### Distribution

Recruit 10 finance managers from a panel. An AI-checked open answer confirms real experience, and you approve each applicant.

- Channel: Recruited panel of professionals
- Screener: 1 question, with an AI-checked open answer
- Approval: You approve each applicant
- Quota: 10 responses, lifetime

```json
{
  "name": "Finance managers",
  "type": "panel",
  "config": {
    "targetMarketType": "b2b",
    "targetNumberOfParticipants": 10
  },
  "quota_limit": 10,
  "automatic_invites": false,
  "screener_questions": [
    {
      "text": "Describe how your team submits and approves expenses today.",
      "type": "open_ended",
      "isRequired": true,
      "earlyScreenout": false,
      "signals": [
        {
          "text": "Manages or approves team expenses",
          "qualifyLogic": "must"
        },
        {
          "text": "Gives a vague or generic answer",
          "qualifyLogic": "must_not"
        }
      ]
    }
  ]
}
```

### Video ad test with facial reactions

Method: Video ad and creative testing. Usually run in: Survey tools and creative-testing panels.

Measure brand use first. Then respondents watch the ad with the webcam on and recall it unaided, and finally rate it and name the moment that stood out.

#### Design

Build, from section 1 down:

- Section 1, Brand use: [Multiple choice]
- Section 2, Ad reaction (on [YouTube video: Spring ad, 30s], [Record: webcam + voice]): [Open-ended]
- Section 3, Ad ratings: [Rating scale: 1–5] [Rating scale: 1–5] [Open-ended]

```json
{
  "version": "2025_04",
  "randomizations": [],
  "sections": [
    {
      "intro": "First, a question about snacks.",
      "steps": [
        {
          "type": "multi_select",
          "question": "Which of these brands have you bought in the past three months?",
          "options": [
            {
              "value": "Crunchly"
            },
            {
              "value": "Oat & Co"
            },
            {
              "value": "Harvest Bar"
            },
            {
              "value": "Peak"
            },
            {
              "value": "None of these",
              "anchor": true,
              "exclusive": true
            }
          ],
          "shuffle_options": true
        }
      ]
    },
    {
      "intro": "You will watch a 30-second ad. Your camera will record your reaction.",
      "stimulus": {
        "type": "youtube",
        "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
        "name": "Spring ad, 30s"
      },
      "recording": {
        "audio": true,
        "video": true,
        "screen": false,
        "mobile_screen": false
      },
      "steps": [
        {
          "type": "long_question",
          "question": "What was the ad about, in your own words?",
          "probing_type": "none"
        }
      ]
    },
    {
      "intro": "Now a few questions about the ad.",
      "steps": [
        {
          "type": "rating_scale",
          "question": "How much did you like the ad?",
          "options": [
            {
              "value": "1"
            },
            {
              "value": "2"
            },
            {
              "value": "3"
            },
            {
              "value": "4"
            },
            {
              "value": "5"
            }
          ],
          "lowest_rating_label": "Not at all",
          "highest_rating_label": "A lot"
        },
        {
          "type": "rating_scale",
          "question": "After the ad, how likely are you to try Crunchly?",
          "options": [
            {
              "value": "1"
            },
            {
              "value": "2"
            },
            {
              "value": "3"
            },
            {
              "value": "4"
            },
            {
              "value": "5"
            }
          ],
          "lowest_rating_label": "Not at all likely",
          "highest_rating_label": "Very likely"
        },
        {
          "type": "long_question",
          "question": "Which moment stood out most, and why?",
          "probing_type": "none"
        }
      ]
    }
  ]
}
```

#### Distribution

Recruit 100 consumers from a panel, with a quota for each gender.

- Channel: Recruited panel of consumers
- Quota: 100 responses, lifetime
- Segment quotas: By gender

```json
{
  "name": "Ad test sample",
  "type": "panel",
  "config": {
    "targetMarketType": "b2c",
    "targetNumberOfParticipants": 100
  },
  "quota_limit": 100,
  "segment_quotas": {
    "segment_key": "gender",
    "values": {
      "woman": {
        "quota": 50
      },
      "man": {
        "quota": 50
      }
    }
  }
}
```

### Value proposition test

Method: Message, copy, and claims testing. Usually run in: Survey tools.

Each respondent rates three of five messages, one at a time, for belief and relevance. Then they rank all five headlines.

#### Design

Build, from section 1 down:

- Section 1, Background: [Single choice]
- Section 2, Message loop (on [Group: loops through 3 of 5 texts, one at a time + Metadata]): [Rating scale: 1–7] [Rating scale: 1–7] [Open-ended]
- Section 3, Headline ranking: [Ranking] [Open-ended]

```json
{
  "version": "2025_04",
  "randomizations": [],
  "sections": [
    {
      "intro": "First, a little about your work.",
      "steps": [
        {
          "type": "single_select",
          "question": "How does your team close the books each month?",
          "options": [
            {
              "value": "In spreadsheets"
            },
            {
              "value": "With accounting software"
            },
            {
              "value": "An outside accountant does it"
            },
            {
              "value": "I'm not sure",
              "anchor": true
            }
          ]
        }
      ]
    },
    {
      "intro": "You will read a few short messages, one at a time.",
      "stimulus": {
        "type": "group",
        "showCount": 3,
        "stimuli": [
          {
            "type": "text",
            "name": "Speed",
            "content": "**Close your books in a day, not a week.**",
            "metadata": {
              "theme": "speed"
            }
          },
          {
            "type": "text",
            "name": "Accuracy",
            "content": "**Every transaction matched. Every time.**",
            "metadata": {
              "theme": "accuracy"
            }
          },
          {
            "type": "text",
            "name": "Cost",
            "content": "**Cut your month-end costs in half.**",
            "metadata": {
              "theme": "cost"
            }
          },
          {
            "type": "text",
            "name": "Control",
            "content": "**See every approval and every change in one place.**",
            "metadata": {
              "theme": "control"
            }
          },
          {
            "type": "text",
            "name": "Calm",
            "content": "**No more late nights at month-end.**",
            "metadata": {
              "theme": "calm"
            }
          }
        ]
      },
      "steps": [
        {
          "type": "rating_scale",
          "question": "How believable is this message?",
          "options": [
            {
              "value": "1"
            },
            {
              "value": "2"
            },
            {
              "value": "3"
            },
            {
              "value": "4"
            },
            {
              "value": "5"
            },
            {
              "value": "6"
            },
            {
              "value": "7"
            }
          ],
          "lowest_rating_label": "Not at all believable",
          "highest_rating_label": "Completely believable"
        },
        {
          "type": "rating_scale",
          "question": "How relevant is this message to your team?",
          "options": [
            {
              "value": "1"
            },
            {
              "value": "2"
            },
            {
              "value": "3"
            },
            {
              "value": "4"
            },
            {
              "value": "5"
            },
            {
              "value": "6"
            },
            {
              "value": "7"
            }
          ],
          "lowest_rating_label": "Not at all relevant",
          "highest_rating_label": "Very relevant"
        },
        {
          "type": "long_question",
          "question": "What, if anything, makes you doubt this message?",
          "probing_type": "none"
        }
      ]
    },
    {
      "intro": "Here are all five headlines.",
      "steps": [
        {
          "type": "ranking",
          "question": "Rank these headlines from most to least appealing to you.",
          "options": [
            {
              "value": "Close your books in a day, not a week."
            },
            {
              "value": "Every transaction matched. Every time."
            },
            {
              "value": "Cut your month-end costs in half."
            },
            {
              "value": "See every approval and every change in one place."
            },
            {
              "value": "No more late nights at month-end."
            }
          ],
          "shuffle_options": true
        },
        {
          "type": "long_question",
          "question": "What would make your top headline even stronger?",
          "probing_type": "none"
        }
      ]
    }
  ]
}
```

#### Distribution

Recruit 150 professionals from a panel. A screener question admits only people who take part in the monthly close.

- Channel: Recruited panel of professionals
- Screener: 1 question
- Quota: 150 responses, lifetime

```json
{
  "name": "Finance teams",
  "type": "panel",
  "config": {
    "targetMarketType": "b2b",
    "targetNumberOfParticipants": 150
  },
  "quota_limit": 150,
  "screener_questions": [
    {
      "text": "Do you take part in your company's monthly financial close?",
      "type": "radio",
      "isRequired": true,
      "earlyScreenout": true,
      "randomizeOptions": false,
      "options": [
        {
          "text": "Yes, I lead it",
          "qualification": "qualify"
        },
        {
          "text": "Yes, I help with it",
          "qualification": "qualify"
        },
        {
          "text": "No",
          "qualification": "disqualify"
        }
      ]
    }
  ]
}
```

### Radio spot and brand voice test

Method: Audio testing (podcasts, voice assistants, sonic branding). Usually run in: Survey tools with media hosting.

Respondents hear a radio spot and recall it. Then they hear two candidate brand voices in random order and rate how well each fits a bank.

#### Design

Build, from section 1 down:

- Section 1, Listening habits: [Multiple choice]
- Section 2, Radio spot (on [Audio: Radio spot, 30s]): [Open-ended] [Rating scale: 1–5]
- Section 3, Voice loop (on [Group: loops through all 2 audio clips, one at a time + Metadata]): [Rating scale: 1–5] [Open-ended]
- Section 4, Voice choice: [Open-ended]

```json
{
  "version": "2025_04",
  "randomizations": [],
  "sections": [
    {
      "intro": "First, a question about how you listen.",
      "steps": [
        {
          "type": "multi_select",
          "question": "Where do you listen to radio or podcasts?",
          "options": [
            {
              "value": "In the car"
            },
            {
              "value": "At home"
            },
            {
              "value": "At work"
            },
            {
              "value": "While working out"
            },
            {
              "value": "On public transit"
            }
          ],
          "shuffle_options": true
        }
      ]
    },
    {
      "intro": "Please turn up your sound. You will hear a 30-second ad.",
      "stimulus": {
        "type": "audio",
        "url": "https://cdn.example.com/audio/radio-spot.mp3",
        "name": "Radio spot, 30s"
      },
      "steps": [
        {
          "type": "long_question",
          "question": "What do you remember from the ad?",
          "probing_type": "none"
        },
        {
          "type": "rating_scale",
          "question": "How much did you like the ad?",
          "options": [
            {
              "value": "1"
            },
            {
              "value": "2"
            },
            {
              "value": "3"
            },
            {
              "value": "4"
            },
            {
              "value": "5"
            }
          ],
          "lowest_rating_label": "Not at all",
          "highest_rating_label": "A lot"
        }
      ]
    },
    {
      "intro": "Next, you will hear two voices, one at a time.",
      "stimulus": {
        "type": "group",
        "showCount": 2,
        "stimuli": [
          {
            "type": "audio",
            "url": "https://cdn.example.com/audio/voice-warm.mp3",
            "name": "Voice A",
            "metadata": {
              "tone": "warm"
            }
          },
          {
            "type": "audio",
            "url": "https://cdn.example.com/audio/voice-bright.mp3",
            "name": "Voice B",
            "metadata": {
              "tone": "bright"
            }
          }
        ]
      },
      "steps": [
        {
          "type": "rating_scale",
          "question": "How well does this voice fit a bank?",
          "options": [
            {
              "value": "1"
            },
            {
              "value": "2"
            },
            {
              "value": "3"
            },
            {
              "value": "4"
            },
            {
              "value": "5"
            }
          ],
          "lowest_rating_label": "Not at all",
          "highest_rating_label": "Perfectly"
        },
        {
          "type": "long_question",
          "question": "Describe this voice in a few words.",
          "probing_type": "none"
        }
      ]
    },
    {
      "intro": null,
      "steps": [
        {
          "type": "long_question",
          "question": "Which of the two voices would you rather hear from your bank, and why?",
          "probing_type": "none"
        }
      ]
    }
  ]
}
```

#### Distribution

Recruit 80 consumers from a panel, split evenly across two age groups.

- Channel: Recruited panel of consumers
- Quota: 80 responses, lifetime
- Segment quotas: By age_group

```json
{
  "name": "Radio listeners",
  "type": "panel",
  "config": {
    "targetMarketType": "b2c",
    "targetNumberOfParticipants": 80
  },
  "quota_limit": 80,
  "segment_quotas": {
    "segment_key": "age_group",
    "values": {
      "18-34": {
        "quota": 40
      },
      "35+": {
        "quota": 40
      }
    }
  }
}
```

### In-home product test

Method: Packaging, in-home use, and physical product tests. Usually run in: In-person research and home-use test vendors.

Respondents unbox a physical product on camera, use it for the first time, and then rate it with the camera off.

#### Design

Build, from section 1 down:

- Section 1, Unboxing (on [Physical product: Sample kit], [Record: webcam + voice]): [Task] [Open-ended]
- Section 2, First use (on [Physical product: Sample kit], [Record: webcam + voice]): [Task] [Open-ended + AI probing]
- Section 3, Overall rating: [Rating scale: 1–5] [Single choice]

```json
{
  "version": "2025_04",
  "randomizations": [],
  "sections": [
    {
      "intro": "Please have the box we sent you in front of you.",
      "stimulus": {
        "type": "offline",
        "url": "",
        "name": "Sample kit"
      },
      "recording": {
        "audio": true,
        "video": true,
        "screen": false,
        "mobile_screen": false
      },
      "steps": [
        {
          "type": "task",
          "question": "Open the box and take everything out. Talk us through what you see.",
          "task_type": "generic_instruction",
          "expected_duration_seconds": 180
        },
        {
          "type": "long_question",
          "question": "What was your first impression of the packaging?",
          "probing_type": "none"
        }
      ]
    },
    {
      "intro": "Now use the product for the first time.",
      "stimulus": {
        "type": "offline",
        "url": "",
        "name": "Sample kit"
      },
      "recording": {
        "audio": true,
        "video": true,
        "screen": false,
        "mobile_screen": false
      },
      "steps": [
        {
          "type": "task",
          "question": "Set up the product and use it as you normally would. Talk us through it.",
          "task_type": "generic_instruction",
          "expected_duration_seconds": 300
        },
        {
          "type": "long_question",
          "question": "What surprised you, good or bad?",
          "probing_type": "light"
        }
      ]
    },
    {
      "intro": "You can turn your camera off now. A few last questions.",
      "steps": [
        {
          "type": "rating_scale",
          "question": "Overall, how satisfied are you with the product?",
          "options": [
            {
              "value": "1"
            },
            {
              "value": "2"
            },
            {
              "value": "3"
            },
            {
              "value": "4"
            },
            {
              "value": "5"
            }
          ],
          "lowest_rating_label": "Very dissatisfied",
          "highest_rating_label": "Very satisfied"
        },
        {
          "type": "single_select",
          "question": "Would you buy this product for $49?",
          "options": [
            {
              "value": "Yes, definitely"
            },
            {
              "value": "Maybe"
            },
            {
              "value": "No"
            }
          ]
        }
      ]
    }
  ]
}
```

#### Distribution

Only the people who received a sample kit can take the study. An email allow-list checks each respondent.

- Channel: Link
- Allow-list: Only emails on your list
- Email: Collected before the study

```json
{
  "name": "Sample kit recipients",
  "type": "link",
  "collect_email": true,
  "screen_email": true,
  "email_list_id": "list_sample_kit"
}
```

### AI answer evaluation

Method: AI output and model evaluation. Usually run in: Internal eval tooling and labeling vendors.

Respondents rate a random sample of AI answers, one at a time. Then they compare two answers side by side. Metadata records which model wrote each answer, so analysis can compare the models.

#### Design

Build, from section 1 down:

- Plan: [Desktop only]
- Section 1, Background: [Single choice]
- Section 2, Answer loop (on [Group: loops through 3 of 4 texts, one at a time + Metadata]): [Rating scale: 1–5] [Open-ended]
- Section 3, Answer A vs. B (on [Side by side: 2 images at once + Metadata]): [Single choice] [Open-ended]

```json
{
  "version": "2025_04",
  "device": "desktop",
  "randomizations": [],
  "sections": [
    {
      "intro": "First, a question about AI assistants.",
      "steps": [
        {
          "type": "single_select",
          "question": "How often do you ask an AI assistant for advice?",
          "options": [
            {
              "value": "Every day"
            },
            {
              "value": "Every week"
            },
            {
              "value": "Every month"
            },
            {
              "value": "Rarely"
            },
            {
              "value": "Never"
            }
          ]
        }
      ]
    },
    {
      "intro": "You will read answers from a home energy assistant.",
      "stimulus": {
        "type": "group",
        "showCount": 3,
        "stimuli": [
          {
            "type": "text",
            "name": "Answer 1",
            "content": "Switch to LED bulbs and lower your thermostat by two degrees at night...",
            "metadata": {
              "model": "model-a",
              "prompt": "lower-bill"
            }
          },
          {
            "type": "text",
            "name": "Answer 2",
            "content": "Start with an energy audit. Many utilities offer one for free...",
            "metadata": {
              "model": "model-b",
              "prompt": "lower-bill"
            }
          },
          {
            "type": "text",
            "name": "Answer 3",
            "content": "Seal drafts around doors and windows, then check your insulation...",
            "metadata": {
              "model": "model-a",
              "prompt": "insulation"
            }
          },
          {
            "type": "text",
            "name": "Answer 4",
            "content": "Insulation matters most in the attic. Here is how to check it...",
            "metadata": {
              "model": "model-b",
              "prompt": "insulation"
            }
          }
        ]
      },
      "steps": [
        {
          "type": "rating_scale",
          "question": "How helpful is this answer?",
          "options": [
            {
              "value": "1"
            },
            {
              "value": "2"
            },
            {
              "value": "3"
            },
            {
              "value": "4"
            },
            {
              "value": "5"
            }
          ],
          "lowest_rating_label": "Not helpful",
          "highest_rating_label": "Very helpful"
        },
        {
          "type": "long_question",
          "question": "What would make this answer better?",
          "probing_type": "none"
        }
      ]
    },
    {
      "intro": "Now compare two answers to the same question, shown as screenshots.",
      "stimulus": {
        "type": "side_by_side",
        "stimuli": [
          {
            "type": "image",
            "url": "https://cdn.example.com/outputs/answer-x.png",
            "name": "Answer X",
            "metadata": {
              "model": "model-a"
            }
          },
          {
            "type": "image",
            "url": "https://cdn.example.com/outputs/answer-y.png",
            "name": "Answer Y",
            "metadata": {
              "model": "model-b"
            }
          }
        ]
      },
      "steps": [
        {
          "type": "single_select",
          "question": "Which answer would you trust more?",
          "options": [
            {
              "value": "{{stimulus.first.label}}"
            },
            {
              "value": "{{stimulus.second.label}}"
            }
          ]
        },
        {
          "type": "long_question",
          "question": "Why did you pick that answer?",
          "probing_type": "none"
        }
      ]
    }
  ]
}
```

#### Distribution

Collect ratings from 50 Spanish speakers in the US. The plan is in English, and each respondent sees it in Spanish.

- Channel: Recruited panel of consumers
- Quota: 50 responses, lifetime
- Language: es-US

```json
{
  "name": "Spanish-speaking raters",
  "type": "panel",
  "config": {
    "targetMarketType": "b2c",
    "targetNumberOfParticipants": 50
  },
  "quota_limit": 50,
  "default_response_language": "es-US"
}
```

### Roadmap and pricing survey

Method: Feature prioritization and pricing research. Usually run in: Survey tools.

Customers rank five planned features and react to a price. People who call the price too expensive get a section about what a fair price would be.

#### Design

Build, from section 1 down:

- Section 1, Current use: [Multiple choice]
- Section 2, Feature ranking: [Ranking] [Open-ended]
- Section 3, Pro plan price: [Single choice]
- Section 4, Follow-up if too expensive ([Show if: answer 3.1 is Too expensive]): [Open-ended + AI probing]

```json
{
  "version": "2025_04",
  "randomizations": [],
  "sections": [
    {
      "intro": "First, a question about how you use our product today.",
      "steps": [
        {
          "type": "multi_select",
          "question": "What do you use our product for?",
          "options": [
            {
              "value": "Task tracking"
            },
            {
              "value": "Sprint planning"
            },
            {
              "value": "Roadmaps"
            },
            {
              "value": "Time tracking"
            },
            {
              "value": "Client reporting"
            }
          ],
          "shuffle_options": true
        }
      ]
    },
    {
      "intro": "We are planning some new features.",
      "steps": [
        {
          "type": "ranking",
          "question": "Rank these features from most to least useful to you.",
          "options": [
            {
              "value": "Offline mode"
            },
            {
              "value": "AI status summaries"
            },
            {
              "value": "Calendar sync"
            },
            {
              "value": "Custom fields"
            },
            {
              "value": "Client portal"
            }
          ],
          "shuffle_options": true
        },
        {
          "type": "long_question",
          "question": "Why is your top feature the most useful to you?",
          "probing_type": "none"
        }
      ]
    },
    {
      "intro": "Now imagine that these features are part of a new Pro plan.",
      "steps": [
        {
          "type": "single_select",
          "question": "At $15 per user per month, how would you describe the Pro plan?",
          "options": [
            {
              "value": "A bargain"
            },
            {
              "value": "A fair price"
            },
            {
              "value": "Expensive, but worth it"
            },
            {
              "value": "Too expensive"
            }
          ]
        }
      ]
    },
    {
      "intro": null,
      "conditionalBranch": {
        "sourceType": "question",
        "sourceSectionIndex": 2,
        "sourceStepIndex": 0,
        "triggerValues": [
          "Too expensive"
        ]
      },
      "steps": [
        {
          "type": "long_question",
          "question": "What price would feel fair, and what would the plan need to include?",
          "probing_type": "custom",
          "probing_areas": "The price they would pay, the features that justify it, and the tools they compare it to."
        }
      ]
    }
  ]
}
```

#### Distribution

A link in your product newsletter. It stops at 300 completed responses.

- Channel: Link
- Quota: 300 responses, lifetime

```json
{
  "name": "Newsletter readers",
  "type": "link",
  "quota_limit": 300,
  "quota_frequency": "lifetime"
}
```

### Brand awareness and perception tracker

Method: Brand perception and awareness. Usually run in: Survey tools.

Unaided awareness first, then aided awareness. Each respondent then sees a section for each brand they know, in random order, and picks the brand they would buy next.

#### Design

Build, from section 1 down:

- Plan: [Shuffle: sections 3–5]
- Section 1, Unaided recall: [Open-ended]
- Section 2, Aided awareness: [Multiple choice]
- Section 3, Stride (on [Image: Stride logo], [Show if: answer 2.1 is Stride]): [Multiple choice] [Open-ended]
- Section 4, Apex (on [Image: Apex logo], [Show if: answer 2.1 is Apex]): [Multiple choice] [Open-ended]
- Section 5, Northline (on [Image: Northline logo], [Show if: answer 2.1 is Northline]): [Multiple choice] [Open-ended]
- Section 6, Next purchase: [Single choice]

```json
{
  "version": "2025_04",
  "randomizations": [
    {
      "sectionIndices": [
        2,
        3,
        4
      ]
    }
  ],
  "sections": [
    {
      "intro": "Let's talk about running shoes.",
      "steps": [
        {
          "type": "long_question",
          "question": "When you think of running shoes, which brands come to mind?",
          "probing_type": "none"
        }
      ]
    },
    {
      "intro": null,
      "steps": [
        {
          "type": "multi_select",
          "question": "Which of these brands have you heard of?",
          "options": [
            {
              "value": "Stride"
            },
            {
              "value": "Apex"
            },
            {
              "value": "Northline"
            },
            {
              "value": "Pace"
            },
            {
              "value": "None of these",
              "anchor": true,
              "exclusive": true
            }
          ],
          "shuffle_options": true
        }
      ]
    },
    {
      "intro": "A few questions about Stride.",
      "stimulus": {
        "type": "image",
        "url": "https://cdn.example.com/logos/stride.png",
        "name": "Stride logo"
      },
      "conditionalBranch": {
        "sourceType": "question",
        "sourceSectionIndex": 1,
        "sourceStepIndex": 0,
        "triggerValues": [
          "Stride"
        ]
      },
      "steps": [
        {
          "type": "multi_select",
          "question": "Which words describe Stride?",
          "options": [
            {
              "value": "Innovative"
            },
            {
              "value": "Trustworthy"
            },
            {
              "value": "Expensive"
            },
            {
              "value": "Stylish"
            },
            {
              "value": "Comfortable"
            },
            {
              "value": "None of these",
              "anchor": true,
              "exclusive": true
            }
          ],
          "shuffle_options": true
        },
        {
          "type": "long_question",
          "question": "What comes to mind when you think of Stride?",
          "probing_type": "none"
        }
      ]
    },
    {
      "intro": "A few questions about Apex.",
      "stimulus": {
        "type": "image",
        "url": "https://cdn.example.com/logos/apex.png",
        "name": "Apex logo"
      },
      "conditionalBranch": {
        "sourceType": "question",
        "sourceSectionIndex": 1,
        "sourceStepIndex": 0,
        "triggerValues": [
          "Apex"
        ]
      },
      "steps": [
        {
          "type": "multi_select",
          "question": "Which words describe Apex?",
          "options": [
            {
              "value": "Innovative"
            },
            {
              "value": "Trustworthy"
            },
            {
              "value": "Expensive"
            },
            {
              "value": "Stylish"
            },
            {
              "value": "Comfortable"
            },
            {
              "value": "None of these",
              "anchor": true,
              "exclusive": true
            }
          ],
          "shuffle_options": true
        },
        {
          "type": "long_question",
          "question": "What comes to mind when you think of Apex?",
          "probing_type": "none"
        }
      ]
    },
    {
      "intro": "A few questions about Northline.",
      "stimulus": {
        "type": "image",
        "url": "https://cdn.example.com/logos/northline.png",
        "name": "Northline logo"
      },
      "conditionalBranch": {
        "sourceType": "question",
        "sourceSectionIndex": 1,
        "sourceStepIndex": 0,
        "triggerValues": [
          "Northline"
        ]
      },
      "steps": [
        {
          "type": "multi_select",
          "question": "Which words describe Northline?",
          "options": [
            {
              "value": "Innovative"
            },
            {
              "value": "Trustworthy"
            },
            {
              "value": "Expensive"
            },
            {
              "value": "Stylish"
            },
            {
              "value": "Comfortable"
            },
            {
              "value": "None of these",
              "anchor": true,
              "exclusive": true
            }
          ],
          "shuffle_options": true
        },
        {
          "type": "long_question",
          "question": "What comes to mind when you think of Northline?",
          "probing_type": "none"
        }
      ]
    },
    {
      "intro": "Last question.",
      "steps": [
        {
          "type": "single_select",
          "question": "Which brand would you buy next?",
          "options": [
            {
              "value": "Stride"
            },
            {
              "value": "Apex"
            },
            {
              "value": "Northline"
            },
            {
              "value": "Pace"
            },
            {
              "value": "Another brand",
              "anchor": true
            }
          ],
          "shuffle_options": true
        }
      ]
    }
  ]
}
```

#### Distribution

Recruit 300 consumers from a panel, with a quota for each US region.

- Channel: Recruited panel of consumers
- Quota: 300 responses, lifetime
- Segment quotas: By region

```json
{
  "name": "US runners",
  "type": "panel",
  "config": {
    "targetMarketType": "b2c",
    "targetNumberOfParticipants": 300
  },
  "quota_limit": 300,
  "segment_quotas": {
    "segment_key": "region",
    "values": {
      "northeast": {
        "quota": 75
      },
      "south": {
        "quota": 75
      },
      "midwest": {
        "quota": 75
      },
      "west": {
        "quota": 75
      }
    }
  }
}
```

### Multi-country app launch study

Method: Global and multi-country studies. Usually run in: Survey tools with translation services.

Write the study once, in English. Each market gets its own distribution and language, and the AI conversation runs in the respondent's language too.

#### Design

Build, from section 1 down:

- Section 1, Delivery habits: [Single choice]
- Section 2, Home screen (on [Image: Home screen]): [Open-ended] [Rating scale: 1–5]
- Section 3, Delivery apps today: [Multiple choice] [AI conversation: 2 min]

```json
{
  "version": "2025_04",
  "randomizations": [],
  "sections": [
    {
      "intro": "First, a question about food delivery.",
      "steps": [
        {
          "type": "single_select",
          "question": "How often do you order food for delivery?",
          "options": [
            {
              "value": "Several times a week"
            },
            {
              "value": "Once a week"
            },
            {
              "value": "A few times a month"
            },
            {
              "value": "Rarely"
            }
          ]
        }
      ]
    },
    {
      "intro": "Here is the home screen of a new delivery app.",
      "stimulus": {
        "type": "image",
        "url": "https://cdn.example.com/app/home-screen.png",
        "name": "Home screen"
      },
      "steps": [
        {
          "type": "long_question",
          "question": "What do you think you can do with this app?",
          "probing_type": "none"
        },
        {
          "type": "rating_scale",
          "question": "How appealing is this app to you?",
          "options": [
            {
              "value": "1"
            },
            {
              "value": "2"
            },
            {
              "value": "3"
            },
            {
              "value": "4"
            },
            {
              "value": "5"
            }
          ],
          "lowest_rating_label": "Not at all appealing",
          "highest_rating_label": "Very appealing"
        }
      ]
    },
    {
      "intro": null,
      "steps": [
        {
          "type": "multi_select",
          "question": "Which of these would make you try a new delivery app?",
          "options": [
            {
              "value": "Lower fees"
            },
            {
              "value": "Faster delivery"
            },
            {
              "value": "More restaurants"
            },
            {
              "value": "Loyalty rewards"
            },
            {
              "value": "Better customer support"
            }
          ],
          "shuffle_options": true
        },
        {
          "type": "conversation",
          "question": "Tell us about the delivery apps you use today.",
          "time_limit_seconds": 120,
          "conversation_mode": "no-guide"
        }
      ]
    }
  ]
}
```

#### Distribution

This distribution recruits 50 consumers in Japan, who take the study in Japanese. Copy it with de-DE and pt-BR for the German and Brazilian markets.

- Channel: Recruited panel of consumers
- Quota: 50 responses, lifetime
- Language: ja-JP

```json
{
  "name": "Japan launch",
  "type": "panel",
  "config": {
    "targetMarketType": "b2c",
    "targetNumberOfParticipants": 50
  },
  "quota_limit": 50,
  "default_response_language": "ja-JP"
}
```

### Personalized dashboard test for each account

Method: Personalized and segmented studies. Usually run in: Survey tools with advanced logic.

Link parameters put the customer's plan name into the questions and their account into the asset URL. Enterprise accounts get an extra section about data access.

#### Design

Build, from section 1 down:

- Plan: [Desktop only]
- Section 1, Plan context: [Single choice]
- Section 2, Dashboard task (on [Website: Dashboard preview], [Record: screen + voice]): [Task] [Rating scale: 1–5]
- Section 3, Enterprise only ([Show if: plan_tier is enterprise]): [Open-ended]
- Section 4, Wrap-up: [Open-ended]

```json
{
  "version": "2025_04",
  "device": "desktop",
  "randomizations": [],
  "sections": [
    {
      "intro": "Thanks for being a {{plan}} customer.",
      "steps": [
        {
          "type": "single_select",
          "question": "What is the main reason your team uses the {{plan}} plan?",
          "options": [
            {
              "value": "Reporting"
            },
            {
              "value": "Automation"
            },
            {
              "value": "Collaboration"
            },
            {
              "value": "Integrations"
            },
            {
              "value": "Something else",
              "anchor": true
            }
          ],
          "shuffle_options": true
        }
      ]
    },
    {
      "intro": "Here is a new dashboard, built with your own data.",
      "stimulus": {
        "type": "website",
        "url": "https://app.example.com/{{account}}/dashboard-preview?rid={{response_id}}",
        "name": "Dashboard preview"
      },
      "recording": {
        "audio": true,
        "video": false,
        "screen": true,
        "mobile_screen": false
      },
      "steps": [
        {
          "type": "task",
          "question": "Find last month's revenue and compare it to the month before.",
          "task_type": "generic_instruction",
          "expected_duration_seconds": 180
        },
        {
          "type": "rating_scale",
          "question": "How easy was that?",
          "options": [
            {
              "value": "1"
            },
            {
              "value": "2"
            },
            {
              "value": "3"
            },
            {
              "value": "4"
            },
            {
              "value": "5"
            }
          ],
          "lowest_rating_label": "Very difficult",
          "highest_rating_label": "Very easy"
        }
      ]
    },
    {
      "intro": "A question for enterprise accounts.",
      "conditionalBranch": {
        "sourceType": "segment",
        "segmentationKey": "plan_tier",
        "triggerValues": [
          "enterprise"
        ]
      },
      "steps": [
        {
          "type": "long_question",
          "question": "How does your team control who can see this data?",
          "probing_type": "none"
        }
      ]
    },
    {
      "intro": null,
      "steps": [
        {
          "type": "long_question",
          "question": "What would make this dashboard more useful for your team?",
          "probing_type": "none"
        }
      ]
    }
  ]
}
```

#### Distribution

Your app builds a link for each customer, such as ?cid=123&plan=Pro&account=acme. The plan_tier segmentation must exist on the study, and the redirect sends each respondent back to their account.

- Channel: Link
- Quota: 200 responses, lifetime
- Redirects: 1 URL

```json
{
  "name": "In-app research link",
  "type": "link",
  "quota_limit": 200,
  "quota_frequency": "lifetime",
  "complete_redirect_url": "https://app.example.com/{{account}}/research/thanks?response={{response_id}}"
}
```

### Beta program check-in

Method: Customer panels and beta programs. Usually run in: Research CRMs and email tools.

Beta testers report how much they used the beta. People who did not use it say why. Everyone completes a task in the beta on screen, and answers a product-market fit question.

#### Design

Build, from section 1 down:

- Plan: [Desktop only]
- Section 1, Beta use: [Single choice]
- Section 2, Follow-up if unused ([Show if: answer 1.1 is Not at all]): [Open-ended]
- Section 3, Report task (on [Website: Report builder beta], [Record: screen + voice]): [Task] [Rating scale: 1–5]
- Section 4, Value check: [Single choice] [Open-ended]

```json
{
  "version": "2025_04",
  "device": "desktop",
  "randomizations": [],
  "sections": [
    {
      "intro": "Thanks for testing the new report builder.",
      "steps": [
        {
          "type": "single_select",
          "question": "How often did you use the beta this week?",
          "options": [
            {
              "value": "Every day"
            },
            {
              "value": "A few times"
            },
            {
              "value": "Once"
            },
            {
              "value": "Not at all"
            }
          ]
        }
      ]
    },
    {
      "intro": null,
      "conditionalBranch": {
        "sourceType": "question",
        "sourceSectionIndex": 0,
        "sourceStepIndex": 0,
        "triggerValues": [
          "Not at all"
        ]
      },
      "steps": [
        {
          "type": "long_question",
          "question": "What kept you from trying the beta?",
          "probing_type": "none"
        }
      ]
    },
    {
      "intro": "Please open the beta. We will record your screen.",
      "stimulus": {
        "type": "website",
        "url": "https://beta.example.com/reports",
        "name": "Report builder beta"
      },
      "recording": {
        "audio": true,
        "video": false,
        "screen": true,
        "mobile_screen": false
      },
      "steps": [
        {
          "type": "task",
          "question": "Create a report of last week's sales and share it with a teammate.",
          "task_type": "generic_instruction",
          "expected_duration_seconds": 240
        },
        {
          "type": "rating_scale",
          "question": "How easy was that?",
          "options": [
            {
              "value": "1"
            },
            {
              "value": "2"
            },
            {
              "value": "3"
            },
            {
              "value": "4"
            },
            {
              "value": "5"
            }
          ],
          "lowest_rating_label": "Very difficult",
          "highest_rating_label": "Very easy"
        }
      ]
    },
    {
      "intro": null,
      "steps": [
        {
          "type": "single_select",
          "question": "How would you feel if you could no longer use the new report builder?",
          "options": [
            {
              "value": "Very disappointed"
            },
            {
              "value": "Somewhat disappointed"
            },
            {
              "value": "Not disappointed"
            }
          ]
        },
        {
          "type": "long_question",
          "question": "What is the main benefit you get from it?",
          "probing_type": "none"
        }
      ]
    }
  ]
}
```

#### Distribution

Only members of your beta list can take the study. Voicepanel checks each email against the list, and each respondent gets a thank-you code at the end.

- Channel: Link
- Allow-list: Only emails on your list
- Email: Collected before the study
- Incentive: promo code

```json
{
  "name": "Beta testers",
  "type": "link",
  "collect_email": true,
  "screen_email": true,
  "email_list_id": "list_beta_testers",
  "incentive": {
    "type": "promo_code",
    "title": "Thank you!",
    "description": "Use this code for a free month of Pro.",
    "code": "BETA-THANKS"
  }
}
```

## Frequently asked questions

### What kinds of research can I run in Voicepanel?

Almost any unmoderated study. That includes usability tests, concept and ad tests, NPS surveys, in-product intercepts, discovery interviews, in-home product tests, and AI output evaluations. You build each one from the same blocks. Then you send it out by link, through a panel, or as an intercept on your site.

### Is Voicepanel an AI interviewer?

It can be, but that is only one part of it. You can add AI follow-up questions or a full AI conversation to any section. You can also leave AI out and run a plain survey or usability test.

### Can Voicepanel replace a usability testing tool such as UserTesting or Maze?

For unmoderated usability tests, yes. Show a website, a Figma prototype, or a mobile app, and Voicepanel records the screen and the respondent's voice as they do your tasks. You can branch on whether they finished each task. Voicepanel can also recruit the participants for you.

### Can Voicepanel replace a survey tool such as Qualtrics or SurveyMonkey?

For most survey work, yes. You get choice, rating, NPS, and ranking questions, plus logic, randomization, answer piping, screeners, quotas, and 37 languages. Voice answers then tell you why people gave each score.

### Can Voicepanel replace a form builder such as Typeform?

For research forms and feedback surveys, yes. A link study shows one question at a time, with your logo, logic, and redirects. You also get voice answers and screen and webcam recording.

### How do I choose who takes my study?

You add one or more distributions to the study. Send a link to your own customers, describe the audience you want from a panel, or invite visitors on your site with an intercept. Each distribution has its own screener, quotas, and language.

### Can I run one study in several countries and languages?

Yes. You write the plan once, and each respondent takes it in their own language, from 37 languages. You can review the translations before launch and set a quota for each country.

### Do respondents have to speak their answers?

No. Voice is the default for open-ended questions, but you can let people type instead, or require one or the other. Choice, rating, and ranking questions use taps and clicks.

### What can respondents see or use during a study?

Websites, prototypes, iOS and Android apps, images, videos, audio, text, HTML pages, and physical products. You can show one per section, rotate through a pool, or show up to four side by side.

### What happens after the responses come in?

Voicepanel analyzes every response with AI. You get summaries, themes, findings with quotes, segments, and highlight reels from the recordings.

### Can I create studies with code or with an AI agent?

Yes. Send the plan JSON from this page to POST /api/v1/studies in the REST API. Or connect Claude or another AI assistant to the Voicepanel MCP server, and describe the study you want.

## Resources

- [This page as Markdown](https://www.voicepanel.com/docs/study-reference.md): The full reference in one plain-text file.
- [llms.txt](https://www.voicepanel.com/llms.txt): An index of Voicepanel pages for language models.
- [REST API reference](https://app.voicepanel.co/api/docs): Create studies with /api/v1/studies and distributions with /api/v1/distributions.
- [OpenAPI specification](https://app.voicepanel.co/api/docs/openapi): The machine-readable JSON Schema of the plan and every endpoint.
- [MCP server](https://www.voicepanel.com/docs/mcp): Connect Claude or another MCP client. get_study_design_guide, create_study, generate_study, and review_study work with this schema.