Types overview

Answer

The submitted answer for a question.
Fields
fileUploadAnswers

object (FileUploadAnswers)

Output only. The answers to a file upload question.

grade

object (Grade)

Output only. The grade for the answer if the form was a quiz.

questionId

string

Output only. The question's ID. See also Question.question_id.

textAnswers

object (TextAnswers)

Output only. The specific answers as text.

BatchUpdateFormRequest

A batch of updates to perform on a form. All the specified updates are made or none of them are.
Fields
includeFormInResponse

boolean

Whether to return an updated version of the model in the response.

requests[]

object (Request)

Required. The update requests of this batch.

writeControl

object (WriteControl)

Provides control over how write requests are executed.

BatchUpdateFormResponse

Response to a BatchUpdateFormRequest.
Fields
form

object (Form)

Based on the bool request field include_form_in_response, a form with all applied mutations/updates is returned or not. This may be later than the revision ID created by these changes.

replies[]

object (Response)

The reply of the updates. This maps 1:1 with the update requests, although replies to some requests may be empty.

writeControl

object (WriteControl)

The updated write control after applying the request.

ChoiceQuestion

A radio/checkbox/dropdown question.
Fields
options[]

object (Option)

Required. List of options that a respondent must choose from.

shuffle

boolean

Whether the options should be displayed in random order for different instances of the quiz. This is often used to prevent cheating by respondents who might be looking at another respondent's screen, or to address bias in a survey that might be introduced by always putting the same options first or last.

type

enum

Required. The type of choice question.

Enum type. Can be one of the following:
CHOICE_TYPE_UNSPECIFIED Default value. Unused.
RADIO Radio buttons: All choices are shown to the user, who can only pick one of them.
CHECKBOX Checkboxes: All choices are shown to the user, who can pick any number of them.
DROP_DOWN Drop-down menu: The choices are only shown to the user on demand, otherwise only the current choice is shown. Only one option can be chosen.

CloudPubsubTopic

A Pub/Sub topic.
Fields
topicName

string

Required. A fully qualified Pub/Sub topic name to publish the events to. This topic must be owned by the calling project and already exist in Pub/Sub.

CorrectAnswer

A single correct answer for a question. For multiple-valued (CHECKBOX) questions, several CorrectAnswers may be needed to represent a single correct response option.
Fields
value

string

Required. The correct answer value. See the documentation for TextAnswer.value for details on how various value types are formatted.

CorrectAnswers

The answer key for a question.
Fields
answers[]

object (CorrectAnswer)

A list of correct answers. A quiz response can be automatically graded based on these answers. For single-valued questions, a response is marked correct if it matches any value in this list (in other words, multiple correct answers are possible). For multiple-valued (CHECKBOX) questions, a response is marked correct if it contains exactly the values in this list.

CreateItemRequest

Create an item in a form.
Fields
item

object (Item)

Required. The item to create.

location

object (Location)

Required. Where to place the new item.

CreateItemResponse

The result of creating an item.
Fields
itemId

string

The ID of the created item.

questionId[]

string

The ID of the question created as part of this item, for a question group it lists IDs of all the questions created for this item.

CreateWatchRequest

Create a new watch.
Fields
watch

object (Watch)

Required. The watch object. No ID should be set on this object; use watch_id instead.

watchId

string

The ID to use for the watch. If specified, the ID must not already be in use. If not specified, an ID is generated. This value should be 4-63 characters, and valid characters are /a-z-/.

DateQuestion

A date question. Date questions default to just month + day.
Fields
includeTime

boolean

Whether to include the time as part of the question.

includeYear

boolean

Whether to include the year as part of the question.

DeleteItemRequest

Delete an item in a form.
Fields
location

object (Location)

Required. The location of the item to delete.

ExtraMaterial

Supplementary material to the feedback.
Fields
link

object (TextLink)

Text feedback.

video

object (VideoLink)

Video feedback.

Feedback

Feedback for a respondent about their response to a question.
Fields
material[]

object (ExtraMaterial)

Additional information provided as part of the feedback, often used to point the respondent to more reading and resources.

text

string

Required. The main text of the feedback.

FileUploadAnswer

Info for a single file submitted to a file upload question.
Fields
fileId

