DashboardGet Started

Polls API

Create, manage, and collect votes on polls programmatically.

GET/api/polls

List all polls

Returns a list of all polls for the authenticated user.

Response

JSON
[
  {
    "id": "poll_abc123",
    "title": "What feature should we build next?",
    "options": [
      { "id": "opt_1", "label": "Dark mode" },
      { "id": "opt_2", "label": "Mobile app" }
    ],
    "allow_multiple": false,
    "published": true,
    "created_at": "2025-01-15T10:30:00Z"
  }
]
POST/api/polls

Create a poll

Creates a new poll. Requires Pro or Business subscription.

Request body

JSON
{
  "title": "What feature should we build next?",
  "description": "Help us prioritize our roadmap",
  "options": [
    { "id": "opt_1", "label": "Dark mode" },
    { "id": "opt_2", "label": "Mobile app" },
    { "id": "opt_3", "label": "API improvements" }
  ],
  "allow_multiple": false,
  "show_results_before_vote": false,
  "show_results_after_vote": true,
  "anonymous": true,
  "published": false
}

Response

JSON
{
  "id": "poll_abc123",
  "title": "What feature should we build next?",
  "published": false,
  "created_at": "2025-01-15T10:30:00Z"
}
GET/api/polls/:id

Get a poll

Returns poll details. Published polls are publicly accessible.

Response

JSON
{
  "id": "poll_abc123",
  "title": "What feature should we build next?",
  "description": "Help us prioritize our roadmap",
  "options": [...],
  "allow_multiple": false,
  "show_results_before_vote": false,
  "show_results_after_vote": true,
  "anonymous": true,
  "published": true,
  "starts_at": null,
  "ends_at": null
}
POST/api/polls/:id/vote

Submit a vote

Submit a vote on a published poll. No authentication required.

Request body

JSON
{
  "option_ids": ["opt_1"],
  "fingerprint": "abc123..."
}

Response

JSON
{
  "success": true,
  "results": {
    "poll_id": "poll_abc123",
    "total_votes": 42,
    "results": [
      { "option_id": "opt_1", "count": 25 },
      { "option_id": "opt_2", "count": 17 }
    ]
  }
}
GET/api/polls/:id/results

Get poll results

Returns current vote counts for a poll.

Response

JSON
{
  "poll_id": "poll_abc123",
  "total_votes": 42,
  "results": [
    { "option_id": "opt_1", "count": 25 },
    { "option_id": "opt_2", "count": 17 }
  ]
}
DELETE/api/polls/:id

Delete a poll

Permanently deletes a poll and all its votes.

Response

JSON
{ "success": true }
← Forms APIWidgets API →