# Google Forms (/integrations/google_forms)





{/* MANUAL-CONTENT-START:intro */}

[Google Forms](https://www.google.com/forms/about/) collects structured responses. Use this integration to read and update forms, retrieve responses, and manage watches. Its triggers can start workflows when forms receive responses or change.

{/* MANUAL-CONTENT-END */}

## OAuth scopes [#oauth-scopes]

Sim requests these scopes when someone connects a Google Forms account. For a self-hosted deployment, register your own app with the provider using the settings below. See [Integrations and OAuth](/platform/self-hosting/integrations-oauth) for setup.

| Setting | Value |
| - | - |
| Redirect URI | `<NEXT_PUBLIC_APP_URL>/api/auth/oauth2/callback/google-forms` |
| Environment variables | `GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET` |

| Scope | Description |
| - | - |
| `https://www.googleapis.com/auth/userinfo.email` | View email address |
| `https://www.googleapis.com/auth/userinfo.profile` | View basic profile info |
| `https://www.googleapis.com/auth/drive` | View, edit, create, and delete all Google Drive files |
| `https://www.googleapis.com/auth/forms.body` | View and manage Google Forms |
| `https://www.googleapis.com/auth/forms.responses.readonly` | View responses to Google Forms |

## Use the block [#usage-instructions]

Read form structure, get responses, create forms, update content, and manage notification watches.

## Actions [#actions]

### Google Forms: Get Responses [#google-forms-get-responses]

Retrieve a single response or list responses from a Google Form

<ReferenceDetails>
  #### Input [#input]

  | Parameter | Type | Required | Description |
  | - | - | - | - |
  | `formId` | string | Yes | Google Forms form ID |
  | `responseId` | string | No | Response ID - if provided, returns this specific response |
  | `pageSize` | number | No | Maximum number of responses to return (service may return fewer). Defaults to 5000. |
  | `pageToken` | string | No | Page token from a previous list response to fetch the next page of responses |
  | `filter` | string | No | Filter responses, e.g. "timestamp > 2024-01-01T00:00:00Z" (RFC3339 UTC). Only timestamp filters are supported. |

  #### Output [#output]

  | Parameter | Type | Description |
  | - | - | - |
  | `responses` | array | Array of form responses (when no responseId provided) |
  | ↳ `responseId` | string | Unique response ID |
  | ↳ `createTime` | string | When the response was created |
  | ↳ `lastSubmittedTime` | string | When the response was last submitted |
  | ↳ `answers` | json | Map of question IDs to answer values |
  | `nextPageToken` | string | Token to fetch the next page of responses (null when no more pages) |
  | `response` | object | Single form response (when responseId is provided) |
  | ↳ `responseId` | string | Unique response ID |
  | ↳ `createTime` | string | When the response was created |
  | ↳ `lastSubmittedTime` | string | When the response was last submitted |
  | ↳ `answers` | json | Map of question IDs to answer values |
  | `raw` | json | Raw API response data |
</ReferenceDetails>

### Google Forms: Get Form [#google-forms-get-form]

Retrieve a form structure including its items, settings, and metadata

<ReferenceDetails>
  #### Input [#input-1]

  | Parameter | Type | Required | Description |
  | - | - | - | - |
  | `formId` | string | Yes | Google Forms form ID to retrieve |

  #### Output [#output-1]

  | Parameter | Type | Description |
  | - | - | - |
  | `formId` | string | The form ID |
  | `title` | string | The form title visible to responders |
  | `description` | string | The form description |
  | `documentTitle` | string | The document title visible in Drive |
  | `responderUri` | string | The URI to share with responders |
  | `linkedSheetId` | string | The ID of the linked Google Sheet |
  | `revisionId` | string | The revision ID of the form |
  | `items` | array | The form items (questions, sections, etc.) |
  | ↳ `itemId` | string | Item ID |
  | ↳ `title` | string | Item title |
  | ↳ `description` | string | Item description |
  | `settings` | json | Form settings |
  | `publishSettings` | json | Form publish settings |
</ReferenceDetails>

### Google Forms: Create Form [#google-forms-create-form]

Create a new Google Form with a title

<ReferenceDetails>
  #### Input [#input-2]

  | Parameter | Type | Required | Description |
  | - | - | - | - |
  | `title` | string | Yes | The title of the form visible to responders |
  | `documentTitle` | string | No | The document title visible in Drive (defaults to form title) |
  | `unpublished` | boolean | No | If true, create an unpublished form that does not accept responses |

  #### Output [#output-2]

  | Parameter | Type | Description |
  | - | - | - |
  | `formId` | string | The ID of the created form |
  | `title` | string | The form title |
  | `documentTitle` | string | The document title in Drive |
  | `responderUri` | string | The URI to share with responders |
  | `revisionId` | string | The revision ID of the form |
</ReferenceDetails>

### Google Forms: Batch Update [#google-forms-batch-update]

Apply multiple updates to a form (add items, update info, change settings, etc.)

<ReferenceDetails>
  #### Input [#input-3]

  | Parameter | Type | Required | Description |
  | - | - | - | - |
  | `formId` | string | Yes | Google Forms form ID |
  | `requests` | json | Yes | Array of update requests (updateFormInfo, updateSettings, createItem, updateItem, moveItem, deleteItem) |
  | `includeFormInResponse` | boolean | No | Whether to return the updated form in the response |

  #### Output [#output-3]

  | Parameter | Type | Description |
  | - | - | - |
  | `replies` | array | The replies from each update request |
  | `writeControl` | object | Write control information with revision IDs |
  | ↳ `requiredRevisionId` | string | Required revision ID for conflict detection |
  | ↳ `targetRevisionId` | string | Target revision ID |
  | `form` | object | The updated form (if includeFormInResponse was true) |
  | ↳ `formId` | string | The form ID |
  | ↳ `info` | object | Form info containing title and description |
  | ↳ `title` | string | The form title visible to responders |
  | ↳ `description` | string | The form description |
  | ↳ `documentTitle` | string | The document title visible in Drive |
  | ↳ `settings` | object | Form settings |
  | ↳ `quizSettings` | object | Quiz settings |
  | ↳ `isQuiz` | boolean | Whether the form is a quiz |
  | ↳ `emailCollectionType` | string | Email collection type |
  | ↳ `items` | array | The form items (questions, sections, etc.) |
  | ↳ `itemId` | string | Item ID |
  | ↳ `title` | string | Item title |
  | ↳ `description` | string | Item description |
  | ↳ `questionItem` | json | Question item configuration |
  | ↳ `questionGroupItem` | json | Question group configuration |
  | ↳ `pageBreakItem` | json | Page break configuration |
  | ↳ `textItem` | json | Text item configuration |
  | ↳ `imageItem` | json | Image item configuration |
  | ↳ `videoItem` | json | Video item configuration |
  | ↳ `revisionId` | string | The revision ID of the form |
  | ↳ `responderUri` | string | The URI to share with responders |
  | ↳ `linkedSheetId` | string | The ID of the linked Google Sheet |
  | ↳ `publishSettings` | object | Form publish settings |
  | ↳ `publishState` | object | Current publish state |
  | ↳ `isPublished` | boolean | Whether the form is published |
  | ↳ `isAcceptingResponses` | boolean | Whether the form is accepting responses |
</ReferenceDetails>

### Google Forms: Set Publish Settings [#google-forms-set-publish-settings]

Update the publish settings of a form (publish/unpublish, accept responses)

<ReferenceDetails>
  #### Input [#input-4]

  | Parameter | Type | Required | Description |
  | - | - | - | - |
  | `formId` | string | Yes | Google Forms form ID |
  | `isPublished` | boolean | Yes | Whether the form is published and visible to others |
  | `isAcceptingResponses` | boolean | No | Whether the form accepts responses (forced to false if isPublished is false) |

  #### Output [#output-4]

  | Parameter | Type | Description |
  | - | - | - |
  | `formId` | string | The form ID |
  | `publishSettings` | json | The updated publish settings |
  | ↳ `publishState` | object | The publish state |
  | ↳ `isPublished` | boolean | Whether the form is published |
  | ↳ `isAcceptingResponses` | boolean | Whether the form accepts responses |
</ReferenceDetails>

### Google Forms: Create Watch [#google-forms-create-watch]

Create a notification watch for form changes (schema changes or new responses)

<ReferenceDetails>
  #### Input [#input-5]

  | Parameter | Type | Required | Description |
  | - | - | - | - |
  | `formId` | string | Yes | Google Forms form ID to watch |
  | `eventType` | string | Yes | Event type to watch: SCHEMA (form changes) or RESPONSES (new submissions) |
  | `topicName` | string | Yes | The Cloud Pub/Sub topic name (format: projects/\{project}/topics/\{topic}) |
  | `watchId` | string | No | Custom watch ID (4-63 chars, lowercase letters, numbers, hyphens) |

  #### Output [#output-5]

  | Parameter | Type | Description |
  | - | - | - |
  | `id` | string | The watch ID |
  | `eventType` | string | The event type being watched |
  | `topicName` | string | The Cloud Pub/Sub topic |
  | `createTime` | string | When the watch was created |
  | `expireTime` | string | When the watch expires (7 days after creation) |
  | `state` | string | The watch state (ACTIVE, SUSPENDED) |
</ReferenceDetails>

### Google Forms: List Watches [#google-forms-list-watches]

List all notification watches for a form

<ReferenceDetails>
  #### Input [#input-6]

  | Parameter | Type | Required | Description |
  | - | - | - | - |
  | `formId` | string | Yes | Google Forms form ID |

  #### Output [#output-6]

  | Parameter | Type | Description |
  | - | - | - |
  | `watches` | array | List of watches for the form |
  | ↳ `id` | string | Watch ID |
  | ↳ `eventType` | string | Event type (SCHEMA or RESPONSES) |
  | ↳ `createTime` | string | When the watch was created |
  | ↳ `expireTime` | string | When the watch expires |
  | ↳ `state` | string | Watch state |
</ReferenceDetails>

### Google Forms: Delete Watch [#google-forms-delete-watch]

Delete a notification watch from a form

<ReferenceDetails>
  #### Input [#input-7]

  | Parameter | Type | Required | Description |
  | - | - | - | - |
  | `formId` | string | Yes | Google Forms form ID |
  | `watchId` | string | Yes | Watch ID to delete |

  #### Output [#output-7]

  | Parameter | Type | Description |
  | - | - | - |
  | `deleted` | boolean | Whether the watch was successfully deleted |
</ReferenceDetails>

### Google Forms: Renew Watch [#google-forms-renew-watch]

Renew a notification watch for another 7 days

<ReferenceDetails>
  #### Input [#input-8]

  | Parameter | Type | Required | Description |
  | - | - | - | - |
  | `formId` | string | Yes | Google Forms form ID |
  | `watchId` | string | Yes | Watch ID to renew |

  #### Output [#output-8]

  | Parameter | Type | Description |
  | - | - | - |
  | `id` | string | The watch ID |
  | `eventType` | string | The event type being watched |
  | `expireTime` | string | The new expiration time |
  | `state` | string | The watch state |
</ReferenceDetails>

## Triggers [#triggers]

A trigger starts a workflow when a supported event occurs in this service.

### Google Forms Webhook [#google-forms-webhook]

Trigger workflow from Google Form submissions (via Apps Script forwarder)

#### Configuration [#configuration]

| Parameter | Type | Required | Description |
| - | - | - | - |
| `token` | string | Yes | We validate requests using this secret. Send it as Authorization: Bearer \<token> or a custom header. |
| `secretHeaderName` | string | No | If set, the webhook will validate this header equals your Shared Secret instead of Authorization. |
| `triggerFormId` | string | No | Optional, for clarity and matching in workflows. Not required for webhook to work. |
| `includeRawPayload` | boolean | No | Include the original payload from Apps Script in the workflow input. |
| `setupScript` | string | No | Copy this code and paste it into your Google Forms Apps Script editor |

#### Output [#output-9]

| Parameter | Type | Description |
| - | - | - |
| `responseId` | string | Unique response identifier (if available) |
| `createTime` | string | Response creation timestamp |
| `lastSubmittedTime` | string | Last submitted timestamp |
| `formId` | string | Google Form ID |
| `answers` | object | Normalized map of question -> answer |
| `raw` | object | Original payload (when enabled) |