> ## 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.

# FAQ

> Short answers to the questions client developers ask most, with links to the detail.

Every request to `api.dizplai.com` sends your API key in `x-api-key`. When a fan takes part, it also sends the fan's token in `Authorization: Bearer <the fan's token>`. A file sent to an upload's link takes neither. See [Authentication](https://developer.dizplai.com/authentication.md).

## Reading experiences

> [accordion] How do I list my experiences?
>
> [List experiences](https://developer.dizplai.com/api-reference/experiences/list-experiences.md) with your API key. Polls and Fan Voices come together, newest first, and only live ones unless you ask for others with `status`, such as `status=scheduled,live`.

> [accordion] How do I show the experiences for one collection?
>
> A collection groups experiences for a match or a show. [Get the collection](https://developer.dizplai.com/api-reference/collections/get-a-collection.md) with your API key and `include=experiences`: its experiences come in the collection's order.

> [accordion] How do I get a poll's results?
>
> [Get the poll](https://developer.dizplai.com/api-reference/polls/get-a-poll.md) with your API key. Its `results` hold the votes and percentages, when fans may see them.

> [accordion] Why are a poll's results withheld?
>
> The poll's `results_visibility`, which your producers choose for each poll, says fans can't see them yet. See [Results](https://developer.dizplai.com/experiences/polls.md#results).

> [accordion] How often should my app read?
>
> An open poll every 10 seconds, and lists and collections every 30 seconds. See [How often to read](https://developer.dizplai.com/experiences/overview.md#how-often-to-read).

> [accordion] What language is an experience in?
>
> The one in its `locale`: for now, always `en-GB`. Dizplai doesn't translate it.

## Taking part

> [accordion] How does a fan vote?
>
> [Cast a vote](https://developer.dizplai.com/api-reference/polls/cast-a-vote.md) with your API key, the fan's token, a new `Idempotency-Key` and the option's ID. The answer is `202`, with a snapshot of the results that includes the vote.

> [accordion] How do I know whether a fan has already voted?
>
> [Get the fan's vote](https://developer.dizplai.com/api-reference/polls/get-the-fans-vote.md) with your API key and the fan's token. It's `null` until they've voted and the vote is counted: straight after a `202`, keep showing the fan's pick.

> [accordion] What happens if a fan votes twice?
>
> Only their first vote counts. A later vote, from any device, still answers `202`.

> [accordion] What if the connection drops?
>
> Send the same request again with the same `Idempotency-Key`. A vote is never counted twice, a message's key is kept for 24 hours, and an upload's for 5 minutes. See [Errors and retries](https://developer.dizplai.com/errors.md#retrying).

> [accordion] How does a fan send a message?
>
> Text is one request, with your API key, the fan's token and a new `Idempotency-Key`. A voice note or photo takes three: create an upload, send the file to its link, then send the message. See [Fan Voices](https://developer.dizplai.com/experiences/fan-voices.md).

> [accordion] How does a fan see what happened to their message?
>
> [List the fan's messages](https://developer.dizplai.com/api-reference/fan-voices/list-the-fans-messages.md) with your API key and the fan's token. Each one is waiting for your team, approved, not approved or removed.

> [accordion] Can guests take part?
>
> Only if your setup with Dizplai allows them. Even then, an experience whose `requires_sign_in` is `true`, and every voice note and photo, needs a signed-in fan. See [Guests](https://developer.dizplai.com/authentication.md#guests).

## Setting up and errors

> [accordion] Can my API key ship in my app?
>
> Yes. It identifies your organisation, not a fan, and isn't a secret.

> [accordion] Where does the fan's token come from?
>
> From your own login. Dizplai checks it against your login's details, agreed when you're set up.

> [accordion] What should my app do when a request fails?
>
> Act on the error's `code`, which says whether to retry. Retry `rate_limited` and `unavailable` once `Retry-After` has passed. See [Errors and retries](https://developer.dizplai.com/errors.md).


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