These endpoints all authenticate with the x-api-key header (see Get API Access). The create, launch, and wallet endpoints below build and launch studies; the response and study endpoints further down retrieve data from studies that are already live. For the full study-guide schema (every block type, question type, conditional, and validation rule) see the Study Creation API reference.

Create Study

Validates a study guide and creates a draft study in the API key’s organization. Nothing is visible to participants until you launch it. POST https://listenlabs.ai/api/public/v1/studies/create

Request Body

title string required Internal title of the study. externalTitle string Title shown to participants. background string Context about your company or product that the interviewer can draw on. studyGoal string What you are trying to learn. Guides the interviewer’s follow-ups. config object Interview settings. interviewMode (text, audio, audio_text, audio_screen, video, video_screen), questionLanguage (e.g. en, de), optional availableLanguages for auto-translation, and optional targetPlatforms. welcomeMessage object Optional title and message shown before the interview starts. closingMessage string Message shown when the interview ends. studyGuide Block[] required The ordered list of blocks that make up the interview. Each block has a type (flat, concept, or screening), a title, and an items array of questions. See the Study Guide Reference for the complete schema, all question types, conditionals, carry-forward, and cross-field validation rules.

Response

id uuid Permanent unique identifier for the study. Use it to launch. linkId string The link ID of the study (editable later in study settings). Use it with the response endpoints. status string Always draft for a freshly created study.

Example 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"
          }
        ]
      }
    ]
  }'

Example Response

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

Errors

Every error response returns an error message and a stable code you should branch on. 400 schema failures (code: invalid_request_body) also include an issues array pointing at the offending fields; broken study-guide rules return code: invalid_study_guide.

{
  "error": "Invalid request body",
  "code": "invalid_request_body",
  "issues": [
    { "path": ["title"], "message": "Required" }
  ]
}

Launch Study

Publishes a draft and returns its self-recruit link. Requires the API key’s user to have permission to start recruitment on the study. Project responses bill to the launch wallet. POST https://listenlabs.ai/api/public/v1/studies/{studyId}/launch

Path Parameters

studyId uuid The study’s permanent id returned from Create Study.

Request Body

The body is optional. walletId uuid Wallet to bill this study from; must be granted to the API key’s organization (see List Wallets). It can only be omitted when the organization has exactly one wallet, which is then auto-selected. If you have access to more than one wallet, omitting it returns a 400 (code: wallet_required).

Response

id uuid The study’s permanent identifier. linkId string The link ID of the study. selfRecruitLink string The public link to share with participants. status string Always live after a successful launch. wallet object The wallet this launch is billed to. Omitted when no wallet is bound (organization without wallet billing).

Example 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" }'

Example Response

{
  "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 }
  }
}

Errors

Status	Code	Meaning
`400`	`wallet_required`	The organization has multiple wallets and `walletId` was omitted.
`400`	`insufficient_credits`	The wallet can’t fund the launch (insufficient balance or grant limit).
`403`	`launch_permission_denied`	The key’s user lacks permission to launch this study.
`403`	`wallet_access_denied`	No access to the specified wallet.
`404`	`study_not_found`	Study not found in the key’s organization.
`409`	`study_busy` / `conflict`	The study is mid-update or the publish raced a concurrent edit — retry after a moment.

List Wallets

Lists the wallets granted to the API key’s organization, each with recruitment and project credit balances. Use a wallet’s walletId when launching a study. GET https://listenlabs.ai/api/public/v1/wallets

Response

wallets Wallet[] Each wallet is an object with the following fields:

walletId uuid — Identifier to pass when launching a study.
name string — Human-readable wallet name.
recruitmentCreditBalance object — Credits for recruiting participants. Has balance and usage (includes active holds).
projectCreditBalance object — Credits for project responses. Same balance / usage shape.

Example Request

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

Example Response

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

Get Responses

Deprecated starting August 1, 2026. This unversioned endpoint has been replaced by GET /api/public/v1/responses/{linkId}, which returns the same data with camelCase parameters and fields. Migrate before August 1, 2026.

This endpoint lists all responses for a given study. GET https://listenlabs.ai/api/public/responses/{link_id}

Path Parameters

