Get Survey Responses

Get the responses of a survey.

You can

  • use our recommended approach, which is to use the startingFrom token so you only get the responses that have been submitted or modified since your last call.
  • get all the responses each call and will be charged for each response for every call.

Please note that from Monday 5th December 2022 usage of the API becomes chargeable. The charge is that 0.1 unit will be consumed each time a survey response is delivered by the API.  This applies if the same survey response is delivered by the API multiple times. The survey responses are delivered using the Get Survey Responses endpoint.

Changes from v1.0

  • A ‘filter’ property has been added.
  • The ‘variableId’ property has been renamed ‘id’.
  • The ‘value’ property has been renamed ‘v’.
  • The ‘status’ property has been renamed ‘s’.
  • Additional validation: invalid filter or startingFrom parameter now leads to a 400 response code rather than 500.

Endpoint

MethodURL
GETsurveys/{surveyId}/responses

Get the responses of the specific survey identified with the surveyId path variable

Parameters

Path parameters

Path parameterDescription
{surveyId}The id of the survey. This is the survey GUID and not the Interview URL.

Query string parameters

Query string parameterRequired / OptionalDescriptionTypeRangeDefault
maxResponsesOptionalThe number of responses to return.Integer1-50005000
startingFromOptionalWe recommended always using the startingFrom token.
Returns responses from the startingFrom token. This value is “0” to start at the beginning, or a token to start from a particular point in the responses collection.   Example: #IBCGEGG.
To get the next set of responses (if the output UpToDate property is false) feed the progress token of the output into the startingFrom token and make the call.
NB the # needs to be URL encoded e.g. %23IBCGEGG		StringN/A“0”
returnCaseIdsOptionalWhether to return the case ID in the response.BooleanN/Afalse
useCodeLabelsOptionalWhether to return code labels (true) or code indexes (false) for choice questions.BooleanN/Afalse
variablesOptionalDetermines which variables to return in each response.  
Default returns all variables.

This is a comma separated list of V numbers. Can also use ~ to specify a range of variables.

Example: V10~V12,V15 will return V10, V11, V12 and V15.		StringN/A“”
filterOptionalThe Snap XMP filter to use.
The default does not use a filter.

Example: (ID.endDate>=2021/01/01) and (ID.endDate<=2021/06/01)		StringN/A“”

Note: There are two ways to identify the V number required in the restrictedVariables parameter:

1. Postman: Make the Get Survey Variables call and examine the result.

2. Snap XMP Desktop: Tick the UniqueIDs checkbox in the Variable Tailoring dialog. A new Id column will then be visible in the Variables screen.

Sample Request

curl --location --request GET 'https://<servername>/snaponline/api/surveys/c23a0fd8-6219-4130-a6a7-f312829e56eb/responses?maxResponses=100&variables= 
V16,V45~V47&returnCaseIds=true&useCodeLabels=true&startingFrom=0' \
--header 'X-USERNAME: {USERNAME}' \
--header 'X-API-KEY: {APIKEY}' \
--header 'X-VERSION: 2.0' \
--data-raw ''

(In the above code, replace {APIKEY} with your actual API key and {USERNAME} with your actual username.)

Sample Response

200 OK with body:

{
    "surveyId": "6834a5f1-46e5-4b12-9e0c-a38a3d9be12c",
    "filter": "Q1>1",
    "startingFrom": "0",
    "progress": "#IBCGEGG",
    "upToDate": "false",
    "responses": [
        {
            "status": "new",
            "caseId": "8e4591b0-c1e3-4612-88b4-7b96cd28dd2d",
            "variables": [
                {
                    "id": "V46",
                    "v": "Plane"
                },
                {
                    "id": "V48",
                    "v": "\"Restaurant / Cafe\",\"Gift Shop\",\"Customer Services\""
                },
                {
                    "id": "V52",
                    "s": "NR"
                }
            ]
        },
        {
            "status": "new",
            "caseId": "5458bfcb-97df-4326-879d-4868406761ae",
            "variables": [
                {
                    "id": "V46",
                    "v": "Bike"
                },
                {
                    "id": "V48",
                    "v": "\"Gift Shop\""
                },
                {
                    "id": "V52",
                    "v": "Very busy."
                }
            ]
        }
    ]
}

Follow on Sample Request using the progress response item

In the sample response above, ‘progress’ represents where you have got to in the data file. This token is then used as the startingFrom value in the next /Responses request, to retrieve responses that have been submitted or modified since your last call.

“progress”: “#IBCGEGG”,

Use this token as the startingFrom parameter in order to retrieve responses that have been submitted or modified since your last call.

