Skip to main content
The Study Creation API lets you build and launch studies entirely from code: define a study guide as JSON, create a draft, and launch it to get a self-recruit link you can distribute to participants.

​
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 organization — studies are created in, and wallets are listed for, that organization. 
curl 'https://listenlabs.ai/api/public/v1/wallets' \
  -H 'x-api-key: <api_key>'
Contact support@listenlabs.ai to request an API key. See Get API Access for details.

​
Workflow

1

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

Pick a wallet (optional)

GET /api/public/v1/wallets lists the wallets granted to your organization with their recruitment and project credit balances. walletId can only be omitted at launch when your organization 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.
3

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.
Once responses come in, retrieve them with the existing Get Responses and Get Single Response endpoints.

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 organization’s wallets with balances

​
Errors

Every error response 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 organization has multiple wallets and walletId was omitted (launch only).
400insufficient_creditsThe wallet can’t fund the launch — insufficient balance or grant limit (launch 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 organization.
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 organization.
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.