Surveys

VOTO allows you to build and send multi-question surveys, with three different types of questions:

  • Multiple-choice questions: “What is your priority - For better health care, press 1. For better roads, press 2. For more jobs, press 3.”
  • Numeric questions: “How old are you? Enter your age using the buttons on your keypad.”
  • Open-ended questions: “Is there anything else you want to tell us about your experience at the clinic today? You can start speaking now, and press any button when finished.”

Building and sending a complete survey requires several steps using the API:

  1. Create a new survey
  2. Add questions
  3. (Optional) Add an introduction
  4. (Optional) Add a conclusion
  5. Send the survey in an outgoing call

Complete Example

  1. Create a new survey and retrieve the id:

api_key: 53cf81b821f291.73038305
        survey_title: Malaria Survey

Returns: {status:200, message:"Survey Created", data:{id:14}}
  1. Post an audio-file for the first question (if you don’t have one already) and retrieve the id:

  [audio data]

Returns: {"status":200,"message":"Audio File Saved","data":{id: 17}}
  1. Add the first question to that survey. Make sure to provide the audio files (e.g., id: 17) and corresponding languages (e.g., 3):

  title: Have you every had malaria?
  response_type: 1
  options[]: No
  options[]: Yes
  audio_files[3]: 17

Returns: {"status":200,"message":"Question Added","data":{id: 24434}}
  1. Post an audio file for the second question:

  [audio data]

Returns: {"status":200,"message":"Audio File Added","data":{id: 19}}
  1. Add the second question:

      api_key: 53cf81b821f291.73038305
      response_type: 2
title : How many times have you been to the hospital?
max_digits : 3
      audio_files[19]: 390

    Returns: {"status":200,"message":"Question Added","data":{id: 24557}}
  1. Add a conclusion:

api\_key: api_key: 53cf81b821f291.73038305
audio_file[20]: 395

   Returns:
{"status":200,"message":"Conclusion Created","data":{id: 11223}}
  1. Send out an outgoing call with this survey attached:

  survey_id: 14

Returns:
{"status":200,"message":"Call Queued","data":{id: 445900}}
  1. Get survey results (Data returned depends on the response_type for each question):
{
  "status": 200,
  "code": 1000,
  "data": {
      "survey": {
          "id": "200101",
          "survey_title": "Example Survey"
      },
      "results": [
          {
              "question_id": "200301",
              "question_title": "What is your priority for the annual development plan?",
              "question_number": "1",
              "response_type": "1",
              "total_responses": 37,
              "option_responses": [
                  {
                      "id": "200571",
                      "name": "Schools and education",
                      "num_responses": "26",
                      "percentage": 70.27027027027
                  },
                  {
                      "id": "200572",
                      "name": "Health facilities and health access",
                      "num_responses": "6",
                      "percentage": 16.216216216216
                  },
                  {
                      "id": "200573",
                      "name": "Roads",
                      "num_responses": "4",
                      "percentage": 10.810810810811
                  },
                  {
                      "id": "200574",
                      "name": "Jobs and economic development",
                      "num_responses": "1",
                      "percentage": 2.7027027027027
                  }
              ]
          },
          {
              "question_id": "200302",
              "question_title": "Please feel free to elaborate on your priorities in your own words",
              "question_number": "2",
              "response_type": "3",
              "total_responses": "32",
              "total_voice_responses": "26",
              "total_text_responses": "6",
              "average_audio_length": "8.672173956166143",
              "total_audio_length": "199.4600009918213",
          },
          {
              "question_id": "200303",
              "question_title": "On a scale from 0 to 5, how response do you believe the district government is to citizen priorities?",
              "question_number": "3",
              "response_type": "2",
              "total_responses": "24",
              "response_average": "3.43",
              "response_std": "2.646",
              "response_max": "4",
              "response_min": "1",
          }
      ]
  },
  "message": "Survey results fetched successfully",
  "more_info": ""
}

Create A Survey

Method: POST

URL: https://go.votomobile.org/api/v1/surveys

Parameters:

  • api_key
  • has_voice : Indicate whether the survey (will) contain a voice message. Value should be 1 for true and 0 for false.
  • has_sms : Indicate whether the survey (will) contain sms. Value should be 1 for true and 0 for false.
  • survey_title : The title of the survey
  • response_wait_time (optional) : wait a number of seconds for a response to a question { default : 10 }
  • question_repeat (optional) : the number of times a question should be repeated when no answer is given { default : 2}
  • webhook_url [optional]: If provided, a destination URL to post updates to whenever a survey response is recorded.
  • webhook_method [optional, if using webhook_url]: “GET” or “POST” [Default: “GET”]
  • webhook_secret [optional, if using webhook_url]: A secret key or phrase that will be sent as a parameter with webhook requests to validate that the request is from VOTO. [Default: none]

