Before you start
Use responses:read and collection:read on a reporting key. Limit it to the intended groups. Bulk metadata is not available on a field-restricted key. Obtain group_id from groups.list and set DATUMFORMS_GROUP_ID.
Read all pages
- Request
responses.listwithgroup_id,after_id=0andinclude_collection_details=true. - Process
responses. Retainid,collection_id,version_id,revision,status,submitted_at,answersandcollection_details. - Pass a non-null
next_cursoras the nextafter_id. Stop at null. - For one response’s received-save and correction history, call
collection.getwithresponse_id; follow itscollection.next_cursorusingafter_operation.
Code example
cURL
#!/bin/sh
set -eu
: "${DATUMFORMS_API_KEY:?Set your key}"
: "${DATUMFORMS_GROUP_ID:?Set group ID from groups.list}"
API="${DATUMFORMS_API_URL:-https://app.datumforms.com/api/developer-api}"
after=0
while :; do
page=$(curl --fail-with-body -sS --get "$API" -H "Authorization: Bearer $DATUMFORMS_API_KEY" --data-urlencode operation=responses.list --data-urlencode "group_id=$DATUMFORMS_GROUP_ID" --data-urlencode "after_id=$after" --data-urlencode include_collection_details=true)
printf '%s' "$page" | jq -c '.responses[]'
after=$(printf '%s' "$page" | jq -r '.next_cursor')
[ "$after" = null ] && break
done
Run the complete paginated cURL reader. It prints one JSON response per line and follows every page.
JavaScript
import { get } from './client.mjs';
const groupId=Number(process.env.DATUMFORMS_GROUP_ID);
if (!Number.isSafeInteger(groupId) || groupId<1) throw Error('Set DATUMFORMS_GROUP_ID');
let after=0;
do {
const page=await get('responses.list',{group_id:groupId,after_id:after,limit:100,include_collection_details:true});
for (const response of page.responses) console.log(JSON.stringify(response));
after=page.next_cursor;
} while (after!==null);
Python
import json, os
from client import get
group_id=int(os.environ['DATUMFORMS_GROUP_ID'])
after=0
while True:
page=get('responses.list',group_id=group_id,after_id=after,limit=100,include_collection_details=True)
for response in page['responses']:
print(json.dumps(response))
after=page['next_cursor']
if after is None:
break
Filter and read locations
filters is a JSON array: [{"question_ref":456,"operator":"eq","value":"North"}]. Operators are eq, ne, in and contains, combined with AND. A field-restricted key may filter only its permitted questions. Include location:read and include_location=true for permitted captured and reference coordinates.
Check the result
Answer cells use form_elements_id, row, col and field_response_value. Keep matrix coordinates and the original version. Metadata distinguishes device capture from server receipt; a null value means no value was returned. Anonymous and panel coordinates are omitted, and recruited drafts remain hidden until submission.
Troubleshooting
For 403 on metadata, verify collection:read and remove field restrictions from the dedicated metadata key. For absent rows, check scope, filters and submission. Schemas explain the returned objects; export data for downstream analysis.