Survey Responses

A survey response is an object that represents the answers submitted to a specific version of a specific survey by a responder.

Survey responses are available on the Support Professional plan.

JSON format

Survey Responses are represented as JSON objects with the following properties:

Name	Type	Read-only	Mandatory	Description
answers	array	false	true	An array of survey response answer objects. See Answer object
expires_at	string	false	true	The date and time of when the responder can no longer edit their survey response
id	string	false	true	Automatically assigned when the survey response is created
survey_id	string	false	true	The ID of the survey this survey response belongs to. Automatically assigned when the survey is created
survey_version	integer	false	true	The version of the survey upon which the survey response was based on. Every time the survey is updated, its version is auto-incremented.

Answer object

The answer object can be one of the following types:

• Skipped answer
• Closed-ended answer
• Open-ended answer
• Rating scale answer

Skipped answer object

Name	Type	Optional	Nullable	Descriptions
type	string	false	false	Has the value skipped
question	object	false	false	An object representing the survey question skipped during the survey response submission
created_at	string	false	false	The date when the answer was created
updated_at	string	false	false	The date when the answer was last updated

Closed-ended answer object

Name	Type	Optional	Nullable	Descriptions
type	string	false	false	Has the value closed_ended
selections	array	false	false	An array of options selected as the answer during the survey response submission. The selection objects are of type predefined selection
question	object	false	false	An object representing the survey question answered during the survey response submission. See Closed-ended question object
created_at	string	false	false	The date when the answer was created
updated_at	string	false	false	The date when the answer was last updated

Predefined selection object

Name	Type	Optional	Nullable	Descriptions
type	string	false	false	Has the following value predefined
option_id	string	false	false	The id of the closed-ended survey question option that was selected as the answer

Open-ended answer object

Name	Type	Optional	Nullable	Descriptions
type	string	false	false	Has the value open_ended
value	string	false	false	The plain text value of the provided answer
question	object	false	false	An object representing the survey question answered during the survey response submission. See Open ended question object
created_at	string	false	false	The date when the answer was created
updated_at	string	false	false	The date when the answer was last updated

Rating scale answer object

Name	Type	Optional	Nullable	Descriptions
type	string	false	false	Has the value rating_scale
rating	integer	false	false	The selected rating representing the answer
rating_category	string	false	false	Possible values: bad, neutral, good
question	object	false	false	An object representing the survey question answered during the survey response submission. See Rating scale question object
created_at	string	false	false	The date when the answer was created
updated_at	string	false	false	The date when the answer was last updated

Question object

The question object can be one of the following types:

• Closed-ended question
• Open-ended question
• Rating scale question

Closed-ended question object

Name	Type	Optional	Nullable	Descriptions
type	string	false	false	Has the value closed_ended
id	string	false	false	Automatically assigned when the survey question is created
alias	string	false	false	A human-readable identifier for this survey question
headline	object	false	false	A text content object representing the headline of this survey question
options	array	false	false	An array of closed-ended survey question options

Closed-ended option object

Name	Type	Optional	Nullable	Descriptions
id	string	false	false	Automatically assigned when the survey question option is created
label	object	false	false	A text content object representing the label of this option

Open-ended question object

Name	Type	Optional	Nullable	Descriptions
type	string	false	false	Has the value open_ended
id	string	false	false	Automatically assigned when the survey question is created
alias	string	false	false	A human-readable identifier for this survey question
headline	object	false	false	A text content object representing the headline of this survey question

Rating scale question object

The rating scale question object can be one of the following types:

• Custom text rating scale question
• Emoji rating scale question
• Numeric rating scale question

Custom text rating scale question object

Name	Type	Optional	Nullable	Descriptions
type	string	false	false	Has the value rating_scale_custom_text
id	string	false	false	Automatically assigned when the survey question is created
alias	string	false	false	A human-readable identifier for this survey question
sub_type	string	false	false	One of the following values: customer_satisfaction, other
headline	string	false	false	A text content object representing the headline of this survey question
options	array	false	false	An array of custom text rating scale options

Custom text rating scale option object

Name	Type	Optional	Nullable	Descriptions
rating	integer	false	false	The numeric rating represented by this option
label	object	false	false	A text content object representing the label of this option

Emoji rating scale question object

Name	Type	Optional	Nullable	Descriptions
type	string	false	false	Has the value rating_scale_emoji
id	string	false	false	Automatically assigned when the survey question is created
alias	string	false	false	A human-readable identifier for this survey question
sub_type	string	false	false	One of the following values: customer_satisfaction, other
headline	string	false	false	A text content object representing the headline of this survey question
options	array	false	false	An array of emoji rating scale options

Emoji rating scale option object