Returns:

ID of the survey

{"status":200,"message":"Survey Created","data":{id: 21122}}

Update A Survey

Method: PUT

URL: https://go.votomobile.org/api/v1/surveys/[survey_id]

Parameters:

  • api_key
  • has_voice [optional]: Indicate whether the survey (will) contain a voice message. Value should be 1 for true and 0 for false.
  • has_sms [optional]: Indicate whether the survey (will) contain sms. Value should be 1 for true and 0 for false.
  • survey_title [optional]: The title of the survey
  • response_wait_time [optional]: wait a number of seconds for a response to a question { default : 10 }
  • question_repeat [optional]: the number of times a question shoud be repeated when no answer is given { default : 2}
  • webhook_url [optional]: If provided, a destination URL to post updates to whenever a survey response is recorded.
  • webhook_method [provide if using webhook_url]: “GET” or “POST” [Default: “GET”]
  • webhook_secret [provide if using webhook_url]: A secret key or phrase that will be sent as a parameter with webhook requests to validate that the request is from VOTO. [Default: none]

Note that for PUT, all parameters are optional; only the parameters provided will be updated. Any omitted parameters will keep their old values.

Returns:

ID of the survey

{"status":200,"message":"Survey Created","data":{id: 21122}}

Add a survey introduction

Method: POST

URL: https://go.votomobile.org/api/v1/surveys/[survey_id]/introduction

Parameters:

  • api_key
  • audio_file : should be posted with a language_id associated with it.
audio_file[language_id] = audio_file_id

audio_file[50] = 352,

audio_file[83] = 336,
  • sms_introduction : You can add sms for each language to messages in the following format.
  • Each sms_introduction should be posted with a language_id associated with it.
sms_introduction[language_id] = sms_message

sms_introduction[590] = "Introducing the survey in English."

sms_introduction[854] = "Ka di b3 wula? Ti pagaya pam.",

sms_introduction[1374] = "Introduction a notre sondage."

Returns:

ID of the survey

{"status":200,"message":"Survey Introduction Added","data":{id: 21122}}

Update a survey introduction

Method: PUT

URL: https://go.votomobile.org/api/v1/surveys/[survey_id]/introduction

Parameters:

  • api_key
  • audio_file : should be posted with a language_id associated with it.

To Disable or Delete or Enable a survey introduction simply submit the parameter :

  • has_introduction : 0 (to disable)
  • has_introduction : 1 (to enable)
audio_file[language_id] = audio_file_id

audio_file[50] = 352,

audio_file[83] = 336,
  • sms_introduction : You can add sms for each language to messages in the following format.
  • Each sms_introduction should be posted with a language_id associated with it.
sms_introduction[language_id] = sms_message

sms_introduction[590] = "Introducing the survey in English."

sms_introduction[854] = "Ka di b3 wula? Ti pagaya pam.",

sms_introduction[1374] = "Introduction a notre sondage."

Returns:

ID of the survey

{"status":200,"code":1000,"data":null,"message":"Survey introduction updated successfully","more_info":""}

Get survey introduction details

Method: GET

URL: https://go.votomobile.org/api/v1/surveys/[survey_id]/introduction

Parameters:

  • api_key

Returns:

ID of the survey

{
   "status":200,
   "code":1000,
   "data":{
      "survey_introduction":{
         "sms_content":[
            {
               "language_id":"200247",
               "language_name":"English",
               "sms_content":null
            },
            {
               "language_id":"200248",
               "language_name":"Twi",
               "sms_content":null
            }
         ],
         "audio_files":[
            {
               "language_id":"200247",
               "language_name":"English",
               "audio_file_id":null,
               "audio_file_description":null
            },
            {
               "language_id":"200248",
               "language_name":"Twi",
               "audio_file_id":null,
               "audio_file_description":null
            }
         ]
      }
   },
   "message":"Survey introduction details fetched successfully.",
   "more_info":""
}

Add a survey conclusion

  • (Optional) Post survey conclusion audio file(s) for that survey id

Method: POST