link_id string The link ID of the study. You can find this in the study URL or via the List Studies endpoint. For example, in https://listenlabs.ai/s/abc123 the link ID is abc123.

Query Parameters

page integer default:"0" The page number for pagination. per_page integer default:"1000" Number of responses to return per page. updated_since string ISO 8601 date string to filter responses updated after this date (e.g., 2023-08-18T11:51:54.649916Z). include_in_progress boolean default:"true" Whether to include responses whose analysis is still in progress.

Response

Returns a list of responses for the given study. Each response is an object with the following fields: id uuid Unique identifier for the response. response_number number The ordered number of the response. created_at string UTC timestamp of when the response was created. updated_at string UTC timestamp of when the response was last updated (uses the analysis completion time when available). progress string The completion progress of the response (e.g. "complete", "in_progress"). response_duration_seconds number The total duration of the response in seconds. answers object Answers to all questions of the study.

Summary string — A summary of the entire conversation. Available for all studies.
Question 1 string — Everything the user said in response to question 1.
Question 2 string — Everything the user said in response to question 2.

answers_array Answer[] Answers to all questions of the study as an array.

answer_id string — The answer ID. Matches the answer_id on transcript rows from the single response endpoint, enabling cross-referencing.
discussion_guide_question_id string — The discussion guide question ID. Matches the id field from the Get Study Questions endpoint, enabling you to join answers with their question definitions.
concept_id string | null — The concept ID. Null if not concept-specific.
question_id string deprecated — Deprecated. Use answer_id instead.
question string — The question text, prefixed with its number when available (e.g. "Q1: What is your age?").
answer string — The answer to the question.

attributes object URL parameters that were passed to the study.

id string — An id that is passed to the study, e.g. https://listenlabs.ai/s/abc123?id=123.

short_transcript string | null A transcript of the entire conversation where the assistant messages are shortened to a couple of words. Can be null if the transcript has not been generated yet. short_assistant_messages string[] Condensed assistant turns used to build compact transcript context. bullet_summary string[] Concise bullet-point summary of the response. quality_score number Numeric response quality score, typically on a 1-5 scale. tags string[] Extracted keyword labels for the response. tagline string Short one-line synthesis for the response. summary string A natural-language summary of the response. May be omitted from the payload when a summary has not yet been generated for the response.

Example Request

curl 'https://listenlabs.ai/api/public/responses/study123?page=0&per_page=100&updated_since=2023-08-18T00:00:00Z' \
  -H 'x-api-key: <api_key>'

Example Response

[
  {
    "id": "12345678-0000-0000-0000-000000000000",
    "response_number": 1,
    "created_at": "2023-08-18T11:51:54.649916+00:00",
    "updated_at": "2023-08-18T12:05:30.123456+00:00",
    "progress": "complete",
    "response_duration_seconds": 245,
    "answers": {
      "Summary": "Summary of response 1",
      "Question 1": "Answer of question 1",
      "Question 2": "Answer of question 2"
    },
    "answers_array": [
      {
        "answer_id": "f1e2d3c4-0000-0000-0000-000000000001",
        "discussion_guide_question_id": "a1b2c3d4-0000-0000-0000-000000000001",
        "concept_id": null,
        "question_id": "f1e2d3c4-0000-0000-0000-000000000001",
        "question": "Question 1",
        "answer": "Answer of question 1"
      },
      {
        "answer_id": "f1e2d3c4-0000-0000-0000-000000000002",
        "discussion_guide_question_id": "a1b2c3d4-0000-0000-0000-000000000002",
        "concept_id": "b2c3d4e5-0000-0000-0000-000000000001",
        "question_id": "f1e2d3c4-0000-0000-0000-000000000002",
        "question": "Question 2",
        "answer": "Answer of question 2"
      }
    ],
    "attributes": {
      "id": "123"
    },
    "short_transcript": "• Welcome → Start\n• Ask for name → John\n• Thank you, bye →",
    "short_assistant_messages": ["Welcome and intro", "Asked for name", "Thanked and closed"],
    "bullet_summary": ["Bullet summary of response 1"],
    "quality_score": 5,
    "tags": ["tag-1", "tag-2"],
    "tagline": "Tagline of response 1",
    "summary": "Summary of response 1"
  },
  {
    "id": "23456789-0000-0000-0000-000000000000",
    "response_number": 2,
    "created_at": "2023-08-19T11:51:54.649916+00:00",
    "updated_at": "2023-08-19T12:10:15.789012+00:00",
    "progress": "complete",
    "response_duration_seconds": 312,
    "answers": {
      "Summary": "Summary of response 2",
      "Question 1": "Answer of question 1",
      "Question 2": "Answer of question 2"
    },
    "answers_array": [
      {
        "answer_id": "f1e2d3c4-0000-0000-0000-000000000001",
        "discussion_guide_question_id": "a1b2c3d4-0000-0000-0000-000000000001",
        "concept_id": null,
        "question_id": "f1e2d3c4-0000-0000-0000-000000000001",
        "question": "Question 1",
        "answer": "Answer of question 1"
      },
      {
        "answer_id": "f1e2d3c4-0000-0000-0000-000000000002",
        "discussion_guide_question_id": "a1b2c3d4-0000-0000-0000-000000000002",
        "concept_id": null,
        "question_id": "f1e2d3c4-0000-0000-0000-000000000002",
        "question": "Question 2",
        "answer": "Answer of question 2"
      }
    ],
    "attributes": {
      "id": "567"
    },
    "short_transcript": "• Welcome → Start\n• Ask for name → Alice\n• Thank you, bye →",
    "short_assistant_messages": ["Welcome and intro", "Asked for name", "Thanked and closed"],
    "bullet_summary": ["Bullet summary of response 2"],
    "quality_score": 4,
    "tags": ["tag-1", "tag-3"],
    "tagline": "Tagline of response 2",
    "summary": "Summary of response 2"
  }
]

