# Polltab

> Polltab is a free poll maker for creating real-time polls and bracket tournament polls. Create a poll, share the link, and watch votes update live. No sign up or API key required.

Polltab supports standard multiple choice polls and single elimination bracket polls. Polls can include images or video, allow multiple selections, hide results until after voting, schedule open and close times, and restrict voting from unlimited down to one vote per browser, one vote per IP, or a required login (Google, Facebook, Reddit, Twitch). A poll's public URL is https://www.polltab.com/<pollId>.

## Key pages

- [Poll maker](https://www.polltab.com/poll-maker): Create a standard multiple choice poll
- [Bracket poll](https://www.polltab.com/bracket-poll): Create a single elimination bracket tournament poll
- [World Cup bracket maker](https://www.polltab.com/world-cup-bracket-maker): Make a free World Cup bracket pool, add up to 32 teams, and vote on each matchup live
- [How to create a poll](https://www.polltab.com/how-to-create-a-poll): Step by step guide
- [How bracket polls work](https://www.polltab.com/how-bracket-polls-work): Bracket tournament guide
- [Voting security](https://www.polltab.com/poll-voting-security): How vote restrictions work
- [FAQ](https://www.polltab.com/faq): Common questions
- [Blog](https://www.polltab.com/blog): Guides and how-tos for polls and brackets
- [About](https://www.polltab.com/about): About Polltab
- [Terms](https://www.polltab.com/terms): Terms of use

## Create a shareable poll in one click (for chat assistants)

If you cannot make HTTP requests, you can still create a poll for a user: build a poll maker deep link and give it to them. The link opens the poll maker with the question and choices already filled in, so the user only has to press Create. Nothing is published until they do. This is the best option when a user asks you to make a quick poll to share with friends.

Link base: `https://www.polltab.com/poll-maker` with these query parameters:

- `q` (string): the poll question. The alias `question` also works.
- `choice` (repeatable): one per choice, for example `&choice=Pepperoni&choice=Mushroom`. Provide at least two. You can instead pass a single `choices` value with the options comma separated.
- `restriction` (string, optional): how votes are limited. One of `ip` (one vote per ISP, the recommended default for sharing with friends), `ck`, `no`, `go`, `fb`, `re`, `tw`. Defaults to `ip` when omitted.
- `multi` (optional): set to `1` to allow selecting more than one choice.
- `hide` (optional): set to `1` to hide results until a user votes.

URL encode the values (a space becomes `+` or `%20`). After the user presses Create they get a live poll at https://www.polltab.com/<pollId> to share.

Example, a poll to share with friends:

```
https://www.polltab.com/poll-maker?q=Best+pizza+topping%3F&choice=Pepperoni&choice=Mushroom&choice=Pineapple&restriction=ck
```

## Create a poll (for agents)

An agent can create a poll with one unauthenticated HTTPS request. No API key or login is needed. Creation is rate limited to 10 polls per 2 minutes per IP.

`POST https://www.polltab.com/api/poll/create` with header `Content-Type: application/json` and a JSON body:

- `question` (string, required): the poll question
- `choices` (array, required): two or more choices, each `{ "text": "...", "media": "" }`. `media` is an optional image or video URL, use an empty string for none.
- `restriction` (string, required): how votes are limited. One of:
  - `"ck"`: one vote per browser (recommended default)
  - `"ip"`: one vote per household or ISP
  - `"no"`: unlimited votes (a captcha is auto enabled for voting)
  - `"go"`, `"fb"`, `"re"`, `"tw"`: require Google, Facebook, Reddit, or Twitch login to vote
- `allowMultiChoice` (boolean, optional): allow selecting more than one choice. Default false.
- `hideResults` (boolean, optional): hide results until a user votes. Default false.
- `enableComments` (boolean, optional): enable a comment thread. Default false.
- `startDate`, `endDate` (ISO 8601 string, optional): schedule when voting opens and closes.

Response: `{ "status": 200, "data": { "pollId": "<id>" } }`. Share the poll at https://www.polltab.com/<pollId>.

Example:

```
curl -X POST https://www.polltab.com/api/poll/create \
  -H "Content-Type: application/json" \
  -d '{"question":"Best pizza topping?","choices":[{"text":"Pepperoni","media":""},{"text":"Mushroom","media":""}],"restriction":"ck"}'
```

## Read a poll or cast a vote (for agents)

- Read: `GET https://www.polltab.com/api/poll/<pollId>` returns the question, choices with their `choiceId` and vote counts, and the poll settings.
- Vote: `POST https://www.polltab.com/api/poll/<pollId>/vote` with body `{ "choiceIds": ["<choiceId>"] }`. Voting is rate limited to 32 votes per 2 minutes per IP. Polls that use a login restriction or have a captcha enabled also require the matching auth token or captcha response.

## Create a bracket poll (for agents)

A bracket poll is a single elimination tournament. You provide the games for each round and a schedule of when each round opens and closes. Round one starts with your participants, and each later round fills in automatically with the winners of the previous round. Creation uses the same limit of 10 per 2 minutes per IP.

`POST https://www.polltab.com/api/bracket-poll/create` with header `Content-Type: application/json` and a JSON body:

- `title` (string, required): the tournament title
- `titleMedia` (string, optional): an image or video URL for the title
- `restriction` (string, required): same vote restriction codes as a normal poll (`"ck"`, `"ip"`, `"no"`, `"go"`, `"fb"`, `"re"`, `"tw"`)
- `enableCaptcha` (boolean, optional): captcha on voting. Forced on when `restriction` is `"no"`.
- `hideRoundResults` (boolean, optional): hide each round's results until that round closes
- `startDate` (ISO 8601 string, required): when round one opens. Use the current time to start immediately.
- `schedules` (array of ISO 8601 strings, required): the close time for each round, in order, one entry per round. Must be strictly increasing. Round N opens when round N minus 1 closes.
- `brackets` (array, required): the bracket tree, one object per game (see below).

Supported participant counts are 2, 4, 8, 16, and 32. Other counts are padded up to the next size with empty placeholder games marked `"dummy": true`.

Each game in the `brackets` array is an object:

- `bracketNumber` (number): the game's id, numbered sequentially from 1
- `roundNumber` (number): which round the game is in, starting at 1
- `nextGame` (number or null): the `bracketNumber` the winner advances to, or null for the final
- `lastBrackets` (array or null): the two `bracketNumber`s that feed into this game, or null for round one
- `dummy` (boolean): true only for padding games when the participant count is not a power of two
- `poll` (object): `{ "choices": [...] }`. In round one each choice is a participant `{ "text": "...", "media": "" }`. In later rounds use empty objects `{}` for the slots the winners will fill.

Example, a 4 participant bracket (two round one games feeding one final). This exact payload is valid:

```json
{
  "title": "Best Movie of 2025",
  "restriction": "ck",
  "startDate": "2026-05-30T18:00:00.000Z",
  "schedules": ["2026-05-31T18:00:00.000Z", "2026-06-01T18:00:00.000Z"],
  "brackets": [
    { "bracketNumber": 1, "roundNumber": 1, "nextGame": 3, "lastBrackets": null, "dummy": false,
      "poll": { "choices": [ {"text": "Movie A", "media": ""}, {"text": "Movie B", "media": ""} ] } },
    { "bracketNumber": 2, "roundNumber": 1, "nextGame": 3, "lastBrackets": null, "dummy": false,
      "poll": { "choices": [ {"text": "Movie C", "media": ""}, {"text": "Movie D", "media": ""} ] } },
    { "bracketNumber": 3, "roundNumber": 2, "nextGame": null, "lastBrackets": [1, 2], "dummy": false,
      "poll": { "choices": [ {}, {} ] } }
  ]
}
```

Response: `{ "status": 200, "data": { "bracketPollId": "<id>" } }`. The bracket is shared at https://www.polltab.com/bracket-poll/<bracketPollId>.

Wiring the tree by hand (nextGame, lastBrackets, dummy placement) gets tricky for larger brackets. For anything past a few participants, the [bracket builder](https://www.polltab.com/bracket-poll) generates the structure for you from a simple list of participants.

## Read or vote on a bracket poll (for agents)

`GET https://www.polltab.com/api/bracket-poll/<bracketPollId>` returns the title and every game with its round, wiring, and the underlying poll. Each game's `poll` has its own `_id` and `choices` (each with a `choiceId` and vote count).

To vote in a bracket, vote on the individual game using the normal poll vote endpoint: `POST https://www.polltab.com/api/poll/<game poll _id>/vote` with body `{ "choiceIds": ["<choiceId>"] }`.