URL: https://go.votomobile.org/api/v1/surveys/[survey_id]/conclusion

Parameters:

  • api_key
  • audio_file : should be posted with a language_id associated with it.
audio_file[language_id] = audio_file_id

audio_file[510] = 34545,

audio_file[823] = 43545,
  • sms_conclusion : You can add sms for each language to messages in the following format.
  • Each sms_conclusion should be posted with a language_id associated with it.
sms_conclusion[language_id] = sms_message

sms_conclusion[12] = "Concluding the survey in English."

sms_conclusion[23] = "Ka di b3 wula? Ti pagaya pam.",

sms_conclusion[34] = "Conclusion pour notre sondage."

Returns:

ID of the survey

{"status":200,"code":1000,"data":null,"message":"Survey conclusion created successfully","more_info":""}

Get survey conclusion details

Method: GET

URL: https://go.votomobile.org/api/v1/surveys/[survey_id]/conclusion

Parameters:

  • api_key

Returns:

ID of the survey

{
   "status":200,
   "code":1000,
   "data":{
      "survey_conclusion":{
         "sms_content":[
            {
               "language_id":"200247",
               "language_name":"English",
               "sms_content":"Thanks for taking our survey, good bye!"
            },
            {
               "language_id":"200248",
               "language_name":"Twi",
               "sms_content":null
            }
         ],
         "audio_files":[
            {
               "language_id":"200247",
               "language_name":"English",
               "audio_file_id":"200595",
               "audio_file_description":"Uploaded file: silence.wav"
            },
            {
               "language_id":"200248",
               "language_name":"Twi",
               "audio_file_id":null,
               "audio_file_description":null
            }
         ]
      }
   },
   "message":"Survey conclusion details fetched successfully.",
   "more_info":""
}

Update a survey conclusion

Method: PUT

URL: https://go.votomobile.org/api/v1/surveys/[survey_id]/conclusion

Parameters:

  • api_key
  • audio_file : should be posted with a language_id associated with it.

To Disable or Delete or Enable a survey conclusion simply submit the parameter :

  • has_conclusion : 0 (to disable)
  • has_conclusion : 1 (to enable)
audio_file[language_id] = audio_file_id

audio_file[510] = 34545,

audio_file[823] = 43545,
  • sms_conclusion : You can add sms for each language to messages in the following format.
  • Each sms_conclusion should be posted with a language_id associated with it.
sms_conclusion[language_id] = sms_message

sms_conclusion[12] = "Concluding the survey in English."

sms_conclusion[23] = "Ka di b3 wula? Ti pagaya pam.",

sms_conclusion[34] = "Conclusion pour notre sondage."

Returns:

ID of the survey

{"status":200,"code":1000,"data":null,"message":"Survey conclusion updated successfully","more_info":""}

Create A Survey Question

  • Create a survey question for that survey id
  • Indicate whether the survey question will be multi choice, numeric, or open. Each response type has different parameters to provide.

Method: POST

URL: https://go.votomobile.org/api/v1/surveys/[survey_id]/questions

Parameters:

  • api_key
  • question_title
  • audio_file : Audio files for this question; should be indexed with the language_id that each audio file is used for it:
audio_file[language_id] = audio_file_id

audio_file[510] = 34545,

audio_file[823] = 43545,
  • response_type: Determines the type of survey question. 1 for a multiple choice question, 2 for a numeric question, 3 for an open-ended response question, and 4 for a simple message inserted into the survey.
  • options: (Used only for multiple choice questions): Provide an array of multiple choice response options from which respondents can choose from. They should be in the order they are asked for each Response-Choice field:
options[0] = 'apple'

options[1] = 'banana'

options[2] = 'orange'
  • max_numeric_digits (optional) (Used only for numeric questions): Set the maximum number of accepted digits for a response (voice interactions only). [Default if not provided: 2]
  • max_open_length (optional) (Used only for open-ended questions): Set the maximum recording duration for a response, in seconds (voice interactions only). [Default if not provided: 60]
  • webhook_enabled (optional): If this survey has wehooks enabled, selectively enable or disable webhook posts for this question [Default if not provided: true for surveys with webhooks]

Returns:

ID of the survey question

{"status":200,"message":"Survey Question Added","data":{id: 21122}}

Update A Survey Question

  • Indicate whether the survey question will be multi choice, numeric, or open. Each response type has different parameters to provide.

Method: PUT

