Listen LabsDocs

    Getting Started

    Quickstart: Create & Launch a Study

    Go from JSON to a live self-recruit link in three requests

    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 workspace; 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 workspace 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

    The path takes the study's id from step 1 — the linkId is not accepted here.

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

    If you omit the body and your workspace 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 (the study's id is accepted too):

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