Surveys (Retiring – 28 Sept. 2018)

Important

We are retiring the Surveys feature in a planned release for September 28th, 2018.

Users would no longer be able to create or update surveys after the release. Reads via the API will remain available until further notice. Do report any issues to support@viamo.io

Viamo 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 Viamo. [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 Viamo. [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/[question_id]

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"}