Name	Type	Optional	Nullable	Descriptions
rating	integer	false	false	The numeric rating represented by this option
emoji	object	false	false	A text content object representing the emoji of this option
label	object	false	false	A text content object representing the label of this option

Numeric rating scale question object

Name	Type	Optional	Nullable	Descriptions
type	string	false	false	Has the value rating_scale_numeric
id	string	false	false	Automatically assigned when the survey question is created
alias	string	false	false	A human-readable identifier for this survey question
sub_type	string	false	false	One of the following values: customer_satisfaction, other
headline	string	false	false	A text content object representing the headline of this survey question
options	array	false	false	An array of numeric rating scale options

Numeric rating scale option object

Name	Type	Optional	Nullable	Descriptions
rating	integer	false	false	The numeric rating represented by this option
label	object	false	false	A text content object representing the label of this option

Text content object

A text content object can be one of the following types:

• Static text content
• Dynamic text content

Static text content object

Name	Type	Optional	Nullable	Descriptions
type	string	false	false	Has the value static
value	string	false	false	A static (non-translatable) plain text content

Dynamic text content object

Name	Type	Optional	Nullable	Descriptions
type	string	false	false	Has the value dynamic
key	string	false	false	The key of a dynamic content
value	string	false	false	The translated value of the dynamic content represented by its key for a given locale (determined by the locale path parameter)

Example

{
  "answers": [
    {
      "created_at": "2024-08-14T12:00:00.000Z",
      "question": {
        "alias": "comment",
        "headline": {
          "type": "static",
          "value": "Anything else you would like to share about your experience?"
        },
        "id": "01GFYBENPDGN1R6NAA4WRDNVFR",
        "type": "open_ended"
      },
      "type": "skipped",
      "updated_at": "2024-08-14T12:00:00.000Z"
    }
  ],
  "expires_at": "2024-08-14T12:00:00.000Z",
  "id": "01J1WB51MG6HXTYWE6Q0C93RNW",
  "survey_id": "01J58KJ9RAE0D2EK7HRVM7Z8F2",
  "survey_version": 3
}

Show Survey Response

• GET /api/v2/guide/{locale}/survey_responses/{id}

Shows information about the specified survey response.

Allowed for

• Admins
• End users (responders only)

Parameters

Name	Type	In	Required	Description
id	string	Path	true	The survey response id
locale	string	Path	true	The locale used for the display of the corresponding survey questions and options

Code Samples

curl

curl https://{subdomain}.zendesk.com/api/v2/guide/{locale}/survey_responses/{id} \
  -v -u {email_address}/token:{api_token}

Go

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	url := "https://your_account_subdomain.zendesk.com/api/v2/api/v2/guide/en-us/survey_responses/01GFYBENPDGN1R6NAA4WRDNVFR"
	method := "GET"
	req, err := http.NewRequest(method, url, nil)

	if err != nil {
		fmt.Println(err)
		return
	}
	req.Header.Add("Content-Type", "application/json")
	req.Header.Add("Authorization", "Basic <auth-value>") // Base64 encoded "{email_address}/token:{api_token}"

	client := &http.Client {}
	res, err := client.Do(req)
	if err != nil {
		fmt.Println(err)
		return
	}
	defer res.Body.Close()

	body, err := io.ReadAll(res.Body)
	if err != nil {
		fmt.Println(err)
		return
	}
	fmt.Println(string(body))
}

Java

import com.squareup.okhttp.*;
OkHttpClient client = new OkHttpClient();
HttpUrl.Builder urlBuilder = HttpUrl.parse("https://your_account_subdomain.zendesk.com/api/v2/api/v2/guide/en-us/survey_responses/01GFYBENPDGN1R6NAA4WRDNVFR")
		.newBuilder();
String userCredentials = "your_email_address" + "/token:" + "your_api_token";
String basicAuth = "Basic " + java.util.Base64.getEncoder().encodeToString(userCredentials.getBytes());

Request request = new Request.Builder()
		.url(urlBuilder.build())
		.method("GET", null)
		.addHeader("Content-Type", "application/json")
		.addHeader("Authorization", basicAuth)
		.build();
Response response = client.newCall(request).execute();

Nodejs

var axios = require('axios');

var config = {
  method: 'GET',
  url: 'https://your_account_subdomain.zendesk.com/api/v2/api/v2/guide/en-us/survey_responses/01GFYBENPDGN1R6NAA4WRDNVFR',
  headers: {
	'Content-Type': 'application/json',
	'Authorization': 'Basic <auth-value>', // Base64 encoded "{email_address}/token:{api_token}"
  },
};

axios(config)
.then(function (response) {
  console.log(JSON.stringify(response.data));
})
.catch(function (error) {
  console.log(error);
});

