Google Forms API: Create a Form Programmatically (Overview)

Building a Google Form by hand is fine for a one-off survey, but it scales terribly when you need to generate dozens of customized assessments every week.

The Google Forms REST API changes that math by letting you generate, update, and manage forms entirely through code.

It turns a manual click-and-drag chore into a repeatable, automated pipeline.

Setting it up requires navigating Google Cloud credentials and understanding a highly nested JSON structure.

Here is how to authenticate your application, create a blank form, and inject questions using the API.

What are the prerequisites for using the Google Forms REST API?

Before you write any code, you need a project configured in the Google Cloud Console.

The Google Forms API does not support simple API keys for creating forms, because every form must live inside a specific user's Google Drive.

You must use OAuth 2.0 to authenticate as a user and grant your application permission to act on their behalf.

Setting this up requires a few specific configuration steps in the cloud console.

If you are building an internal script for yourself, you can keep your OAuth consent screen in Testing mode.

If you plan to release your application to the public, you will eventually need to submit your consent screen for Google's verification process.

How do you authenticate and initialize the Google Forms API client?

Authenticating with Google's APIs involves exchanging your client credentials for an access token.

Because we are creating a form in a user's Drive, we need a user-level access token.

The examples below use the standard Google client libraries to handle the OAuth 2.0 flow, which involves opening a browser, asking the user to log in, and capturing the resulting token.

In a production web application, this flow would happen via redirects.

For local scripts and backend services, you typically run a local server flow to grab the initial token, and then rely on a refresh token for subsequent requests.

Here is how to initialize the client in Node.js using the googleapis package.

// Node.js Authentication Example
// Install required packages: npm install googleapis
const { google } = require('googleapis');
const fs = require('fs');
const path = require('path');

// Load your client secrets downloaded from Google Cloud Console
const CREDENTIALS_PATH = path.join(__dirname, 'credentials.json');
const TOKEN_PATH = path.join(__dirname, 'token.json');

async function authenticate() {
  const content = fs.readFileSync(CREDENTIALS_PATH, 'utf8');
  const credentials = JSON.parse(content);
  const { client_secret, client_id, redirect_uris } = credentials.installed;
  
  const oAuth2Client = new google.auth.OAuth2(
    client_id, client_secret, redirect_uris[0]
  );

  // Check if we have previously stored a token
  try {
    const token = fs.readFileSync(TOKEN_PATH, 'utf8');
    oAuth2Client.setCredentials(JSON.parse(token));
    return oAuth2Client;
  } catch (err) {
    console.log('No token found. You need to implement the initial OAuth flow to generate token.json.');
    // In practice, you would generate an auth URL, open the browser, 
    // capture the code, and call oAuth2Client.getToken(code)
    throw new Error('Authentication required');
  }
}

async function getFormsClient() {
  const auth = await authenticate();
  return google.forms({ version: 'v1', auth });
}

If your stack is Python, the process relies on the google-auth-oauthlib and google-api-python-client packages.

Python's client library includes a convenient InstalledAppFlow class that handles the local browser redirect automatically.

import os.path
from google.auth.transport.requests import Request
from google.oauth2.credentials import Credentials
from google_auth_oauthlib.flow import InstalledAppFlow
from googleapiclient.discovery import build

SCOPES = ['https://www.googleapis.com/auth/forms.body']

def get_forms_client():
    creds = None

    if os.path.exists('token.json'):
        creds = Credentials.from_authorized_user_file('token.json', SCOPES)

    if not creds or not creds.valid:
        if creds and creds.expired and creds.refresh_token:
            creds.refresh(Request())
        else:
            flow = InstalledAppFlow.from_client_secrets_file(
                'credentials.json', SCOPES)
            creds = flow.run_local_server(port=0)

        with open('token.json', 'w') as token:
            token.write(creds.to_json())

    return build('forms', 'v1', credentials=creds)

Both examples assume you have downloaded your OAuth client ID file from Google Cloud Console and saved it as credentials.json in your project directory.

Once authenticated, the initialized client object is your gateway to all Forms API endpoints.

How to create a blank form programmatically using forms.create?

A common point of confusion with the Google Forms API is that creating a form and adding questions are two separate operations.

The forms.create endpoint strictly creates the empty shell of the form.

You cannot pass an array of questions into this initial request.

You must first create the form document, capture its unique ID, and then send a second request to populate it.

1. Define the form metadata. Construct a basic JSON object containing the info property. The only required field here is the title. You can also optionally include a documentTitle (the name of the file in Google Drive, which can differ from the public title) and a description.
2. Execute the POST request. Send the payload to the https://forms.googleapis.com/v1/forms endpoint.
3. Capture the returned formId. The API will return a representation of the newly created form. Extract the formId property from this response, as you will need it for all subsequent updates.

Here is how to execute this initial creation step in Node.js.

async function createBlankForm() {
  const forms = await getFormsClient();
  
  const newForm = {
    info: {
      title: 'Customer Feedback Survey',
      documentTitle: 'Internal - Q3 Feedback Form'
    }
  };

  try {
    const response = await forms.forms.create({
      requestBody: newForm,
    });
    
    console.log('Form created successfully!');
    console.log('Form ID:', response.data.formId);
    console.log('Edit URL:', response.data.responderUri);
    
    return response.data.formId;
  } catch (error) {
    console.error('Error creating form:', error);
  }
}

When this code runs, a new, completely blank form appears in the authenticated user's Google Drive root folder.

The API response includes a responderUri, which is the public link you can share with users to collect responses.

