Studies

Create a study

Create a new research study, with an optional plan configuration with sections, steps, and recording settings. The study belongs to the account of the API token unless account_id names it.

post/api/v1/studies

Request

Base URL
https://app.voicepanel.com
URL
https://app.voicepanel.com/api/v1/studies
Auth
HTTP bearer

Request body

account_idstring

ID of the account to create the study under. Defaults to the account of the API token.

display_namestring nullable

Public-facing study name shown to participants

internal_namestring nullable

Internal name for organization purposes

objectivestring nullable

Research objective for the study

contextstring nullable

Brand or product context for the AI interviewer

brand_logo_urlstring nullable

URL of brand logo shown during the interview

show_welcome_pageboolean

Whether to show a welcome page before starting

target_length_minnumber nullable

Target interview length in minutes

welcome_textstring nullable

Custom welcome page text

written_in_languagestring

Language code the study is written in

is_archivedboolean

Whether the study is archived

brand_wordsstring[] nullable

Brand-related keywords for AI interviewer context

enable_tts_defaultboolean

Whether text-to-speech is enabled by default

tts_voice_idstring nullable

Voice ID for text-to-speech

tagsstring[]

Tags for organizing studies

Example request

{
  "account_id": "acct_7Kq2mVbXpR4nZa",
  "display_name": "Grocery delivery habits",
  "internal_name": "Q1 grocery delivery interviews",
  "objective": "Learn why shoppers try a grocery delivery app and what keeps them ordering.",
  "context": "Acme Fresh is a same-day grocery delivery app for city neighborhoods.",
  "plan": {
    "version": "2025_04",
    "sections": [
      {
        "intro": "First, a few questions about how you shop for groceries.",
        "steps": [
          {
            "question": "How often do you order groceries for delivery?",
            "type": "single_select",
            "options": [
              {
                "value": "Weekly or more",
                "anchor": null,
                "exclusive": null
              },
              {
                "value": "A few times a month",
                "anchor": null,
                "exclusive": null
              },
              {
                "value": "Rarely or never",
                "anchor": null,
                "exclusive": null
              }
            ],
            "shuffle_options": false,
            "vertically_align_choices": null
          },
          {
            "question": "What made you try Acme Fresh for the first time?",
            "type": "long_question",
            "probing_type": "light",
            "probing_areas": null,
            "response_format": "audio"
          },
          {
            "question": "How likely are you to recommend Acme Fresh to a friend?",
            "type": "rating_scale",
            "options": [
              {
                "value": "1",
                "anchor": null,
                "exclusive": null
              },
              {
                "value": "2",
                "anchor": null,
                "exclusive": null
              },
              {
                "value": "3",
                "anchor": null,
                "exclusive": null
              },
              {
                "value": "4",
                "anchor": null,
                "exclusive": null
              },
              {
                "value": "5",
                "anchor": null,
                "exclusive": null
              }
            ],
            "lowest_rating_label": "Not at all likely",
            "highest_rating_label": "Extremely likely"
          }
        ],
        "stimulus": null,
        "recording": null,
        "conditionalBranch": null
      }
    ],
    "randomizations": [],
    "device": "any"
  },
  "brand_logo_url": "https://cdn.example.com/acme-fresh/logo.png",
  "show_welcome_page": true,
  "target_length_min": 5,
  "welcome_text": "Thanks for taking part. You will talk with an AI interviewer about how you shop for groceries.",
  "written_in_language": "en-US",
  "brand_words": [
    "Acme Fresh",
    "Acme"
  ],
  "tags": [
    "Q1 research"
  ]
}

Response

Created

idstring required

Study ID

account_idstring required

Account that owns the study

display_namestring nullable required

Public-facing study name shown to participants

internal_namestring nullable required

Internal name for organization purposes

objectivestring nullable required

Research objective for the study

contextstring nullable required

Brand or product context for the AI interviewer

plan_source'study.questions' | 'study.plan' required

Field that holds the interview content. Studies created through the API use study.plan.

brand_logo_urlstring nullable required

URL of brand logo shown during the interview

show_welcome_pageboolean required

Whether to show a welcome page before starting

welcome_textstring nullable required

