The Poll Everywhere API

Getting started

We're really stoked that you want to integrate Poll Everywhere into your application. We built this API with goal of providing developers with a simple, reliable, and enjoyable way to integrate Poll Everywhere into applications.

We ♥ JSON

JSON key-value data structures are used throughout the API application to persist and modify data to the web application. Typically resources will include a root key that corresponds with the name of the name of the resource; from example, multiple choice polls all have the root key 'multiple_choice_poll'.

Authentication

A Poll Everywhere username and password is used to login to the API and manipulate polls on an account. These credentials can be created at Poll Everywhere.

The credentials can be configured on the Poll Everywhere gem or manually via HTTP Basic authentication (More information on HTTP Basic credentials an encoding can be found at Wikipedia).

PollEverywhere.config do
  username  "my_pollev_username"
  password  "my_pollev_password"
end

Support

We regularly run a suite of integration tests against our API to make sure that our API is running smoothly.

Now lets roll up our sleeves and get our hands dirty!

Polls

Multiple choice polls

These polls are great for collecting structured information from audiences if you want to define a set of answers that participants may choose from.

Attributes

multiple_choice_poll
Root key for multiple choice poll data.
id
updated_at
The date and time the poll was last updated.
title
Name of the poll. The title is visible when viewing charts, tables, and other views.
opened_at
Date and time that the poll was started.
permalink
An obscufated ID that's used as a private link for sharing the poll
state
Determines whether or not a poll can recieve responses. If the state is 'closed', the poll won't receive responses from the audience. If the poll is 'opened', the poll can receive responses from the audience. If the state is 'maxed_out', the poll won't receive responses until the account is upgraded to support more poll responses.
sms_enabled
Allow participants to respond to the poll using SMS text messages.
twitter_enabled
Allow participants to respond to the poll with Twitter.
web_enabled
Allow participants to respond to the poll with their web browsers through the poll owners PollEv.com page.
sharing_enabled
Allow participants to respond to the poll through the obscufated permalink.
options
The possible choices that people choose for a poll.
id
Unique identifier for the option. This is primarily used to keep track of what option attributes are changed.
value
Text that is displayed in the chart that represents what a participant chooses when they response to a poll.
keyword
The keyword that's used to submit a response to the poll from participants that use SMS.

Creating a multiple choice poll

Specify a title and a few options to create a multiple choice poll.

@mcp = PollEverywhere::MultipleChoicePoll.from_hash(:title => 'Hey dude!', :options => %w[red blue green]).save
curl -X POST -H "Content-Type: application/json" -H "Accept: application/json" -H "Authorization: Basic YXBpdGVzdDphcGl0ZXN0" -d "{\
  \"multiple_choice_poll\": {\"id\":null,\"updated_at\":null,\"title\":\"Hey dude\!\",\"opened_at\":null,\"permalink\":null,\"state\":null,\"sms_enabled\":null,\"twitter_enabled\":null,\"web_enabled\":null,\"sharing_enabled\":null,\"options\":[{\"id\":null,\"value\":\"red\",\"keyword\":null},{\"id\":null,\"value\":\"blue\",\"keyword\":null},{\"id\":null,\"value\":\"green\",\"keyword\":null}]}\
}" "http://api.polleverywhere.com/multiple_choice_polls"

Changing the title of a multiple choice poll

@mcp.title = "I like different titles"
@mcp.save
curl -X PUT -H "Content-Type: application/json" -H "Accept: application/json" -H "Authorization: Basic YXBpdGVzdDphcGl0ZXN0" -d "{\
  \"multiple_choice_poll\": {\"id\":3015725,\"updated_at\":null,\"title\":\"I like different titles\",\"opened_at\":null,\"permalink\":\"MTIwOTIyNjk0Nw\",\"state\":\"opened\",\"sms_enabled\":null,\"twitter_enabled\":null,\"web_enabled\":null,\"sharing_enabled\":null,\"options\":[{\"id\":16453875,\"value\":\"red\",\"keyword\":null},{\"id\":16453877,\"value\":\"blue\",\"keyword\":null},{\"id\":16453879,\"value\":\"green\",\"keyword\":null}]}\
}" "http://api.polleverywhere.com/multiple_choice_polls/MTIwOTIyNjk0Nw"

Starting and stopping multiple choice polls

To prevent audience members from responding to a poll, change the poll state to "closed".

@mcp.stop
curl -X PUT -H "Content-Type: application/json" -H "Accept: application/json" -H "Authorization: Basic YXBpdGVzdDphcGl0ZXN0" -d "{\
  \"multiple_choice_poll\": {\"id\":3015725,\"updated_at\":null,\"title\":\"I like different titles\",\"opened_at\":null,\"permalink\":\"MTIwOTIyNjk0Nw\",\"state\":\"closed\",\"sms_enabled\":null,\"twitter_enabled\":null,\"web_enabled\":null,\"sharing_enabled\":null,\"options\":[{\"id\":16453875,\"value\":\"red\",\"keyword\":null},{\"id\":16453877,\"value\":\"blue\",\"keyword\":null},{\"id\":16453879,\"value\":\"green\",\"keyword\":null}]}\
}" "http://api.polleverywhere.com/multiple_choice_polls/MTIwOTIyNjk0Nw"

