The doopoll API

About

The doopoll API is intended for existing or potential doopoll users who wish to extend the capabilities of our application into their own site or product. Primarily this allows users to get and display surveys and their results, and allow their own web visitors to answer them. To use the doopoll API you will need an authentic API key and a paid doopoll account.

Overview

The main endpoints for displaying and answering surveys are as follows.


            'https://api.doopoll.co/survey/'
            'https://api.doopoll.co/response/'
            'https://api.doopoll.co/respondents/'
            

Survey

https://api.doopoll.co/survey/:id/?results=true

A survey is composed of three things

  • poll ( poll settings, name, identifying features )
  • questions ( array of questions nested within a poll, including label, type and settings )
  • options ( array of options nested within a question, including label, order and existing votes )

Collectively these make a survey, the core document you deal with when working with the doopoll API

Using the survey endpoint allows you to retrieve a whole survey, to display the results, or to allow users to answer it. You can access a list of all your surveys on this endpoint, or by specifying the :id to get a single one. To include any results use the optional query results=true


Get all surveys


            curl --request GET 
                  --url 'https://api.doopoll.co/survey/' 
                  --header 'content-type: application/json' 
                  --header 'x-api-key: YOUR_API_KEY'
                

Example response

{
              "id": "ACCOUNT_ID",
              "polls": {
                "total": 1,
                "limit": 500,
                "skip": 0,
                "data": [
                  {
                    "_id": "POLL_ID",
                    "name": "Test",
                    "baseLanguage": "en",
                    "account": "ACCOUNT_ID",
                    "questions": [
                      "QUESTION_ONE_ID",
                      "QUESTION_TWO_ID",
                      "QUESTION_THREE_ID"
                    ],
                    "isOpen": true,
                    "showIntroduction": true,
                    "responses": 0,
                    "showDataCapture": false
                }

Get single survey


           curl --request GET
                  --url 'https://api.doopoll.co/survey/:id/?results=true'
                  --header 'content-type: application/json'
                  --header 'x-api-key: YOUR_API_KEY'
        

Example response

{
                "id": "POLL_ID",
                "poll": {
                  "_id": "POLL_ID",
                  "name": "POLL_NAME",
                  "baseLanguage": "en",
                  "account": "ACCOUNT_ID",
                  "questions": [
                    {
                      "_id": "QUESTION_ID",
                      "label": "Yes",
                      "type": "yesNo",
                      "chooseMultiple": false,
                      "allowSkipping": false,
                      "commentsEnabled": false,
                      "order": 0,
                      "pollId": "POLL_ID",
                      "account": "ACCOUNT_ID",
                      "options": [
                        {
                          "_id": "OPTION_ID",
                          "label": "Yes",
                          "order": 0,
                          "questionId": "QUESTION_ID",
                          "pollId": "POLL_ID",
                          "type": "yesNo",
                          "score": 0,
                          "account": "ACCOUNT_ID"
                        },
                        {
                          "_id": "OPTION_ID",
                          "label": "No",
                          "order": 1,
                          "questionId": "QUESTION_ID",
                          "pollId": "POLL_ID",
                          "type": "yesNo",
                          "score": 0,
                          "account": "ACCOUNT_ID"
                        }
                      ]
                    },
                  ],
                  "isOpen": true,
                  "showIntroduction": true,
                  "responses": 0,
                  "showDataCapture": false
                }
              }

Response

https://api.doopoll.co/response

Send a response

Responses have one mandatory field. An array of objects under the "options" field. You may submit multiple options in one to allow for multiple choice selections.

In this object you must supply an option "_id", and optionally the "score". Setting a score will only work on slider type questions and takes a number between 0 and 1. (This gets translated into a percentage later on).

If you do not add a respondent ID you will recieve one in the response to your request, this can then be used on subsequent submissions of other questions in the survey. Allowing you to attribute them all to the same respondent. If you do not include a respondent ID each submission will be regarded as unique.

The "comments" field is also optional, to use this make sure to enable comments in your question settings.


            curl --request POST 
              --url http://api.doopoll.co/response 
              --header 'content-type: application/json' 
              --header 'x-api-key: YOUR_API_KEY' 
              --data '{
              "respondentId": "OPTIONAL_RESPONDENT_ID",
              "options": [
                { "_id": "OPTIONID", "score": 1 },
             ],
              "comment": "OPTIONAL_COMMENT"
            }'
            

Respondent

https://api.doopoll.co/respondents

Create a profile for your respondents

If you want to capture contact, or demographic information from you respondents you can create a new respondent, using the respondent Id generated from answering a question and submitting it as a new respondent here.

Respondent Id and pollId are mandatory fields.

The options for the ageRange field can be ['1-17', '18-25', '26-30', '31-40', '41-55', '56-80', '80+']

The options for the employmentStatus field can be ['employed', 'self-employed', 'retired', 'unemployed', 'house-person', 'student', 'unemployed-disability']

The options for the gender field can be ['female', 'male', 'other', 'undisclosed']

curl --request POST 
              --url http://api.doopoll.co/respondents 
              --header 'content-type: application/json' 
              --header 'x-api-key: YOUR_API_KEY' 
              --data '{
            	"name": "Ruby Dagenham",
            	"email": "ruby@yahoo.com",
            	"ageRange": "26-30",
            	"employmentStatus": "employed",
            	"postcode": "POST_CODE",
            	"respondentId": "RESPONDENT_ID",
            	"pollId": "POLL_ID"