Google Forms

Access the Google Forms API with managed OAuth authentication. Create forms, add questions, and retrieve responses.

Quick Start

# Get form
curl -s -X GET 'https://gateway.maton.ai/google-forms/v1/forms/{formId}' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Base URL

https://gateway.maton.ai/google-forms/v1/forms/{formId}

The gateway proxies requests to forms.googleapis.com and automatically injects your OAuth token.

Authentication

All requests require the Maton API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Environment Variable: Set your API key as MATON_API_KEY:

export MATON_API_KEY="YOUR_API_KEY"

Getting Your API Key

Sign in at maton.ai
Go to maton.ai/settings
Copy your API key

Connection Management

Manage your Google OAuth connections at https://ctrl.maton.ai.

List Connections

curl -s -X GET 'https://ctrl.maton.ai/connections?app=google-forms&status=ACTIVE' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Create Connection

curl -s -X POST 'https://ctrl.maton.ai/connections' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -d '{"app": "google-forms"}'

Get Connection

curl -s -X GET 'https://ctrl.maton.ai/connections/{connection_id}' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response:

{
  "connection": {
    "connection_id": "21fd90f9-5935-43cd-b6c8-bde9d915ca80",
    "status": "ACTIVE",
    "url": "https://connect.maton.ai/?session_token=...",
    "app": "google-forms"
  }
}

Open the returned url in a browser to complete OAuth authorization.

Delete Connection

curl -s -X DELETE 'https://ctrl.maton.ai/connections/{connection_id}' \
  -H 'Authorization: Bearer YOUR_API_KEY'

API Reference

Get Form

GET /google-forms/v1/forms/{formId}

Create Form

POST /google-forms/v1/forms
Content-Type: application/json

{
  "info": {
    "title": "Customer Feedback Survey"
  }
}

Batch Update Form

POST /google-forms/v1/forms/{formId}:batchUpdate
Content-Type: application/json

{
  "requests": [
    {
      "createItem": {
        "item": {
          "title": "What is your name?",
          "questionItem": {
            "question": {
              "required": true,
              "textQuestion": {"paragraph": false}
            }
          }
        },
        "location": {"index": 0}
      }
    }
  ]
}

List Responses

GET /google-forms/v1/forms/{formId}/responses

Get Response

GET /google-forms/v1/forms/{formId}/responses/{responseId}

Common batchUpdate Requests

Create Text Question

{
  "createItem": {
    "item": {
      "title": "Question text",
      "questionItem": {
        "question": {
          "required": true,
          "textQuestion": {"paragraph": false}
        }
      }
    },
    "location": {"index": 0}
  }
}

Create Multiple Choice

{
  "createItem": {
    "item": {
      "title": "Select an option",
      "questionItem": {
        "question": {
          "choiceQuestion": {
            "type": "RADIO",
            "options": [
              {"value": "Option A"},
              {"value": "Option B"}
            ]
          }
        }
      }
    },
    "location": {"index": 0}
  }
}

Create Scale Question

{
  "createItem": {
    "item": {
      "title": "Rate your experience",
      "questionItem": {
        "question": {
          "scaleQuestion": {
            "low": 1,
            "high": 5,
            "lowLabel": "Poor",
            "highLabel": "Excellent"
          }
        }
      }
    },
    "location": {"index": 0}
  }
}

Question Types

textQuestion - Short or paragraph text
choiceQuestion - Radio, checkbox, or dropdown
scaleQuestion - Linear scale
dateQuestion - Date picker
timeQuestion - Time picker

Code Examples

JavaScript

const response = await fetch(
  'https://gateway.maton.ai/google-forms/v1/forms/FORM_ID/responses',
  {
    headers: {
      'Authorization': `Bearer ${process.env.MATON_API_KEY}`
    }
  }
);

Python

import os
import requests

response = requests.get(
    f'https://gateway.maton.ai/google-forms/v1/forms/FORM_ID/responses',
    headers={'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'}
)

Notes

Form IDs are found in the form URL
Use updateMask to specify fields to update
Location index is 0-based

Error Handling

Status	Meaning
400	Missing Google Forms connection
401	Invalid or missing Maton API key
429	Rate limited (10 req/sec per account)
4xx/5xx	Passthrough error from Google Forms API

google-forms