To open it back up and allow responses to come on through change the state to "opened".

@mcp.start
curl -X PUT -H "Content-Type: application/json" -H "Accept: application/json" -H "Authorization: Basic YXBpdGVzdDphcGl0ZXN0" -d "{\
  \"multiple_choice_poll\": {\"id\":3015725,\"updated_at\":null,\"title\":\"I like different titles\",\"opened_at\":null,\"permalink\":\"MTIwOTIyNjk0Nw\",\"state\":\"opened\",\"sms_enabled\":null,\"twitter_enabled\":null,\"web_enabled\":null,\"sharing_enabled\":null,\"options\":[{\"id\":16453875,\"value\":\"red\",\"keyword\":null},{\"id\":16453877,\"value\":\"blue\",\"keyword\":null},{\"id\":16453879,\"value\":\"green\",\"keyword\":null}]}\
}" "http://api.polleverywhere.com/multiple_choice_polls/MTIwOTIyNjk0Nw"

Archive the poll results

To clear out any current results on a poll, you call the archive method

@mcp.archive
curl -X DELETE -H "Content-Type: application/json" -H "Accept: application/json" -H "Authorization: Basic YXBpdGVzdDphcGl0ZXN0" "http://api.polleverywhere.com/multiple_choice_polls/MTIwOTIyNjk0Nw/results/archive"

Permanently delete the poll results

To permanetly delete the current results on a poll, you call the clear method

@mcp.clear
curl -X DELETE -H "Content-Type: application/json" -H "Accept: application/json" -H "Authorization: Basic YXBpdGVzdDphcGl0ZXN0" "http://api.polleverywhere.com/multiple_choice_polls/MTIwOTIyNjk0Nw/results"

Retrieving poll results

To retrieve poll results list

@mcp.results
curl -H "Content-Type: application/json" -H "Accept: application/json" -H "Authorization: Basic YXBpdGVzdDphcGl0ZXN0" "http://api.polleverywhere.com/multiple_choice_polls/MTIwOTIyNjk0Nw/results"

Delete a multiple choice poll

When you're totally finished with the poll and you want to tidy things up a bit, you can delete polls

@mcp.destroy
curl -X DELETE -H "Content-Type: application/json" -H "Accept: application/json" -H "Authorization: Basic YXBpdGVzdDphcGl0ZXN0" "http://api.polleverywhere.com/multiple_choice_polls/MTIwOTIyNjk0Nw/results"

Free text polls

These polls are used to collect short answers or unstructured responses from participants.

Attributes

free_text_poll
Root key for free text poll data.
id
updated_at
The date and time the poll was last updated.
title
Name of the poll. The title is visible when viewing charts, tables, and other views.
opened_at
Date and time that the poll was started.
permalink
An obscufated ID that's used as a private link for sharing the poll
state
Determines whether or not a poll can recieve responses. If the state is 'closed', the poll won't receive responses from the audience. If the poll is 'opened', the poll can receive responses from the audience. If the state is 'maxed_out', the poll won't receive responses until the account is upgraded to support more poll responses.
sms_enabled
Allow participants to respond to the poll using SMS text messages.
twitter_enabled
Allow participants to respond to the poll with Twitter.
web_enabled
Allow participants to respond to the poll with their web browsers through the poll owners PollEv.com page.
sharing_enabled
Allow participants to respond to the poll through the obscufated permalink.
keyword
The keyword that's used to submit a response to the poll from participants that use SMS.

Create free text polls

Creating a free text poll is similar to building a multiple choice poll, just without the options attribute.

@ftp = PollEverywhere::FreeTextPoll.from_hash(:title => "What is the meaning of life?").save
curl -X POST -H "Content-Type: application/json" -H "Accept: application/json" -H "Authorization: Basic YXBpdGVzdDphcGl0ZXN0" -d "{\
  \"free_text_poll\": {\"id\":null,\"updated_at\":null,\"title\":\"What is the meaning of life?\",\"opened_at\":null,\"permalink\":null,\"state\":null,\"sms_enabled\":null,\"twitter_enabled\":null,\"web_enabled\":null,\"sharing_enabled\":null,\"keyword\":null}\
}" "http://api.polleverywhere.com/free_text_polls"

Modify a free text poll

Change the title attribute to change the poll

