Sviluppatori / Riferimento API

Forms API

v4

Crea sondaggi e moduli, pubblicali, raccogli le risposte e leggi i risultati dal tuo codice.

URL di base
https://api.strawpoll.com/v4
Specifica
OpenAPI 3

Introduzione

Con la Forms API (v4) il tuo codice crea sondaggi e moduli, li pubblica, raccoglie le risposte e legge i risultati. È la stessa API che usa l’editor di StrawPoll.

  • URL di base: https://api.strawpoll.com/v4 (disponibile anche su https://strawpoll.com/api/v4)
  • Formato: JSON in entrata e in uscita. I timestamp sono stringhe ISO 8601, gli id sono UUID.
  • Specifica leggibile da una macchina: OpenAPI 3.1

Ogni modulo ha un id pubblico breve, lo slug, come in https://strawpoll.com/r/AZPg4n1Td3-hnVAj6Q8p. Tutti gli endpoint dei moduli usano lo slug.

Autenticazione

Crea una chiave in Impostazioni → Chiavi API. Viene mostrata una sola volta: conservala in un posto sicuro. Inviala con ogni richiesta:

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

Funziona anche Authorization: Bearer sp_your_key. Una chiave agisce a tuo nome: può gestire tutti i moduli che gestisci nella dashboard, compresi quelli degli spazi di lavoro di cui fai parte. Elimina una chiave nelle impostazioni per revocarla subito.

Gli endpoint per i partecipanti, submit e verify, non richiedono una chiave da un browser. Le richieste di script, librerie HTTP, browser headless, bot e agenti IA, riconosciuti dal loro user agent, vengono rifiutate con automated se non inviano una chiave.

Errori

Gli errori usano lo stato HTTP e un corpo JSON:

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

error è scritto per le persone; code, quando presente, è pensato per il tuo codice.

StatoSignificato
400La richiesta non è valida. Gli errori di voto indicano anche la domanda in step.
401Nessuna chiave API, oppure invalid_api_key.
403Non puoi gestire questo modulo, oppure il modulo non accetta questa risposta.
404Non trovato.
409Conflitto, ad esempio una risposta duplicata (duplicate).
429rate_limited: attendi i secondi indicati da Retry-After.
503busy: stanno arrivando moltissimi voti nello stesso momento; riprova tra poco.

Limiti di frequenza

120 richieste al minuto per chiave. Senza chiave, le richieste da un browser vengono contate per utente che ha eseguito l’accesso o per browser (tramite il suo cookie di voto), fino a 3.000 al minuto per tutti i browser dietro uno stesso indirizzo IP; le richieste senza nessuno dei due vengono contate per indirizzo IP. Ogni risposta indica la tua quota in X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset (secondi Unix).

Struttura di un modulo

Un modulo è un elenco di sections. Le sezioni con domande contengono fields, e i campi a scelta contengono choices.

type della sezioneCosa chiedeFields
multiple_choiceScegliere una o più opzioni; properties.layout dropdown mostra una risposta come menu a tendinaun field multiple_choice con choices
picture_choiceScegliere immaginiun field multiple_choice, choices con mediaId
rankingOrdinare le opzioni, con punti per posizioneun field ranking con choices
ranked_choiceScheda con voto a preferenza ordinata, conteggiata con ballottaggio istantaneoun field ranked_choice con choices
meetingTrovare un orarioun field date per giorno (label YYYY-MM-DD), un choice per fascia oraria (label 09:00-10:00 o All day)
contentTesto, oppure una domanda con properties.variant impostato su yes_no, rating, scale, text, long_text, name, email o word_cloudun field per la domanda
contact_infoNome e indirizzo emailfields text_small ed email
page_break, welcome_screen, thank_you_screen, end_screen, redirectImpaginazione e schermate finalinessuno

Le impostazioni valide per tutto il modulo si trovano in properties. Le più usate:

ProprietàValoriPredefinito
resultsVisibilitypublic, public_after_response, public_after_close, privatepublic
responsesVisibilitypublic mostra i nomi accanto ai risultati, private no, secret nasconde anche a te chi ha dato quali risposteprivate
responseDuplicateChecknone, session, ip, name, email, codeip
responseDuplicateCheckIntervalminuti prima che lo stesso partecipante possa rispondere di nuovo, o nullnull
opensAt, closesAttimestamp ISO, o nullnull
responseLimitnumero massimo di risposte, o nullnull
allowComments, commentsVisibilitytrue/false, public/privatefalse, private
editResponsePermissionsadmin_own_responses, own_responses, admin, nobodyadmin_own_responses
blockVPNUsers, useCaptchaVerificationtrue/falsetrue, false

