Forms API

Présentation

Avec la Forms API (v4), votre propre code crée des sondages et des formulaires, les publie, recueille les réponses et lit les résultats. C’est la même API que celle utilisée par l’éditeur StrawPoll.

• URL de base : https://api.strawpoll.com/v4 (également disponible sur https://strawpoll.com/api/v4)
• Format : du JSON en entrée comme en sortie. Les horodatages sont des chaînes ISO 8601, les identifiants des UUID.
• Spécification lisible par machine : OpenAPI 3.1

Chaque formulaire possède un court identifiant public, le slug, comme dans https://strawpoll.com/r/AZPg4n1Td3-hnVAj6Q8p. Tous les endpoints de formulaire attendent le slug.

Authentification

Créez une clé dans Paramètres → Clés API. Elle ne s’affiche qu’une seule fois : conservez-la en lieu sûr. Envoyez-la avec chaque requête :

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

Authorization: Bearer sp_your_key fonctionne aussi. Une clé agit en votre nom : elle peut gérer tous les formulaires que vous gérez dans le tableau de bord, y compris ceux des espaces de travail dont vous êtes membre. Supprimez une clé dans les paramètres pour la révoquer immédiatement.

Les endpoints destinés aux participants, submit et verify, ne demandent pas de clé depuis un navigateur. Les requêtes provenant de scripts, de bibliothèques HTTP, de navigateurs headless, de bots et d’agents IA, reconnus à leur user agent, sont refusées avec automated si elles n’envoient pas de clé.

Erreurs

Les erreurs renvoient le statut HTTP correspondant et un corps JSON :

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

error s’adresse aux humains ; code, lorsqu’il est présent, s’adresse à votre code.

Limites de débit

120 requêtes par minute et par clé. Sans clé, les requêtes d’un navigateur sont comptées par compte connecté ou par navigateur (via son cookie de vote), jusqu’à 3 000 par minute pour l’ensemble des navigateurs derrière une même adresse IP ; les requêtes sans l’un ni l’autre sont comptées par adresse IP. Chaque réponse indique votre quota dans X-RateLimit-Limit, X-RateLimit-Remaining et X-RateLimit-Reset (secondes Unix).

Structure d’un formulaire

Un formulaire est une liste de sections. Les sections de question contiennent des fields, et les champs à choix contiennent des choices.

Les paramètres valables pour tout le formulaire se trouvent dans properties. Les plus utilisés :

La spécification OpenAPI liste toutes les propriétés des sections, fields et choices.

Créer un sondage

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

La réponse contient le formulaire complet, avec les identifiants générés et ses liens dans urls.formUrl et urls.resultsUrl. Sans "status": "published", un formulaire démarre comme brouillon, visible par vous seul.

Un sondage de réunion propose des créneaux sur certains jours, dans le fuseau horaire de la section :

{
	"title": "Point d’équipe",
	"status": "published",
	"sections": [
		{
			"type": "meeting",
			"properties": { "timezone": "Europe/Paris", "duration": 60, "location": "Salle 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" }] }
			]
		}
	]
}

Assistants IA (MCP)

StrawPoll fait tourner un serveur Model Context Protocol : des assistants IA comme Claude, ChatGPT ou Cursor peuvent ainsi créer des sondages et lire les résultats pour vous.

• URL du serveur : https://strawpoll.com/mcp (Streamable HTTP)
• Connexion : OAuth. Ajoutez l’URL comme connecteur personnalisé dans votre assistant et connectez-vous à StrawPoll quand il vous le demande ; c’est vous qui décidez d’autoriser l’accès. Les clients sans OAuth peuvent envoyer à la place une clé API via X-API-Key ou Authorization: Bearer sp_your_key.

Les sondages créés par un assistant vous appartiennent comme les autres et reprennent vos réglages par défaut pour les nouveaux sondages. Un assistant peut en créer jusqu’à 30 par heure.

Liens de sondage

Les assistants sans outils peuvent vous donner un lien qui ouvre l’éditeur avec le sondage déjà rempli, prêt à être vérifié et publié :

https://strawpoll.com/forms/new?title=On%20mange%20o%C3%B9%20%3F&options=Pizza|Sushi|Tacos

options est découpé sur | (ou répétez option=). Ajoutez type=ranking ou type=meeting (options comme 2026-11-03 ou 2026-11-03 14:00-15:00, avec timezone=Europe/Paris), multiple=1 pour autoriser plusieurs réponses et other=1 pour une réponse libre.

Endpoints

Compte

Formulaires

PUT remplace tout : les sections, fields et choices que vous omettez sont supprimés, avec leurs réponses. Renvoyez les identifiants des éléments à conserver pour que leurs réponses restent. Les formulaires retirés par la modération (deleted, blocked) répondent 403.

Brouillons et publication

L’éditeur enregistre les modifications comme brouillon et les publie en une seule étape. D’ici là, les participants continuent de voir le formulaire publié.

Réponses

Les totaux par option figurent sur le formulaire lui-même : responseCount sur chaque field et chaque choice, et score pour les classements. L’objet fields d’une réponse contient ses réponses sous la forme décrite dans Envoyer une réponse.

Envoyer une réponse

POST/forms/{slug}/submit envoie une réponse comme le fait la page de vote, en appliquant toutes les règles du formulaire : calendrier, limites, une réponse par personne, captcha, blocage des VPN, codes et vérification de l’adresse e-mail. Les navigateurs n’ont pas besoin de clé ; les scripts et autres clients automatisés doivent en envoyer une.

{
	"fields": {
		"<id du champ à choix>": ["<id du choice>"],
		"<id du champ de classement>": [
			"<id du meilleur choice>",
			"<id du choice suivant>",
			"<id du dernier choice>"
		],
		"<id du champ de date>": [{ "choiceId": "<id du choice>", "status": "yes" }],
		"<id du champ oui/non>": "yes",
		"<id du champ texte>": "Texte libre"
	},
	"name": "Ada",
	"comment": "Facultatif",
	"code": "Code unique facultatif"
}

Un envoi réussi renvoie l’id de la réponse. Les refus portent un code : upcoming, closed, full, unavailable, decided, captcha, vpn, code, verify_email, disposable, automated (tous en 403), duplicate (409) et busy (503).

Le navigateur du participant reçoit un cookie sp_voter. Avec lui, PUT/forms/{slug}/submit et l’id de la réponse modifient cette réponse, si le formulaire autorise les participants à la modifier.

Pour les formulaires limités à une réponse par adresse e-mail, vérifiez d’abord l’adresse avec POST/forms/{slug}/verify : envoyez action: "send" avec l’email, puis action: "verify" avec le code à 6 chiffres reçu par le participant.

Codes et invitations

Les messages d’invitation peuvent utiliser les variables name, form et link entre doubles accolades.

Médias et thèmes

Migrer depuis la Poll API (v3)

La Poll API v3 continue de fonctionner, avec les mêmes chemins, clés et sondages. Le guide de compatibilité v3 indique ce qui correspond à quoi.