Get Single Response

Deprecated starting August 1, 2026. This unversioned endpoint has been replaced by GET /api/public/v1/responses/{linkId}/{responseId}, which returns the same data with camelCase fields and also accepts a readable numeric ID. Migrate before August 1, 2026.

This endpoint retrieves a single response for a specific study. GET https://listenlabs.ai/api/public/responses/{link_id}/{response_id}

Path Parameters

link_id string The link ID of the study. You can find this in the study URL or via the List Studies endpoint. For example, in https://listenlabs.ai/s/abc123 the link ID is abc123. response_id string The unique ID of the specific response you want to retrieve.

Response

Returns a single response with detailed information: id string Unique identifier for the response. survey string The link ID of the survey this response belongs to. transcript array A complete transcript of the conversation, with each entry containing:

moderator string — The message from the assistant/moderator.
user string — The response from the user.
discussion_guide_question_id string — The discussion guide question ID for this row. Matches the id field from the Get Study Questions endpoint, enabling you to join transcript rows with their question definitions.
concept_id string | null — The concept ID for this row. Null if the question isn’t concept-specific.
answer_id string | null — The answer ID for this question. Matches the answer_id in the list endpoint’s answers_array, enabling cross-referencing between endpoints. Null for non-question rows (e.g. intro messages).
response_index number — The zero-based index of this row in the conversation history.
is_followup boolean — Whether this row is a follow-up to the same question as the previous row.
audio string | null — A signed URL to the audio recording of the user’s response, if available. This URL is valid for 1 hour. Null if no audio recording exists.
video object | null — Video playback information, if available. If no video recording exists, this will be null.
- stream_url string — HLS stream URL for the video recording.
- mp4_url string — Direct MP4 download URL for the video recording.
question_uuid string deprecated — Deprecated. Use discussion_guide_question_id instead.

Example Request

curl 'https://listenlabs.ai/api/public/responses/study-1/12345678-0000-0000-0000-000000000000' \
  -H 'x-api-key: <api_key>'

Example Response — Audio and Text