string

Output only. The ID of the Google Drive file.

fileName

string

Output only. The file name, as stored in Google Drive on upload.

mimeType

string

Output only. The MIME type of the file, as stored in Google Drive on upload.

FileUploadAnswers

All submitted files for a FileUpload question.
Fields
answers[]

object (FileUploadAnswer)

Output only. All submitted files for a FileUpload question.

FileUploadQuestion

A file upload question. The API currently does not support creating file upload questions.
Fields
folderId

string

Required. The ID of the Drive folder where uploaded files are stored.

maxFileSize

string (int64 format)

Maximum number of bytes allowed for any single file uploaded to this question.

maxFiles

integer (int32 format)

Maximum number of files that can be uploaded for this question in a single response.

types[]

string

File types accepted by this question.

Form

A Google Forms document. A form is created in Drive, and deleting a form or changing its access protections is done via the Drive API.
Fields
formId

string

Output only. The form ID.

info

object (Info)

Required. The title and description of the form.

items[]

object (Item)

Required. A list of the form's items, which can include section headers, questions, embedded media, etc.

linkedSheetId

string

Output only. The ID of the linked Google Sheet which is accumulating responses from this Form (if such a Sheet exists).

responderUri

string

Output only. The form URI to share with responders. This opens a page that allows the user to submit responses but not edit the questions.

revisionId

string

Output only. The revision ID of the form. Used in the WriteControl in update requests to identify the revision on which the changes are based. The format of the revision ID may change over time, so it should be treated opaquely. A returned revision ID is only guaranteed to be valid for 24 hours after it has been returned and cannot be shared across users. If the revision ID is unchanged between calls, then the form has not changed. Conversely, a changed ID (for the same form and user) usually means the form has been updated; however, a changed ID can also be due to internal factors such as ID format changes.

settings

object (FormSettings)

The form's settings. This must be updated with UpdateSettingsRequest; it is ignored during forms.create and UpdateFormInfoRequest.

FormResponse

A form response.
Fields
answers

map (key: string, value: object (Answer))

Output only. The actual answers to the questions, keyed by question_id.

createTime

string (Timestamp format)

Output only. Timestamp for the first time the response was submitted.

formId

string

Output only. The form ID.

lastSubmittedTime

string (Timestamp format)

Output only. Timestamp for the most recent time the response was submitted. Does not track changes to grades.

respondentEmail

string

Output only. The email address (if collected) for the respondent.

responseId

string

Output only. The response ID.

totalScore

number (double format)

Output only. The total number of points the respondent received for their submission Only set if the form was a quiz and the response was graded. This includes points automatically awarded via autograding adjusted by any manual corrections entered by the form owner.

FormSettings

A form's settings.
Fields
quizSettings

object (QuizSettings)

Settings related to quiz forms and grading.

Grade

Grade information associated with a respondent's answer to a question.
Fields
correct

boolean

Output only. Whether the question was answered correctly or not. A zero-point score is not enough to infer incorrectness, since a correctly answered question could be worth zero points.

feedback

object (Feedback)

Output only. Additional feedback given for an answer.

score

number (double format)

Output only. The numeric score awarded for the answer.

Grading

Grading for a single question
Fields
correctAnswers

object (CorrectAnswers)

Required. The answer key for the question. Responses are automatically graded based on this field.

generalFeedback

object (Feedback)

The feedback displayed for all answers. This is commonly used for short answer questions when a quiz owner wants to quickly give respondents some sense of whether they answered the question correctly before they've had a chance to officially grade the response. General feedback cannot be set for automatically graded multiple choice questions.

pointValue

integer (int32 format)

Required. The maximum number of points a respondent can automatically get for a correct answer. This must not be negative.

whenRight

object (Feedback)

The feedback displayed for correct responses. This feedback can only be set for multiple choice questions that have correct answers provided.

whenWrong

object (Feedback)

The feedback displayed for incorrect responses. This feedback can only be set for multiple choice questions that have correct answers provided.

Grid

A grid of choices (radio or check boxes) with each row constituting a separate question. Each row has the same choices, which are shown as the columns.
Fields
columns

object (ChoiceQuestion)