Python

import requests
from requests.auth import HTTPBasicAuth

url = "https://your_account_subdomain.zendesk.com/api/v2/api/v2/guide/en-us/survey_responses/01GFYBENPDGN1R6NAA4WRDNVFR"
headers = {
	"Content-Type": "application/json",
}
email_address = 'your_email_address'
api_token = 'your_api_token'
# Use basic authentication
auth = HTTPBasicAuth(f'{email_address}/token', api_token)

response = requests.request(
	"GET",
	url,
	auth=auth,
	headers=headers
)

print(response.text)

Ruby

require "net/http"
require "base64"
uri = URI("https://your_account_subdomain.zendesk.com/api/v2/api/v2/guide/en-us/survey_responses/01GFYBENPDGN1R6NAA4WRDNVFR")
request = Net::HTTP::Get.new(uri, "Content-Type": "application/json")
email = "your_email_address"
api_token = "your_api_token"
credentials = "#{email}/token:#{api_token}"
encoded_credentials = Base64.strict_encode64(credentials)
request["Authorization"] = "Basic #{encoded_credentials}"
response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|
	http.request(request)
end

Example response(s)

200 OK

// Status 200 OK

{
  "survey_response": {
    "answers": [
      {
        "created_at": "2024-08-14T12:00:00.000Z",
        "question": {
          "alias": "customer satisfaction rating",
          "headline": {
            "key": "dc.surveys.customer_satisfaction.questions.rating",
            "type": "dynamic",
            "value": "How would you rate your experience?"
          },
          "id": "01J1WBE8QR0YQVE373K2JDJR0F",
          "options": [
            {
              "label": {
                "key": "dc.surveys.customer_satisfaction.question.rating.options.bad_rating",
                "type": "dynamic",
                "value": "Bad"
              },
              "rating": 1
            },
            {
              "label": {
                "key": "dc.surveys.customer_satisfaction.question.rating.options.good_rating",
                "type": "dynamic",
                "value": "Good"
              },
              "rating": 2
            }
          ],
          "sub_type": "customer_satisfaction",
          "type": "rating_scale_numeric"
        },
        "rating": 1,
        "rating_category": "bad",
        "type": "rating_scale",
        "updated_at": "2024-08-14T12:00:00.000Z"
      },
      {
        "created_at": "2024-08-14T12:00:00.000Z",
        "question": {
          "alias": "reason",
          "headline": {
            "key": "dc.surveys.customer_satisfaction.questions.reason",
            "type": "dynamic",
            "value": "Select a reason for your experience"
          },
          "id": "01J1WBGX1BR4ECKTS87CRJTXSF",
          "options": [
            {
              "id": "01J1WBKRG57E6M8C1145EXJ535",
              "label": {
                "key": "dc.surveys.customer_satisfaction.question.reason.options.too_long",
                "type": "dynamic",
                "value": "The issue took too long to resolve"
              }
            }
          ],
          "type": "closed_ended"
        },
        "selections": [
          {
            "option_id": "01J1WBKRG57E6M8C1145EXJ535",
            "type": "predefined"
          }
        ],
        "type": "closed_ended",
        "updated_at": "2024-08-14T12:00:00.000Z"
      },
      {
        "created_at": "2024-08-14T12:00:00.000Z",
        "question": {
          "alias": "comment",
          "headline": {
            "key": "dc.surveys.customer_satisfaction.questions.comment",
            "type": "dynamic",
            "value": "Share your thoughts on the support you received"
          },
          "id": "01J1WBNS76ZC4TTFWP9RCNQ1S8",
          "type": "open_ended"
        },
        "type": "open_ended",
        "updated_at": "2024-08-14T12:00:00.000Z",
        "value": "I had to repeatedly answer the same questions."
      },
      {
        "created_at": "2024-08-14T12:00:00.000Z",
        "question": {
          "alias": "additional comment",
          "headline": {
            "type": "static",
            "value": "A question to demonstrate a static headline"
          },
          "id": "01J1WBSAZWVY2XR1EFZKS3CM13",
          "type": "open_ended"
        },
        "type": "skipped",
        "updated_at": "2024-08-14T12:00:00.000Z"
      }
    ],
    "expires_at": "2024-08-14T12:00:00.000Z",
    "id": "01J1WB51MG6HXTYWE6Q0C93RNW",
    "survey_id": "01J58KJ9RAE0D2EK7HRVM7Z8F2",
    "survey_version": 3
  }
}

404 Not Found

// Status 404 Not Found

{
  "errors": [
    {
      "code": "NotFound",
      "status": "404",
      "title": "The survey response could not be found"
    }
  ]
}