{
  "id": "12345678-0000-0000-0000-000000000000",
  "survey": "audio-survey",
  "transcript": [
    {
      "moderator": "Welcome to our audio survey. Can you describe your experience with our product?",
      "user": "The product has been very helpful for our team's workflow.",
      "discussion_guide_question_id": "a1b2c3d4-0000-0000-0000-000000000001",
      "concept_id": null,
      "answer_id": "f1e2d3c4-0000-0000-0000-000000000001",
      "response_index": 0,
      "is_followup": false,
      "audio": "https://storage.listenlabs.ai/audio/responses/abc123.mp3?token=...",
      "video": null,
      "question_uuid": "a1b2c3d4-0000-0000-0000-000000000001"
    },
    {
      "moderator": "What specific features do you find most useful?",
      "user": "The task management and integration capabilities are standouts for us.",
      "discussion_guide_question_id": "a1b2c3d4-0000-0000-0000-000000000002",
      "concept_id": "b2c3d4e5-0000-0000-0000-000000000001",
      "answer_id": "f1e2d3c4-0000-0000-0000-000000000002",
      "response_index": 1,
      "is_followup": false,
      "audio": "https://storage.listenlabs.ai/audio/responses/def456.mp3?token=...",
      "video": null,
      "question_uuid": "a1b2c3d4-0000-0000-0000-000000000002"
    }
  ]
}

Example Response — Video and Text

{
  "id": "23456789-0000-0000-0000-000000000000",
  "survey": "video-interview",
  "transcript": [
    {
      "moderator": "Tell us about your background in the industry.",
      "user": "I've been working in software development for over 10 years, primarily focusing on frontend technologies.",
      "discussion_guide_question_id": "a1b2c3d4-0000-0000-0000-000000000001",
      "concept_id": null,
      "answer_id": "f1e2d3c4-0000-0000-0000-000000000001",
      "response_index": 0,
      "is_followup": false,
      "audio": null,
      "video": {
        "stream_url": "https://stream.mux.com/vWx123.m3u8",
        "mp4_url": "https://stream.mux.com/vWx123/capped-1080p.mp4"
      },
      "question_uuid": "a1b2c3d4-0000-0000-0000-000000000001"
    },
    {
      "moderator": "What attracted you to our company?",
      "user": "Your focus on innovative solutions and strong company culture really resonated with me.",
      "discussion_guide_question_id": "a1b2c3d4-0000-0000-0000-000000000002",
      "concept_id": null,
      "answer_id": "f1e2d3c4-0000-0000-0000-000000000002",
      "response_index": 1,
      "is_followup": false,
      "audio": null,
      "video": {
        "stream_url": "https://stream.mux.com/yZ456.m3u8",
        "mp4_url": "https://stream.mux.com/yZ456/capped-1080p.mp4"
      },
      "question_uuid": "a1b2c3d4-0000-0000-0000-000000000002"
    }
  ]
}

Example Response — Text Only

{
  "id": "34567890-0000-0000-0000-000000000000",
  "survey": "text-feedback",
  "transcript": [
    {
      "moderator": "How would you rate your satisfaction with our customer service?",
      "user": "I would rate it 9/10. Your support team was quick to respond and very helpful.",
      "discussion_guide_question_id": "a1b2c3d4-0000-0000-0000-000000000001",
      "concept_id": null,
      "answer_id": "f1e2d3c4-0000-0000-0000-000000000001",
      "response_index": 0,
      "is_followup": false,
      "audio": null,
      "video": null,
      "question_uuid": "a1b2c3d4-0000-0000-0000-000000000001"
    },
    {
      "moderator": "What suggestions do you have for improvement?",
      "user": "It would be nice to have weekend support hours for urgent issues.",
      "discussion_guide_question_id": "a1b2c3d4-0000-0000-0000-000000000002",
      "concept_id": null,
      "answer_id": "f1e2d3c4-0000-0000-0000-000000000002",
      "response_index": 1,
      "is_followup": false,
      "audio": null,
      "video": null,
      "question_uuid": "a1b2c3d4-0000-0000-0000-000000000002"
    }
  ]
}

Get Study Questions

This endpoint retrieves all questions for a specific study. GET https://listenlabs.ai/api/public/studies/{study_id}/questions

Path Parameters

study_id string The link ID of the study you want to retrieve questions for. You can find this in the study URL or via the List Studies endpoint.

Response

Returns an object containing a list of questions from the study’s latest revision. Each question includes its type and relevant metadata. questions array An array of question objects. Each question has a type field that determines its shape. All question types share these base fields:

