Survey Results

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