Before you start
Use a project-wide key with groups:write, surveys:write, surveys:read, assignments:write and surveys:publish. Download the JavaScript client or Python client. Set DATUMFORMS_API_KEY and a persisted DATUMFORMS_RUN_ID. cURL recipes also use jq.
Run the sequence
- Call
groups.saveand retain itsgroup_id: this collection will hold responses. - Call
surveys.savewith the page’s questions. Retainform_id. - Call
groups.assign_formwith thatgroup_idanddata.form_id. - Call
surveys.reviewwith the group ID. Inspect the returned changes and any blocking issues; retain the currentreview_token. - Call
surveys.publishwith the group and that token after review.
Code example
cURL
#!/bin/sh
set -eu
: "${DATUMFORMS_API_KEY:?Set your project key}"
: "${DATUMFORMS_RUN_ID:?Set your persisted run identity}"
API="${DATUMFORMS_API_URL:-https://app.datumforms.com/api/developer-api}"
post() { curl --fail-with-body -sS "$API" -H "Authorization: Bearer $DATUMFORMS_API_KEY" -H 'Content-Type: application/json' --data "$1"; }
group=$(post "$(jq -nc --arg run "$DATUMFORMS_RUN_ID" '{operation:"groups.save",idempotency_key:($run+":group"),data:{name:"Service feedback"}}')")
group_id=$(printf '%s' "$group" | jq -er .group_id)
form=$(post "$(jq -nc --arg run "$DATUMFORMS_RUN_ID" '{operation:"surveys.save",idempotency_key:($run+":form"),data:{name:"Service feedback questions",elements:[{type:"radio",client_id:"resolved",caption:"Was your issue resolved?",options:[{name:"Yes",value:"yes"},{name:"No",value:"no"}]}]}}')")
form_id=$(printf '%s' "$form" | jq -er .form_id)
post "$(jq -nc --arg run "$DATUMFORMS_RUN_ID" --argjson group "$group_id" --argjson form "$form_id" '{operation:"groups.assign_form",group_id:$group,idempotency_key:($run+":attach"),data:{form_id:$form}}')"
review=$(curl --fail-with-body -sS --get "$API" -H "Authorization: Bearer $DATUMFORMS_API_KEY" --data-urlencode operation=surveys.review --data-urlencode "group_id=$group_id")
printf '%s\n' "$review" | jq .
if [ "${DATUMFORMS_PUBLISH:-no}" = yes ]; then
token=$(printf '%s' "$review" | jq -er .review_token)
post "$(jq -nc --arg run "$DATUMFORMS_RUN_ID" --argjson group "$group_id" --arg token "$token" '{operation:"surveys.publish",group_id:$group,idempotency_key:($run+":publish"),data:{review_token:$token}}')"
fi
Download and run the complete cURL sequence. Run it once to inspect the review. Run again with DATUMFORMS_PUBLISH=yes and the same run identity to publish the reviewed definition. Each stage retains its own retry identity.
JavaScript
import { get, post } from './client.mjs';
const group = await post('group', 'groups.save', {name:'Service feedback'});
const form = await post('form', 'surveys.save', {
name:'Service feedback questions', page_number:1,
elements:[{type:'radio',client_id:'resolved',caption:'Was your issue resolved?',required:true,
options:[{name:'Yes',value:'yes'},{name:'No',value:'no'}]}]
});
await post('attach','groups.assign_form',{form_id:form.form_id},{group_id:group.group_id});
const review = await get('surveys.review',{group_id:group.group_id});
console.log(JSON.stringify(review,null,2));
if (process.env.DATUMFORMS_PUBLISH !== 'yes') {
console.log('Inspect the review, then rerun with DATUMFORMS_PUBLISH=yes and the same run ID.');
} else {
const result=await post('publish','surveys.publish',{review_token:review.review_token},{group_id:group.group_id});
console.log(JSON.stringify({group_id:group.group_id,form_id:form.form_id,result},null,2));
}
Python
import json, os
from client import get, post
group=post('group','groups.save',{'name':'Service feedback'})
form=post('form','surveys.save',{'name':'Service feedback questions','page_number':1,'elements':[
{'type':'radio','client_id':'resolved','caption':'Was your issue resolved?','required':True,
'options':[{'name':'Yes','value':'yes'},{'name':'No','value':'no'}]}]})
post('attach','groups.assign_form',{'form_id':form['form_id']},group_id=group['group_id'])
review=get('surveys.review',group_id=group['group_id'])
print(json.dumps(review,indent=2))
if os.environ.get('DATUMFORMS_PUBLISH')=='yes':
result=post('publish','surveys.publish',{'review_token':review['review_token']},group_id=group['group_id'])
print(json.dumps(dict(group_id=group['group_id'],form_id=form['form_id'],result=result),indent=2))
else:
print('Inspect the review, then rerun with DATUMFORMS_PUBLISH=yes and the same run ID.')
Check the result
Read groups.list and verify the group’s published_version_id. Save the group ID and the published version for response reads and recruitment. Use surveys.get to obtain saved question references for answer imports; a temporary client_id is not a saved question ID.
Troubleshooting
A 409 on save means the definition or retry request changed. A publication conflict requires a fresh review. Existing responses retain their original versions. Handle conflicts and read collected responses.