REST Resource: forms

Resource: 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.

JSON representation 
{
  "formId": string,
  "info": {
    object (Info)
  },
  "settings": {
    object (FormSettings)
  },
  "items": [
    {
      object (Item)
    }
  ],
  "revisionId": string,
  "responderUri": string,
  "linkedSheetId": string
}
Fields
formId

string

Output only. The form ID.
info

object (Info)

Required. The title and description of the form.
settings

object (FormSettings)

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

object (Item)

Required. A list of the form's items, which can include section headers, questions, embedded media, etc.
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.
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.
linkedSheetId

string

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

Info

The general information for a form.

JSON representation 
{
  "title": string,
  "documentTitle": string,
  "description": string
}
Fields
title

string

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

string

Output only. The title of the document which is visible in Drive. If Info.title is empty, documentTitle may appear in its place in the Google Forms UI and be visible to responders. documentTitle 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 documentTitle.
description

string

The description of the form.

FormSettings

A form's settings.

JSON representation 
{
  "quizSettings": {
    object (QuizSettings)
  }
}
Fields
quizSettings

object (QuizSettings)

Settings related to quiz forms and grading.

QuizSettings

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

JSON representation 
{
  "isQuiz": boolean
}
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.

Item

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

JSON representation 
{
  "itemId": string,
  "title": string,
  "description": string,

  // Union field kind can be only one of the following:
  "questionItem": {
    object (QuestionItem)
  },
  "questionGroupItem": {
    object (QuestionGroupItem)
  },
  "pageBreakItem": {
    object (PageBreakItem)
  },
  "textItem": {
    object (TextItem)
  },
  "imageItem": {
    object (ImageItem)
  },
  "videoItem": {
    object (VideoItem)
  }
  // End of list of possible types for union field kind.
}
Fields
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.
title

string

The title of the item.
description

string

The description of the item.
Union field kind. Required. The kind of item this is. kind can be only one of the following:
questionItem

object (QuestionItem)

Poses a question to the user.
questionGroupItem

object (QuestionGroupItem)

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

object (PageBreakItem)

Starts a new page with a title.
textItem

object (TextItem)

Displays a title and description on the page.
imageItem

object (ImageItem)

Displays an image on the page.
videoItem

object (VideoItem)

Displays a video on the page.

QuestionItem

A form item containing a single question.

JSON representation 
{
  "question": {
    object (Question)
  },
  "image": {
    object (Image)
  }
}
Fields
question

object (Question)

Required. The displayed question.
image

object (Image)

The image displayed within the question.

Question

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

JSON representation 
{
  "questionId": string,
  "required": boolean,
  "grading": {
    object (Grading)
  },

  // Union field kind can be only one of the following:
  "choiceQuestion": {
    object (ChoiceQuestion)
  },
  "textQuestion": {
    object (TextQuestion)
  },
  "scaleQuestion": {
    object (ScaleQuestion)
  },
  "dateQuestion": {
    object (DateQuestion)
  },
  "timeQuestion": {
    object (TimeQuestion)
  },
  "fileUploadQuestion": {
    object (FileUploadQuestion)
  },
  "rowQuestion": {
    object (RowQuestion)
  }
  // End of list of possible types for union field kind.
}
Fields
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.
grading

object (Grading)

Grading setup for the question.
Union field kind. Required. The type of question offered to a respondent. kind can be only one of the following:
choiceQuestion

object (ChoiceQuestion)

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

object (TextQuestion)

A respondent can enter a free text response.
scaleQuestion

object (ScaleQuestion)

A respondent can choose a number from a range.
dateQuestion

object (DateQuestion)

A respondent can enter a date.
timeQuestion

object (TimeQuestion)

A respondent can enter a time.
fileUploadQuestion

object (FileUploadQuestion)

A respondent can upload one or more files.
rowQuestion

object (RowQuestion)

A row of a QuestionGroupItem.

ChoiceQuestion

A radio/checkbox/dropdown question.

JSON representation 
{
  "type": enum (ChoiceType),
  "options": [
    {
      object (Option)
    }
  ],
  "shuffle": boolean
}
Fields
type

enum (ChoiceType)

Required. The type of choice question.
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.

ChoiceType

The type of choice.

Enums
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.

Option

An option for a Choice question.

JSON representation 
{
  "value": string,
  "image": {
    object (Image)
  },
  "isOther": boolean,

  // Union field go_to_section can be only one of the following:
  "goToAction": enum (GoToAction),
  "goToSectionId": string
  // End of list of possible types for union field go_to_section.
}
Fields
value

string

Required. The choice as presented to the user.
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.
Union field go_to_section. Which section to go to if this option is selected. Currently only applies to RADIO and SELECT choice type, but is not allowed in a QuestionGroupItem. go_to_section can be only one of the following:
goToAction

