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
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.
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.
A complete create → launch example you can copy and run.
Endpoints
| Endpoint | Description |
|---|---|
POST /api/public/v1/studies/create | Validate a study guide and create a draft study |
POST /api/public/v1/studies/{studyId}/launch | Publish a draft and return the self-recruit link |
GET /api/public/v1/wallets | List the workspace's wallets with balances |
GET /api/public/v1/studies | List studies with response counts, creators, and folder paths |
GET /api/public/v1/studies/{studyId}/questions | Get 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/responses | Search responses by an exact URL parameter value |
DELETE /api/public/v1/responses | Request 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 on400schema failures (code: invalid_request_body): an array of per-field violations, each with apathandmessage.
Error codes
| Status | Code | Meaning |
|---|---|---|
400 | invalid_json | Request body isn't valid JSON. |
400 | invalid_request_body | Body failed schema validation. See issues for per-field details. |
400 | invalid_study_guide | The study guide broke a cross-field rule (create only). |
400 | wallet_required | The workspace has multiple wallets and walletId was omitted (launch only). |
400 | insufficient_credits | The wallet can't fund the launch — insufficient balance or grant limit (launch only). |
400 | bad_request | A query or path parameter is invalid (response endpoints only). |
401 | missing_api_key | No x-api-key header. |
401 | invalid_api_key | The API key is invalid. |
403 | forbidden | The key's user isn't a member of the key's workspace. |
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 workspace. |
404 | response_not_found | Response not found in the study (get response only). |
404 | not_found | Response or deletion not found in the key's workspace (deletion endpoints only). |
409 | concurrent_modification | The draft was modified concurrently; retry (create only). |
409 | study_busy | An update is in flight; retry after a moment (launch only). |
409 | conflict | The publish raced a concurrent edit; refresh and retry (launch only). |
500 | internal_error | Internal 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.