SheetgoDevelopers

Developers › REST API › Forms & Integrations

REST API · 7 endpoints

forms

Complete for this group. Each operation below lists its parameters, request body, responses and errors. Every model they use is documented under Models used on this page, so you do not need another page to build a request. Base URL https://dev-api.sheetgo.com; send Authorization: Bearer sg_…. Latest version: https://dev-api.sheetgo.com/rest/reference/forms (Markdown).

Conventions for every endpoint. Lists take page (from 1) and per_page (1-100, default 50), and total counts pages, not items. Collection URLs end with /. POST …/run returns 200 when the run is queued; poll GET …/run. Google Sheets use provider: "drive"; column fields take letters ("E"). Error bodies and status codes: api.html#api-errors.

Python recipes. API client helper · Read every page of a list.

A Sheetgo form collects data straight into a workflow. Its fields come from your spreadsheet's columns, and every submission is appended as a new row — a simple way to feed a workflow from people instead of another system.

Use these endpoints to list a workflow's forms and read their configuration.

Operations

GET/rest/beta/workflows/{workflow_id}/forms/Get a paginated list of forms

Return a list of forms following the pagination parameters

Parameters
NameInTypeDescription
workflow_idpathstringrequiredWorkflow identification
pagequeryintegeroptionalPage number, 1-based
Default: 1 · Min: 1
per_pagequeryintegeroptionalNumber of items per page (1-100; values above 100 are clamped to 100 and the effective size is echoed in the response)
Default: 50 · Min: 1
Responses
StatusMeaningBody
200A paginated list of formsPaginatedResponse_FormModel_
401Authentication failed or token is invalid—
404Not found—
422Validation ErrorHTTPValidationError
Example request
curl -s -X GET "https://dev-api.sheetgo.com/rest/beta/workflows/WORKFLOW_ID/forms/" \
  -H "Authorization: Bearer $SHEETGO_API_KEY"

Latest version: https://dev-api.sheetgo.com/rest/reference/forms#get-rest-beta-workflows-workflow-id-forms

POST/rest/beta/workflows/{workflow_id}/forms/Create a new form

Create a new form

Parameters
NameInTypeDescription
workflow_idpathstringrequiredWorkflow identification
Request body (optional)

application/json · FormCreate

FieldTypeDescription
confirmation_messagestringnullableConfirmation message
descriptionstringnullableForm description
include_headerbooleannullableTrue if include header
Default: false
limit_responsesbooleannullableTrue if should limit responses
Default: false
require_authbooleannullableTrue if it requires authentication
Default: false
sourceFormFilerequiredForm fields source file
targetFormFilerequiredResponse destination file
titlestringoptionalTitle for the form
Default: "Untitled form"
Responses
StatusMeaningBody
200The form model createdFormModel
401Authentication failed or token is invalid—
404Not found—
422Validation ErrorHTTPValidationError
Example request
curl -s -X POST "https://dev-api.sheetgo.com/rest/beta/workflows/WORKFLOW_ID/forms/" \
  -H "Authorization: Bearer $SHEETGO_API_KEY" \
  -H "Content-Type: application/json" \
  -d @body.json

Latest version: https://dev-api.sheetgo.com/rest/reference/forms#post-rest-beta-workflows-workflow-id-forms

GET/rest/beta/workflows/{workflow_id}/forms/{form_id}Get a form

Returns the form model data

Parameters
NameInTypeDescription
workflow_idpathstringrequiredWorkflow identification
form_idpathstringrequiredForm identification
Responses
StatusMeaningBody
200The form model dataFormModel
401Authentication failed or token is invalid—
404Not found—
422Validation ErrorHTTPValidationError
Example request
curl -s -X GET "https://dev-api.sheetgo.com/rest/beta/workflows/WORKFLOW_ID/forms/FORM_ID" \
  -H "Authorization: Bearer $SHEETGO_API_KEY"

Latest version: https://dev-api.sheetgo.com/rest/reference/forms#get-rest-beta-workflows-workflow-id-forms-form-id