Keep the formId safe in a variable, as the next step requires it to build out the actual survey structure.

How do you add questions and structure using batchUpdate?

To add questions, modify settings, or rearrange items, you must use the forms.batchUpdate endpoint.

This endpoint accepts an array of requests.

Google designed the payload structure to be highly granular, which means the JSON required to build a single multiple-choice question is deeply nested.

If you are trying to generate a Google Form from a text description, mapping your parsed text into this exact JSON structure is usually the most complex part of the integration.

Every item you add requires a createItemRequest.

You must specify an index for each item, which dictates its order on the page.

The index is zero-based. If you add three questions in a single batch update, you must explicitly assign them indexes 0, 1, and 2.

Here is an example of a batchUpdate payload containing two common field types: a short text input and a multiple-choice question.

async function addQuestionsToForm(formId) {
  const forms = await getFormsClient();
  
  const updateRequest = {
    requests: [
      {
        createItemRequest: {
          item: {
            title: 'What is your name?',
            questionItem: {
              question: {
                required: true,
                textQuestion: {
                  paragraph: false // false = short answer, true = paragraph
                }
              }
            }
          },
          location: {
            index: 0 // First question
          }
        }
      },
      {
        createItemRequest: {
          item: {
            title: 'Which department do you work in?',
            questionItem: {
              question: {
                required: true,
                choiceQuestion: {
                  type: 'RADIO', // RADIO = multiple choice, CHECKBOX = checkboxes
                  options: [
                    { value: 'Engineering' },
                    { value: 'Marketing' },
                    { value: 'Sales' },
                    { value: 'Support' }
                  ]
                }
              }
            }
          },
          location: {
            index: 1 // Second question
          }
        }
      }
    ]
  };

  try {
    const response = await forms.forms.batchUpdate({
      formId: formId,
      requestBody: updateRequest,
    });
    console.log('Questions added successfully!');
  } catch (error) {
    console.error('Failed to add questions:', error);
  }
}

The nesting in this payload is strict.

• The wrapper: Every operation is wrapped in a createItemRequest.
• The item: The item object holds the public title (the question text itself) and an optional description.
• The question block: Inside the item, you define a questionItem, which then contains a question object. This is where you set the required flag.
• The specific type: Finally, inside the question object, you declare the specific field type, such as textQuestion or choiceQuestion, and configure its specific parameters.

If you omit a required nested property, the API will reject the entire batch request.

For developers looking to parse existing documents into forms without writing custom JSON mapping logic or managing these deep payloads manually, checking out tools to convert a document into a Google Form can save significant development time.

If you are building the integration yourself, the most efficient approach is to construct your entire array of question objects in memory first, and then send them all in a single batchUpdate array.

Sending a separate batchUpdate HTTP request for every individual question is inefficient and will rapidly burn through your API rate limits.

What are the common error codes and troubleshooting strategies?

When working with the Forms API, you will inevitably encounter HTTP error responses.

Because the API relies on strict index ordering and deep JSON nesting, syntax errors are the most common cause of failure.

Understanding the standard error codes helps isolate the problem quickly.

If you receive a 400 error specifically on a batchUpdate request, the error message in the response body will usually indicate exactly which item in the array failed.

Always log the full error response object, not just the status code, as Google's detailed error messages are surprisingly specific about which JSON key is missing or invalid.

What are the rate limits and security considerations to keep in mind?

Like all Google Cloud services, the Forms API enforces strict quotas to prevent abuse and ensure platform stability.

If your application generates forms in bulk - for example, building customized quizzes for hundreds of students at once - you must design your script to respect these limits.

To handle quotas gracefully, always implement exponential backoff in your API wrapper.

If your application receives a 429 status code, it should not fail immediately.

Instead, it should pause for one second and retry. If the retry fails, it should pause for two seconds, then four, and so on.

From a security perspective, treat the OAuth credentials generated in the Google Cloud Console as highly sensitive secrets.

Never commit your credentials.json or token.json files to a public version control repository.

If a malicious actor gains access to a valid token.json file with the forms.body scope, they can read, modify, or delete any Google Form owned by that user.

Store tokens securely in a database or an encrypted keystore, and restrict your OAuth Client ID in the Google Cloud Console to only accept requests from your verified application domains.

FAQ

Can I use the Google Forms API to read user responses programmatically?

Yes. The API supports reading form responses via the forms.responses.list and forms.responses.get endpoints. You will need to authenticate the user with the https://www.googleapis.com/auth/forms.responses.readonly scope to access this data. The response payload will include timestamps, responder emails (if collected), and the specific answers mapped to the underlying question IDs.

What is the difference between Google Apps Script and the Google Forms REST API?

Google Apps Script runs directly on Google's servers and is deeply integrated into Workspace, making it the simplest choice for basic triggers or internal spreadsheet automations. The REST API is a standard web interface built for external applications. It allows you to create and manage forms from your own Node.js, Python, or Ruby backend, integrating form creation into external platforms.

Do I need a Google Workspace account to use the Forms API?

No. The REST API works perfectly fine with standard, free Google accounts (Gmail). You can create a Google Cloud Project and authenticate personal accounts without paying for Workspace. However, paid Workspace accounts offer additional administrative controls and the ability to use service accounts with domain-wide delegation for enterprise applications.

Building raw API requests is powerful, but maintaining the deep JSON payloads and OAuth flows requires ongoing developer effort. If you need a reliable way to turn text, PDFs, or Word documents into Google Forms without writing custom parsing logic or managing Google Cloud credentials, Doc2Form handles the entire translation and creation process automatically.