Required. The choices shared by each question in the grid. In other words, the values of the columns. Only CHECK_BOX and RADIO choices are allowed.

shuffleQuestions

boolean

If true, the questions are randomly ordered. In other words, the rows appear in a different order for every respondent.

Image

Data representing an image.
Fields
altText

string

A description of the image that is shown on hover and read by screenreaders.

contentUri

string

Output only. A URI from which you can download the image; this is valid only for a limited time.

properties

object (MediaProperties)

Properties of an image.

sourceUri

string

Input only. The source URI is the URI used to insert the image. The source URI can be empty when fetched.

ImageItem

An item containing an image.
Fields
image

object (Image)

Required. The image displayed in the item.

Info

The general information for a form.
Fields
description

string

The description of the form.

documentTitle

string

Output only. The title of the document which is visible in Drive. If Info.title is empty, document_title may appear in its place in the Google Forms UI and be visible to responders. document_title can be set on create, but cannot be modified by a batchUpdate request. Please use the Google Drive API if you need to programmatically update document_title.

title

string

Required. The title of the form which is visible to responders.

Item

A single item of the form. kind defines which kind of item it is.
Fields
description

string

The description of the item.

imageItem

object (ImageItem)

Displays an image on the page.

itemId

string

The item ID. On creation, it can be provided but the ID must not be already used in the form. If not provided, a new ID is assigned.

pageBreakItem

object (PageBreakItem)

Starts a new page with a title.

questionGroupItem

object (QuestionGroupItem)

Poses one or more questions to the user with a single major prompt.

questionItem

object (QuestionItem)

Poses a question to the user.

textItem

object (TextItem)

Displays a title and description on the page.

title

string

The title of the item.

videoItem

object (VideoItem)

Displays a video on the page.

ListFormResponsesResponse

Response to a ListFormResponsesRequest.
Fields
nextPageToken

string

If set, there are more responses. To get the next page of responses, provide this as page_token in a future request.

responses[]

object (FormResponse)

The returned responses.

ListWatchesResponse

The response of a ListWatchesRequest.
Fields
watches[]

object (Watch)

The returned watches.

Location

A specific location in a form.
Fields
index

integer (int32 format)

The index of an item in the form. This must be in the range [0..N), where N is the number of items in the form.

MediaProperties

Properties of the media.
Fields
alignment

enum

Position of the media.

Enum type. Can be one of the following:
ALIGNMENT_UNSPECIFIED Default value. Unused.
LEFT Left align.
RIGHT Right align.
CENTER Center.
width

integer (int32 format)

The width of the media in pixels. When the media is displayed, it is scaled to the smaller of this value or the width of the displayed form. The original aspect ratio of the media is preserved. If a width is not specified when the media is added to the form, it is set to the width of the media source. Width must be between 0 and 740, inclusive. Setting width to 0 or unspecified is only permitted when updating the media source.

MoveItemRequest

Move an item in a form.
Fields
newLocation

object (Location)

Required. The new location for the item.

originalLocation

object (Location)

Required. The location of the item to move.

Option

An option for a Choice question.
Fields
goToAction

enum

Section navigation type.

Enum type. Can be one of the following:
GO_TO_ACTION_UNSPECIFIED Default value. Unused.
NEXT_SECTION Go to the next section.
RESTART_FORM Go back to the beginning of the form.
SUBMIT_FORM Submit form immediately.
goToSectionId

string

Item ID of section header to go to.

image

object (Image)

Display image as an option.

isOther

boolean

Whether the option is "other". Currently only applies to RADIO and CHECKBOX choice types, but is not allowed in a QuestionGroupItem.

value

string

Required. The choice as presented to the user.

Question

Any question. The specific type of question is known by its kind.
Fields
choiceQuestion

object (ChoiceQuestion)

A respondent can choose from a pre-defined set of options.

dateQuestion

object (DateQuestion)

A respondent can enter a date.

fileUploadQuestion

object (FileUploadQuestion)

A respondent can upload one or more files.

grading

object (Grading)

Grading setup for the question.

questionId

string

Read only. The question ID. On creation, it can be provided but the ID must not be already used in the form. If not provided, a new ID is assigned.

required

boolean

Whether the question must be answered in order for a respondent to submit their response.

