Introduction

The Cortex Polls product includes a fan-facing front end component, with customisable styling, which can be embedded into any website or app using a brief javascript embed code, as explained in How to embed a poll. However, there may be a need for something more bespoke, so this article explains how to create a custom polls component.

Endpoints

Base URL (production-standard): https://polls.fanscore.com

Base URL (production-USA): https://polls.fanscore.us

General poll actions:

/v2/polls?clientId={clientId}

Method	Description	Parameters
GET	Get a list of polls for a given client	page, size, active, from, to, tags, linkedIds, language, fallbackLanguage

/v1/answers?clientId={clientId}

Method	Description	Parameters
GET	Get answers (votes)	page, size, from, to

Actions relating to a specific poll:

/v2/polls/{pollId}

Method	Description	Parameters
GET	Get a specific poll	N/A

/v1/polls/{pollId}/answer

Method	Description	Parameters
POST	Submit an answer (vote) to a poll. A token is required. See below for further details.	N/A

Parameters

page is a number representing the index of the page to return. The default is page=0, meaning only one page - the first page - should be returned.

size is a number representing the page size. The default is size=100.

active is a boolean e.g. active=true. If set to true then only active polls are returned, meaning polls that are published, open and not yet closed.

from is a timestamp in the RFC3339 format e.g. from=2025-12-31T23:59:59Z. If used, the endpoint will return polls that open on or after the specified date and time.

to is a timestamp in the RFC3339 format e.g. to=2026-12-31T23:59:59Z. If used, the endpoint will return polls that open before the specified date and time.

tags is a comma-delimited list of tags e.g. tags=app,web. It returns only the articles with at least one of those tags.

linkedIds is a delimited list of data providers and their internal data IDs. The semicolon is the delimiter. The format is SOURCE:ID,ID,ID;SOURCE:ID. For example linkedIds=OPTA_FOOTBALL_PLAYER:3992,3492;OPTA_FOOTBALL_TEAM:t43.

{language} is a code for the declared language for the poll, set from a drop-down list in Cortex, and following the BCP-47 standard. For example language=en.

fallbackLanguages is the list of fallback languages, to be used if there is no version of a given poll available in the primary language. Fallback languages should be comma separated, and specified in the order in which they should be prioritised. For example fallbackLanguages=en-US,es.

Response

Base

Key	Data Type	Required	Notes
id	string	Y	Unique identifier per poll, generated by the backend on poll creation.
clientId	string	Y	Unique identifier for the client, as per client in Cortex.
label	string	Y	The title of the poll.
language	string	Y	Represents the language in which the poll is created. Where the poll is multilingual, this will specify the language of the variant that is included in the response.
publishDate	string? (rfc3339)	Y	The date the poll should be published from.
validFrom	string? (rfc3339)	Y	The date the poll should be open and available for voting. Between `publishDate` and `validFrom`, the expected behaviour is that the poll is visible but in a pending or preview state with no voting possible.
validTo	string? (rfc3339)	Y	The date the poll should be closed, and no longer available for voting.
publishResultDate	string? (rfc3339)	Y	The date from which the poll begins showing fans the results of the poll.
active	Boolean	N	Indicates that the poll is currently open. That is, the current date is between the `validFrom` and the `validTo` dates.
tags	string array	N	Tags associated with the poll, which can be used for searching.
linkedIds	linkedId array (see below)	N	A list of associated IDs related to the poll, identical to other Cortex systems. This will be an ID relating to an external data provider such as Opta, and will allow for searching.
heroMedia	heroMedia (see below)	Y	Content block to render at the top of the poll. Follows the same logic as hero content in other Cortex systems.
sponsorImageUrl	string	N	The image that should be used as a sponsor banner.
uiConfig	object	N	Represents the Cortex user's chosen layout and styling.
showNumberOfVotes	Boolean	Y	`true` indicates that the number of votes should be displayed, set by the Cortex user.
votes	number	N	The total number of votes against the poll so far.
shareable	Boolean	Y	`true` indicates that share buttons should be included.
options	array	Y	The list of options or answers which fans can select from when interacting with the poll, as well as the success message which fans should be shown following the vote interaction.

linkedId

Key	Data Type	Required	Notes
text	string	Y	Textual representation of the linked ID (used for rendering in Cortex).
sourceSystem	string	Y	The data source of the linked ID, e.g. `OPTA_FOOTBALL_TEAM` = football team from Opta's feeds.
sourceSystemId	string	Y	The ID of the linked item in the data source's system.

heroMedia

Key	Data Type	Required	Notes
content	content	N	`contentType` may be `IMAGE` or `VIDEO`. If `contentType: "IMAGE"`, `imageUrl` will be provided. If `contentType: "VIDEO"`, then `sourceSystem: "YOUTUBE"`, `link` and `sourceSystemId` will all be provided.