La specifica OpenAPI elenca tutte le proprietà di sections, fields e choices.

Creare un sondaggio

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

La risposta contiene il modulo completo, con gli id generati e i suoi link in urls.formUrl e urls.resultsUrl. Senza "status": "published" un modulo nasce come bozza, visibile solo a te.

Un sondaggio per riunioni propone orari in determinate date, nel fuso orario della sezione:

json
{
	"title": "Riunione di team",
	"status": "published",
	"sections": [
		{
			"type": "meeting",
			"properties": { "timezone": "Europe/Rome", "duration": 60, "location": "Sala 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" }] }
			]
		}
	]
}

Assistenti IA (MCP)

StrawPoll offre un server Model Context Protocol: così assistenti IA come Claude, ChatGPT o Cursor possono creare sondaggi e leggere i risultati per te.

  • URL del server: https://strawpoll.com/mcp (Streamable HTTP)
  • Accesso: OAuth. Aggiungi l’URL come connettore personalizzato nel tuo assistente e accedi a StrawPoll quando te lo chiede; sei tu a decidere se autorizzarlo. I client senza OAuth possono invece inviare una chiave API come X-API-Key o Authorization: Bearer sp_your_key.
StrumentoCosa fa
create_pollUna domanda con opzioni: una votazione, una classifica o un sondaggio per riunioni. Pubblicato.
create_formUn questionario con più domande, da multiple_choice a matrix. Una bozza.
publish_pollPubblica una bozza.
list_pollsI tuoi sondaggi, dal più recente, con il numero di risposte.
get_resultsVoti per opzione, posizioni medie, disponibilità nei sondaggi per riunioni e ultime risposte di testo.
set_poll_openChiude un sondaggio o lo riapre.

I sondaggi creati da un assistente sono tuoi come tutti gli altri e usano le tue impostazioni predefinite per i nuovi sondaggi. Un assistente può crearne fino a 30 all’ora.

Gli assistenti senza strumenti possono darti un link che apre l’editor con il sondaggio già compilato, pronto da controllare e pubblicare:

undefined
https://strawpoll.com/forms/new?title=Dove%20andiamo%20a%20pranzo%3F&options=Pizza|Sushi|Tacos

options viene diviso su | (oppure ripeti option=). Aggiungi type=ranking o type=meeting (opzioni come 2026-11-03 o 2026-11-03 14:00-15:00, con timezone=Europe/Rome), multiple=1 per consentire più risposte e other=1 per una risposta libera.

Endpoint

Account

GET/meIl proprietario della chiave e i suoi spazi di lavoro.

Moduli

GET/formsI tuoi moduli, dal più recente. ?workspaceId= elenca i moduli di uno spazio di lavoro.
POST/formsCrea un modulo. workspaceId facoltativo; per impostazione predefinita, il tuo primo spazio di lavoro.
GET/forms/{slug}Il modulo pubblicato, con sections, fields, choices e conteggi.
PUT/forms/{slug}Sostituisce il modulo pubblicato (vedi sotto).
PATCH/forms/{slug}Modifica solo name, isOpen o properties.
DELETE/forms/{slug}Elimina definitivamente il modulo e le sue risposte.

PUT sostituisce tutto: le sections, i fields e i choices che ometti vengono eliminati, insieme alle loro risposte. Rinvia gli id degli elementi che vuoi mantenere, così le loro risposte restano. I moduli rimossi dalla moderazione (deleted, blocked) rispondono 403.

Bozze e pubblicazione

L’editor salva le modifiche come bozza e le pubblica in un solo passaggio. Fino ad allora i partecipanti continuano a vedere il modulo pubblicato.

PUT/forms/{slug}/draftSalva title, themeId, properties e sections come bozza.
DELETE/forms/{slug}/draftScarta la bozza.
POST/forms/{slug}/publishPubblica la bozza. Un corpo con sections viene salvato prima.

Risposte