rowQuestion

object (RowQuestion)

A row of a QuestionGroupItem.

scaleQuestion

object (ScaleQuestion)

A respondent can choose a number from a range.

textQuestion

object (TextQuestion)

A respondent can enter a free text response.

timeQuestion

object (TimeQuestion)

A respondent can enter a time.

QuestionGroupItem

Defines a question that comprises multiple questions grouped together.
Fields
grid

object (Grid)

The question group is a grid with rows of multiple choice questions that share the same options. When grid is set, all questions in the group must be of kind row.

image

object (Image)

The image displayed within the question group above the specific questions.

questions[]

object (Question)

Required. A list of questions that belong in this question group. A question must only belong to one group. The kind of the group may affect what types of questions are allowed.

QuestionItem

A form item containing a single question.
Fields
image

object (Image)

The image displayed within the question.

question

object (Question)

Required. The displayed question.

QuizSettings

Settings related to quiz forms and grading. These must be updated with the UpdateSettingsRequest.
Fields
isQuiz

boolean

Whether this form is a quiz or not. When true, responses are graded based on question Grading. Upon setting to false, all question Grading is deleted.

Request

The kinds of update requests that can be made.
Fields
createItem

object (CreateItemRequest)

Create a new item.

deleteItem

object (DeleteItemRequest)

Delete an item.

moveItem

object (MoveItemRequest)

Move an item to a specified location.

updateFormInfo

object (UpdateFormInfoRequest)

Update Form's Info.

updateItem

object (UpdateItemRequest)

Update an item.

updateSettings

object (UpdateSettingsRequest)

Updates the Form's settings.

Response

A single response from an update.
Fields
createItem

object (CreateItemResponse)

The result of creating an item.

RowQuestion

Configuration for a question that is part of a question group.
Fields
title

string

Required. The title for the single row in the QuestionGroupItem.

ScaleQuestion

A scale question. The user has a range of numeric values to choose from.
Fields
high

integer (int32 format)

Required. The highest possible value for the scale.

highLabel

string

The label to display describing the highest point on the scale.

low

integer (int32 format)

Required. The lowest possible value for the scale.

lowLabel

string

The label to display describing the lowest point on the scale.

TextAnswer

An answer to a question represented as text.
Fields
value

string

Output only. The answer value. Formatting used for different kinds of question: * ChoiceQuestion * RADIO or DROP_DOWN: A single string corresponding to the option that was selected. * CHECKBOX: Multiple strings corresponding to each option that was selected. * TextQuestion: The text that the user entered. * ScaleQuestion: A string containing the number that was selected. * DateQuestion * Without time or year: MM-DD e.g. "05-19" * With year: YYYY-MM-DD e.g. "1986-05-19" * With time: MM-DD HH:MM e.g. "05-19 14:51" * With year and time: YYYY-MM-DD HH:MM e.g. "1986-05-19 14:51" * TimeQuestion: String with time or duration in HH:MM format e.g. "14:51" * RowQuestion within QuestionGroupItem: The answer for each row of a QuestionGroupItem is represented as a separate Answer. Each will contain one string for RADIO-type choices or multiple strings for CHECKBOX choices.

TextAnswers

A question's answers as text.
Fields
answers[]

object (TextAnswer)

Output only. Answers to a question. For multiple-value ChoiceQuestions, each answer is a separate value.

TextQuestion

A text-based question.
Fields
paragraph

boolean

Whether the question is a paragraph question or not. If not, the question is a short text question.

TimeQuestion

A time question.
Fields
duration

boolean

true if the question is about an elapsed time. Otherwise it is about a time of day.

UpdateFormInfoRequest

Update Form's Info.
Fields
info

object (Info)

The info to update.

updateMask

string (FieldMask format)

Required. Only values named in this mask are changed. At least one field must be specified. The root info is implied and should not be specified. A single "*" can be used as short-hand for updating every field.

UpdateItemRequest

Update an item in a form.
Fields
item

object (Item)

Required. New values for the item. Note that item and question IDs are used if they are provided (and are in the field mask). If an ID is blank (and in the field mask) a new ID is generated. This means you can modify an item by getting the form via forms.get, modifying your local copy of that item to be how you want it, and using UpdateItemRequest to write it back, with the IDs being the same (or not in the field mask).