URL: https://go.votomobile.org/api/v1/surveys/[survey_id]/questions

Parameters:

  • api_key
  • question_title
  • audio_file : should be posted with a language_id associated with it.
audio_file[language_id] = audio_file_id

audio_file[510] = 34545,

audio_file[823] = 43545
  • response_type: Determines the type of survey question. 1 for a multiple choice question, 2 for a numeric question, 3 for an open-ended response question, and 4 for a simple message inserted into the survey.
  • options: (Used only for multiple choice questions): Provide an array of multiple choice response options from which respondents can choose from. They should be in the order they are asked for each Response-Choice field:
options[0] = 'apple'

options[1] = 'banana'

options[2] = 'orange'
  • max_numeric_digits (optional) (Used only for numeric questions): Set the maximum number of accepted digits for a response (voice interactions only).
  • max_open_length (optional) (Used only for open-ended questions): Set the maximum recording duration for a response, in seconds (voice interactions only).
  • condition (Multiple choice questions only): To enable branching dependent on survey responses: provide an array of conditions for multiple choice responses in the following format:
condition[] = choice number,action (action: either a question id to jump to, 'end_call', or 'conclude')

condition[0] = 1,conclude

condition[1] = 2,end_call

condition[2] = 3,25

condition[3] = any_option,223
  • condition (Numeric questions only): To enable branching dependent on survey responses: provide an array of conditions for numeric responses in the following format:
condition[] = numberic condition text or symbol, numeric value or specification, action (action: either a question id to jump to, 'end_call', or 'conclude')

condition[0] : >,23,89283 (if numeric value entered is greater than 23, go to question id 89283)

condition[1] : =,45,end_call (if numeric value entered is equal to 45, end the call)

condition[2] : <,11,conclude (if numeric value entered is less than 11, conclude the survey, go to conclusion)
  • webhook_enabled [optional]: If this survey has wehooks enabled, allows you to selectively enable or disable webhook posts for this question

Returns:

ID of the survey question

{"status":200,"message":"Survey Question Added","data":{id: 21122}}

List All Surveys

Method: GET

URL: https://go.votomobile.org/api/v1/surveys

Parameters:

  • api_key

Returns:

{
status: 200
code: 1000
data: {
    surveys: [
        {
            id: "200255"
            has_voice: "1"
            has_sms: "1"
            title: "Example Survey"
            num_questions: "3"
            repeat_times: "2"
            subscribers_answered: "0"
            questions_answered: "0"
            has_conclusion: "1"
            has_introduction: "0"
            webhook_url: "http://requestb.in/17rmyum1"
            webhook_method: "GET"
            webhook_secret: ""
            created_at: "2014-03-08 23:33:46"
            updated_at: "2014-03-08 23:37:58"
        },
        {
            id: "200259"
            has_voice: "1"
            has_sms: "1"
            title: "Int'l Women's Day Survey"
            num_questions: "1"
            repeat_times: "2"
            subscribers_answered: "0"
            questions_answered: "0"
            has_conclusion: "0"
            has_introduction: "0"
            webhook_url: "http://requestb.in/17rmyum1"
            webhook_method: "GET"
            webhook_secret: ""
            created_at: "2014-03-09 00:02:52"
            updated_at: "2014-03-09 00:02:53"
        }
    ]
}
message: "Surveys fetched successfully"
more_info: ""
}

List Survey Details

Method: GET

URL: https://go.votomobile.org/api/v1/surveys/[survey_id]

Parameters:

  • api_key

Returns:

{
    status: 200
    code: 1000
    data: {
        survey: {
            id: "200255"
            has_voice: "1"
            has_sms: "1"
            title: "Example Survey"
            num_questions: "3"
            repeat_times: "2"
            subscribers_answered: "0"
            questions_answered: "0"
            has_conclusion: "1"
            has_introduction: "0"
            webhook_url: "http://requestb.in/17rmyum1"
            webhook_method: "GET"
            webhook_secret: ""
            created_at: "2014-03-08 23:33:46"
            updated_at: "2014-03-08 23:37:58"
        }
    }
    message: "Survey details fetched successfully"
    more_info: ""
    }

List Survey Questions

Method: GET

URL: https://go.votomobile.org/api/v1/surveys/[survey_id]/questions

Parameters:

  • api_key

Returns:

