Before you start
Connect the intended spreadsheet through the project’s Google Sheets flow. Create a server integration key with sheets:read and sheets:write, scoped to the survey group. Restrict access to the Apps Script project because its editors can access Script properties.
Configure the script
- Open your spreadsheet’s Extensions → Apps Script.
- In Apps Script Project Settings → Script properties, add
DATUMFORMS_API_KEYandDATUMFORMS_GROUP_ID. Obtain the group ID fromgroups.list. - Paste the script below. Run
readDatumFormsStatusand authorize the script’s requested Google access. - Run
refreshDatumFormsonce, then run the status check again untilrefresh_pendingis false and the expected revision has completed. - If required, add a time-driven trigger for the refresh function after confirming the one-off flow.
Apps Script
function refreshDatumForms() {
const props=PropertiesService.getScriptProperties();
const key=props.getProperty('DATUMFORMS_API_KEY');
const group=props.getProperty('DATUMFORMS_GROUP_ID');
if(!key||!group)throw Error('Set key and group ID in Script properties');
const r=UrlFetchApp.fetch('https://app.datumforms.com/api/developer-api',{
method:'post',contentType:'application/json',
headers:{Authorization:'Bearer '+key},
payload:JSON.stringify({operation:'sheets.refresh',group_id:Number(group),data:{},idempotency_key:'sheets:'+Utilities.getUuid()}),
muteHttpExceptions:true
});
const result=JSON.parse(r.getContentText());
if(r.getResponseCode()>=400||result.success===false)throw Error(result.message||'Refresh failed');
console.log('Refresh queued for group '+result.group_id);
}
function readDatumFormsStatus() {
const p=PropertiesService.getScriptProperties();
const url='https://app.datumforms.com/api/developer-api?operation=sheets.status&group_id='+encodeURIComponent(p.getProperty('DATUMFORMS_GROUP_ID'));
const r=UrlFetchApp.fetch(url,{headers:{Authorization:'Bearer '+p.getProperty('DATUMFORMS_API_KEY')},muteHttpExceptions:true});
const result=JSON.parse(r.getContentText());
if(r.getResponseCode()>=400||result.success===false)throw Error(result.message||'Status failed');
console.log(JSON.stringify({refresh_pending:result.refresh_pending,revision:result.revision,spreadsheet_id:result.spreadsheet_id}));
}
cURL, server JavaScript and Python
The same workflow uses sheets.refresh followed by sheets.status. Those reference pages include complete examples in all three languages. Every refresh request has its own stable retry identity; when recovering an uncertain request, reuse that exact identity instead of generating a different one.
Check the result
Open the returned spreadsheet_id and confirm known responses, headers and revision. A queued refresh is not the same as a finished export. Keep the connected export’s managed layout intact.
Troubleshooting
A 409 stating that Google Sheets must be connected requires the project’s existing Google connection. For 403, check sheet permissions and the API key’s group scope. Avoid logging the secret or response contents. Connect Google Sheets or handle retries.