# Google Forms API gebruiken voor formulierintegraties

[[TOC]]

Formulieren zijn een eenvoudige manier om data te verzamelen, maar die data wil je vaak verder verwerken: doorsturen naar een CRM, een ticket aanmaken of een bevestiging sturen. Met de Google Forms API maak je formulieren als code en lees je inzendingen uit. Zo verbind je de eenvoud van Forms met de kracht van je eigen systemen.

In dit artikel bouw je het aanmaken, het uitlezen en het realtime verwerken stap voor stap op.

## Een formulier aanmaken

Je maakt eerst een leeg formulier met een titel, en voegt daarna vragen toe via een aparte `batchUpdate`-call.

```python
formulier = service.forms().create(
    body={'info': {'title': 'Aanmelding webinar'}}
).execute()
form_id = formulier['formId']
```

:::info title="Alleen de titel bij create"
Bij `create` geef je alleen de info-sectie met de titel op. Andere velden in dat verzoek worden genegeerd. Vragen voeg je dus niet bij create toe, maar in een aparte `batchUpdate`-call. Dit tweetrapspatroon is even wennen maar consistent met andere Workspace-API's.
:::

:::warn title="Nieuwe formulieren staan vanaf 30 juni 2026 op niet-gepubliceerd"
Formulieren die je na 30 juni 2026 via de API aanmaakt, krijgen standaard de status niet-gepubliceerd. Ze accepteren dan nog geen antwoorden tot je ze expliciet publiceert. Roep daarvoor `forms.setPublishSettings()` aan op het form-ID nadat je de vragen hebt toegevoegd. Vergeet je dit, dan lijkt je formulier leeg of ontoegankelijk voor respondenten.
:::

## Vragen toevoegen

Met `batchUpdate` stuur je een lijst van requests, elk met een `createItem`. De requests worden als groep verwerkt: faalt er een, dan wordt niets uit de batch weggeschreven.

:::howto title="Zo voeg je vragen toe"
1. Bouw per vraag een `createItem`-request met een titel en het vraagtype.
2. Stel het type in, bijvoorbeeld `textQuestion`, `choiceQuestion` (meerkeuze) of `scaleQuestion` (schaal).
3. Geef per request een `location.index` mee voor de positie in het formulier.
4. Verstuur alle requests samen via `forms.batchUpdate()`.
:::

```python
service.forms().batchUpdate(formId=form_id, body={'requests': [{
    'createItem': {
        'item': {'title': 'Wat is je naam?',
                  'questionItem': {'question': {'required': True,
                  'textQuestion': {}}}},
        'location': {'index': 0}
    }
}]}).execute()
```

## Antwoorden ophalen

Inzendingen vraag je op met `responses.list`. Elk antwoord bevat de waarden per vraag, gekoppeld aan question-ID's.

```python
antwoorden = service.forms().responses().list(formId=form_id).execute()
for response in antwoorden.get('responses', []):
    print(response['answers'])
```

:::tip title="Bewaar de question-ID's"
Bewaar de question-ID's die je bij het aanmaken terugkrijgt. De antwoorden refereren namelijk aan die ID's, niet aan de vraagteksten. Met een mapping van ID naar betekenis verwerk je inzendingen veel makkelijker en betrouwbaarder.
:::

## Realtime verwerken met een watch

In plaats van te pollen, laat je Forms je een seintje geven bij elke nieuwe inzending. Je maakt een watch aan op het event-type `RESPONSES`, die meldingen publiceert naar een Cloud Pub/Sub-topic.

1. Maak in Google Cloud een Pub/Sub-topic aan en geef de Forms-serviceaccount publiceerrechten op dat topic.
2. Maak met `forms.watches.create()` een watch aan op het formulier voor het event-type `RESPONSES`.
3. Forms publiceert bij elke nieuwe of gewijzigde inzending een melding naar je topic.
4. Je verwerker ontvangt de melding en haalt het nieuwe antwoord op met `forms.responses.list()`, gefilterd op een timestamp groter dan de laatste die je al verwerkte.
5. Je verwerkt het antwoord, bijvoorbeeld door een record in je CRM aan te maken.
6. Vernieuw de watch met `forms.watches.renew()` voordat die verloopt.

:::warn title="Verwerk inzendingen idempotent"
Een watch verloopt zeven dagen na het aanmaken, dus plan een tijdige `renew()`. Verwerk antwoorden bovendien idempotent: een melding kan in zeldzame gevallen meer dan eens binnenkomen. Houd bij welke response-ID's je al verwerkt hebt, zodat je geen dubbele records of dubbele bevestigingsmails veroorzaakt.
:::

## Welke scopes heb je nodig

Vraag alleen de OAuth-scopes aan die je echt gebruikt. Een te brede scope is een onnodig veiligheidsrisico bij je verificatie.

| Taak | Scope |
| --- | --- |
| Formulier aanmaken en bewerken | `https://www.googleapis.com/auth/forms.body` |
| Antwoorden lezen | `https://www.googleapis.com/auth/forms.responses.readonly` |
| Watch aanmaken op antwoorden | `https://www.googleapis.com/auth/forms.responses.readonly` |

## Veelgestelde vragen

:::faq
### Kan ik een bestaand formulier bewerken?
Ja. Met `batchUpdate` voeg je items toe, wijzig je ze of verwijder je ze in een bestaand formulier waarvoor je rechten hebt.

### Krijg ik ook quizscores via de API?
Ja. Als het formulier een quiz is, bevatten de antwoorden de toegekende punten per vraag in de grading-informatie.

### Hoe koppel ik antwoorden aan een spreadsheet?
Dat kan via de Forms-koppeling in de interface, of je leest de antwoorden via de API en schrijft ze zelf naar een sheet met de Sheets API.

### Waarom accepteert mijn nieuwe formulier geen antwoorden?
Sinds 30 juni 2026 staan via de API aangemaakte formulieren standaard op niet-gepubliceerd. Publiceer het formulier met `forms.setPublishSettings()` voordat respondenten kunnen invullen.

### Hoe vaak moet ik mijn watch vernieuwen?
Een watch verloopt zeven dagen na het aanmaken. Roep `forms.watches.renew()` aan voordat die termijn voorbij is, zodat je geen meldingen mist.
:::

Met de Forms API verander je losse formulieren in een geintegreerd onderdeel van je dataverwerking, van aanmaken tot realtime opvolging.