Listen LabsDocs

    Getting Started

    Listen Labs API

    Create, launch, and retrieve data from Listen Labs studies programmatically

    The Listen Labs API lets you run studies entirely from code: define a study guide as JSON, create a draft, launch it to get a self-recruit link you can distribute to participants, and pull responses back out once interviews come in.

    Base URL

    https://listenlabs.ai

    Authentication

    All endpoints authenticate with an API key passed in the x-api-key header. The key is scoped to a single workspace and acts as an admin there: it can read, change, and delete every study in that workspace, including restricted studies. Studies are created in, and wallets are listed for, that workspace. See Get API Access for how keys work.

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

    Admins and Supervisors can create API keys from the Developer section of their account page on Listen. See Get API Access for details.

    Workflow

    Create a draft study

    POST /api/public/v1/studies/create with a title and a study guide. The guide is validated up front; if it passes, you get back a draft study's id and linkId. Nothing is visible to participants yet — you can still review or edit the draft in the dashboard.

    Pick a wallet (optional)

    GET /api/public/v1/wallets lists the wallets granted to your workspace with their recruitment and project credit balances. walletId can only be omitted at launch when your workspace has exactly one wallet (it's auto-selected). If you have access to more than one, omitting it returns a 400 (wallet_required) — you must pass one from this list.

    Launch

    POST /api/public/v1/studies/{studyId}/launch publishes the draft and opens its self-recruit link. The response includes selfRecruitLink — share it with participants (or plug it into your own recruitment flow). Project responses bill to the launch wallet.

    Retrieve responses

    Once interviews come in, pull them with Get Responses (GET /api/public/v1/responses/{linkId}) and drill into a single transcript with Get Single Response. The linkId comes back from create/launch, or from List Studies. The Data Map shows how these entities join together. To get a signed request when each response is ready, set up Webhooks.

    Quickstart

    A complete create → launch example you can copy and run.

    Endpoints

    EndpointDescription
    POST /api/public/v1/studies/createValidate a study guide and create a draft study
    POST /api/public/v1/studies/{studyId}/launchPublish a draft and return the self-recruit link
    GET /api/public/v1/walletsList the workspace's wallets with balances
    GET /api/public/v1/studiesList studies with response counts, creators, and folder paths
    GET /api/public/v1/studies/{studyId}/questionsGet a study's questions and concepts
    GET /api/public/v1/responses/{linkId}List all responses for a study
    GET /api/public/v1/responses/{linkId}/{responseId}Retrieve a single response
    GET /api/public/v1/responsesSearch responses by an exact URL parameter value
    DELETE /api/public/v1/responsesRequest asynchronous response deletion
    GET /api/public/v1/response-deletions/{deletionId}Check deletion status

    Errors

    Every error response from the /api/public/v1/* endpoints shares one JSON envelope:

    • error — a human-readable message. Useful for logs, but it may change; don't branch on it.
    • code — a stable, machine-readable identifier. Branch on this.
    • issues — present only on 400 schema failures (code: invalid_request_body): an array of per-field violations, each with a path and message.
    400 Schema violation
    {
      "error": "Invalid request body",
      "code": "invalid_request_body",
      "issues": [
        {
          "code": "invalid_type",
          "expected": "string",
          "received": "undefined",
          "path": ["title"],
          "message": "Required"
        }
      ]
    }
    400 Invalid study guide
    {
      "error": "Invalid study guide: conditional references unknown item externalId 'q2'",
      "code": "invalid_study_guide"
    }

    Error codes

    StatusCodeMeaning
    400invalid_jsonRequest body isn't valid JSON.
    400invalid_request_bodyBody failed schema validation. See issues for per-field details.
    400invalid_study_guideThe study guide broke a cross-field rule (create only).
    400wallet_requiredThe workspace has multiple wallets and walletId was omitted (launch only).
    400insufficient_creditsThe wallet can't fund the launch — insufficient balance or grant limit (launch only).
    400bad_requestA query or path parameter is invalid (response endpoints only).
    401missing_api_keyNo x-api-key header.
    401invalid_api_keyThe API key is invalid.
    403forbiddenThe key's user isn't a member of the key's workspace.
    403launch_permission_deniedThe key's user lacks permission to launch this study.
    403wallet_access_deniedNo access to the specified wallet.
    404study_not_foundStudy not found in the key's workspace.
    404response_not_foundResponse not found in the study (get response only).
    404not_foundResponse or deletion not found in the key's workspace (deletion endpoints only).
    409concurrent_modificationThe draft was modified concurrently; retry (create only).
    409study_busyAn update is in flight; retry after a moment (launch only).
    409conflictThe publish raced a concurrent edit; refresh and retry (launch only).
    500internal_errorInternal error. Details are logged server-side, not returned.

    Beyond field-level validation, the server enforces cross-field rules on the study guide (screening block placement, minSelect/maxSelect coupling, unique externalIds, reference resolution, exclusiveOption placement) and returns violations as 400 responses (code: invalid_study_guide). The full list is in the Study Guide Reference.