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.
Reading experiences
How do I list my experiences?
How do I list my experiences?
List experiences 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.How do I show the experiences for one collection?
How do I show the experiences for one collection?
A collection groups experiences for a match or a show. Get the collection with your API key and
include=experiences: its experiences come in the collection’s order.How do I get a poll's results?
How do I get a poll's results?
Get the poll with your API key. Its
results hold the votes and percentages, when fans may see them.Why are a poll's results withheld?
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.How often should my app read?
How often should my app read?
An open poll every 10 seconds, and lists and collections every 30 seconds. See How often to read.
What language is an experience in?
What language is an experience in?
The one in its
locale: for now, always en-GB. Dizplai doesn’t translate it.Taking part
How does a fan vote?
How does a fan vote?
Cast a vote 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.How do I know whether a fan has already voted?
How do I know whether a fan has already voted?
Get the fan’s vote 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.What happens if a fan votes twice?
What happens if a fan votes twice?
Only their first vote counts. A later vote, from any device, still answers
202.What if the connection drops?
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.How does a fan send a message?
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.How does a fan see what happened to their message?
How does a fan see what happened to their message?
List the fan’s messages with your API key and the fan’s token. Each one is waiting for your team, approved, not approved or removed.
Can guests take part?
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.Setting up and errors
Can my API key ship in my app?
Can my API key ship in my app?
Yes. It identifies your organisation, not a fan, and isn’t a secret.
Where does the fan's token come from?
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.
What should my app do when a request fails?
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.