A form that contains overall properties and items. Properties include title, settings, and where
responses are stored. Items include question items like checkboxes or radio items, while layout
items refer to things like page breaks. Forms can be accessed or created from FormApp
.
// Open a form by ID and create a new spreadsheet. var form = FormApp.openById('1234567890abcdefghijklmnopqrstuvwxyz'); var ss = SpreadsheetApp.create('Spreadsheet Name'); // Update form properties via chaining. form.setTitle('Form Name') .setDescription('Description of form') .setConfirmationMessage('Thanks for responding!') .setAllowResponseEdits(true) .setAcceptingResponses(false); // Update the form's response destination. form.setDestination(FormApp.DestinationType.SPREADSHEET, ss.getId());
Methods
Method | Return type | Brief description |
---|---|---|
addCheckboxGridItem() | CheckboxGridItem | Appends a new question item, presented as a grid of columns and rows, that allows the respondent to select multiple choices per row from a sequence of checkboxes. |
addCheckboxItem() | CheckboxItem | Appends a new question item that allows the respondent to select one or more checkboxes, as well as an optional "other" field. |
addDateItem() | DateItem | Appends a new question item that allows the respondent to indicate a date. |
addDateTimeItem() | DateTimeItem | Appends a new question item that allows the respondent to indicate a date and time. |
addDurationItem() | DurationItem | Appends a new question item that allows the respondent to indicate a length of time. |
addEditor(emailAddress) | Form | Adds the given user to the list of editors for the Form . |
addEditor(user) | Form | Adds the given user to the list of editors for the Form . |
addEditors(emailAddresses) | Form | Adds the given array of users to the list of editors for the Form . |
addGridItem() | GridItem | Appends a new question item, presented as a grid of columns and rows, that allows the respondent to select one choice per row from a sequence of radio buttons. |
addImageItem() | ImageItem | Appends a new layout item that displays an image. |
addListItem() | ListItem | Appends a new question item that allows the respondent to select one choice from a dropdown list. |
addMultipleChoiceItem() | MultipleChoiceItem | Adds a new question item that allows the respondent to select one choice from a list of radio buttons or an optional "other" field. |
addPageBreakItem() | PageBreakItem | Adds a new layout item that marks the start of a page. |
addParagraphTextItem() | ParagraphTextItem | Adds a new question item that allows the respondent to enter a block of text. |
addScaleItem() | ScaleItem | Appends a new question item that allows the respondent to choose one option from a numbered sequence of radio buttons. |
addSectionHeaderItem() | SectionHeaderItem | Appends a new layout item that visually indicates the start of a section. |
addTextItem() | TextItem | Appends a new question item that allows the respondent to enter a single line of text. |
addTimeItem() | TimeItem | Appends a new question item that allows the respondent to indicate a time of day. |
addVideoItem() | VideoItem | Appends a new layout item that displays a video. |
canEditResponse() | Boolean | Determines whether the form displays a link to edit a response after submitting it. |
collectsEmail() | Boolean | Determines whether the form collects respondents' email addresses. |
createResponse() | FormResponse | Creates a new response to the form. |
deleteAllResponses() | Form | Deletes all submitted responses from the form's response store. |
deleteItem(index) | void | Deletes the item at a given index among all the items in the form. |
deleteItem(item) | void | Deletes the given item. |
deleteResponse(responseId) | Form | Deletes a single response from the form's response store. |
getConfirmationMessage() | String | Gets the form's confirmation message. |
getCustomClosedFormMessage() | String | Gets the custom message that will be displayed if the form is not accepting responses, or an empty string if no custom message has been set. |
getDescription() | String | Gets the form's description. |
getDestinationId() | String | Gets the ID of the form's response destination. |
getDestinationType() | DestinationType | Gets the type of the form's response destination. |
getEditUrl() | String | Gets the URL that can be used to access the form's edit mode. |
getEditors() | User[] | Gets the list of editors for this Form . |
getId() | String | Gets the ID of the form. |
getItemById(id) | Item | Gets the item with a given ID. |
getItems() | Item[] | Gets an array of all items in the form. |
getItems(itemType) | Item[] | Gets an array of all items of a given type. |
getPublishedUrl() | String | Gets the URL that can be used to respond to the form. |
getResponse(responseId) | FormResponse | Gets a single form response based on its response ID. |
getResponses() | FormResponse[] | Gets an array of all of the form's responses. |
getResponses(timestamp) | FormResponse[] | Gets an array of all of the form's responses after a given date and time. |
getShuffleQuestions() | Boolean | Determines whether the order of the questions on each page of the form is randomized. |
getSummaryUrl() | String | Gets the URL that can be used to view a summary of the form's responses. |
getTitle() | String | Gets the form's title. |
hasLimitOneResponsePerUser() | Boolean | Determines whether the form allows only one response per respondent. |
hasProgressBar() | Boolean | Determines whether the form displays a progress bar. |
hasRespondAgainLink() | Boolean | Determines whether the form displays a link to submit another response after a respondent completes the form. |
isAcceptingResponses() | Boolean | Determines whether the form is currently accepting responses. |
isPublishingSummary() | Boolean | Determines whether the form displays a link to view a summary of responses after a respondent completes the form. |
isQuiz() | Boolean | Determines whether the form is a quiz. |
moveItem(from, to) | Item | Moves an item at a given index among all the items in the form to another given index. |
moveItem(item, toIndex) | Item | Moves a given item to an given index among all the items in the form. |
removeDestination() | Form | Unlinks the form from its current response destination. |
removeEditor(emailAddress) | Form | Removes the given user from the list of editors for the Form . |
removeEditor(user) | Form | Removes the given user from the list of editors for the Form . |
requiresLogin() | Boolean | Determines whether the form requires respondents to log in to an account in the same domain or a subdomain before responding. |
setAcceptingResponses(enabled) | Form | Sets whether the form is currently accepting responses. |
setAllowResponseEdits(enabled) | Form | Sets whether the form displays a link to edit a response after submitting it. |
setCollectEmail(collect) | Form | Sets whether the form collects respondents' email addresses. |
setConfirmationMessage(message) | Form | Sets the form's confirmation message. |
setCustomClosedFormMessage(message) | Form | Sets the message to display if the form is not accepting responses. |
setDescription(description) | Form | Sets the form's description. |
setDestination(type, id) | Form | Sets the destination where form responses are saved. |
setIsQuiz(enabled) | Form | Sets whether the form is a quiz. |
setLimitOneResponsePerUser(enabled) | Form | Sets whether the form allows only one response per respondent. |
setProgressBar(enabled) | Form | Sets whether the form has a progress bar. |
setPublishingSummary(enabled) | Form | Sets whether the form displays a link to view a summary of responses after a respondent submits the form. |
setRequireLogin(requireLogin) | Form | Sets whether the form requires respondents to log in to an account in the same domain or a subdomain before responding. |
setShowLinkToRespondAgain(enabled) | Form | Sets whether the form displays a link to submit another response after a respondent completes the form. |
setShuffleQuestions(shuffle) | Form | Sets whether the order of the questions on each page of the form is randomized. |
setTitle(title) | Form | Sets the form's title. |
shortenFormUrl(url) | String | Converts a long URL for a form to a short URL. |
submitGrades(responses) | Form | Submits grades for the given FormResponses. |
Detailed documentation
addCheckboxGridItem()
Appends a new question item, presented as a grid of columns and rows, that allows the respondent to select multiple choices per row from a sequence of checkboxes.
// Opens the Forms file by its URL. If you created your script from within a // Google Forms file, you can use FormApp.getActiveForm() instead. // TODO(developer): Replace the URL with your own. const form = FormApp.openByUrl('https://docs.google.com/forms/d/abc123456/edit'); // Adds a checkbox grid item. const item = form.addCheckboxGridItem(); // Sets the title 'Where did you celebrate New Year's?' item.setTitle('Where did you celebrate New Year's?'); // Sets the grid's rows and columns. item.setRows(['New York', 'San Francisco', 'London']) .setColumns(['2014', '2015', '2016', '2017']);
Return
CheckboxGridItem
— The newly created item.
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/forms.currentonly
-
https://www.googleapis.com/auth/forms
addCheckboxItem()
Appends a new question item that allows the respondent to select one or more checkboxes, as well as an optional "other" field.
// Opens the Forms file by its URL. If you created your script from within a // Google Forms file, you can use FormApp.getActiveForm() instead. // TODO(developer): Replace the URL with your own. const form = FormApp.openByUrl('https://docs.google.com/forms/d/abc123456/edit'); // Adds a checkbox item. const item = form.addCheckboxItem(); // Sets the title of the checkbox item to 'Do you prefer cats or dogs?' item.setTitle('Do you prefer cats or dogs?'); // Sets the choices. item.setChoiceValues(['Cats', 'Dogs']);
Return
CheckboxItem
— The newly created item.
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/forms.currentonly
-
https://www.googleapis.com/auth/forms
addDateItem()
Appends a new question item that allows the respondent to indicate a date.
Return
DateItem
— the newly created item
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/forms.currentonly
-
https://www.googleapis.com/auth/forms
addDateTimeItem()
Appends a new question item that allows the respondent to indicate a date and time.
Return
DateTimeItem
— the newly created item
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/forms.currentonly
-
https://www.googleapis.com/auth/forms
addDurationItem()
Appends a new question item that allows the respondent to indicate a length of time.
Return
DurationItem
— the newly created item
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/forms.currentonly
-
https://www.googleapis.com/auth/forms
addEditor(emailAddress)
Adds the given user to the list of editors for the Form
. If the user was already
on the list of viewers, this method promotes the user out of the list of viewers.
Parameters
Name | Type | Description |
---|---|---|
emailAddress | String | The email address of the user to add. |
Return
Form
— This Form
, for chaining.
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/forms.currentonly
-
https://www.googleapis.com/auth/forms
addEditor(user)
Adds the given user to the list of editors for the Form
. If the user was already
on the list of viewers, this method promotes the user out of the list of viewers.
Parameters
Name | Type | Description |
---|---|---|
user | User | A representation of the user to add. |
Return
Form
— This Form
, for chaining.
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/forms.currentonly
-
https://www.googleapis.com/auth/forms
addEditors(emailAddresses)
Adds the given array of users to the list of editors for the Form
. If any of the
users were already on the list of viewers, this method promotes them out of the list of
viewers.
Parameters
Name | Type | Description |
---|---|---|
emailAddresses | String[] | An array of email addresses of the users to add. |
Return
Form
— This Form
, for chaining.
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/forms.currentonly
-
https://www.googleapis.com/auth/forms
addGridItem()
Appends a new question item, presented as a grid of columns and rows, that allows the respondent to select one choice per row from a sequence of radio buttons.
// Opens the Forms file by its URL. If you created your script from within a // Google Forms file, you can use FormApp.getActiveForm() instead. // TODO(developer): Replace the URL with your own. const form = FormApp.openByUrl('https://docs.google.com/forms/d/abc123456/edit'); // Adds a multiple choice grid. const item = form.addGridItem(); // Sets the title to 'Rate your interests.' item.setTitle('Rate your interests'); // Sets the grid's rows and columns. item.setRows(['Cars', 'Computers', 'Celebrities']) .setColumns(['Boring', 'So-so', 'Interesting']);
Return
GridItem
— The newly created item.
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/forms.currentonly
-
https://www.googleapis.com/auth/forms
addImageItem()
addListItem()
Appends a new question item that allows the respondent to select one choice from a dropdown list.
// Opens the Forms file by its URL. If you created your script from within a // Google Forms file, you can use FormApp.getActiveForm() instead. // TODO(developer): Replace the URL with your own. const form = FormApp.openByUrl('https://docs.google.com/forms/d/abc123456/edit'); // Adds a dropdown list to the form. const item = form.addListItem(); // Sets the title to 'Do you prefer cats or dogs?' item.setTitle('Do you prefer cats or dogs?'); // Sets the description to 'This is description text...' item.setHelpText('This is description text...'); // Creates and adds choices to the dropdown list. item.setChoices([ item.createChoice('dog'), item.createChoice('cat') ]);
Return
ListItem
— The newly created item.
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/forms.currentonly
-
https://www.googleapis.com/auth/forms
addMultipleChoiceItem()
Adds a new question item that allows the respondent to select one choice from a list of radio buttons or an optional "other" field.
// Opens the Forms file by its URL. If you created your script from within a // Google Forms file, you can use FormApp.getActiveForm() instead. // TODO(developer): Replace the URL with your own. const form = FormApp.openByUrl('https://docs.google.com/forms/d/abc123456/edit'); // Adds a multiple choice item to the form. const item = form.addMultipleChoiceItem(); // Sets the title. item.setTitle('What is your favorite ice cream flavor?'); // Creates some choice items. const vanilla = item.createChoice('vanilla'); const chocolate = item.createChoice('chocolate'); const strawberry = item.createChoice('strawberry'); // Sets the choices. item.setChoices([vanilla, chocolate, strawberry]);
Return
MultipleChoiceItem
— The newly created item.
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/forms.currentonly
-
https://www.googleapis.com/auth/forms
addPageBreakItem()
Adds a new layout item that marks the start of a page.
// Opens the Forms file by its URL. If you created your script from within a // Google Forms file, you can use FormApp.getActiveForm() instead. // TODO(developer): Replace the URL with your own. const form = FormApp.openByUrl('https://docs.google.com/forms/d/abc123456/edit'); // Adds page break items to create a second and third page for the form. const pageTwo = form.addPageBreakItem(); const pageThree = form.addPageBreakItem(); // Sets the titles for the pages. pageTwo.setTitle('Page two'); pageThree.setTitle('Page three'); // Upon completion of the first page, sets the form to navigate to the third page. pageTwo.setGoToPage(pageThree); // Upon completion of the second page, sets the form to navigate back to the first page. pageThree.setGoToPage(FormApp.PageNavigationType.RESTART);
Return
PageBreakItem
— The newly created item.
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/forms.currentonly
-
https://www.googleapis.com/auth/forms
addParagraphTextItem()
Adds a new question item that allows the respondent to enter a block of text.
// Opens the form by its URL. If you created your script from within a // Google Forms file, you can use FormApp.getActiveForm() instead. // TODO(developer): Replace the URL with your own. const form = FormApp.openByUrl('https://docs.google.com/forms/d/abc123456/edit'); // Adds the paragraph text item. const item = form.addParagraphTextItem(); // Sets the title to 'What is your address?' item.setTitle('What is your address?');
Return
ParagraphTextItem
— The newly created item.
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/forms.currentonly
-
https://www.googleapis.com/auth/forms
addScaleItem()
Appends a new question item that allows the respondent to choose one option from a numbered sequence of radio buttons.
// Opens the Forms file by its URL. If you created your script from within a // Google Forms file, you can use FormApp.getActiveForm() instead. // TODO(developer): Replace the URL with your own. const form = FormApp.openByUrl('https://docs.google.com/forms/d/abc123456/edit'); // Adds the scale item. const item = form.addScaleItem(); // Sets the title of the scale item to 'Choose a number.' item.setTitle('Choose a number'); // Sets the scale to 1-5. item.setBounds(1, 5); // Sets the label for the lower and upper bounds. item.setLabels('Lowest', 'Highest');
Return
ScaleItem
— The newly created item.
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/forms.currentonly
-
https://www.googleapis.com/auth/forms
addSectionHeaderItem()
Appends a new layout item that visually indicates the start of a section.
// Opens the Forms file by its URL. If you created your script from within a // Google Forms file, you can use FormApp.getActiveForm() instead. // TODO(developer): Replace the URL with your own. const form = FormApp.openByUrl('https://docs.google.com/forms/d/abc123456/edit'); // Adds the section heading item. const item = form.addSectionHeaderItem(); // Sets the title to 'Title of new section.' item.setTitle('Title of new section'); // Sets the description. item.setHelpText('Description of new section');
Return
SectionHeaderItem
— The newly created item.
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/forms.currentonly
-
https://www.googleapis.com/auth/forms
addTextItem()
Appends a new question item that allows the respondent to enter a single line of text.
// Opens the Forms file by its URL. If you created your script from within a // Google Forms file, you can use FormApp.getActiveForm() instead. // TODO(developer): Replace the URL with your own. const form = FormApp.openByUrl('https://docs.google.com/forms/d/abc123456/edit'); // Adds a single-line text item. const item = form.addTextItem(); // Sets the title to 'What is your name?' item.setTitle('What is your name?');
Return
TextItem
— The newly created item.
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/forms.currentonly
-
https://www.googleapis.com/auth/forms
addTimeItem()
Appends a new question item that allows the respondent to indicate a time of day.
Return
TimeItem
— the newly created item
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/forms.currentonly
-
https://www.googleapis.com/auth/forms
addVideoItem()
canEditResponse()
Determines whether the form displays a link to edit a response after submitting it.
Regardless of this setting, the method FormResponse.getEditResponseUrl()
allows a
script author who has edit access to the form to generate a URL that can be used to edit a
response.
Return
Boolean
— true
if the form displays an "Edit your response" link; false
if not
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/forms.currentonly
-
https://www.googleapis.com/auth/forms
collectsEmail()
Determines whether the form collects respondents' email addresses.
Return
Boolean
— true
if the form collects email addresses; false
if not
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/forms.currentonly
-
https://www.googleapis.com/auth/forms
createResponse()
Creates a new response to the form. To answer a question item, create an ItemResponse
from the item, then attach it to this form response by calling FormResponse.withItemResponse(response)
. To save the assembled response, call FormResponse.submit()
.
Return
FormResponse
— the newly created form response
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/forms.currentonly
-
https://www.googleapis.com/auth/forms
deleteAllResponses()
Deletes all submitted responses from the form's response store. This method does not delete copies of responses stored in an external response destination (like a spreadsheet), but does clear the form's summary view.
Return
Form
— this Form
, for chaining
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/forms.currentonly
-
https://www.googleapis.com/auth/forms
deleteItem(index)
Deletes the item at a given index among all the items in the form. Throws a scripting exception if no item exists at the given index.
Parameters
Name | Type | Description |
---|---|---|
index | Integer | the index of the item among all the items in the form |
Throws
Error
— if no item exists at the given index
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/forms.currentonly
-
https://www.googleapis.com/auth/forms
deleteItem(item)
Deletes the given item. Throws a scripting exception if the item has already been deleted.
Parameters
Name | Type | Description |
---|---|---|
item | Item | the item to be deleted |
Throws
Error
— if the item does not exist in the form
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/forms.currentonly
-
https://www.googleapis.com/auth/forms
deleteResponse(responseId)
Deletes a single response from the form's response store. This method does not delete copies of
responses stored in an external response destination (like a spreadsheet), but does remove the
response from the form's summary view. The response ID can be retrieved with FormResponse.getId()
.
Parameters
Name | Type | Description |
---|---|---|
responseId | String | the ID of the form response to delete |
Return
Form
— this Form
, for chaining
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/forms.currentonly
-
https://www.googleapis.com/auth/forms
getConfirmationMessage()
Gets the form's confirmation message.
Return
String
— the form's confirmation message
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/forms.currentonly
-
https://www.googleapis.com/auth/forms
getCustomClosedFormMessage()
Gets the custom message that will be displayed if the form is not accepting responses, or an empty string if no custom message has been set.
Return
String
— the custom message that will be displayed if the form is not accepting responses, or an
empty string if no custom message has been set
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/forms.currentonly
-
https://www.googleapis.com/auth/forms
getDescription()
Gets the form's description.
Return
String
— the form's description
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/forms.currentonly
-
https://www.googleapis.com/auth/forms
getDestinationId()
Gets the ID of the form's response destination.
Return
String
— the ID of the form's response destination
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/forms.currentonly
-
https://www.googleapis.com/auth/forms
getDestinationType()
Gets the type of the form's response destination.
Return
DestinationType
— the type of the form's response destination
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/forms.currentonly
-
https://www.googleapis.com/auth/forms
getEditUrl()
Gets the URL that can be used to access the form's edit mode.
Return
String
— the URL to edit the form
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/forms.currentonly
-
https://www.googleapis.com/auth/forms
getEditors()
getId()
Gets the ID of the form.
Return
String
— the ID of the form
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/forms.currentonly
-
https://www.googleapis.com/auth/forms
getItemById(id)
Gets the item with a given ID. Returns null
if the ID does not correspond to an item in
the form.
Parameters
Name | Type | Description |
---|---|---|
id | Integer | the item's ID |
Return
Item
— the item with the given ID, or null
if the item does not exist in the form
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/forms.currentonly
-
https://www.googleapis.com/auth/forms
getItems()
getItems(itemType)
Gets an array of all items of a given type.
Parameters
Name | Type | Description |
---|---|---|
itemType | ItemType | the type of items to retrieve |
Return
Item[]
— an array of all items of that type
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/forms.currentonly
-
https://www.googleapis.com/auth/forms
getPublishedUrl()
Gets the URL that can be used to respond to the form.
Return
String
— the URL to respond to the form
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/forms.currentonly
-
https://www.googleapis.com/auth/forms
getResponse(responseId)
Gets a single form response based on its response ID. Response IDs can be retrieved from FormResponse.getId()
.
Parameters
Name | Type | Description |
---|---|---|
responseId | String | the ID for the form response |
Return
FormResponse
— the form response
Throws
Error
— if the response does not exist
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/forms.currentonly
-
https://www.googleapis.com/auth/forms
getResponses()
Gets an array of all of the form's responses.
Return
FormResponse[]
— an array of all of the form's responses
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/forms.currentonly
-
https://www.googleapis.com/auth/forms
getResponses(timestamp)
Gets an array of all of the form's responses after a given date and time.
Parameters
Name | Type | Description |
---|---|---|
timestamp | Date | the earliest date and time for which form responses should be returned |
Return
FormResponse[]
— the list of form responses
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/forms.currentonly
-
https://www.googleapis.com/auth/forms
getShuffleQuestions()
Determines whether the order of the questions on each page of the form is randomized.
Return
Boolean
— true
if the order of the questions on each page of the form is randomized;
false
if not
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/forms.currentonly
-
https://www.googleapis.com/auth/forms
getSummaryUrl()
Gets the URL that can be used to view a summary of the form's responses. Unless setPublishingSummary(enabled)
is set to true
, only users with edit permission to the form
will be able to access the URL.
Return
String
— the URL to view a summary of responses
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/forms.currentonly
-
https://www.googleapis.com/auth/forms
getTitle()
Gets the form's title.
Return
String
— the form's title
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/forms.currentonly
-
https://www.googleapis.com/auth/forms
hasLimitOneResponsePerUser()
Determines whether the form allows only one response per respondent. If the value is true
, the script cannot submit form responses at all.
Return
Boolean
— true
if the form allows only one response per respondent; false
if not
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/forms.currentonly
-
https://www.googleapis.com/auth/forms
hasProgressBar()
Determines whether the form displays a progress bar.
Return
Boolean
— true
if the form displays a progress bar; false
if not
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/forms.currentonly
-
https://www.googleapis.com/auth/forms
hasRespondAgainLink()
Determines whether the form displays a link to submit another response after a respondent completes the form.
Return
Boolean
— true
if the form displays a "Submit another response" link; false
if
not
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/forms.currentonly
-
https://www.googleapis.com/auth/forms
isAcceptingResponses()
Determines whether the form is currently accepting responses.
Return
Boolean
— true
if the form is accepting responses; false
if not
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/forms.currentonly
-
https://www.googleapis.com/auth/forms
isPublishingSummary()
Determines whether the form displays a link to view a summary of responses after a respondent completes the form.
Return
Boolean
— true
if the form displays a "See previous responses" link; false
if not
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/forms.currentonly
-
https://www.googleapis.com/auth/forms
isQuiz()
Determines whether the form is a quiz.
Return
Boolean
— true
if the form is accepting responses; false
if not
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/forms.currentonly
-
https://www.googleapis.com/auth/forms
moveItem(from, to)
Moves an item at a given index among all the items in the form to another given index. Throws a
scripting exception if the to
index is out of bounds.
Parameters
Name | Type | Description |
---|---|---|
from | Integer | the current index of the item among all the items in the form |
to | Integer | the new index for the item among all the items in the form |
Return
Item
— the item that was moved
Throws
Error
— if either index is out of bounds
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/forms.currentonly
-
https://www.googleapis.com/auth/forms
moveItem(item, toIndex)
Moves a given item to an given index among all the items in the form. Throws a scripting exception if the given index is out of bounds.
Parameters
Name | Type | Description |
---|---|---|
item | Item | the item to move |
toIndex | Integer | the new index for the item among all the items in the form |
Return
Item
— the item that was moved
Throws
Error
— if the index is out of bounds
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/forms.currentonly
-
https://www.googleapis.com/auth/forms
removeDestination()
Unlinks the form from its current response destination. The unlinked former destination still retains a copy of all previous responses. All forms, including those that do not have a destination set explicitly, save a copy of responses in the form's response store. If the form does not currently have a response destination, this method has no effect.
Return
Form
— this Form
, for chaining
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/forms.currentonly
-
https://www.googleapis.com/auth/forms
removeEditor(emailAddress)
Removes the given user from the list of editors for the Form
. This method doesn't
block users from accessing the Form
if they belong to a class of users who have
general access—for example, if the Form
is shared with the user's entire
domain, or if the Form
is in a shared drive that the user can access.
For Drive files, this also removes the user from the list of viewers.
Parameters
Name | Type | Description |
---|---|---|
emailAddress | String | The email address of the user to remove. |
Return
Form
— This Form
, for chaining.
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/forms.currentonly
-
https://www.googleapis.com/auth/forms
removeEditor(user)
Removes the given user from the list of editors for the Form
. This method doesn't
block users from accessing the Form
if they belong to a class of users who have
general access—for example, if the Form
is shared with the user's entire
domain, or if the Form
is in a shared drive that the user can access.
For Drive files, this also removes the user from the list of viewers.
Parameters
Name | Type | Description |
---|---|---|
user | User | A representation of the user to remove. |
Return
Form
— This Form
, for chaining.
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/forms.currentonly
-
https://www.googleapis.com/auth/forms
requiresLogin()
Determines whether the form requires respondents to log in to an account in the same domain or a subdomain before responding.
Return
Boolean
— true
if the form requires users to log in; false
if not
setAcceptingResponses(enabled)
Sets whether the form is currently accepting responses. The default for new forms is true
.
Parameters
Name | Type | Description |
---|---|---|
enabled | Boolean | true if the form should accept responses; false if not |
Return
Form
— this Form
, for chaining
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/forms.currentonly
-
https://www.googleapis.com/auth/forms
setAllowResponseEdits(enabled)
Sets whether the form displays a link to edit a response after submitting it. The default for
new forms is false
.
Regardless of this setting, the method FormResponse.getEditResponseUrl()
allows a
script author who has edit permission to the form to generate a URL that can be used to edit a
response.
Parameters
Name | Type | Description |
---|---|---|
enabled | Boolean | true if the form should display an "Edit your response" link; false if not |
Return
Form
— this Form
, for chaining
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/forms.currentonly
-
https://www.googleapis.com/auth/forms
setCollectEmail(collect)
Sets whether the form collects respondents' email addresses. The default for new forms is
false
.
Parameters
Name | Type | Description |
---|---|---|
collect | Boolean | true if the form should collect email addresses; false if not |
Return
Form
— this Form
, for chaining
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/forms.currentonly
-
https://www.googleapis.com/auth/forms
setConfirmationMessage(message)
Sets the form's confirmation message.
Parameters
Name | Type | Description |
---|---|---|
message | String | the form's new confirmation message |
Return
Form
— this Form
, for chaining
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/forms.currentonly
-
https://www.googleapis.com/auth/forms
setCustomClosedFormMessage(message)
Sets the message to display if the form is not accepting responses. If no message is set, the form will use a default message.
Parameters
Name | Type | Description |
---|---|---|
message | String | the message to display if the form is not accepting responses |
Return
Form
— this Form
, for chaining
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/forms.currentonly
-
https://www.googleapis.com/auth/forms
setDescription(description)
Sets the form's description.
Parameters
Name | Type | Description |
---|---|---|
description | String | the form's new description |
Return
Form
— this Form
, for chaining
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/forms.currentonly
-
https://www.googleapis.com/auth/forms
setDestination(type, id)
Sets the destination where form responses are saved. All forms, including those that do not have a destination set explicitly, save a copy of responses in the form's response store.
Parameters
Name | Type | Description |
---|---|---|
type | DestinationType | the type of the form's response destination |
id | String | the ID of the form's response destination |
Return
Form
— this Form
, for chaining
Throws
Error
— if the given destination ID is invalid
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/forms.currentonly
-
https://www.googleapis.com/auth/forms
setIsQuiz(enabled)
Sets whether the form is a quiz. The default for new forms is false
.
Graded questions are only allowed in Quizzes, so setting this to false will cause all grading options to be removed from all questions.
Quiz settings are only available in the new Forms UI; making a form a Quiz will opt the form into using the new UI.
Parameters
Name | Type | Description |
---|---|---|
enabled | Boolean | true if quiz features should be enabled for the form; false if
not |
Return
Form
— this Form
, for chaining
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/forms.currentonly
-
https://www.googleapis.com/auth/forms
setLimitOneResponsePerUser(enabled)
Sets whether the form allows only one response per respondent. The default for new forms is
false
. If the value is set to true
, the script cannot submit form responses at
all.
Parameters
Name | Type | Description |
---|---|---|
enabled | Boolean | true if the form should allow only one response per respondent; false if not |
Return
Form
— this Form
, for chaining
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/forms.currentonly
-
https://www.googleapis.com/auth/forms
setProgressBar(enabled)
Sets whether the form has a progress bar. The default for new forms is false
.
Parameters
Name | Type | Description |
---|---|---|
enabled | Boolean | true if the form should display a progress bar; false if not |
Return
Form
— this Form
, for chaining
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/forms.currentonly
-
https://www.googleapis.com/auth/forms
setPublishingSummary(enabled)
Sets whether the form displays a link to view a summary of responses after a respondent submits
the form. The default for new forms is false
.
Parameters
Name | Type | Description |
---|---|---|
enabled | Boolean | true if the form should display a "See previous responses" link; false if not |
Return
Form
— this Form
, for chaining
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/forms.currentonly
-
https://www.googleapis.com/auth/forms
setRequireLogin(requireLogin)
Sets whether the form requires respondents to log in to an account in the same domain or a
subdomain before responding. The default for new forms is false
unless a domain
administrator changes the default.
This feature is available only for forms created by Google Workspace users. Users of other types of Google accounts can't be required to log in.
Parameters
Name | Type | Description |
---|---|---|
requireLogin | Boolean | true if the form requires users to log in; false if not |
Return
Form
— the current form (for chaining)
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/forms.currentonly
-
https://www.googleapis.com/auth/forms
setShowLinkToRespondAgain(enabled)
Sets whether the form displays a link to submit another response after a respondent completes
the form. The default for new forms is true
.
Parameters
Name | Type | Description |
---|---|---|
enabled | Boolean | true if the form should display a "Submit another response" link; false if not |
Return
Form
— this Form
, for chaining
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/forms.currentonly
-
https://www.googleapis.com/auth/forms
setShuffleQuestions(shuffle)
Sets whether the order of the questions on each page of the form is randomized.
Parameters
Name | Type | Description |
---|---|---|
shuffle | Boolean | true if the order of the questions on each page of the form should be
randomized; false if not |
Return
Form
— this Form
, for chaining
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/forms.currentonly
-
https://www.googleapis.com/auth/forms
setTitle(title)
Sets the form's title.
Parameters
Name | Type | Description |
---|---|---|
title | String | the form's new title |
Return
Form
— this Form
, for chaining
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/forms.currentonly
-
https://www.googleapis.com/auth/forms
shortenFormUrl(url)
Converts a long URL for a form to a short URL. Throws an exception if the long URL does not belong to Google Forms.
Parameters
Name | Type | Description |
---|---|---|
url | String |
Return
String
— a URL in the form http://goo.gl/forms/1234
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/forms.currentonly
-
https://www.googleapis.com/auth/forms
submitGrades(responses)
Submits grades for the given FormResponses.
If your code includes an onFormSubmit
trigger, calling submitGrades()
triggers the onFormSubmit
condition and causes an infinite loop. To prevent the
infinite loop, add code that checks whether grades already exist before calling submitGrades()
.
Parameters
Name | Type | Description |
---|---|---|
responses | FormResponse[] |
Return
Form
— This Form
, for chaining.
Authorization
Scripts that use this method require authorization with one or more of the following scopes:
-
https://www.googleapis.com/auth/forms.currentonly
-
https://www.googleapis.com/auth/forms