PATCH/rest/beta/workflows/{workflow_id}/forms/{form_id}Update an existing form

Patches form data

Parameters
NameInTypeDescription
workflow_idpathstringrequiredWorkflow identification
form_idpathstringrequiredForm identification
Request body (optional)

application/json · FormPatch

FieldTypeDescription
confirmation_messagestringnullableConfirmation message
descriptionstringnullableForm description
limit_responsesbooleannullableLimit each respondent to one response. Must be sent together with require_auth — identifying the respondent is how the limit is enforced.
require_authbooleannullableRequire respondents to authenticate. SG-14657 — must be sent together with limit_responses; sending one alone is a 422. Setting limit_responses true forces this on.
sourceFormFilenullableForm fields source file
sync_fields_after_submissionbooleannullableTrue it should sync fields after submission
targetFormFilenullableResponse destination file
titlestringnullableTitle for the form
Responses
StatusMeaningBody
200The form model patchedFormModel
401Authentication failed or token is invalid—
404Not found—
422Validation ErrorHTTPValidationError
Example request
curl -s -X PATCH "https://dev-api.sheetgo.com/rest/beta/workflows/WORKFLOW_ID/forms/FORM_ID" \
  -H "Authorization: Bearer $SHEETGO_API_KEY" \
  -H "Content-Type: application/json" \
  -d @body.json

Latest version: https://dev-api.sheetgo.com/rest/reference/forms#patch-rest-beta-workflows-workflow-id-forms-form-id

DELETE/rest/beta/workflows/{workflow_id}/forms/{form_id}Delete a form

Deletes a form

Parameters
NameInTypeDescription
workflow_idpathstringrequiredWorkflow identification
form_idpathstringrequiredForm identification
Responses
StatusMeaningBody
200The form was successfully deletedSuccessResponse
401Authentication failed or token is invalid—
404Not found—
422Validation ErrorHTTPValidationError
Example request
curl -s -X DELETE "https://dev-api.sheetgo.com/rest/beta/workflows/WORKFLOW_ID/forms/FORM_ID" \
  -H "Authorization: Bearer $SHEETGO_API_KEY"

Latest version: https://dev-api.sheetgo.com/rest/reference/forms#delete-rest-beta-workflows-workflow-id-forms-form-id

GET/rest/beta/workflows/{workflow_id}/forms/{form_id}/responsesGet a form's responses (paginated)

Return the form's responses (from its first target spreadsheet), paginated.

Parameters
NameInTypeDescription
workflow_idpathstringrequiredWorkflow identification
form_idpathstringrequiredForm identification
pagequeryintegeroptionalPage number
Default: 1 · Min: 1
per_pagequeryintegeroptionalItems per page
Default: 50 · Min: 1 · Max: 100
strip_tagsquerybooleanoptionalStrip trailing ' [config]' tags from response headers
Default: false
Responses
StatusMeaningBody
200Paginated form responsesPaginatedResponse
401Authentication failed or token is invalid—
404Form or workflow not found—
422Validation ErrorHTTPValidationError
Example request
curl -s -X GET "https://dev-api.sheetgo.com/rest/beta/workflows/WORKFLOW_ID/forms/FORM_ID/responses" \
  -H "Authorization: Bearer $SHEETGO_API_KEY"

Latest version: https://dev-api.sheetgo.com/rest/reference/forms#get-rest-beta-workflows-workflow-id-forms-form-id-responses

HEAD/rest/beta/workflows/{workflow_id}/forms/{form_id}/responsesInspect a form's responses metadata without downloading them

Return response count / columns / last-modified in headers, no body.

Parameters
NameInTypeDescription
workflow_idpathstringrequiredWorkflow identification
form_idpathstringrequiredForm identification
strip_tagsquerybooleanoptionalStrip trailing ' [config]' tags from response headers
Default: false
Responses
StatusMeaningBody
200Response metadata in X-Sheetgo-* headersany
401Authentication failed or token is invalid—
404Form or workflow not found—
422Validation ErrorHTTPValidationError
Example request
curl -s -X HEAD "https://dev-api.sheetgo.com/rest/beta/workflows/WORKFLOW_ID/forms/FORM_ID/responses" \
  -H "Authorization: Bearer $SHEETGO_API_KEY"

