Skip to main content
GET
Get a poll

Authorizations

x-api-key
string
header
required

Your organisation's API key, supplied by Dizplai. Send it on every request. It isn't a secret, so it can ship in your app: what a fan does is protected by the fan's token.

Path Parameters

poll_id
string<uuid>
required

The poll's ID, from a list of experiences or polls. A poll's ID, a UUID.

Example:

"0192fa7b-8d41-7bbc-9b58-02311fc6ef8e"

Response

The poll. results.state says what to show now, and results_visibility when fans may see results. While the poll is open, read it every 10 seconds. After a vote, show the vote's snapshot first: a read straight after the vote may not include it yet.

A poll: one question, its options, and the results when fans may see them. Show the question with one choice for each option, and send the chosen option's id as the fan's vote.

id
string<uuid>
required

A poll's ID, a UUID.

Example:

"0192fa7b-8d41-7bbc-9b58-02311fc6ef8e"

type
enum<string>
required

Tells polls apart from other experiences in a list.

Available options:
poll
status
string
required

Whether fans can take part now. scheduled: coming up, and goes live at starts_at. live: taking votes or messages. closed: taking part has stopped; it can reopen. An experience your producers take down or delete drops out of lists, and getting it answers 404. More statuses may be added: treat one you don't know as closed to taking part.

starts_at
string<date-time> | null
required

When it's due to open. Null if your producers open it by hand.

ends_at
string<date-time> | null
required

When it's due to close. Null if no closing time is set.

metadata
object
required

Tags for finding and grouping things, such as the match or show they're about. Filter lists by them with metadata[key]=value. Up to 50 keys of up to 40 characters, values up to 500. One key is reserved, event_id, set by your producers; every other key is yours, and never interpreted.

locale
string
required

The language the experience's text is written in, such as en-GB.

Maximum string length: 35
Pattern: ^[A-Za-z]{2,3}(-[A-Za-z0-9]{2,8})*$
Example:

"en-GB"

created_at
string<date-time>
required

When the poll was created.

updated_at
string<date-time>
required

Changes when anything a fan can see changes, including visible results, but not when only withheld results change.

results_visibility
string
required

When fans may see results. live: always. after_vote: once they've voted, or once voting has stopped; the results are in every read, so your app hides them until then. after_close: once voting has stopped; until then results are withheld. hidden: never; results are always withheld, for on air or your own team only. Results that mustn't be seen early use after_close or hidden. More values may be added: whatever the value, results.state says what to show now.

results
Withheld · object
required

What to show for the poll's results, by state. withheld: fans may not see them yet, as results_visibility says, and nothing else is sent. live: the current counts. final: voting has stopped and these are the confirmed totals, which can differ from the last live numbers, and go back to live if the poll opens again. Counts are never null: 0 means no votes. More states may be added: treat a state you don't know as withheld: show no counts.

requires_sign_in
boolean
required

True if only signed-in fans may take part: show a guest your sign-in prompt instead. A guest's vote or message here answers 403 (sign_in_required). Voice notes and photos are always for signed-in fans.

question
string
required

The question fans answer.

Required string length: 1 - 300
options
object[]
required

Every option, 2 to 10, in the poll's order. Once the poll has gone live, its number of options is fixed: your producers can correct an option's label, such as a typo, but can't add or remove options.

Required array length: 2 - 10 elements
subtitle
string

Supporting text under the question.

Maximum string length: 300