The Google Forms API is currently in Open Beta. To use the API, apply for access at the Early Adopter Program page.

Method: forms.batchUpdate

Change the form with a batch of updates.

HTTP request

POST https://forms.googleapis.com/v1beta/forms/{formId}:batchUpdate

The URL uses gRPC Transcoding syntax.

Path parameters

Parameters
formId

string

Required. The form ID.

Request body

The request body contains data with the following structure:

JSON representation
{
  "includeFormInResponse": boolean,
  "requests": [
    {
      object (Request)
    }
  ],
  "writeControl": {
    object (WriteControl)
  }
}
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.

Response body

If successful, the response body contains data with the following structure:

Response to a BatchUpdateFormRequest.

JSON representation
{
  "form": {
    object (Form)
  },
  "replies": [
    {
      object (Response)
    }
  ],
  "writeControl": {
    object (WriteControl)
  }
}
Fields
form

object (Form)

Based on the bool request field includeFormInResponse, 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.

Authorization Scopes

Requires one of the following OAuth scopes:

  • https://www.googleapis.com/auth/drive
  • https://www.googleapis.com/auth/forms.body

For more information, see the OAuth 2.0 Overview.

Request

The kinds of update requests that can be made.

JSON representation
{

  // Union field kind can be only one of the following:
  "updateFormInfo": {
    object (UpdateFormInfoRequest)
  },
  "updateSettings": {
    object (UpdateSettingsRequest)
  },
  "createItem": {
    object (CreateItemRequest)
  },
  "moveItem": {
    object (MoveItemRequest)
  },
  "deleteItem": {
    object (DeleteItemRequest)
  },
  "updateItem": {
    object (UpdateItemRequest)
  }
  // End of list of possible types for union field kind.
}
Fields
Union field kind. The kind of request. kind can be only one of the following:
updateFormInfo

object (UpdateFormInfoRequest)

Update Form's Info.

updateSettings

object (UpdateSettingsRequest)

Updates the Form's settings.

createItem

object (CreateItemRequest)

Create a new item.

moveItem

object (MoveItemRequest)

Move an item to a specified location.

deleteItem

object (DeleteItemRequest)

Delete an item.

updateItem

object (UpdateItemRequest)

Update an item.

UpdateFormInfoRequest

Update Form's Info.

JSON representation
{
  "info": {
    object (Info)
  },
  "updateMask": string
}
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.

This is a comma-separated list of fully qualified names of fields. Example: "user.displayName,photo".

UpdateSettingsRequest

Update Form's FormSettings.

JSON representation
{
  "settings": {
    object (FormSettings)
  },
  "updateMask": string
}
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.

This is a comma-separated list of fully qualified names of fields. Example: "user.displayName,photo".

CreateItemRequest

Create an item in a form.

JSON representation
{
  "item": {
    object (Item)
  },
  "location": {
    object (Location)
  }
}
Fields
item

object (Item)

Required. The item to create.

location

object (Location)

Required. Where to place the new item.

Location

A specific location in a form.

JSON representation
{
  "index": integer
}
Fields
index

integer

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.

MoveItemRequest

Move an item in a form.

JSON representation
{
  "originalLocation": {
    object (Location)
  },
  "newLocation": {
    object (Location)
  }
}
Fields
originalLocation

object (Location)

Required. The location of the item to move.

newLocation

object (Location)

Required. The new location for the item.

DeleteItemRequest

Delete an item in a form.

JSON representation
{
  "location": {
    object (Location)
  }
}
Fields
location

object (Location)

Required. The location of the item to delete.

UpdateItemRequest

Update an item in a form.

JSON representation
{
  "item": {
    object (Item)
  },
  "location": {
    object (Location)
  },
  "updateMask": string
}
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.

This is a comma-separated list of fully qualified names of fields. Example: "user.displayName,photo".

WriteControl

Provides control over how write requests are executed.

JSON representation
{

  // Union field control can be only one of the following:
  "requiredRevisionId": string,
  "targetRevisionId": string
  // End of list of possible types for union field control.
}
Fields
Union field control. Determines the revision of the form from which changes are to be applied, and how the request should behave if that revision is not the current revision of the form. control can be only one of the following:
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.

Response

A single response from an update.

JSON representation
{
  "createItem": {
    object (CreateItemResponse)
  }
}
Fields
createItem

object (CreateItemResponse)

The result of creating an item.

CreateItemResponse

The result of creating an item.

JSON representation
{
  "itemId": string,
  "questionId": [
    string
  ]
}
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.