Getting Started
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). The key is scoped to one workspace; 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.
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 workspace has exactly one wallet — launch then auto-selects it. With multiple wallets you must pass one explicitly, so list them and pick:
usage includes active holds.
3. Launch
The path takes the study's id from step 1 — the linkId is not accepted here.
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 or read them back later from each response's urlParams.
If you omit the body and your workspace 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 (the study's id is accepted too):