Ontwikkelaars / API-referentie

Forms API

v4

Maak polls en formulieren, publiceer ze, verzamel antwoorden en lees de resultaten uit met je eigen code.

Basis-URL
https://api.strawpoll.com/v4
Specificatie
OpenAPI 3

Overzicht

Met de Forms API (v4) maakt je eigen code polls en formulieren, publiceert ze, verzamelt reacties en leest de resultaten uit. Het is dezelfde API die de editor van StrawPoll zelf gebruikt.

  • Basis-URL: https://api.strawpoll.com/v4 (ook bereikbaar via https://strawpoll.com/api/v4)
  • Formaat: JSON erin, JSON eruit. Tijdstempels zijn ISO 8601-strings, id’s zijn UUID’s.
  • Machineleesbare specificatie: OpenAPI 3.1

Elk formulier heeft een korte openbare id, de slug, zoals in https://strawpoll.com/r/AZPg4n1Td3-hnVAj6Q8p. Alle formulier-endpoints werken met de slug.

Authenticatie

Maak een sleutel aan in Instellingen → API-sleutels. Je ziet hem maar één keer, dus bewaar hem op een veilige plek. Stuur hem mee met elk verzoek:

bash
curl https://api.strawpoll.com/v4/me 
  -H "X-API-Key: sp_your_key"

Authorization: Bearer sp_your_key werkt ook. Een sleutel handelt namens jou: hij kan elk formulier beheren dat jij in het dashboard beheert, ook die in werkruimtes waar je lid van bent. Verwijder een sleutel in Instellingen om hem direct in te trekken.

De endpoints voor deelnemers, submit en verify, hebben vanuit een browser geen sleutel nodig. Verzoeken van scripts, HTTP-bibliotheken, headless browsers, bots en AI-agents, herkend aan hun user agent, worden geweigerd met automated, tenzij ze een sleutel meesturen.

Fouten

Fouten gebruiken de HTTP-status en een JSON-body:

json
{ "error": "This poll is closed.", "code": "closed" }

error is bedoeld voor mensen; code, als die er is, is bedoeld voor je code.

StatusBetekenis
400Het verzoek is ongeldig. Bij stemfouten staat de vraag ook in step.
401Geen API-sleutel, of invalid_api_key.
403Je mag dit formulier niet beheren, of het accepteert deze reactie niet.
404Niet gevonden.
409Conflict, zoals een dubbele reactie (duplicate).
429rate_limited: wacht het aantal seconden uit Retry-After.
503busy: er komen veel stemmen tegelijk binnen; probeer het zo opnieuw.

Limieten

120 verzoeken per minuut per sleutel. Zonder sleutel tellen verzoeken uit een browser per ingelogde gebruiker of per browser (via de stemcookie), tot 3.000 per minuut voor alle browsers achter één IP-adres; verzoeken zonder een van beide tellen per IP-adres. Elke reactie meldt je budget in X-RateLimit-Limit, X-RateLimit-Remaining en X-RateLimit-Reset (Unix-seconden).

Zo is een formulier opgebouwd

Een formulier is een lijst van sections. Vraagsecties bevatten fields, en keuzevelden bevatten choices.

Section-typeWat het vraagtFields
multiple_choiceEen of meer opties kiezen; properties.layout dropdown toont één antwoord als keuzelijstéén multiple_choice-field met choices
picture_choiceAfbeeldingen kiezenéén multiple_choice-field, choices met mediaId
rankingOpties in volgorde zetten, met punten per plaatséén ranking-field met choices
ranked_choiceStembiljet voor rangschikkend stemmen, geteld als instant runofféén ranked_choice-field met choices
meetingEen tijdstip vindenéén date-field per dag (label YYYY-MM-DD), één choice per tijd (label 09:00-10:00 of All day)
contentTekst, of één vraag met properties.variant op yes_no, rating, scale, text, long_text, name, email of word_cloudéén field voor de vraag
contact_infoNaam en e-mailadrestext_small- en email-fields
page_break, welcome_screen, thank_you_screen, end_screen, redirectOpmaak en eindschermengeen

Instellingen voor het hele formulier staan in properties. De meestgebruikte:

PropertyWaardenStandaard
resultsVisibilitypublic, public_after_response, public_after_close, privatepublic
responsesVisibilitypublic toont namen bij de resultaten, private niet, secret verbergt ook voor jou wie wat antwoorddeprivate
responseDuplicateChecknone, session, ip, name, email, codeip
responseDuplicateCheckIntervalminuten tot dezelfde stemmer opnieuw mag reageren, of nullnull
opensAt, closesAtISO-tijdstempels, of nullnull
responseLimitmaximaal aantal reacties, of nullnull
allowComments, commentsVisibilitytrue/false, public/privatefalse, private
editResponsePermissionsadmin_own_responses, own_responses, admin, nobodyadmin_own_responses
blockVPNUsers, useCaptchaVerificationtrue/falsetrue, false