Latest version: https://dev-api.sheetgo.com/rest/reference/forms#head-rest-beta-workflows-workflow-id-forms-form-id-responses

Models used on this page

Every request and response model referenced above, including nested ones (12). The full catalogue is on api-models.html.

FileType

Type: one of "gsheets", "xlsx", "csv", "tsv", "folder"

FormCreate

Form creation data

FieldTypeDescription
confirmation_messagestringnullableConfirmation message
descriptionstringnullableForm description
include_headerbooleannullableTrue if include header
Default: false
limit_responsesbooleannullableTrue if should limit responses
Default: false
require_authbooleannullableTrue if it requires authentication
Default: false
sourceFormFilerequiredForm fields source file
targetFormFilerequiredResponse destination file
titlestringoptionalTitle for the form
Default: "Untitled form"

Used by: POST /rest/beta/workflows/{workflow_id}/forms/

FormFile

Used in form creation and update

FieldTypeDescription
file_typeFileTyperequiredType of the file
idstringrequiredId of the file
namestringrequiredName of the file
providerProviderrequiredService origin of the file
tab_idintegerrequiredTab id of the file
tab_namestringrequiredTab name of the file

FormFileModel

For displaying data

FieldTypeDescription
file_typeFileTypenullableType of the file
idstringrequiredId of the file
namestringnullableName of the file
providerProvidernullableService origin of the file
tab_idintegernullableTab id of the file
tab_namestringnullableTab name of the file

FormModel

For displaying data

FieldTypeDescription
confirmation_messagestringnullableConfirmation message
descriptionstringnullableForm description
idstringoptionalForm identification
include_headerbooleannullableTrue if include header
Default: false
limit_responsesbooleannullableTrue if should limit responses
Default: false
require_authbooleannullableTrue if it requires authentication
Default: false
sourceFormFileModelnullableForm fields source file
targetFormFileModelnullableResponse destination file
titlestringoptionalTitle for the form
Default: "Untitled form"

Used by: POST /rest/beta/workflows/{workflow_id}/forms/, GET /rest/beta/workflows/{workflow_id}/forms/{form_id}, PATCH /rest/beta/workflows/{workflow_id}/forms/{form_id}

FormPatch

Form update data

FieldTypeDescription
confirmation_messagestringnullableConfirmation message
descriptionstringnullableForm description
limit_responsesbooleannullableLimit each respondent to one response. Must be sent together with require_auth — identifying the respondent is how the limit is enforced.
require_authbooleannullableRequire respondents to authenticate. SG-14657 — must be sent together with limit_responses; sending one alone is a 422. Setting limit_responses true forces this on.
sourceFormFilenullableForm fields source file
sync_fields_after_submissionbooleannullableTrue it should sync fields after submission
targetFormFilenullableResponse destination file
titlestringnullableTitle for the form

Used by: PATCH /rest/beta/workflows/{workflow_id}/forms/{form_id}

HTTPValidationError

FieldTypeDescription
detailarray of ValidationErroroptional

