Survey Results

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

Retrieve aggregate results and individual responses to Survey questions

Get Aggregate Survey Results

Get aggregate results (summary statistics) for all questions in a survey

Method: GET

Parameters:

  • api_key
  • poll_identifier: (Optional) Filter results to a specific poll

Returns:

{
  "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,
              "choice_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",
              "average_audio_lengh": "8.672173956166143",       // DEPRECATED: Will be removed 2015-11-01. Please use average_audio_length instead.
              "total_audio_lengh": "199.4600009918213"          // DEPRECATED: Will be removed 2015-11-01. Please use total_audio_lengh instead.
          },
          {
              "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",                    // Average value of all responses
              "response_std": "2.646",                       // Standard deviation of all responses
              "response_max": "4",                           // Maximum response value
              "response_min": "1",                           // Minimum response value
          }
      ]
  },
  "message": "Survey results fetched successfully",
  "more_info": ""
}

Count Interactions (Delivery Logs) for a Survey

Count the number of delivery logs (individual subscriber interactions) associated with a Survey. You can optionally filter by delivery status and by date/time range.

Method: GET

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

Parameters:

  • api_key
  • filter_delivery_status (optional): Include only interactions with this delivery_status (e.g.: ‘6’ for Finished (Completed); ‘5’ for Failed (No Answer), etc.)
  • filter_after_date (optional): Include only interactions that ended after this date/time. Allowed format: ‘2015-09-23’ or ‘2015-09-23 14:02:37’, in UTC.
  • filter_before_date (optional): Include only interactions that ended before this date/time. Allowed format: ‘2015-09-23’ or ‘2015-09-23 14:02:37’, in UTC.

Returns:

{
  "status": 200,
  "code": 1000,
  "data": {
      "survey_id": "200568",
      "filter_delivery_status": "6",
      "filter_after_date": "2014-02-15",
      "count": 78
  },
  "message": "Fetched Survey Counts: times accessed.",
  "more_info": "",
  "pagination": null,
  "url": "https://go.votomobile.org/api/v1/surveys/200568/counts?filter_delivery_status=6&filter_after_date=2014-02-15"
}

Get All Responses to a Survey Question

Retrieve all responses to a single survey question (optionally filtered by date range)

Method: GET

Parameters:

  • api_key
  • poll_identifier (optional): Filter results to a specific poll
  • filter_after_date (optional): Include only responses after this date/time. Allowed format: ‘2015-09-23’ or ‘2015-09-23 14:02:37’, in UTC.
  • filter_before_date (optional): Include only responses before this date/time. Allowed format: ‘2015-09-23’ or ‘2015-09-23 14:02:37’, in UTC.
  • limit (optional): Specify the pagination limit for number of results to return on one page [max: 500]. You can follow the URLs given for nextURL and previousURL in the ‘pagination’ section of the response to navigate through pages.

Returns:

{
  "status": 200,
  "code": 1000,
  "data": {
      "question": {
          "id": "201183",
          "title": "Location",
          "survey_id": "200568",
          "question_number": "1",
          "num_choices": "4",
          "response_type": "1",
          "is_conditional": "0"
      },
      "number_of_respondents": "3",
      "number_of_responses": 22,
      "responses": [
          {
              "response_type": "1",
              "id": "239422",
              "date_received": "2014-05-21 03:29:54",
              "question_id": "201183",
              "poll_id": "204881",
              "delivery_log_id": "546178",
              "choice_id": "211151",
              "choice_name": "Bosumtwe",
              "subscriber": {
                  "id": "373648",
                  "phone": "233264164182",
                  "preferred_language": "200247"
              }
          },
          {
              "response_type": "1",
              "id": "244930",
              "date_received": "2014-06-04 18:40:43",
              "question_id": "201183",
              "poll_id": "207313",
              "delivery_log_id": "599326",
              "choice_id": "211152",
              "choice_name": "Other",
              "subscriber": {
                  "id": "559224",
                  "phone": "14165652037",
                  "preferred_language": "200247"
              }
          }
      ]
  },
  "message": "Survey Question Results Fetched Successfully",
  "more_info": "",
  "pagination": {
      "nextURL": "https://go.votomobile.org/api/v1/surveys/200568/questions/201183/results?limit=2&page_after=244930",
      "previousURL": null
  },
  "url": "https://go.votomobile.org/api/v1/surveys/200568/questions/201183/results?limit=2"
}

Count All Responses to a Survey Question

Count all responses to a single survey question (optionally filtered by date range). Returns the number of unique respondents (subscribers), and the number of individual responses (in case a subscriber answered the survey more than once).

Tip

Use this instead of https://go.votomobile.org/api/v1/surveys/[survey_id]/questions/[question_id]/results if you only need to know total counts, but don’t care about the individual results.

Method: GET

Parameters:

  • api_key
  • poll_identifier (optional): Filter results to a specific poll
  • filter_after_date (optional): Include only responses after this date/time. Allowed format: ‘2015-09-23’ or ‘2015-09-23 14:02:37’, in UTC.
  • filter_before_date (optional): Include only responses before this date/time. Allowed format: ‘2015-09-23’ or ‘2015-09-23 14:02:37’, in UTC.

Returns:

