COVERITLIVE API - POLL/LIST (V. 2.0)

The Request

This method provides a list of polls for an event. All polls are returned, including those that have been ended or hidden. All relevant data for each poll is returned.

URL:
https://api.coveritlive.com/remote/2/poll/list
Response Format:
JSON
HTTP Method(s):
GET
API Rate Limited:
false
In addition to the parameters listed in the Request Parameters section, the poll/list method also includes the following parameters:

Parameter Description Required
event_code The event code for the event for which poll data is being retreived. Each CiL event that is created is assigned a unique event code that identifies it in the database - The event owner can find this value after creating a new event, by selecting the "altcast_code" which is found in their Viewer Window embed code (e.g. the event code is "46e6cd22b5" in "altcast_code=46e6cd22b5"). This value is also returned by the event/list API method. yes
status

A pipe (|) delimited list of poll types to retrieve. Possible values include:

published - poll has been created

ended - poll has been closed to further votes. An event entry has been added containing final poll results.

hidden - poll has been removed from display

yes

The Response

The poll listing data is returned in the data field of a general response. This field will consist of an array of poll objects.

Poll objects have the following fields:

Field Name Field Value(s) Explanation
poll_id {string} The ID of the poll. Can be used in further requests against a single poll
status {string} One of: published, ended, hidden. When a poll is first created, it is in a published state. When a poll has been closed to further votes, it is in a ended state. Finally, a poll can be unpublished, which would leave it in a hidden state.
published_timestamp {integer} The time that the poll was published, in seconds since the Unix Epoch. The timestamp is in GMT time.
modified_timestamp {integer} The last time that the poll was modified, in seconds since the Unix Epoch. The timestamp is in GMT time.
question {string} The poll question.
answers {array} An array of answer objects

Answer objects have the following fields:

Field Name Field Value(s) Explanation
result {string} The number of votes for this answer
answer {string} The text of this poll answer

Example response to a successful poll/list request:


{
	"result":"success",
	"message":"true",
	"type":"poll",
	"action":"list",
	"version":2,
	"data":[
		{
			"poll_id":"13921238",
			"status":"published",
			"published_timestamp":1319464335,
			"modified_timestamp":1319464335,
			"question":"Sample poll question",
			"answers":[
				{
					"result":"\"\"",
					"answer":"Sample answer 1"
				},
				{
					"result":"\"\"",
					"answer":"Sample answer 2"
				}
			]
		},
		{
			"poll_id":"13926018",
			"status":"ended",
			"published_timestamp":1319470140,
			"modified_timestamp":1319470140,
			"question":"Sample poll question 2",
			"answers":[
				{
					"result":"\"\"",
					"answer":"Sample answer 1"
				},
				{
					"result":"\"\"",
					"answer":"Sample answer 2"
				},
				{
					"result":"\"\"",
					"answer":"Sample answer 3"
				}
			]
		}
	]
}	

poll/list Error Responses

A variety of error responses (in addition to the common error responses) to poll/list requests, and instructions on how to rectify them:

result response message response solution
missing_status_param Required parameter empty: status. Ensure that the status parameter is present for poll/list requests.
invalid_status_param Event status parameter contains invalid values. Ensure that the status parameter only contains valid values (pipe delimited list, which can include 'published', 'ended' and 'hidden').