uiConfig

Field	Type	Description
optionImageOrientation	string	Indicates the Cortex user's chosen option image orientation, being either `"PORTRAIT"` or `"LANDSCAPE`"
layout	layout	Indicates the Cortex user's chosen option layout, being either `"LIST"` or `"HORIZONTAL"`.
themeId	string	The unique identifier of the theme applied to the poll.
theme	object	The details of the theme to be applied to the poll. See explanation below.

theme

Field	Type	Description
titleFont	font	See explanation below.
captionFont	font	See explanation below.
captionFontColor	string	Value provided as a hexadecimal code e.g. `#000000"`.
backgroundColor	string	Value provided as a hexadecimal code e.g. `"#000000"`.
backgroundBorderColor	string	Value provided as a hexadecimal code e.g. `"#000000"`.
backgroundRadius	string	Value can be one of `"SHARP"`, or `"SMOOTH"`
buttonFont	Font	See explanation below.
buttonFontColor	string	Value provided as a hexadecimal code e.g. `"#000000"`.
buttonBackgroundColor	string	Value provided as a hexadecimal code e.g. `"#000000"`.
buttonBorderColor	string	Value provided as a hexadecimal code e.g. `"#000000"`.
buttonRadius	string	Value can be one of `"SHARP"`, `"SMOOTH"`, or `"PILL"`
optionFont	font	See explanation below.
optionRadius	string	Value can be one of `"SHARP"`, `"SMOOTH"`, or `"PILL"`
selectedOptionFontColor	string	Value provided as a hexadecimal code e.g. `"#000000"`.
selectedOptionBackgroundColor	string	Value provided as a hexadecimal code e.g. `"#000000"`.
selectedOptionBorderColor	string	Value provided as a hexadecimal code e.g. `"#000000"`.
unselectedOptionFontColor	string	Value provided as a hexadecimal code e.g. `"#000000"`.
unselectedOptionBackgroundColor	string	Value provided as a hexadecimal code e.g. `"#000000"`.
unselectedOptionBorderColor	string	Value provided as a hexadecimal code e.g. `"#000000"`.
checkIconBackgroundColor	string	Value provided as a hexadecimal code e.g. `"#000000"`.
checkIconBorderColor	string	Value provided as a hexadecimal code e.g. `"#000000"`.

Font

Field	Type	Description
name	string	The font name
size	number	The font size
url	string	The URL on which the font file is hosted.

options

Field	Type	Description
uiIndex	integer	Indicates the sort order set in Cortex.
selected	Boolean	If the fan has previously voted, `true` indicates the option they voted for.
imageURL	string	If images have been added to the poll options in Cortex, then an image URL will be provided.
label	string	The name of the poll option.
votes	number	Indicates the number of votes submitted so far for the poll option.
id	string	The unique identifier for the poll option.
postVoteMessage	object	The details to be displayed in the success message following a successful vote. See below.

postVoteMessage

Field	Type	Required	Description
link	string	N	If a link has been added to the success message in Cortex, then a URL will be provided.
linkText	string	N	If a link has been added to the success message in Cortex, then text will be provided. It is expected that this would be used as display text for the link.
message	string	Y	The success message written in Cortex.
content	object	N	`contentType` may be `IMAGE`, `VIDEO`, `FORM`, or `PROMO`. If `contentType: "IMAGE"`, `imageUrl` will be provided. If `contentType: "VIDEO"`, then `sourceSystem: "YOUTUBE"`, `link` and `sourceSystemId` will all be provided. If `contentType: "FORM"`, then `sourceSystemID` will be provided, with the value being the ID of a Cortex form to be displayed in the success message. If `contentType: "PROMO"`, then `sourceSystemID` will be provided, with the value being the ID of a Cortex promo asset to be displayed in the success message. If using the Cortex embed code for either forms or promo assets, the fan's auth ID should be passed from the poll to the promo asset or form.

Passing in a token

If Cortex SSO is used, and the fan is logged in, then the fan's token should be passed in, in the Authorization header, when fetching the poll and when submitting a vote. If this is not possible - e.g. because the fan is logged out - then an anonymous token should be generated, then passed in in the same way.

This will help limit fans' ability to vote more than once, it will enable display of the fan's previous vote, and it will also enable segmentation in Audience Builder (if used) based on poll interactions.

Upsert answer (submit a vote)

/v1/polls/{pollId}/answer

Method	Description	Parameters
POST	Submit an answer (vote) to a poll.	N/A

Requires a valid Access Token in the Authorization header.

The body must be a JSON object containing a single key: answerId. This ID is the unique identifier for the specific option the fan selected within the poll. For example:

{
  "answerId": "337f3973-9d25-4788-9e56-3eb780fb9841"
}