GET/forms/{slug}/responsesLe risposte, dalla più recente. limit (fino a 100) e offset.
DELETE/forms/{slug}/responsesReimposta: elimina tutte le risposte e riporta i conteggi a zero.

I totali per opzione si trovano nel modulo stesso: responseCount su ogni field e ogni choice, e score per le classifiche. L’oggetto fields di una risposta contiene le sue risposte nella forma descritta in Inviare una risposta.

Inviare una risposta

POST/forms/{slug}/submit invia una risposta come fa la pagina di voto, applicando tutte le regole del modulo: programmazione, limiti, una risposta per persona, captcha, blocco VPN, codici e verifica dell’email. I browser non hanno bisogno di una chiave; gli script e gli altri client automatizzati devono inviarne una.

json
{
	"fields": {
		"<id del campo a scelta>": ["<id del choice>"],
		"<id del campo di classifica>": [
			"<id del choice migliore>",
			"<id del choice successivo>",
			"<id dell’ultimo choice>"
		],
		"<id del campo data della riunione>": [{ "choiceId": "<id del choice>", "status": "yes" }],
		"<id del campo sì/no>": "yes",
		"<id del campo di testo>": "Testo libero"
	},
	"name": "Ada",
	"comment": "Facoltativo",
	"code": "Codice univoco facoltativo"
}
RispostaForma
Domande a scelta e con immaginielenco di id dei choices, più un testo se sono consentite risposte libere
Classificaogni id dei choices, dal migliore
Voto a preferenza ordinatal’id del choice in ogni posizione, dal migliore, null per una posizione lasciata vuota
Sondaggio per riunioniper ogni field data, un elenco di choiceId e status (yes, if_need_be, no); name è obbligatorio
Sì/no"yes" o "no"
Valutazione e scalail numero come stringa, ad esempio "4"
Campi di testo e di contattouna stringa

Un invio riuscito restituisce l’id della risposta. I rifiuti riportano un code: upcoming, closed, full, unavailable, decided, captcha, vpn, code, verify_email, disposable, automated (tutti 403), duplicate (409) e busy (503).

Il browser del partecipante riceve un cookie strawpoll_session. Con questo cookie, PUT/forms/{slug}/submit e l’id della risposta modificano quella risposta, se il modulo consente ai partecipanti di modificarla.

Per i moduli limitati a una risposta per indirizzo email, verifica prima l’indirizzo con POST/forms/{slug}/verify: invia action: "send" e l’email, poi action: "verify" con il code di 6 cifre ricevuto dal partecipante.

Codici e inviti

GET/forms/{slug}/codesCodici univoci.
POST/forms/{slug}/codesGenera count codici di length caratteri, con style e prefix facoltativi.
DELETE/forms/{slug}/codesElimina i codici indicati in ids.
GET/forms/{slug}/invitesInviti via email.
POST/forms/{slug}/invitesAggiunge un invito, o fino a 1000 tramite invites.
PATCH/forms/{slug}/invites/{id}Modifica un invito.
DELETE/forms/{slug}/invites/{id}Elimina un invito.
DELETE/forms/{slug}/invitesElimina gli inviti indicati in ids.
POST/forms/{slug}/invites/importInvita tutte le persone di una lista di invitati (inviteListId).
POST/forms/{slug}/invites/sendInvia gli inviti via email con subject e message.

I messaggi di invito possono usare i segnaposto name, form e link tra doppie parentesi graffe.

Media e temi

POST/mediaCarica un’immagine (file multipart, fino a 5 MB). Usa il suo id come mediaId di un choice.
GET/themesI tuoi temi, quelli dei tuoi spazi di lavoro e quelli integrati; ?workspaceId= per quelli di uno spazio di lavoro.
POST/themesCrea un tema con name e properties di colore; aggiungi workspaceId per condividerlo con uno spazio di lavoro che possiedi o gestisci.
PUT/themes/{id}Modifica un tema. workspaceId lo condivide con uno spazio di lavoro; null lo riporta al solo proprietario.
DELETE/themes/{id}Elimina un tema. I temi di uno spazio di lavoro possono essere modificati ed eliminati dal proprietario e dagli amministratori.

Passare dalla Poll API (v3)

La Poll API v3 continua a funzionare, con gli stessi percorsi, le stesse chiavi e gli stessi sondaggi. La guida alla compatibilità v3 spiega cosa corrisponde a cosa.