DatumForms.
Join the panel Sign in Create a survey

DATUMFORMS DOCUMENTATION

Refresh a connected Google Sheet with Apps Script

Queue the existing survey spreadsheet export and check its completion from Apps Script.

For developers

Updated 15 November 2026

On this page

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

  1. Open your spreadsheet’s Extensions → Apps Script.
  2. In Apps Script Project Settings → Script properties, add DATUMFORMS_API_KEY and DATUMFORMS_GROUP_ID. Obtain the group ID from groups.list.
  3. Paste the script below. Run readDatumFormsStatus and authorize the script’s requested Google access.
  4. Run refreshDatumForms once, then run the status check again until refresh_pending is false and the expected revision has completed.
  5. 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.

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