DatumForms.
Join the panel Sign in Create a survey

DATUMFORMS DOCUMENTATION

Read responses and collection metadata through the API

Retrieve every permitted response page and retain its original version and collection context.

For developers

Updated 15 November 2026

On this page

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

  1. Request responses.list with group_id, after_id=0 and include_collection_details=true.
  2. Process responses. Retain id, collection_id, version_id, revision, status, submitted_at, answers and collection_details.
  3. Pass a non-null next_cursor as the next after_id. Stop at null.
  4. For one response’s received-save and correction history, call collection.get with response_id; follow its collection.next_cursor using after_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

Download read-responses.sh

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.

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