Quickstart: Create & Launch a Study

This walkthrough creates a study with a screener, an interview section, and conditional logic — then launches it and gets a link you can send to participants.

You’ll need an API key (see Get API Access). The key is scoped to one organization; the study is created there.

1. Create a draft study

POST /api/public/v1/studies/create takes the study definition and validates it. Note the externalId on the multiple choice question — the later open-ended question references it in a conditional.

Request

curl -X POST 'https://listenlabs.ai/api/public/v1/studies/create' \
  -H 'x-api-key: <api_key>' \
  -H 'Content-Type: application/json' \
  -d '{
    "title": "Coffee habits — API demo",
    "externalTitle": "A short interview about your coffee routine",
    "background": "We are a specialty coffee brand exploring how people choose what to buy.",
    "studyGoal": "Understand what drives brand switching among regular coffee drinkers.",
    "config": {
      "interviewMode": "audio_text",
      "questionLanguage": "en"
    },
    "welcomeMessage": {
      "title": "Thanks for joining!",
      "message": "This interview takes about 10 minutes. There are no wrong answers."
    },
    "closingMessage": "That is all — thank you for your time!",
    "studyGuide": [
      {
        "type": "screening",
        "title": "Screener",
        "items": [
          {
            "type": "multiple_choice",
            "text": "How often do you drink coffee?",
            "options": [
              { "text": "Every day", "status": "approve" },
              { "text": "A few times a week", "status": "approve" },
              { "text": "Rarely or never", "status": "reject" }
            ]
          }
        ]
      },
      {
        "type": "flat",
        "title": "Interview",
        "items": [
          {
            "externalId": "purchase-channels",
            "type": "multiple_choice",
            "text": "Where do you usually buy coffee?",
            "multiSelect": true,
            "options": [
              { "externalId": "opt-cafe", "text": "Cafés" },
              { "externalId": "opt-grocery", "text": "Grocery stores" },
              { "externalId": "opt-online", "text": "Online" },
              { "text": "Somewhere else", "exclusiveOption": true }
            ]
          },
          {
            "type": "open_ended",
            "text": "What do you like about buying coffee online?",
            "followUp": "medium",
            "conditional": {
              "operator": "and",
              "criteria": [
                {
                  "type": "selectedTemplateOptions",
                  "questionId": "purchase-channels",
                  "matchingCriteria": "mustSelect",
                  "choices": ["opt-online"]
                }
              ]
            }
          },
          {
            "type": "open_ended",
            "text": "Tell me about the last time you tried a new coffee brand.",
            "followUp": "heavy"
          }
        ]
      }
    ]
  }'

Response (201)

{
  "id": "9b2f1c3e-0000-0000-0000-000000000000",
  "linkId": "coffee-habits-api-demo",
  "status": "draft"
}

The study is now a draft — participants can’t see it yet, and you can review or tweak it in the dashboard before launching. If validation fails, you get a 400 whose code tells you what went wrong (invalid_request_body includes an issues array pointing at the offending fields; invalid_study_guide flags a broken cross-field rule). Branch on code, not on the human-readable error text.

2. Find your wallet

Launching bills project responses to a wallet. walletId can only be omitted when your organization has exactly one wallet — launch then auto-selects it. With multiple wallets you must pass one explicitly, so list them and pick:

Request

curl 'https://listenlabs.ai/api/public/v1/wallets' \
  -H 'x-api-key: <api_key>'

Response (200)

{
  "wallets": [
    {
      "walletId": "5e8a7d40-0000-0000-0000-000000000000",
      "name": "Research team",
      "recruitmentCreditBalance": { "balance": 480, "usage": 20 },
      "projectCreditBalance": { "balance": 950, "usage": 50 }
    }
  ]
}

usage includes active holds.

3. Launch

Request

curl -X POST 'https://listenlabs.ai/api/public/v1/studies/9b2f1c3e-0000-0000-0000-000000000000/launch' \
  -H 'x-api-key: <api_key>' \
  -H 'Content-Type: application/json' \
  -d '{ "walletId": "5e8a7d40-0000-0000-0000-000000000000" }'

Response (200)

{
  "id": "9b2f1c3e-0000-0000-0000-000000000000",
  "linkId": "coffee-habits-api-demo",
  "selfRecruitLink": "https://listenlabs.ai/s/coffee-habits-api-demo",
  "status": "live",
  "wallet": {
    "walletId": "5e8a7d40-0000-0000-0000-000000000000",
    "name": "Research team",
    "recruitmentCreditBalance": { "balance": 480, "usage": 20 },
    "projectCreditBalance": { "balance": 950, "usage": 50 }
  }
}

The study is live. Share selfRecruitLink with participants — you can also append URL parameters (e.g. ?segment=pro) and route on them with searchParam conditionals or read them back later from each response’s attributes.

If you omit the body and your organization has multiple wallets, launch returns 400 with code: wallet_required asking for an explicit walletId. A 409 (code: study_busy or conflict) means the study is mid-publish — retry after a moment.

4. Collect the results

Once responses come in, pull them with the data endpoints using the linkId:

curl 'https://listenlabs.ai/api/public/v1/responses/coffee-habits-api-demo' \
  -H 'x-api-key: <api_key>'

Study Guide Reference

All block and question types, conditionals, carry-forward, and validation rules.

Get Responses

Retrieve transcripts, answers, and summaries for a launched study.

​1. Create a draft study

​2. Find your wallet

​3. Launch

​4. Collect the results

Study Guide Reference

Get Responses

1. Create a draft study

2. Find your wallet

3. Launch

4. Collect the results