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 viahttps://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:
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:
{ "error": "This poll is closed.", "code": "closed" }error is bedoeld voor mensen; code, als die er is, is bedoeld voor je code.
| Status | Betekenis |
|---|---|
| 400 | Het verzoek is ongeldig. Bij stemfouten staat de vraag ook in step. |
| 401 | Geen API-sleutel, of invalid_api_key. |
| 403 | Je mag dit formulier niet beheren, of het accepteert deze reactie niet. |
| 404 | Niet gevonden. |
| 409 | Conflict, zoals een dubbele reactie (duplicate). |
| 429 | rate_limited: wacht het aantal seconden uit Retry-After. |
| 503 | busy: 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-type | Wat het vraagt | Fields |
|---|---|---|
multiple_choice | Een of meer opties kiezen; properties.layout dropdown toont één antwoord als keuzelijst | één multiple_choice-field met choices |
picture_choice | Afbeeldingen kiezen | één multiple_choice-field, choices met mediaId |
ranking | Opties in volgorde zetten, met punten per plaats | één ranking-field met choices |
ranked_choice | Stembiljet voor rangschikkend stemmen, geteld als instant runoff | één ranked_choice-field met choices |
meeting | Een tijdstip vinden | één date-field per dag (label YYYY-MM-DD), één choice per tijd (label 09:00-10:00 of All day) |
content | Tekst, 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_info | Naam en e-mailadres | text_small- en email-fields |
page_break, welcome_screen, thank_you_screen, end_screen, redirect | Opmaak en eindschermen | geen |
Instellingen voor het hele formulier staan in properties. De meestgebruikte:
| Property | Waarden | Standaard |
|---|---|---|
resultsVisibility | public, public_after_response, public_after_close, private | public |
responsesVisibility | public toont namen bij de resultaten, private niet, secret verbergt ook voor jou wie wat antwoordde | private |
responseDuplicateCheck | none, session, ip, name, email, code | ip |
responseDuplicateCheckInterval | minuten tot dezelfde stemmer opnieuw mag reageren, of null | null |
opensAt, closesAt | ISO-tijdstempels, of null | null |
responseLimit | maximaal aantal reacties, of null | null |
allowComments, commentsVisibility | true/false, public/private | false, private |
editResponsePermissions | admin_own_responses, own_responses, admin, nobody | admin_own_responses |
blockVPNUsers, useCaptchaVerification | true/false | true, false |
De OpenAPI-specificatie bevat elke property van sections, fields en choices.
Een poll maken
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:
{
"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-KeyofAuthorization: Bearer sp_your_key.
| Tool | Wat het doet |
|---|---|
create_poll | Eén vraag met opties: een stemming, een rangschikking of een planningspoll. Gepubliceerd. |
create_form | Een enquête met meerdere vragen, van multiple_choice tot matrix. Een concept. |
publish_poll | Een concept publiceren. |
list_polls | Je polls, nieuwste eerst, met het aantal reacties. |
get_results | Stemmen per optie, gemiddelde posities, beschikbaarheid bij planningspolls en recente tekstantwoorden. |
set_poll_open | Een 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.
Poll-links
Assistenten zonder tools kunnen je een link geven die de editor opent met de poll al ingevuld, klaar om te controleren en te publiceren:
https://strawpoll.com/forms/new?title=Waar%20gaan%20we%20eten%3F&options=Pizza|Sushi|Tacosoptions 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/me | De eigenaar van de sleutel en diens werkruimtes. |
Formulieren
GET/forms | Je formulieren, nieuwste eerst. ?workspaceId= toont de formulieren van een werkruimte. |
POST/forms | Een 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}/draft | title, themeId, properties en sections opslaan als concept. |
DELETE/forms/{slug}/draft | Het concept weggooien. |
POST/forms/{slug}/publish | Het concept live zetten. Een body met sections wordt eerst opgeslagen. |
Reacties
GET/forms/{slug}/responses | Reacties, nieuwste eerst. limit (maximaal 100) en offset. |
DELETE/forms/{slug}/responses | Resetten: 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.
{
"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"
}| Antwoord | Vorm |
|---|---|
| Keuze- en afbeeldingsvragen | lijst van choice-id’s, plus één tekst als eigen antwoorden zijn toegestaan |
| Rangschikking | elke choice-id, beste eerst |
| Rangschikkend stemmen | de choice-id op elke plaats, beste eerst, null voor een lege plaats |
| Planningspoll | per datumveld een lijst van choiceId en status (yes, if_need_be, no); name is verplicht |
| Ja/nee | "yes" of "no" |
| Beoordeling en schaal | het getal als string, zoals "4" |
| Tekst- en contactvelden | een 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}/codes | Unieke codes. |
POST/forms/{slug}/codes | count codes van length tekens genereren, met optioneel style en prefix. |
DELETE/forms/{slug}/codes | Codes verwijderen op ids. |
GET/forms/{slug}/invites | Uitnodigingen per e-mail. |
POST/forms/{slug}/invites | Eé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}/invites | Uitnodigingen verwijderen op ids. |
POST/forms/{slug}/invites/import | Iedereen op een uitnodigingslijst uitnodigen (inviteListId). |
POST/forms/{slug}/invites/send | Uitnodigingen e-mailen met subject en message. |
Uitnodigingsberichten kunnen de placeholders name, form en link tussen dubbele accolades gebruiken.
Media en thema’s
POST/media | Een afbeelding uploaden (multipart file, maximaal 5 MB). Gebruik de id als mediaId van een choice. |
GET/themes | Je eigen thema’s, die van je werkruimtes en de ingebouwde; ?workspaceId= voor die van één werkruimte. |
POST/themes | Een 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.