De OpenAPI-specificatie bevat elke property van sections, fields en choices.

Een poll maken

bash
curl https://api.strawpoll.com/v4/forms 
  -H "X-API-Key: sp_your_key" 
  -H "Content-Type: application/json" 
  -d '{
    "title": "Waar gaan we lunchen?",
    "status": "published",
    "properties": { "responseDuplicateCheck": "ip", "resultsVisibility": "public" },
    "sections": [{
      "type": "multiple_choice",
      "fields": [{
        "type": "multiple_choice",
        "label": "Waar gaan we lunchen?",
        "properties": { "isMultipleChoice": false },
        "choices": [{ "label": "Pizza" }, { "label": "Sushi" }, { "label": "Tacos" }]
      }]
    }]
  }'

De reactie is het volledige formulier, met de gegenereerde id’s en de links in urls.formUrl en urls.resultsUrl. Zonder "status": "published" begint een formulier als concept dat alleen jij kunt zien.

Een planningspoll biedt tijden op bepaalde dagen aan, in de tijdzone van de section:

json
{
	"title": "Teamoverleg",
	"status": "published",
	"sections": [
		{
			"type": "meeting",
			"properties": { "timezone": "Europe/Amsterdam", "duration": 60, "location": "Zaal 1" },
			"fields": [
				{
					"type": "date",
					"label": "2026-11-02",
					"choices": [{ "label": "09:00-10:00" }, { "label": "14:00-15:00" }]
				},
				{ "type": "date", "label": "2026-11-03", "choices": [{ "label": "09:00-10:00" }] }
			]
		}
	]
}

AI-assistenten (MCP)

StrawPoll heeft een Model Context Protocol-server, zodat AI-assistenten zoals Claude, ChatGPT of Cursor voor jou polls kunnen maken en resultaten kunnen lezen.

  • Server-URL: https://strawpoll.com/mcp (Streamable HTTP)
  • Inloggen: OAuth. Voeg de URL als aangepaste connector toe in je assistent en log in bij StrawPoll als daarom gevraagd wordt; jij bepaalt of je toegang geeft. Clients zonder OAuth kunnen in plaats daarvan een API-sleutel sturen als X-API-Key of Authorization: Bearer sp_your_key.
ToolWat het doet
create_pollEén vraag met opties: een stemming, een rangschikking of een planningspoll. Gepubliceerd.
create_formEen enquête met meerdere vragen, van multiple_choice tot matrix. Een concept.
publish_pollEen concept publiceren.
list_pollsJe polls, nieuwste eerst, met het aantal reacties.
get_resultsStemmen per optie, gemiddelde posities, beschikbaarheid bij planningspolls en recente tekstantwoorden.
set_poll_openEen poll sluiten of weer openen.

Polls die een assistent maakt, zijn net zo goed van jou en gebruiken je standaardinstellingen voor nieuwe polls. Een assistent kan er maximaal 30 per uur maken.

Assistenten zonder tools kunnen je een link geven die de editor opent met de poll al ingevuld, klaar om te controleren en te publiceren:

undefined
https://strawpoll.com/forms/new?title=Waar%20gaan%20we%20eten%3F&options=Pizza|Sushi|Tacos

options wordt gesplitst op | (of herhaal option=). Voeg type=ranking of type=meeting toe (opties zoals 2026-11-03 of 2026-11-03 14:00-15:00, met timezone=Europe/Amsterdam), multiple=1 om meerdere antwoorden toe te staan en other=1 voor een eigen antwoord.

Endpoints

Account

GET/meDe eigenaar van de sleutel en diens werkruimtes.

Formulieren

GET/formsJe formulieren, nieuwste eerst. ?workspaceId= toont de formulieren van een werkruimte.
POST/formsEen formulier maken. workspaceId is optioneel; standaard je eerste werkruimte.
GET/forms/{slug}Het live formulier met sections, fields, choices en tellingen.
PUT/forms/{slug}Het live formulier vervangen (zie hieronder).
PATCH/forms/{slug}Alleen name, isOpen of properties wijzigen.
DELETE/forms/{slug}Het formulier en de reacties definitief verwijderen.

PUT vervangt alles: sections, fields en choices die je weglaat, worden verwijderd, samen met hun antwoorden. Stuur de id’s mee van de onderdelen die je wilt houden, zodat hun reacties blijven bestaan. Formulieren die door moderatie zijn verwijderd (deleted, blocked), antwoorden met 403.

Concepten en publiceren

De editor slaat wijzigingen op als concept en publiceert ze in één stap. Tot dan blijven deelnemers het live formulier zien.