NB the # needs to be URL encoded e.g. %23IBCGEGG

Sample Request example using the progress token

curl --location --request GET 'https://<servername>/snaponline/api/surveys/c23a0fd8-6219-4130-a6a7-f312829e56eb/responses?maxResponses=100&variables= 
V16,V45~V47&returnCaseIds=true&useCodeLabels=true&startingFrom=%23IBCGEGG' \
--header 'X-USERNAME: {USERNAME}' \
--header 'X-API-KEY: {APIKEY}' \
--header 'X-VERSION: 2.0' \
--data-raw ''

Response Definitions

Response Item Description Data Type
surveyIdThe survey Id you selected based on the survey Id in the request.String: containing GUID
filterThe filter used.String
startingFromThe startingFrom token in the request. This is recommended.String
progressThe ending token. This token can be used as the startingFrom parameter in the next call.String
upToDateWhether the most recent response is included.String: containing Boolean
responsesThe responses.

The number of responses will be based on the maxResponses request parameter.		List: containing objects
responses/status“new” if this is a brand new response, “updated” if the response has been edited in Snap XMP Desktop or “deleted” if the response has been deleted (although you will only see deleted responses if you have also set the returnCaseIds parameter to true).String
responses/caseIdThe case Id of the response.String (Default: Guid)
responses/variablesThe variables in the response.

This will either be all the variables in the response or restricted to those specified in the variables request parameter.		List: containing objects
responses/variables/idThe variable Id (V number).String
responses/variables/sThe status code of the variable. This field will only appear if the outcome of the variable is not “OK”.   String:   “NR” for no reply, “NA” for not asked, “ERR” for error.
responses/variables/vThe value of the variable.

For choice questions this will either be the code label if the useCodeLabels parameter is true or the code index if it is false.		String – even if returning numbers.

HTTP Status Codes

  • 200 OK
  • 400 Bad Request
    • If maxResponses parameter is not between 1 and 5000.
    • If restrictedVariables parameter is invalid or a variable does not exist.
    • If startingFrom parameter is invalid.
    • If the filter parameter is invalid.
  • 500
    • If something else went wrong while trying to extract the responses from the survey

Other API calls

Updated
Contents

Cookie settings

You can decide which cookies you wish to allow and can change your settings at any time. You cannot prevent our use of strictly necessary cookies. For more information about the cookies we use, please see our cookie policy.

With the slider, you can enable or disable different types of cookies:

This website will:

  • Remember which cookies group you accepted
  • Strictly necessary: remember your cookie permission setting
  • Strictly necessary: allow session cookies
  • Strictly necessary: authenticate that you are logged into your user account

This website won't:

  • Functionality: remember your online chat ID
  • Analytics: keep track of your visited pages and interaction taken
  • Analytics: keep track of your location and region based on your partial IP number
  • Analytics: keep track of the time spent on each page and the videos you watch
  • Analytics: identify the device you are using
  • Targeting: identify if you contacted or called us as a result of one of our adverts

This website will:

  • Remember which cookies group you accepted
  • Strictly necessary: remember your cookie permission setting
  • Strictly necessary: allow session cookies
  • Strictly necessary: authenticate that you are logged into your user account
  • Functionality: remember your online chat ID

This website won't:

  • Analytics: keep track of your visited pages and interaction taken
  • Analytics: keep track of your location and region based on your partial IP number
  • Analytics: keep track of the time spent on each page and the videos you watch
  • Analytics: identify the device you are using
  • Targeting: identify if you contacted or called us as a result of one of our adverts

This website will:

  • Remember which cookies group you accepted
  • Strictly necessary: remember your cookie permission setting
  • Strictly necessary: allow session cookies
  • Strictly necessary: authenticate that you are logged into your user account
  • Functionality: remember your online chat ID
  • Analytics: keep track of your visited pages and interaction taken
  • Analytics: keep track of your location and region based on your partial IP number
  • Analytics: keep track of the time spent on each page and the videos you watch
  • Analytics: identify the device you are using

This website won't:

  • Targeting: identify if you contacted or called us as a result of one of our adverts

This website will:

  • Remember which cookies group you accepted
  • Strictly necessary: remember your cookie permission setting
  • Strictly necessary: allow session cookies
  • Strictly necessary: authenticate that you are logged into your user account
  • Functionality: remember your online chat ID
  • Analytics: keep track of your visited pages and interaction taken
  • Analytics: keep track of your location and region based on your partial IP number
  • Analytics: keep track of the time spent on each page and the videos you watch
  • Analytics: identify the device you are using
  • Targeting: identify if you contacted or called us as a result of one of our adverts

This website won't:

Save & Close