id string — Unique identifier for the question. Matches the discussion_guide_question_id field in the response endpoints, enabling you to join questions with their corresponding transcript rows and answers.
text string — The question text shown to participants.
is_screener boolean — Whether this question is part of the screening section.
type string — The question type. One of: open_ended, multiple_choice, ranking, statement.
question_number number — The human-readable question number for display purposes.
concepts array — An array of concept objects attached to this question (empty if the question is not part of a concept test block). Each concept contains:
- id string — Unique identifier for the concept.
- title string — The concept title.
- description string — The concept description.
- media array — An array of media attachments, each with a type (image or video), a name, and a url.
- embed_url string | null — An optional embed URL for the concept (e.g. a Figma or prototype link).

Multiple choice questions (including scale questions) additionally include:

is_multi_select boolean — Whether the participant can select multiple options.
options string[] — The list of answer options.

Ranking questions additionally include:

options string[] — The list of items to rank.

Example Request

curl 'https://listenlabs.ai/api/public/studies/my-study/questions' \
  -H 'x-api-key: <api_key>'

Example Response

{
  "questions": [
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000001",
      "text": "What is your age range?",
      "is_screener": true,
      "question_number": 1,
      "type": "multiple_choice",
      "is_multi_select": false,
      "options": ["18-24", "25-34", "35-44", "45-54", "55+"],
      "concepts": []
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000002",
      "text": "Tell us about your experience with our product.",
      "is_screener": false,
      "question_number": 2,
      "type": "open_ended",
      "concepts": []
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000003",
      "text": "Rank the following features by importance.",
      "is_screener": false,
      "question_number": 3,
      "type": "ranking",
      "options": ["Ease of use", "Performance", "Price", "Customer support"],
      "concepts": []
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000004",
      "text": "Thank you for your feedback. We will now ask about your preferences.",
      "is_screener": false,
      "question_number": 4,
      "type": "statement",
      "concepts": []
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000005",
      "text": "Which categories interest you? Select all that apply.",
      "is_screener": false,
      "question_number": 5,
      "type": "multiple_choice",
      "is_multi_select": true,
      "options": ["Technology", "Health", "Finance", "Education", "Entertainment"],
      "concepts": []
    }
  ]
}

List Studies

This endpoint lists all studies. GET https://listenlabs.ai/api/public/list_surveys

Response

Returns a list of studies. Each study is an object with the following fields: id uuid Permanent unique identifier for the study. link_id string The link ID of the study. This is editable in the study settings so it might change. title string The title of the study. created_at string UTC timestamp of when the study was created. desc string A description of the study. E.g. “My study (10 Responses)”.

Example Request

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

Example Response

[
  {
    "id": "12345678-0000-0000-0000-000000000000",
    "link_id": "study-1",
    "title": "Example study",
    "created_at": "2023-09-02T07:07:17.960725+00:00",
    "desc": "Example study (12 Responses)"
  },
  {
    "id": "23456789-0000-0000-0000-000000000000",
    "link_id": "study-2",
    "title": "Example study 2",
    "created_at": "2023-09-01T07:07:17.960725+00:00",
    "desc": "Example study 2 (9 Responses)"
  }
]

​Create Study

​Request Body

​Response

​Example Request

​Example Response

​Errors

​Launch Study

​Path Parameters

​Request Body

​Response

​Example Request

​Example Response

​Errors

​List Wallets

​Response

​Example Request

​Example Response

​Get Responses

​Path Parameters

​Query Parameters

​Response

​Example Request

​Example Response

​Get Single Response

​Path Parameters

​Response

​Example Request

​Example Response — Audio and Text

​Example Response — Video and Text

​Example Response — Text Only

​Get Study Questions

​Path Parameters

​Response

​Example Request

​Example Response

​List Studies

​Response

​Example Request

​Example Response

Create Study

Request Body

Response

Example Request

Example Response

Errors

Launch Study

Path Parameters

Request Body

Response

Example Request

Example Response

Errors

List Wallets

Response

Example Request

Example Response

Get Responses

Path Parameters

Query Parameters

Response

Example Request

Example Response

Get Single Response

Path Parameters

Response

Example Request

Example Response — Audio and Text

Example Response — Video and Text

Example Response — Text Only

Get Study Questions

Path Parameters

Response

Example Request

Example Response

List Studies

Response

Example Request

Example Response