Custom welcome page text

target_length_minnumber nullable required

Target interview length in minutes

uniqueness_constraint'custom_id_required' | 'custom_id_required_single_submission' nullable required

Enforce unique responses via custom ID

written_in_languagestring required

Language code the study is written in

is_archivedboolean required

Whether the study is archived

is_pre_draftboolean required

True while an AI-authored study is still being assembled. List endpoints leave these studies out.

enable_tts_defaultboolean required

Whether text-to-speech is enabled by default

tts_voice_idstring nullable required

Voice ID for text-to-speech

screen_out_criteriastring nullable required

Criteria the AI interviewer uses to screen out a participant

template_idstring nullable required

Template the study was created from

authoring_method'scratch' | 'ai_chat' | 'template' required

How the study was authored

sourcestring nullable required

Client that created the study: web, api, or mcp

last_edited_sourcestring nullable required

Client that last edited the study

last_modified_atstring date-time nullable required

When the study content last changed

created_bystring nullable required

ID of the user who created the study

created_atstring date-time nullable required

updated_atstring date-time nullable required

Example response

{
  "id": "stdy_Qm3vR8tLp2XnWz",
  "account_id": "acct_7Kq2mVbXpR4nZa",
  "display_name": "Grocery delivery habits",
  "internal_name": "Q1 grocery delivery interviews",
  "objective": "Learn why shoppers try a grocery delivery app and what keeps them ordering.",
  "context": "Acme Fresh is a same-day grocery delivery app for city neighborhoods.",
  "plan": {
    "version": "2025_04",
    "sections": [
      {
        "intro": "First, a few questions about how you shop for groceries.",
        "steps": [
          {
            "question": "How often do you order groceries for delivery?",
            "type": "single_select",
            "options": [
              {
                "value": "Weekly or more",
                "anchor": null,
                "exclusive": null
              },
              {
                "value": "A few times a month",
                "anchor": null,
                "exclusive": null
              },
              {
                "value": "Rarely or never",
                "anchor": null,
                "exclusive": null
              }
            ],
            "shuffle_options": false,
            "vertically_align_choices": null
          },
          {
            "question": "What made you try Acme Fresh for the first time?",
            "type": "long_question",
            "probing_type": "light",
            "probing_areas": null,
            "response_format": "audio"
          },
          {
            "question": "How likely are you to recommend Acme Fresh to a friend?",
            "type": "rating_scale",
            "options": [
              {
                "value": "1",
                "anchor": null,
                "exclusive": null
              },
              {
                "value": "2",
                "anchor": null,
                "exclusive": null
              },
              {
                "value": "3",
                "anchor": null,
                "exclusive": null
              },
              {
                "value": "4",
                "anchor": null,
                "exclusive": null
              },
              {
                "value": "5",
                "anchor": null,
                "exclusive": null
              }
            ],
            "lowest_rating_label": "Not at all likely",
            "highest_rating_label": "Extremely likely"
          }
        ],
        "stimulus": null,
        "recording": null,
        "conditionalBranch": null
      }
    ],
    "randomizations": [],
    "device": "any"
  },
  "plan_source": "study.plan",
  "brand_logo_url": "https://cdn.example.com/acme-fresh/logo.png",
  "show_welcome_page": true,
  "welcome_text": "Thanks for taking part. You will talk with an AI interviewer about how you shop for groceries.",
  "target_length_min": 5,
  "written_in_language": "en-US",
  "authoring_method": "scratch",
  "source": "api",
  "last_edited_source": "api",
  "last_modified_at": "2026-03-02T15:10:00.000Z",
  "created_by": "0f1b3c6e-9d2a-4b7c-8e5f-2a1d4c6b8e90",
  "created_at": "2026-03-01T09:30:00.000Z",
  "updated_at": "2026-03-02T15:10:00.000Z",
  "tags": [
    {
      "id": "tag_4Hs8kPq1Lm2Zx7",
      "account_id": "acct_7Kq2mVbXpR4nZa",
      "name": "Q1 research",
      "created_at": "2026-02-10T12:00:00.000Z"
    }
  ]
}

Changes

No recorded changes to this operation across all 1 revision of this API.