Before you start
Use https://app.datumforms.com/api/panel with the authenticated project-administrator session in Authorization: Bearer. Supply the project ID from the workspace and the survey ID from GET action=surveys&project_id=...; this is distinct from the response group’s ID. Publish the intended survey version and confirm the study’s funding and budget before launch.
Operation reference
| Method | Action | Required input | Result |
|---|---|---|---|
| GET | audience_options |
project_id |
questions, roles, countries with availability |
| GET | surveys |
project_id |
Survey selection and identifiers |
| POST | quote |
project_id, filters, required_completes, estimated_minutes or question_count; optional survey_id |
Eligible count, quota targets, availability, version and price |
| POST | create_study |
Quote inputs including survey_id, stable UUID request_id, max_budget_minor |
id (study UUID), status: draft, quote |
| POST | launch_study |
study_id, confirm_budget: true; optional allow_partial_audience |
success and aggregate counts |
| GET | studies |
project_id |
Up to 100 studies, newest first |
| GET | study_detail |
study_id |
study, aggregate counts, quota_progress |
| POST | pause_study |
study_id |
success and aggregate counts |
| POST | cancel_study |
study_id |
success and aggregate counts when cancellation is permitted |
GET inputs use query parameters; POST inputs are a JSON object with action and the fields shown. All actions above require project administrator access. quote accepts 1–100,000 completions and 1–120 estimated minutes. Read live audience options and use the returned question/choice keys in filters. Quote normalizes the audience and calculates capacity, price and quota buckets.
Run the workflow
- Read
audience_optionsand select the enabled audience and filters. Set response count and realistic task length. - Request
quoteand inspect eligible capacity, every quota target and price. Set the maximum budget explicitly. - Create the draft study with a stable request UUID. Retain its returned
idasstudy_id. - Confirm the quoted published version, funding and recruitment budget, then call
launch_study. - Monitor
study_detailand retrieve submitted feedback through the response API. Use the response group ID for that read. - Pause recruitment with
pause_study, or use project-key operationrecruitment.stopwithrecruitment:stop.
Code example
Download the full cURL workflow, JavaScript workflow or Python workflow. Set DATUMFORMS_SESSION, DATUMFORMS_PROJECT_ID and DATUMFORMS_RECRUITMENT_INPUT to your approved JSON quote inputs. The scripts read options and quote first. Set DATUMFORMS_CREATE_STUDY=yes with a persisted DATUMFORMS_STUDY_REQUEST_ID to save the draft, then DATUMFORMS_LAUNCH=yes when approved to start. A partial-audience launch requires its separate explicit choice.
cURL
#!/bin/bash
set -euo pipefail
: "${DATUMFORMS_SESSION:?Set administrator session}"
: "${DATUMFORMS_PROJECT_ID:?Set project ID}"
: "${DATUMFORMS_RECRUITMENT_INPUT:?Set approved quote inputs JSON}"
API="${DATUMFORMS_API_ORIGIN:-https://app.datumforms.com}/api/panel"
post() { curl --fail-with-body -sS "$API" -H "Authorization: Bearer $DATUMFORMS_SESSION" -H 'Content-Type: application/json' --data "$1"; }
curl --fail-with-body -sS --get "$API" -H "Authorization: Bearer $DATUMFORMS_SESSION" --data-urlencode action=audience_options --data-urlencode "project_id=$DATUMFORMS_PROJECT_ID"
post "$(jq -nc --argjson input "$DATUMFORMS_RECRUITMENT_INPUT" --argjson project "$DATUMFORMS_PROJECT_ID" '$input+{action:"quote",project_id:$project}')" | jq .
if [ "${DATUMFORMS_CREATE_STUDY:-no}" = yes ]; then
: "${DATUMFORMS_STUDY_REQUEST_ID:?Set persisted study UUID}"
study=$(post "$(jq -nc --argjson input "$DATUMFORMS_RECRUITMENT_INPUT" --argjson project "$DATUMFORMS_PROJECT_ID" --arg request "$DATUMFORMS_STUDY_REQUEST_ID" '$input+{action:"create_study",project_id:$project,request_id:$request}')")
printf '%s\n' "$study" | jq .
if [ "${DATUMFORMS_LAUNCH:-no}" = yes ]; then
partial=false; [ "${DATUMFORMS_ALLOW_PARTIAL:-no}" != yes ] || partial=true
id=$(printf '%s' "$study" | jq -er .id)
post "$(jq -nc --arg id "$id" --argjson partial "$partial" '{action:"launch_study",study_id:$id,confirm_budget:true,allow_partial_audience:$partial}')"
curl --fail-with-body -sS --get "$API" -H "Authorization: Bearer $DATUMFORMS_SESSION" --data-urlencode action=study_detail --data-urlencode "study_id=$id"
fi
fi
JavaScript
// Node.js 18+. Keep a project administrator session in your secret store.
const API=(process.env.DATUMFORMS_API_ORIGIN||'https://app.datumforms.com')+'/api/panel';
const session=process.env.DATUMFORMS_SESSION;
const project=Number(process.env.DATUMFORMS_PROJECT_ID);
async function call(method,input){if(!session||!project)throw Error('Set session and project');const u=new URL(API);if(method==='GET')for(const[k,v]of Object.entries(input))u.searchParams.set(k,v);const r=await fetch(u,{method,headers:{Authorization:'Bearer '+session,'Content-Type':'application/json'},...(method==='POST'?{body:JSON.stringify(input)}:{})});const j=await r.json();if(!r.ok||j.success===false)throw Error(r.status+': '+j.message);return j;}
const options=await call('GET',{action:'audience_options',project_id:project});
console.log(JSON.stringify(options,null,2));
const input=JSON.parse(process.env.DATUMFORMS_RECRUITMENT_INPUT);
// input: survey_id, filters, required_completes, estimated_minutes, max_budget_minor.
const quote=await call('POST',{action:'quote',project_id:project,...input});
console.log(JSON.stringify(quote,null,2));
if(process.env.DATUMFORMS_CREATE_STUDY==='yes'){
const draft=await call('POST',{action:'create_study',project_id:project,...input,request_id:process.env.DATUMFORMS_STUDY_REQUEST_ID});
console.log(JSON.stringify(draft,null,2));
if(process.env.DATUMFORMS_LAUNCH==='yes'){
await call('POST',{action:'launch_study',study_id:draft.id,confirm_budget:true,allow_partial_audience:process.env.DATUMFORMS_ALLOW_PARTIAL==='yes'});
console.log(JSON.stringify(await call('GET',{action:'study_detail',study_id:draft.id}),null,2));
}
}
Python
import json, os, urllib.parse, urllib.request
API=os.environ.get('DATUMFORMS_API_ORIGIN','https://app.datumforms.com')+'/api/panel'
project=int(os.environ['DATUMFORMS_PROJECT_ID'])
def call(method,payload):
url=API+('?' + urllib.parse.urlencode(payload) if method=='GET' else '')
req=urllib.request.Request(url,method=method,data=json.dumps(payload).encode() if method=='POST' else None,headers={'Authorization':'Bearer '+os.environ['DATUMFORMS_SESSION'],'Content-Type':'application/json'})
with urllib.request.urlopen(req,timeout=60) as r: result=json.load(r)
if result.get('success') is False: raise RuntimeError(result.get('message'))
return result
print(json.dumps(call('GET',dict(action='audience_options',project_id=project)),indent=2))
inputs=json.loads(os.environ['DATUMFORMS_RECRUITMENT_INPUT'])
quote=call('POST',dict(action='quote',project_id=project,**inputs))
print(json.dumps(quote,indent=2))
if os.environ.get('DATUMFORMS_CREATE_STUDY')=='yes':
draft=call('POST',dict(action='create_study',project_id=project,request_id=os.environ['DATUMFORMS_STUDY_REQUEST_ID'],**inputs))
print(json.dumps(draft,indent=2))
if os.environ.get('DATUMFORMS_LAUNCH')=='yes':
call('POST',dict(action='launch_study',study_id=draft['id'],confirm_budget=True,allow_partial_audience=os.environ.get('DATUMFORMS_ALLOW_PARTIAL')=='yes'))
print(json.dumps(call('GET',dict(action='study_detail',study_id=draft['id'])),indent=2))
Check the result
The study is recruiting against the quoted version and audience. quota_progress distinguishes reserved and accepted places; invitations do not reserve capacity. DatumForms automatically checks completed panel responses and accepts valid responses. Read the feedback with its original survey version. New evaluation rounds use their own reviewed questionnaire and study identifiers.
Troubleshooting
401 requires a valid session; 403 requires administration of the study project. A 409 can indicate changed publication, pricing, funding state, active reservations or insufficient audience. Read current study state before retrying a launch. A repeated create_study UUID must carry exactly the same inputs.
Recruitment targets · AI evaluation workflow · Stop recruitment with a project key.