> ## Documentation Index
> Fetch the complete documentation index at: https://docs.listenlabs.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# 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](/get-api-access)). The key is scoped to one organization; 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.
```bash Request theme={null}
curl -X POST 'https://listenlabs.ai/api/public/v1/studies/create' \
-H 'x-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"
}
]
}
]
}'
```
```json Response (201) theme={null}
{
"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 organization has exactly one wallet — launch then auto-selects it. With multiple wallets you must pass one explicitly, so list them and pick:
```bash Request theme={null}
curl 'https://listenlabs.ai/api/public/v1/wallets' \
-H 'x-api-key: '
```
```json Response (200) theme={null}
{
"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
```bash Request theme={null}
curl -X POST 'https://listenlabs.ai/api/public/v1/studies/9b2f1c3e-0000-0000-0000-000000000000/launch' \
-H 'x-api-key: ' \
-H 'Content-Type: application/json' \
-d '{ "walletId": "5e8a7d40-0000-0000-0000-000000000000" }'
```
```json Response (200) theme={null}
{
"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](/api-v2/study-guide#conditional-logic) or read them back later from each response's `attributes`.
If you omit the body and your organization 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`:
```bash theme={null}
curl 'https://listenlabs.ai/api/public/v1/responses/coffee-habits-api-demo' \
-H 'x-api-key: '
```
All block and question types, conditionals, carry-forward, and validation rules.
Retrieve transcripts, answers, and summaries for a launched study.