{
   "status":200,
   "code":1000,
   "data":{
      "questions":[
         {
            "id":"200473",
            "title":"How old are you?",
            "survey_id":"200255",
            "response_type":"2",
            "webhook_enabled":"0"
            "max_numeric_digits":"2",
            "audio_files":[
               {
                  "language_id":"200247",
                  "language_name":"English",
                  "audio_file_id":"200592",
                  "audio_file_description":"Uploaded file: q1.wav"
               },
               {
                  "language_id":"200248",
                  "language_name":"Twi",
                  "audio_file_id":null,
                  "audio_file_description":null
               }
            ],
            "sms_content":[
               {
                  "language_id":"200247",
                  "language_name":"English",
                  "sms_content":"How old are you? Reply with up to 2 digits."
               },
               {
                  "language_id":"200248",
                  "language_name":"Twi",
                  "sms_content":null
               }
            ]
         },
         {
            "id":"200474",
            "title":"What is your favorite food?",
            "survey_id":"200255",
            "response_type":"1",
            "webhook_enabled":"0"
            "num_choices":"4",
            "options":[
               "Fufu",
               "Banku",
               "Rice",
               "Something else"
            ],
            "audio_files":[
               {
                  "language_id":"200247",
                  "language_name":"English",
                  "audio_file_id":"200593",
                  "audio_file_description":"Uploaded file: q2.wav"
               },
               {
                  "language_id":"200248",
                  "language_name":"Twi",
                  "audio_file_id":null,
                  "audio_file_description":null
               }
            ],
            "sms_content":[
               {
                  "language_id":"200247",
                  "language_name":"English",
                  "sms_content":"What is your favorite food? Reply 1 for Fufu, 2 for Banku, 3 for Rice, or 4 for something else."
               },
               {
                  "language_id":"200248",
                  "language_name":"Twi",
                  "sms_content":null
               }
            ]
         },
         {
            "id":"200475",
            "title":"What is your hope for the future?",
            "survey_id":"200255",
            "response_type":"3",
            "webhook_enabled":"0"
            "max_open_length":"3600",
            "audio_files":[
               {
                  "language_id":"200247",
                  "language_name":"English",
                  "audio_file_id":"200594",
                  "audio_file_description":"Uploaded file: q3.wav"
               },
               {
                  "language_id":"200248",
                  "language_name":"Twi",
                  "audio_file_id":null,
                  "audio_file_description":null
               }
            ],
            "sms_content":[
               {
                  "language_id":"200247",
                  "language_name":"English",
                  "sms_content":"What is your hope for the future? Please reply with your thoughts."
               },
               {
                  "language_id":"200248",
                  "language_name":"Twi",
                  "sms_content":null
               }
            ]
         }
      ]
   },
   "message":"Survey questions and details fetched successfully",
   "more_info":""
}

Get Survey Question Details

Method: GET

URL: https://go.votomobile.org/api/v1/surveys/[survey_id]/questions/[question_id]

Parameters:

  • api_key

Returns:

{
   "status":200,
   "code":1000,
   "data":{
      "question":{
         "id":"200474",
         "title":"What is your favorite food?",
         "survey_id":"200255",
         "response_type":"1",
         "webhook_enabled":"0"
         "num_choices":"4",
         "options":[
            "Fufu",
            "Banku",
            "Rice",
            "Something else"
         ],
         "audio_files":[
            {
               "language_id":"200247",
               "language_name":"English",
               "audio_file_id":"200593",
               "audio_file_description":"Uploaded file: q2.wav"
            },
            {
               "language_id":"200248",
               "language_name":"Twi",
               "audio_file_id":null,
               "audio_file_description":null
            }
         ],
         "sms_content":[
            {
               "language_id":"200247",
               "language_name":"English",
               "sms_content":"What is your favorite food? Reply 1 for Fufu, 2 for Banku, 3 for Rice, or 4 for something else."
            },
            {
               "language_id":"200248",
               "language_name":"Twi",
               "sms_content":null
            }
         ]
      }
   },
   "message":"Survey questions and details fetched successfully",
   "more_info":""
}

Delete A Question

Method: DELETE

URL: https://go.votomobile.org/api/v1/surveys/[survey_id]/questions/[question_id]

Parameters:

  • api_key

Returns:

{"status":200,"message":"Succesfully deleted survey"}

Delete A Survey

Method: DELETE

URL: https://go.votomobile.org/api/v1/surveys/[survey_id]

Parameters:

  • api_key

Returns:

{"status":200,"code":"1000", "data":null,"message":"Survey deleted successfully"}