API reference: Live poll events

Presenter sessions with a join code. Bearer-auth and workspace-scoped. See Live events for what the features do.

Base URL: https://formspring.io/api/v1

An event from another workspace answers 404, never 403.

Create an event

POST /poll-events
{ "name": "Town hall", "qna_enabled": true, "language": "de",
  "presentation": { "theme": "dark", "accent": "#336699" } }

The response carries join_code, join_url, screen_url (the read-only public screen), presenter_url, state_version and status.

* * *

Add a question

POST /poll-events/{event}/polls
{ "question": "Which are prime?", "format": "quiz",
  "options": ["2", "3", "4"], "correct": [0, 1], "points": 500, "time_limit_seconds": 30 }

format is choice, quiz, rating, ranking, word_cloud or open_text. correct lists the zero-based index of every correct option. The response is the presenter snapshot.

* * *

Run the event

POST /poll-events/{event}/actions
{ "action": "next", "expected_state_version": 7 }

action is start, open (with poll_id), next, close, reveal, leaderboard (with visible), qna (with open) or end. Every accepted action moves state_version up by one. If expected_state_version is stale the call changes nothing and answers:

409 { "error": "revision_conflict", "message": "...", "current_state_version": 8, "snapshot": { } }

Other 409 errors (not_live, poll_not_open, event_ended, ...) mean the action does not fit the current state. Error messages follow the event's language, or Accept-Language when the event sets none.

* * *

Results as a table

GET /poll-events/{event}/polls/{poll}/results returns columns and rows for the question, plus total, average (ratings) and excluded_count (word cloud and open text answers held back by the language filter). It is the text equivalent of the chart.

* * *

Moderation

GET /questions lists the moderation queue (use status=pending for the review queue). It is the moderators' view; pending and hidden questions never appear in results, exports or anything the audience receives.

POST /poll-events/{event}/questions/{question}/moderate
{ "action": "approve", "expected_status": "pending" }

action is approve, hide, answer or restore. If another moderator already acted, the answer is 409 revision_conflict with current_status. Each decision is written to the moderation log (GET /moderation-log).

* * *

Export

GET /export?type=participants|questions|results returns JSON (columns and data) or, with format=csv, a CSV file. questions contains only approved and answered questions.