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
- Get Survey List
- Get Survey
- Get Survey Variables
- Get Survey Variable
- Get User Info
- Get Participant List
- Get Participant
- Add Participant
- Update Participant
- Delete Participant
- Get Participants Subjects
- Get Participant Subject
- Add Participant Subject
- Update Participant Subject
- Delete Participant Subject