Dashboard

Polls API

Create, manage, and collect votes on polls programmatically.

Management endpoints require API key authentication. Voting endpoints are public but require embed tokens.
GET/api/polls

List all polls

Returns a paginated list of polls for the authenticated user. Requires API key.

Response

JSON
{
  "polls": [
    {
      "id": "poll_abc123",
      "title": "What feature should we build next?",
      "description": "Help us prioritize our roadmap",
      "mode": "poll",
      "published": true,
      "starts_at": null,
      "ends_at": "2025-02-01T00:00:00Z",
      "created_at": "2025-01-15T10:30:00Z",
      "updated_at": "2025-01-15T10:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 1,
    "totalPages": 1
  }
}
POST/api/polls

Create a poll

Creates a new poll. Requires API key.

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,
  "starts_at": null,
  "ends_at": "2025-02-01T00:00:00Z",
  "max_responses": 1000
}

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": [
    { "id": "opt_1", "label": "Dark mode" },
    { "id": "opt_2", "label": "Mobile app" }
  ],
  "allow_multiple": false,
  "show_results_before_vote": false,
  "show_results_after_vote": true,
  "anonymous": true,
  "published": true,
  "starts_at": null,
  "ends_at": "2025-02-01T00:00:00Z"
}
PATCH/api/polls/:id

Update a poll

Update poll configuration. Requires API key and poll ownership.

Request body

JSON
{
  "title": "Updated Poll Title",
  "published": true,
  "ends_at": "2025-03-01T00:00:00Z"
}

Response

JSON
{
  "id": "poll_abc123",
  "title": "Updated Poll Title",
  "published": true,
  "updated_at": "2025-01-15T11:00:00Z"
}
DELETE/api/polls/:id

Delete a poll

Permanently deletes a poll and all its votes. Requires API key.

Response

JSON
{ "success": true }

Public voting endpoints

These endpoints are used by the embed SDK. They require embed tokens instead of API keys.

GET/api/polls/:id/token

Get embed token

Issues a signed token required for voting. Tokens expire after 30 minutes.

Response

JSON
{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "expiresIn": 1800
}
GET/api/polls/:id/vote

Check vote status

Check if the current user has already voted (based on fingerprint).

Response

JSON
{ "hasVoted": false }
POST/api/polls/:id/vote

Submit a vote

Submit a vote on a published poll. Requires embed token.

Request body

JSON
{
  "option_ids": ["opt_1"],
  "_token": "eyJhbGciOiJIUzI1NiIs...",
  "fingerprint": "abc123...",
  "clientMetadata": {
    "screenWidth": 1920,
    "language": "en-US"
  }
}

Response

JSON
{
  "success": true,
  "results": {
    "total_votes": 43,
    "results": [
      { "option_id": "opt_1", "count": 26 },
      { "option_id": "opt_2", "count": 17 }
    ]
  }
}
GET/api/polls/:id/results

Get poll results

Returns current vote counts. Respects show_results_before_vote setting.

Response

JSON
{
  "total_votes": 42,
  "results": [
    { "option_id": "opt_1", "count": 25 },
    { "option_id": "opt_2", "count": 17 }
  ]
}

Poll settings

allow_multipleAllow selecting multiple options
show_results_before_voteShow results without voting first
show_results_after_voteShow results after voting
anonymousHide voter identity from results
starts_atPoll start date (ISO 8601)
ends_atPoll end date (ISO 8601)
max_responsesMaximum number of votes allowed
close_messageMessage shown when poll is closed

Error responses

poll_not_found404Poll does not exist
poll_not_published400Poll is not published
poll_closed403Poll ended or reached max votes
invalid_token403Missing or expired embed token
Already voted400User already voted on this poll
← Forms APIWidgets API →