{
  "status": 200,
  "code": 1000,
  "data": {
      "question": {
          "id": "201183",
          "title": "Location",
          "survey_id": "200568",
          "question_number": "1",
          "num_choices": "4",
          "response_type": "1",
          "is_conditional": "0"
      },
      "filter_after_date": "2014-02-15",
      "number_of_respondents": "3",
      "number_of_responses": 22
  },
  "message": "Survey Question Response Count Fetched Successfully",
  "more_info": "",
  "pagination": null,
  "url": "https://go.votomobile.org/api/v1/surveys/200568/questions/201183/counts?filter_after_date=2014-02-15"
}

Get Survey Responses for one Delivery Log

Retrieve a subscriber’s responses to a survey within one delivery log. This returns all responses for a subscriber that took place within a single call or SMS conversation.

Method: GET

Parameters:

  • api_key

Returns:

{
  "status": 200,
  "code": 1000,
  "data": {
      "delivery_log": {
          "id": "200189",
          "subscriber_id": "200088",
          "outgoing_call_id": "200200",
          "incoming_call_id": null,
          "queued_on": "2015-09-14 06:28:41",
          "delivery_status": "6",
          "seconds_completed": "25.402",
          "start_timestamp": "2015-09-14 06:28:58",
          "end_timestamp": "2015-09-14 06:29:23",
          "survey_questions_answered": "2",
          "survey_questions_total": "2",
          "content_type": "1",
          "language_id": "200905",
          "hangup_cause": "NORMAL_CLEARING"
      },
      "survey": {
          "id": "200034",
          "title": "Test Survey",
          "num_questions": "2",
          "response_timeout": "10",
          "created_at": "2015-03-30 04:15:51",
          "updated_at": "2015-09-14 06:29:26"
          "webhook": null
      },
      "questions": [
          {
              "id": "200179",
              "title": "Are you female or male?",
              "question_number": "1",
              "response_type": "1",
              "response_timeout": null,
              "webhook_enabled": "0",
              "response": {
                  "created_at": "2015-09-14 06:29:09",
                  "choice_id": "200321",
                  "choice_name": "Female"
              }
          },
          {
              "id": "200180",
              "title": "Please leave us your open-ended feedback",
              "question_number": "2",
              "response_type": "3",
              "response_timeout": null,
              "max_open_length": "60",
              "webhook_enabled": "0",
              "response": {
                  "created_at": "2015-09-14 06:29:23",
                  "open_audio": "55f669362ed9b6.82619876.wav",
                  "open_text": null,
                  "open_audio_length": "5.58",
                  "open_audio_length_trimmed": "2.53413",
                  "open_audio_is_empty_response": "0",
                  "open_audio_url": "https://s3-us-west-2.amazonaws.com/test.audioresponses.votomobile.org/wav/55f669362ed9b6.82619876.wav"
              }
          }
      ]
  },
  "message": "Survey Question Responses Fetched Successfully",
  "more_info": ""
}

Get Survey Responses for one Subscriber

Retrieve all of single subscriber’s responses to a survey. This subscriber may have interacted with the survey multiple times, so this returns responses within an array of delivery_logs.

Method: GET

Parameters:

  • api_key

Returns:

{
  "status": 200,
  "code": 1000,
  "data": {
      "survey": {
          "id": "200034",
          "title": "Test Survey",
          "num_questions": "2",
          "response_timeout": "10",
          "created_at": "2015-03-30 04:15:51",
          "updated_at": "2015-09-14 06:29:26"
          "webhook": null
      },
      "delivery_logs": [
          {
              "delivery_log": {
                  "id": "200189",
                  "subscriber_id": "200088",
                  "outgoing_call_id": "200200",
                  "incoming_call_id": null,
                  "queued_on": "2015-09-14 06:28:41",
                  "delivery_status": "6",
                  "seconds_completed": "25.402",
                  "start_timestamp": "2015-09-14 06:28:58",
                  "end_timestamp": "2015-09-14 06:29:23",
                  "survey_questions_answered": "2",
                  "survey_questions_total": "2",
                  "content_type": "1",
                  "language_id": "200905",
                  "hangup_cause": "NORMAL_CLEARING"
              },
              "questions": [
                  {
                      "id": "200179",
                      "title": "Are you female or male?",
                      "question_number": "1",
                      "response_type": "1",
                      "response_timeout": null,
                      "webhook_enabled": "0",
                      "response": {
                          "created_at": "2015-09-14 06:29:09",
                          "choice_id": "200321",
                          "choice_name": "Female"
                      }
                  },
                  {
                      "id": "200180",
                      "title": "Please leave us your open-ended feedback",
                      "question_number": "2",
                      "response_type": "3",
                      "response_timeout": null,
                      "max_open_length": "60",
                      "webhook_enabled": "0",
                      "response": {
                          "created_at": "2015-09-14 06:29:23",
                          "open_audio": "55f669362ed9b6.82619876.wav",
                          "open_text": null,
                          "open_audio_length": "5.58",
                          "open_audio_length_trimmed": "2.53413",
                          "open_audio_is_empty_response": "0",
                          "open_audio_url": "https://s3-us-west-2.amazonaws.com/test.audioresponses.votomobile.org/wav/55f669362ed9b6.82619876.wav"
                      }
                  }
              ]
          }
      ]
  },
  "message": "Survey Question Responses Fetched Successfully",
  "more_info": ""
}