Get Survey Responses

Get the latest responses of a survey.

Please note that from Monday 5th December 2022 usage of the API becomes chargeable. The charge is that one 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

Method	URL
GET	surveys/{surveyId}/responses

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

Parameters

Path parameters

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

Query string parameters

Query string parameter	Required / Optional	Description	Type	Range	Default
maxResponses	Optional	The number of responses to return.	Integer	1-5000	5000
startingFrom	Optional	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.	String	N/A	“0”
returnCaseIds	Optional	Whether to return the case ID in the response.	Boolean	N/A	false
useCodeLabels	Optional	Whether to return code labels (true) or code indexes (false) for choice questions.	Boolean	N/A	false
variables	Optional	Determines 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.	String	N/A	“”
filter	Optional	The Snap XMP filter to use. The default does not use a filter. Example: (ID.endDate>=2021/01/01) and (ID.endDate<=2021/06/01)	String	N/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 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&restrictedVariables= V16,V45~V47&returnUniqueIds=true&useCodeLabels=true&startingFrom=0' \
--header 'X-USERNAME: {USERNAME}' \
--header 'X-API-KEY: {APIKEY}' \
--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."
                }
            ]
        }
    ]
}

Response Definitions

Response Item	Description	Data Type
surveyId	The survey Id you selected based on the survey Id in the request.	String: containing GUID
filter	The filter used.	String
startingFrom	The startingFrom token in the request.	String
progress	The ending token. This token can be used as the startingFrom parameter in the next call.	String
upToDate	Whether the most recent response is included.	String: containing Boolean
responses	The 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 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/caseId	The case Id of the response.	String (Default: Guid)
responses/variables	The 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/id	The variable Id (V number).	String
responses/variables/s	The 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/v	The 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

Updated5th December 2022