> ## 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. # Get the fan's vote > Gets the vote that counts for the fan, so your app can show their choice on any device and knows when they've voted. ## OpenAPI ````yaml /experiences/api-reference/experiences.openapi.yaml get /polls/{poll_id}/votes/me openapi: 3.1.0 info: title: 'Dizplai API: Experiences' version: 1.0.0 summary: Read polls, Fan Voices and collections, and let fans vote and send messages. description: > Show polls and Fan Voices in your own apps and sites, and let fans take part: read experiences and collections, send fans' votes and messages, and read back a fan's own vote and messages. **Headers.** Send `x-api-key`, your organisation's API key, on every request. When a fan takes part, or reads their own vote or messages, add their token from your own login as `Authorization: Bearer `. **Names.** An experience is one thing fans take part in: a poll or a Fan Voice. A collection groups experiences for a match or show, and an experience can be in many collections. Every ID is a UUID: store it in a UUID column or as text, and never parse it. **Conventions.** snake_case fields; `after` and `limit` paging (50 by default, 100 at most) with `{items, next}`; errors are RFC 9457 problems with a stable `code` and a `request_id`, and every response carries `x-request-id`. Types, statuses and codes can gain values within v1, so ignore one you don't know. **Refreshing.** Read an open poll every 10 seconds and lists every 30 seconds, and wait as long as `Retry-After` says after a `429` or `503`. The Experiences guide has the details. contact: name: Dizplai servers: - url: https://api.dizplai.com/v1 description: The Dizplai API. security: - apiKey: [] tags: - name: Experiences description: >- Everything fans can take part in, in one list: build a match or show screen from it, drawing each experience by its type. - name: Collections description: >- Groups of experiences, one for each match or show, to organise your screens. An experience can be in many collections, in its own order in each. - name: Polls description: >- A poll asks fans one question with a short list of answers. Read polls and their results, send a fan's vote, and read back the vote they made. - name: Fan Voices description: >- A Fan Voice asks fans to reply in their own words, with text, a voice note or a photo. Read a Fan Voice, send a fan's message, and show the fan what happened to it. Fans never see each other's messages. paths: /polls/{poll_id}/votes/me: parameters: - name: poll_id in: path required: true description: The poll's ID, from a list of experiences or polls. schema: $ref: '#/components/schemas/PollId' get: tags: - Polls summary: Get the fan's vote description: >- Gets the vote that counts for the fan, so your app can show their choice on any device and knows when they've voted. operationId: getMyPollVote responses: '200': description: >- The fan's vote. Show their choice from it whenever you show the poll, and use it to tell when to show after_vote results. vote is null until the fan has voted and their first vote is counted: a fan who hasn't voted gets null, never 404. Not cached, as the answer belongs to one fan. headers: x-request-id: $ref: '#/components/headers/RequestId' Cache-Control: $ref: '#/components/headers/NoStore' content: application/json: schema: $ref: '#/components/schemas/PollMyVoteResult' examples: voted: $ref: '#/components/examples/PollMyVote' notVoted: $ref: '#/components/examples/PollMyVoteNone' '401': $ref: '#/components/responses/FanUnauthorised' '403': $ref: '#/components/responses/ReadForbidden' '404': $ref: '#/components/responses/PollNotFound' '429': $ref: '#/components/responses/TooManyRequests' '503': $ref: '#/components/responses/ReadUnavailable' security: - apiKey: [] fanToken: [] components: schemas: PollId: type: string description: A poll's ID, a UUID. format: uuid examples: - 0192fa7b-8d41-7bbc-9b58-02311fc6ef8e PollMyVoteResult: type: object required: - vote description: The fan's vote on this poll, or null if they haven't voted. properties: vote: anyOf: - $ref: '#/components/schemas/PollMyVote' - title: No vote yet type: 'null' description: >- The vote that counts, or null if the fan hasn't voted or their first vote isn't counted yet. PollMyVote: title: Vote type: object required: - option_id - voted_at description: 'The vote that counts: the fan''s first. Later votes are never counted.' properties: option_id: $ref: '#/components/schemas/OptionId' voted_at: $ref: '#/components/schemas/Timestamp' description: When the vote was accepted. Problem: type: object required: - type - code - title - status - request_id description: >- What went wrong, in the same shape for every error: an RFC 9457 problem with a stable code. Act on code, which never changes meaning within a version, and on the HTTP status for a code you don't know. Quote request_id to support. properties: type: type: string format: uri-reference description: >- One URL per code: https://api.dizplai.com/problems/ followed by the code with hyphens, such as https://api.dizplai.com/problems/unknown-option for unknown_option. code: type: string x-extensible-enum: - invalid_request - unknown_option - not_open - media_not_accepted - invalid_upload - invalid_api_key - invalid_fan_token - forbidden - fan_blocked - sign_in_required - message_limit_reached - not_found - idempotency_conflict - rate_limited - unavailable description: > More codes may be added: for one you don't know, act on the HTTP status. | code | Status | Retry? | Meaning | |---|---|---|---| | invalid_request | 400 | No | The body or a parameter is invalid, or a required header such as Idempotency-Key is missing. | | unknown_option | 400 | No; read the poll again | An option ID the poll doesn't have. | | not_open | 400 | No; read the experience again | The experience isn't taking votes or messages: it isn't live yet, or votes have stopped. | | media_not_accepted | 400 | No | The Fan Voice doesn't take this kind of message, or the file's type or size is outside the limits. | | invalid_upload | 400 | No; upload again | The upload_id is unknown, already used or another fan's, or the file was never uploaded or its type or size differs from what you asked for. | | invalid_api_key | 401 | No | A missing or invalid x-api-key. | | invalid_fan_token | 401 | Once, with a fresh token | A missing, invalid or expired fan token, or one from another organisation's login. It carries WWW-Authenticate. | | forbidden | 403 | No | Your API key isn't allowed to make this request. | | fan_blocked | 403 | No | The fan is blocked from this Fan Voice. | | sign_in_required | 403 | No; ask the fan to sign in | A guest on an experience that needs a signed-in fan, or a guest's voice note or photo. | | message_limit_reached | 403 | No | The fan has used up this Fan Voice's messages of this kind. | | not_found | 404 | No | Not found, or not yours. | | idempotency_conflict | 409 | No | An Idempotency-Key reused with a different body while it's kept: 24 hours, or 5 minutes for an upload. | | rate_limited | 429 | After Retry-After | Too many requests. | | unavailable | 503 | After Retry-After | Votes or messages can't be taken right now. | title: type: string description: A short title for the code, such as Not open. It doesn't change. status: type: integer description: The HTTP status code. minimum: 400 maximum: 599 detail: type: string description: >- What went wrong, in plain English. It can change, so don't act on it. request_id: type: string description: Matches the x-request-id response header. errors: type: array description: Field-level validation errors, with invalid_request. items: type: object required: - pointer - message properties: pointer: type: string description: A JSON Pointer to the field. message: type: string description: What's wrong with that field. OptionId: type: string description: >- An option's ID, what a fan's vote sends. Created with the option, opaque, and never reused, even if the option is removed before the poll goes live. Correcting an option's label keeps its ID. format: uuid examples: - 01a1f97a-b538-778f-bad7-0c1c35ff701c Timestamp: type: string format: date-time description: A date and time, RFC 3339, in UTC. headers: RequestId: description: The request's ID. Quote it to support. schema: type: string NoStore: description: 'no-store: the answer belongs to one fan, so no cache may keep it.' schema: type: string const: no-store WwwAuthenticate: description: >- With invalid_fan_token only: Bearer error="invalid_token", with an error_description. schema: type: string RetryAfter: description: >- How long to wait before retrying, as a whole number of seconds. Sent with every 429 and 503. schema: type: integer minimum: 0 examples: PollMyVote: summary: The fan has voted value: vote: option_id: 01a1f97a-b538-778f-bad7-0c1c35ff701c voted_at: '2026-11-21T20:31:12Z' PollMyVoteNone: summary: The fan hasn't voted value: vote: null responses: FanUnauthorised: description: >- A missing or invalid x-api-key (invalid_api_key), or a missing, invalid or expired fan token, or one from another organisation's login (invalid_fan_token). Only invalid_fan_token carries WWW-Authenticate: refresh the fan's token and retry once. headers: x-request-id: $ref: '#/components/headers/RequestId' WWW-Authenticate: $ref: '#/components/headers/WwwAuthenticate' content: application/problem+json: schema: $ref: '#/components/schemas/Problem' examples: invalid_fan_token: summary: invalid_fan_token value: type: https://api.dizplai.com/problems/invalid-fan-token code: invalid_fan_token title: Invalid fan token status: 401 detail: The fan's token has expired. request_id: 01JBX8P2R4T6V8X0Z2B4D6F8H0 invalid_api_key: summary: invalid_api_key value: type: https://api.dizplai.com/problems/invalid-api-key code: invalid_api_key title: Invalid API key status: 401 detail: The x-api-key isn't recognised. request_id: 01JBX8P2R4T6V8X0Z2B4D6F8H0 ReadForbidden: description: >- Not allowed for this caller or origin (forbidden), such as a browser Origin your organisation hasn't registered, or a platform key sent from a browser. Retrying won't help: check the key and your registered origins. headers: x-request-id: $ref: '#/components/headers/RequestId' content: application/problem+json: schema: $ref: '#/components/schemas/Problem' examples: forbidden: summary: forbidden value: type: https://api.dizplai.com/problems/forbidden code: forbidden title: Forbidden status: 403 detail: This origin isn't registered for this organisation. request_id: 01JBX8P2R4T6V8X0Z2B4D6F8H0 PollNotFound: description: >- The poll doesn't exist, isn't yours, or was taken down or deleted (not_found). headers: x-request-id: $ref: '#/components/headers/RequestId' content: application/problem+json: schema: $ref: '#/components/schemas/Problem' examples: not_found: summary: not_found value: type: https://api.dizplai.com/problems/not-found code: not_found title: Not found status: 404 detail: No such poll. request_id: 01JBX8P2R4T6V8X0Z2B4D6F8H0 TooManyRequests: description: >- Too many requests (rate_limited). Wait the number of seconds in Retry-After, then retry. headers: x-request-id: $ref: '#/components/headers/RequestId' Retry-After: $ref: '#/components/headers/RetryAfter' content: application/problem+json: schema: $ref: '#/components/schemas/Problem' examples: rate_limited: summary: rate_limited value: type: https://api.dizplai.com/problems/rate-limited code: rate_limited title: Rate limited status: 429 detail: Too many requests. Retry after 2 seconds. request_id: 01JBX8P2R4T6V8X0Z2B4D6F8H0 ReadUnavailable: description: >- This can't be read right now (unavailable). Wait the number of seconds in Retry-After, then retry, and keep showing what you last read. headers: x-request-id: $ref: '#/components/headers/RequestId' Retry-After: $ref: '#/components/headers/RetryAfter' content: application/problem+json: schema: $ref: '#/components/schemas/Problem' examples: unavailable: summary: unavailable value: type: https://api.dizplai.com/problems/unavailable code: unavailable title: Unavailable status: 503 detail: This can't be read right now. Retry after 5 seconds. request_id: 01JBX8P2R4T6V8X0Z2B4D6F8H0 securitySchemes: apiKey: type: apiKey in: header name: x-api-key description: >- 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. fanToken: type: http scheme: bearer description: >- The fan's token from your own login, sent as `Authorization: Bearer `: a signed-in fan's or a guest's. Dizplai checks it against your login's details, agreed when you're set up, and a guest's token carries the guest claim agreed at the same time. Needed to vote, upload, send a message, and read the fan's own vote or messages. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.