DatumForms.
Join the panel Sign in Create a survey

DATUMFORMS DOCUMENTATION

Create, review and publish a survey through the API

Create a collection and question page, attach them and publish the reviewed definition.

For developers

Updated 15 November 2026

On this page

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

  1. Call groups.save and retain its group_id: this collection will hold responses.
  2. Call surveys.save with the page’s questions. Retain form_id.
  3. Call groups.assign_form with that group_id and data.form_id.
  4. Call surveys.review with the group ID. Inspect the returned changes and any blocking issues; retain the current review_token.
  5. Call surveys.publish with 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 create-survey.sh

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.

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