PUT/forms/{slug}/drafttitle, themeId, properties en sections opslaan als concept.
DELETE/forms/{slug}/draftHet concept weggooien.
POST/forms/{slug}/publishHet concept live zetten. Een body met sections wordt eerst opgeslagen.

Reacties

GET/forms/{slug}/responsesReacties, nieuwste eerst. limit (maximaal 100) en offset.
DELETE/forms/{slug}/responsesResetten: alle reacties verwijderen en de tellingen op nul zetten.

Totalen per optie staan op het formulier zelf: responseCount bij elk field en elke choice, en score bij rangschikkingen. De fields van een reactie bevatten de antwoorden in de vorm die beschreven staat onder Een reactie versturen.

Een reactie versturen

POST/forms/{slug}/submit verstuurt een reactie zoals de stempagina dat doet, met alle regels van het formulier: planning, limieten, één reactie per persoon, captcha, VPN-blokkering, codes en e-mailverificatie. Browsers hebben geen sleutel nodig; scripts en andere geautomatiseerde clients moeten er een meesturen.

json
{
	"fields": {
		"<id van keuzeveld>": ["<choice-id>"],
		"<id van rangschikkingsveld>": [
			"<beste choice-id>",
			"<volgende choice-id>",
			"<laatste choice-id>"
		],
		"<id van datumveld>": [{ "choiceId": "<choice-id>", "status": "yes" }],
		"<id van ja/nee-veld>": "yes",
		"<id van tekstveld>": "Vrije tekst"
	},
	"name": "Ada",
	"comment": "Optioneel",
	"code": "Optionele unieke code"
}
AntwoordVorm
Keuze- en afbeeldingsvragenlijst van choice-id’s, plus één tekst als eigen antwoorden zijn toegestaan
Rangschikkingelke choice-id, beste eerst
Rangschikkend stemmende choice-id op elke plaats, beste eerst, null voor een lege plaats
Planningspollper datumveld een lijst van choiceId en status (yes, if_need_be, no); name is verplicht
Ja/nee"yes" of "no"
Beoordeling en schaalhet getal als string, zoals "4"
Tekst- en contactveldeneen string

Een geslaagde verzending geeft de id van de reactie terug. Weigeringen hebben een code: upcoming, closed, full, unavailable, decided, captcha, vpn, code, verify_email, disposable, automated (allemaal 403), duplicate (409) en busy (503).

De browser van de stemmer krijgt een strawpoll_session-cookie. Daarmee wijzigen PUT/forms/{slug}/submit en de id van de reactie die reactie, als het formulier stemmers toestaat hun antwoord aan te passen.

Bij formulieren met één reactie per e-mailadres verifieer je het adres eerst met POST/forms/{slug}/verify: stuur action: "send" met het email, en daarna action: "verify" met de 6-cijferige code die de stemmer heeft ontvangen.

Codes en uitnodigingen

GET/forms/{slug}/codesUnieke codes.
POST/forms/{slug}/codescount codes van length tekens genereren, met optioneel style en prefix.
DELETE/forms/{slug}/codesCodes verwijderen op ids.
GET/forms/{slug}/invitesUitnodigingen per e-mail.
POST/forms/{slug}/invitesEén uitnodiging toevoegen, of maximaal 1000 via invites.
PATCH/forms/{slug}/invites/{id}Een uitnodiging wijzigen.
DELETE/forms/{slug}/invites/{id}Een uitnodiging verwijderen.
DELETE/forms/{slug}/invitesUitnodigingen verwijderen op ids.
POST/forms/{slug}/invites/importIedereen op een uitnodigingslijst uitnodigen (inviteListId).
POST/forms/{slug}/invites/sendUitnodigingen e-mailen met subject en message.

Uitnodigingsberichten kunnen de placeholders name, form en link tussen dubbele accolades gebruiken.

Media en thema’s

POST/mediaEen afbeelding uploaden (multipart file, maximaal 5 MB). Gebruik de id als mediaId van een choice.
GET/themesJe eigen thema’s, die van je werkruimtes en de ingebouwde; ?workspaceId= voor die van één werkruimte.
POST/themesEen thema maken met name en kleur-properties; voeg workspaceId toe om het te delen met een werkruimte die je bezit of beheert.
PUT/themes/{id}Een thema wijzigen. workspaceId deelt het met een werkruimte, null maakt het weer van de eigenaar zelf.
DELETE/themes/{id}Een thema verwijderen. De thema’s van een werkruimte kunnen worden gewijzigd en verwijderd door de eigenaar en de beheerders.

Overstappen van de Poll API (v3)

De Poll API v3 blijft werken, met dezelfde paden, sleutels en polls. In de v3-compatibiliteitsgids zie je wat waar terechtkomt.