Guides
Start typing to search…

Polls via API, for broadcast integration or similar use cases

This article explains how to fetch and integrate poll data into a web page or app in a ‘Read Only’ mode that allows anonymous third-parties to access the API and display output they do not own, such as television broadcasters accessing live feeds from the event owner.

Who is this information for?

Cortex provides two polls APIs for broadcast integration in which the authorisation tokens (JWTs) are ignored so the API can be anonymously accessed for results in a read-only mode. For example, this may be useful to a television broadcaster wishing to display the results of the official poll from a sports event.


Polls - API call constructs

Below are the API calls that may be used to fetch poll data.

To fetch all polls:


💻

GET {environment-ID}/v2/polls?clientId={client-ID}

In which:

{environment-ID} is the URL shown below, depending on environment used.

{client-ID} is your client ID, assigned during onboarding.

Query parameters can be added to filter the polls. For example, the following can be used to return all polls which the Cortex user has tagged broadcaster.

💻

GET {environment-ID}/v2/polls?clientId={client-ID}&tags=broadcaster

To fetch a single poll by ID

💻

GET {environment-ID}/v2/polls/{poll-ID}

In which:

{environment-ID} is as described above.

{poll-ID} is the ID for the individual poll, which can be obtained from the 'all polls' API described above, or from the Cortex platform.

Obtaining the JSON from the polls API

Below is an extract of the JSON from the polls API - most fields have been omitted for readability to concentrate on those that are typically required for an integration. The individual poll JSON is the same regardless of the endpoint (polls versus a single poll). The only difference is the number of polls returned and the wrapper being an array. The snippet includes explanatory comments after the --- three dashes.

{
  "id":"eeeb24f4-8eb8-354b-821a-212037ed0652",
  "votes":89,
  "clientId":"CLIENTID",
  "options":[
    {
      "id":"38c613c1-2690-441f-93ef-ece7d17d98b1",
      "votes":78,
      "label":"Player 1"
    },
    {"id":"76178a23-5284-470e-ab94-1e769ad11e88",
     "votes":11,
     "label":"Player 2"
    }
  ],
  "label":"WHO IS YOUR MATCH HERO?"
}

As you can see, this is a poll where fans were asked Who is your match hero? Two options were provided - Player 1 and Player 2. So far there have been 89 votes in total, with 78 votes for player 1 and 11 votes for player 2.

Note that, if showing a percentage breakdown of the votes, you must calculate the percentage yourself - or choose instead to use the raw numbers from the API to display on the graphic. There is a percentage field, however this is deprecated and should not be used.

Updated about 1 month ago