location

object (Location)

Required. The location identifying the item to update.

updateMask

string (FieldMask format)

Required. Only values named in this mask are changed.

UpdateSettingsRequest

Update Form's FormSettings.
Fields
settings

object (FormSettings)

Required. The settings to update with.

updateMask

string (FieldMask format)

Required. Only values named in this mask are changed. At least one field must be specified. The root settings is implied and should not be specified. A single "*" can be used as short-hand for updating every field.

Video

Data representing a video.
Fields
properties

object (MediaProperties)

Properties of a video.

youtubeUri

string

Required. A YouTube URI.

VideoItem

An item containing a video.
Fields
caption

string

The text displayed below the video.

video

object (Video)

Required. The video displayed in the item.

Watch

A watch for events for a form. When the designated event happens, a notification will be published to the specified target. The notification's attributes will include a formId key that has the ID of the watched form and an eventType key that has the string of the type. Messages are sent with at-least-once delivery and are only dropped in extraordinary circumstances. Typically all notifications should be reliably delivered within a few seconds; however, in some situations notifications may be delayed. A watch expires seven days after it is created unless it is renewed with watches.renew
Fields
createTime

string (Timestamp format)

Output only. Timestamp of when this was created.

errorType

enum

Output only. The most recent error type for an attempted delivery. To begin watching the form again a call can be made to watches.renew which also clears this error information.

Enum type. Can be one of the following:
ERROR_TYPE_UNSPECIFIED Unspecified error type.
PROJECT_NOT_AUTHORIZED The cloud project does not have access to the form being watched. This occurs if the user has revoked the authorization for your project to access their form(s). Watches with this error will not be retried. To attempt to begin watching the form again a call can be made to watches.renew
NO_USER_ACCESS The user that granted access no longer has access to the form being watched. Watches with this error will not be retried. To attempt to begin watching the form again a call can be made to watches.renew
OTHER_ERRORS Another type of error has occurred. Whether notifications will continue depends on the watch state.
eventType

enum

Required. Which event type to watch for.

Enum type. Can be one of the following:
EVENT_TYPE_UNSPECIFIED Unspecified event type. This value should not be used.
SCHEMA The schema event type. A watch with this event type will be notified about changes to form content and settings.
RESPONSES The responses event type. A watch with this event type will be notified when form responses are submitted.
expireTime

string (Timestamp format)

Output only. Timestamp for when this will expire. Each watches.renew call resets this to seven days in the future.

id

string

Output only. The ID of this watch. See notes on CreateWatchRequest.watch_id.

state

enum

Output only. The current state of the watch. Additional details about suspended watches can be found by checking the error_type.

Enum type. Can be one of the following:
STATE_UNSPECIFIED Unspecified state.
ACTIVE Watch is active.
SUSPENDED The watch is suspended due to an error that may be resolved. The watch will continue to exist until it expires. To attempt to reactivate the watch a call can be made to watches.renew
target

object (WatchTarget)

Required. Where to send the notification.

WatchTarget

The target for notification delivery.
Fields
topic

object (CloudPubsubTopic)

A Pub/Sub topic. To receive notifications, the topic must grant publish privileges to the Forms service account serviceAccount:forms-notifications@system.gserviceaccount.com. Only the project that owns a topic may create a watch with it. Pub/Sub delivery guarantees should be considered.

WriteControl

Provides control over how write requests are executed.
Fields
requiredRevisionId

string

The revision ID of the form that the write request is applied to. If this is not the latest revision of the form, the request is not processed and returns a 400 bad request error.

targetRevisionId

string

The target revision ID of the form that the write request is applied to. If changes have occurred after this revision, the changes in this update request are transformed against those changes. This results in a new revision of the form that incorporates both the changes in the request and the intervening changes, with the server resolving conflicting changes. The target revision ID may only be used to write to recent versions of a form. If the target revision is too far behind the latest revision, the request is not processed and returns a 400 (Bad Request Error). The request may be retried after reading the latest version of the form. In most cases a target revision ID remains valid for several minutes after it is read, but for frequently-edited forms this window may be shorter.