Used by: GET /rest/beta/workflows/, POST /rest/beta/workflows/, POST /rest/beta/workflows/run/{id}, GET /rest/beta/workflows/{id}, PATCH /rest/beta/workflows/{id}, DELETE /rest/beta/workflows/{id}, GET /rest/beta/workflows/{id}/collaborators, POST /rest/beta/workflows/{id}/collaborators, DELETE /rest/beta/workflows/{id}/collaborators, PATCH /rest/beta/workflows/{id}/collaborators/{email}, DELETE /rest/beta/workflows/{id}/collaborators/{email}, GET /rest/beta/workflows/{id}/destinations, GET /rest/beta/workflows/{id}/files, GET /rest/beta/workflows/{id}/general-access, PUT /rest/beta/workflows/{id}/general-access, DELETE /rest/beta/workflows/{id}/general-access, POST /rest/beta/workflows/{id}/leave, POST /rest/beta/workflows/{id}/request-access, GET /rest/beta/workflows/{id}/run, POST /rest/beta/workflows/{id}/run, GET /rest/beta/workflows/{id}/sources, GET /rest/beta/automations/, POST /rest/beta/automations/run/{id}, GET /rest/beta/automations/{id}, DELETE /rest/beta/automations/{id}, GET /rest/beta/automations/{id}/destinations, GET /rest/beta/automations/{id}/files, GET /rest/beta/automations/{id}/run, POST /rest/beta/automations/{id}/run, GET /rest/beta/automations/{id}/sources, GET /rest/beta/workflows/{id}/trigger, DELETE /rest/beta/workflows/{id}/trigger, GET /rest/beta/workflows/{id}/dashboard, DELETE /rest/beta/workflows/{id}/dashboard/elements/{element_id}, GET /rest/beta/workflows/{id}/dashboard/elements/{element_id}/data, PUT /rest/beta/workflows/{id}/dashboard/publish, GET /rest/beta/workflows/{workflow_id}/forms/, POST /rest/beta/workflows/{workflow_id}/forms/, GET /rest/beta/workflows/{workflow_id}/forms/{form_id}, PATCH /rest/beta/workflows/{workflow_id}/forms/{form_id}, DELETE /rest/beta/workflows/{workflow_id}/forms/{form_id}, GET /rest/beta/workflows/{workflow_id}/forms/{form_id}/responses, HEAD /rest/beta/workflows/{workflow_id}/forms/{form_id}/responses, GET /rest/beta/automations/{automation_id}/webhook, GET /rest/beta/workflows/{workflow_id}/webhooks, GET /rest/beta/api-destination/{public_id}, HEAD /rest/beta/api-destination/{public_id}, GET /rest/beta/integrations/{provider}/options, GET /rest/beta/outlook/messages, POST /rest/beta/outlook/messages/batch, GET /rest/beta/outlook/messages/{message_id}, GET /rest/beta/outlook/messages/{message_id}/attachments/{attachment_id}, POST /rest/beta/outlook/send, POST /rest/beta/gmail/send, GET /rest/beta/files/{provider}, GET /rest/beta/files/{provider}/roots, GET /rest/beta/files/{provider}/search, GET /rest/beta/files/{provider}/{file_id}, GET /rest/beta/bigquery/projects, GET /rest/beta/bigquery/projects/{project}/datasets, GET /rest/beta/bigquery/projects/{project}/datasets/{dataset}/tables, GET /rest/beta/bigquery/projects/{project}/datasets/{dataset}/tables/{table}, POST /rest/beta/bigquery/projects/{project}/validate-query, POST /rest/auth/refresh, POST /rest/auth/token

PaginatedResponse_FormModel_

FieldTypeDescription
pageintegernullablePage number
Default: 1
per_pageintegernullableNumber of items per page
Default: 50
resultsarray of FormModeloptionalList of results
totalintegernullableTotal number of pages
Default: 0

Used by: GET /rest/beta/workflows/{workflow_id}/forms/

SuccessResponse

The legacy success envelope, returned by the pre-existing CRUD routes.

It always carries HTTP 200; the outcome is in code/type, not the status line. Newer endpoints return the resource directly instead.

FieldTypeDescription
codeintegeroptionalResult code. 1 means the operation succeeded.
Default: 1
messagestringoptionalHuman-readable confirmation of what happened.
Default: "OK"
typestringoptionalKind of result — success for this envelope.
Default: "success"

Used by: POST /rest/beta/workflows/run/{id}, DELETE /rest/beta/workflows/{id}, POST /rest/beta/workflows/{id}/run, POST /rest/beta/automations/run/{id}, DELETE /rest/beta/automations/{id}, POST /rest/beta/automations/{id}/run, DELETE /rest/beta/workflows/{workflow_id}/forms/{form_id}

ValidationError

FieldTypeDescription
locarray of string or integerrequired
msgstringrequired
typestringrequired