@ftp.title = "No really, what is the meaning of life?"
@ftp.save
curl -X PUT -H "Content-Type: application/json" -H "Accept: application/json" -H "Authorization: Basic YXBpdGVzdDphcGl0ZXN0" -d "{\
  \"free_text_poll\": {\"id\":3015727,\"updated_at\":null,\"title\":\"No really, what is the meaning of life?\",\"opened_at\":null,\"permalink\":\"MjA5Mzg2OTk4OQ\",\"state\":\"opened\",\"sms_enabled\":null,\"twitter_enabled\":null,\"web_enabled\":null,\"sharing_enabled\":null,\"keyword\":null}\
}" "http://api.polleverywhere.com/free_text_polls/MjA5Mzg2OTk4OQ"

Archive the poll results

To clear out any current results on a poll, you call the archive method

@ftp.archive
curl -X DELETE -H "Content-Type: application/json" -H "Accept: application/json" -H "Authorization: Basic YXBpdGVzdDphcGl0ZXN0" "http://api.polleverywhere.com/free_text_polls/MjA5Mzg2OTk4OQ/results/archive"

Permanently delete the poll results

To permanetly delete the current results on a poll, you call the clear method

@ftp.clear
curl -X DELETE -H "Content-Type: application/json" -H "Accept: application/json" -H "Authorization: Basic YXBpdGVzdDphcGl0ZXN0" "http://api.polleverywhere.com/free_text_polls/MjA5Mzg2OTk4OQ/results"

Retrieving poll results

To retrieve poll results list

@ftp.results
curl -H "Content-Type: application/json" -H "Accept: application/json" -H "Authorization: Basic YXBpdGVzdDphcGl0ZXN0" "http://api.polleverywhere.com/free_text_polls/MjA5Mzg2OTk4OQ/results"

Delete a free text poll

@ftp.destroy
curl -X DELETE -H "Content-Type: application/json" -H "Accept: application/json" -H "Authorization: Basic YXBpdGVzdDphcGl0ZXN0" "http://api.polleverywhere.com/free_text_polls/MjA5Mzg2OTk4OQ/results"

Participants

Participants are used to identify who is responding to your polls.

Attributes

user
Root key for participant data.
first_name
First name of the participant
last_name
Last name of the participant
email
Email address of pariticpant
phone_number
Phone number associated with the participant.
responding_as
This is used to identify the participant in reports.
private_data
This is used to identify the participant in reports (such as a social security number) where access is limited by the account administrator.
password
Password that the participant may use to login to their account and view their response history.
account_subuser
Optional boolean. Try to make this participant a full subuser (can create polls) on the user account that is calling this API.

Creating a new Participant

Specify the details of a new participant

@participant = PollEverywhere::Participant.from_hash(:email => 'b.obama@whitehouse.gov', :first_name => 'Barack', :last_name => 'Obama', :password => 'mickeymouse', :responding_as => 'Barack').save
curl -X PUT -H "Content-Type: application/json" -H "Accept: application/json" -H "Authorization: Basic YXBpdGVzdDphcGl0ZXN0" -d "{\
  \"user\": {\"first_name\":\"Barack\",\"last_name\":\"Obama\",\"email\":\"b.obama@whitehouse.gov\",\"phone_number\":null,\"responding_as\":\"Barack\",\"private_data\":null,\"password\":\"mickeymouse\",\"account_subuser\":null}\
}" "http://api.polleverywhere.com/participants/b.obama@whitehouse.gov"

Updating participant details

@participant.responding_as = "Mr. President"
@participant.save
curl -X PUT -H "Content-Type: application/json" -H "Accept: application/json" -H "Authorization: Basic YXBpdGVzdDphcGl0ZXN0" -d "{\
  \"user\": {\"first_name\":\"Barack\",\"last_name\":\"Obama\",\"email\":\"b.obama@whitehouse.gov\",\"phone_number\":null,\"responding_as\":\"Mr. President\",\"private_data\":null,\"password\":\"mickeymouse\",\"account_subuser\":null}\
}" "http://api.polleverywhere.com/participants/b.obama@whitehouse.gov"

Changing an email address

Changing an email address is a slightly special case at an HTTP level because the new email address should be in the body of the participant data and should be PUT to the original email address.

@participant.email = "mr.president@hotmail.com"
@participant.save
curl -X PUT -H "Content-Type: application/json" -H "Accept: application/json" -H "Authorization: Basic YXBpdGVzdDphcGl0ZXN0" -d "{\
  \"user\": {\"first_name\":\"Barack\",\"last_name\":\"Obama\",\"email\":\"mr.president@hotmail.com\",\"phone_number\":null,\"responding_as\":\"Mr. President\",\"private_data\":null,\"password\":\"mickeymouse\",\"account_subuser\":null}\
}" "http://api.polleverywhere.com/participants/b.obama@whitehouse.gov"

Delete a Participant

@participant.destroy
curl -X DELETE -H "Content-Type: application/json" -H "Accept: application/json" -H "Authorization: Basic YXBpdGVzdDphcGl0ZXN0" "http://api.polleverywhere.com/participants/mr.president@hotmail.com"