> ## Documentation Index
> Fetch the complete documentation index at: https://developer.dizplai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Polls

> Send a fan's vote, and show the results when fans may see them.

A poll asks fans to pick one of its options. Once it has gone live, its options are fixed: your producers can correct a label, but can't add or remove an option.

## Voting

When the fan picks an option, send its ID with the fan's token and a new `Idempotency-Key`:

```http theme={null}
POST /v1/polls/0192fa7b-8d41-7bbc-9b58-02311fc6ef8e/votes
x-api-key: <your API key>
Authorization: Bearer <the fan's token>
Idempotency-Key: <a new UUID for this vote>
Content-Type: application/json

{ "option_id": "01a1f97a-b538-778f-bad7-0c1c35ff701c" }
```

The answer is `202 Accepted`: received, not yet counted. It has a snapshot of the poll's results with the vote added. See [Cast a vote](https://developer.dizplai.com/api-reference/polls/cast-a-vote.md).

* **Show the snapshot straight away,** as a static view. It doesn't update, and it follows the poll's `results_visibility`.
* **Only the fan's first vote counts.** A later vote, from any device, also answers `202`, but is never counted.
* **To show the fan's choice,** [get the fan's vote](https://developer.dizplai.com/api-reference/polls/get-the-fans-vote.md) whenever you show the poll. Straight after a `202` it can still be `null`, until the vote is counted: keep showing the fan's pick until it appears.

## Results

The poll's `results_visibility` says when fans may see its results. Your producers choose it for each poll in Dizplai's tools, and can change it later. If they don't choose, it's `after_vote`.

| Results visibility | Fans see results |
| - | - |
| `live` | At any time |
| `after_vote` | Once they've voted, or once voting has stopped. Your app hides the results until then |
| `after_close` | Once voting has stopped |
| `hidden` | Never. The results are for on air or your own team only |

With `after_vote`, the numbers are in every response, so anyone who reads it can see them. If results mustn't be seen early, your producers choose `after_close` or `hidden`.

The poll's `results.state` says what to show now:

* **`withheld`:** no counts yet. Show nothing, or a note such as "Results when voting closes" for `after_close`.
* **`live`:** the current votes and percentages, which change as fans vote.
* **`final`:** voting has stopped, and these are the confirmed totals. They can differ from the last live numbers.
* **A state you don't know:** treat it as `withheld`, and show no counts.

Match each result to its option by `option_id`. Percentages are rounded, so they may not add up to exactly 100.

## Keeping results current

* **Read an open poll every 10 seconds.** After a vote, show its snapshot and wait for your next read: a read straight after the vote may not include it yet.
* **After the poll closes,** keep reading until `results.state` is `final`, then stop. A `hidden` poll never shows results, so stop when it closes.
* **If your producers open it again,** it shows as `live` in lists, and its results go back to `live`, or `withheld` for `after_close`. Start reading it again.

Results reach your app and Dizplai's on-air graphics separately, so they don't change at the same moment.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.