DatumForms.
Join the panel Sign in Create a survey

DATUMFORMS DOCUMENTATION

Select an audience and launch recruitment through the API

Quote an audience, create a study, launch it and monitor collected feedback.

For developers

Updated 15 November 2026

On this page

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

  1. Read audience_options and select the enabled audience and filters. Set response count and realistic task length.
  2. Request quote and inspect eligible capacity, every quota target and price. Set the maximum budget explicitly.
  3. Create the draft study with a stable request UUID. Retain its returned id as study_id.
  4. Confirm the quoted published version, funding and recruitment budget, then call launch_study.
  5. Monitor study_detail and retrieve submitted feedback through the response API. Use the response group ID for that read.
  6. Pause recruitment with pause_study, or use project-key operation recruitment.stop with recruitment: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

Download recruitment.sh

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));
 }
}

Download recruitment.mjs

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))

Download recruitment.py

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.

Need help with this task? Contact DatumForms. Include the article URL and the step you reached.

Tracking preferences

Essential functions stay on. Choose whether to allow optional tracking on this website. You can change your choices in the footer at any time.

Read our privacy policy