enum (GoToAction)

Section navigation type.
goToSectionId

string

Item ID of section header to go to.

GoToAction

Constants for section navigation.

Enums
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.

Image

Data representing an image.

JSON representation 
{
  "contentUri": string,
  "altText": string,
  "properties": {
    object (MediaProperties)
  },

  // Union field image_source can be only one of the following:
  "sourceUri": string
  // End of list of possible types for union field image_source.
}
Fields
contentUri

string

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

string

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

object (MediaProperties)

Properties of an image.
Union field image_source. The kind of image source. Exactly one image source field must be set when creating new images. image_source can be only one of the following:
sourceUri

string

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

MediaProperties

Properties of the media.

JSON representation 
{
  "alignment": enum (Alignment),
  "width": integer
}
Fields
alignment

enum (Alignment)

Position of the media.
width

integer

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.

Alignment

Alignment on the page.

Enums
ALIGNMENT_UNSPECIFIED Default value. Unused.
LEFT Left align.
RIGHT Right align.
CENTER Center.

TextQuestion

A text-based question.

JSON representation 
{
  "paragraph": boolean
}
Fields
paragraph

boolean

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

ScaleQuestion

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

JSON representation 
{
  "low": integer,
  "high": integer,
  "lowLabel": string,
  "highLabel": string
}
Fields
low

integer

Required. The lowest possible value for the scale.
high

integer

Required. The highest possible value for the scale.
lowLabel

string

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

string

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

DateQuestion

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

JSON representation 
{
  "includeTime": boolean,
  "includeYear": boolean
}
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.

TimeQuestion

A time question.

JSON representation 
{
  "duration": boolean
}
Fields
duration

boolean

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

FileUploadQuestion

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

JSON representation 
{
  "folderId": string,
  "types": [
    enum (FileType)
  ],
  "maxFiles": integer,
  "maxFileSize": string
}
Fields
folderId

string

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

enum (FileType)

File types accepted by this question.
maxFiles

integer

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

string (int64 format)

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

FileType

File types that can be uploaded to a file upload question.

Enums
FILE_TYPE_UNSPECIFIED Default value. Unused.
ANY No restrictions on type.
DOCUMENT A Google Docs document.
PRESENTATION A Google Slides presentation.
SPREADSHEET A Google Sheets spreadsheet.
DRAWING A drawing.
PDF A PDF.
IMAGE An image.
VIDEO A video.
AUDIO An audio file.

RowQuestion

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

JSON representation 
{
  "title": string
}
Fields
title

string

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

Grading

Grading for a single question

JSON representation 
{
  "pointValue": integer,
  "correctAnswers": {
    object (CorrectAnswers)
  },
  "whenRight": {
    object (Feedback)
  },
  "whenWrong": {
    object (Feedback)
  },
  "generalFeedback": {
    object (Feedback)
  }
}
Fields
pointValue

integer

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

object (CorrectAnswers)

Required. The answer key for the question. Responses are automatically graded based on this field.
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.
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.

CorrectAnswers

The answer key for a question.

JSON representation 
{
  "answers": [
    {
      object (CorrectAnswer)
    }
  ]
}
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.

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.

JSON representation 
{
  "value": string
}
Fields
value

string

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

QuestionGroupItem

Defines a question that comprises multiple questions grouped together.

JSON representation 
{
  "questions": [
    {
      object (Question)
    }
  ],
  "image": {
    object (Image)
  },

  // Union field kind can be only one of the following:
  "grid": {
    object (Grid)
  }
  // End of list of possible types for union field kind.
}
Fields
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.
image

object (Image)

The image displayed within the question group above the specific questions.
Union field kind. Required. The type of question group, which determines what types of questions are allowed and how they are displayed. kind can be only one of the following:
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.

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.

JSON representation 
{
  "columns": {
    object (ChoiceQuestion)
  },
  "shuffleQuestions": boolean
}
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.

PageBreakItem

This type has no fields.

A page break. The title and description of this item are shown at the top of the new page.

TextItem

This type has no fields.

A text item.

ImageItem

An item containing an image.

JSON representation 
{
  "image": {
    object (Image)
  }
}
Fields
image

object (Image)

Required. The image displayed in the item.

VideoItem

An item containing a video.

JSON representation 
{
  "video": {
    object (Video)
  },
  "caption": string
}
Fields
video

object (Video)

Required. The video displayed in the item.
caption

string

The text displayed below the video.

Video

Data representing a video.

JSON representation 
{
  "youtubeUri": string,
  "properties": {
    object (MediaProperties)
  }
}
Fields
youtubeUri

string

Required. A YouTube URI.
properties

object (MediaProperties)

Properties of a video.

Methods

batchUpdate

 Change the form with a batch of updates.

create

 Create a new form using the title given in the provided form message in the request.

get

 Get a form.