API Reference

This document covers the most recent version 3.0 of the API in build 1.0.0.1381.

Please note that from Monday 5th December 2022 usage of the API became 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.

List of API endpoints

Endpoint	Description
Get User Info	Returns information for the authenticated user.
Get Survey List	Returns a list of surveys that are accessible by the user.
Get Survey	Returns the details for a specific survey ID.
Get Survey Variables	Returns the details for a specific survey ID.
Get Survey Variable	Returns the details for a specific variable ID.
Get Survey Responses	Gets the responses for a specific survey ID. Please note that from Monday 5th December 2022 usage of the API became chargeable. When one survey response is delivered by the API, 0.1 unit will be consumed.
Get Participant List	Returns a list of participants for a survey.
Get Participant	Returns the details for a specific participant in a survey.
Add Participant	Add a new participant to a survey.
Update Participant	Update an existing participant of a survey.
Delete Participant	Delete a participant from a survey.
Get Participant Subjects	Returns a list of subjects for a participant of a survey.
Get Participant Subject	Returns the details of a specific subject for a participant of a survey.
Add Participant Subject	Add a new subject to a participant of a survey.
Update Participant Subject	Update an existing subject for a participant of a survey.
Delete Participant Subject	Delete a subject from a participant of a survey.
Bulk Participant Import	Add many participants to a survey.

Get User Info

Get information for the authenticated user.

Endpoint

Method	URL
GET	https://<servername>/snaponline/api/account

Get information for the authenticated user.

Parameters

Path parameters

None

Query string parameters

None

Sample Request

curl --location --request GET 'https://<servername>/snaponline/api/account' \
--header 'X-USERNAME: {USERNAME}' \
--header 'X-API-KEY: {APIKEY}'\
--header 'X-VERSION: 3.0'

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

Sample Response

200 OK with body:

{
 "username": "jbloggs@snapsurveys.com", 
 "fullname": "Joe Bloggs",
 "emailAddress": "jbloggs@snapsurveys.com"
}

Response Definitions

Response Item	Description	Data Type
username	The username for the user.	String
fullname	The full name of the user.	String
emailAddress	The email address of the user.	String

HTTP Status Codes

200 OK

Get Survey List

Get a list of surveys that are accessible by the user. This includes surveys that are shared to the user.

Endpoint

Method	URL
GET	https://<servername>/snaponline/api/surveys

Get a list of surveys that are accessible by the user.

Parameters

Path parameters

None

Query string parameters

None

Sample Request

curl --location --request GET 'https://<servername>/snaponline/api/surveys' \
--header 'X-USERNAME: {USERNAME}' \
--header 'X-API-KEY: {APIKEY}' \
--header 'X-VERSION: 3.0'

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

Sample Response

200 OK with body:

[
    {
        "id": "2c4be70c-fe6d-4883-9fd3-629943bec836",
        "ownerId": "644f58a7-8526-4901-af7d-20969e5c68e4", 
        "ownerName": "a@example.com", 
        "name": "APIv3 Example Survey", 
        "path": [ 
            "Your work", 
            "APIv3"
        ], 
        "title": "APIv3 Example Survey", 
        "url": "https://<servername>/snaponline/Home/Index/2c4be70c-fe6d-4883-9fd3-629943bec836", 
        "interviewUrl": "https://<servername>/interview/2c4be70c-fe6d-4883-9fd3-629943bec836", 
        "interviewPreviewUrl": "https://<servername>/interview/2c4be70c-fe6d-4883-9fd3-629943bec836?preview=true", 
        "isPublished": true, 
        "lastPublishedDate": "2025-08-05T09:15:43.92",
        "interviewingState": "Started",
        "startInterviewingScheduleDate": null,
        "endInterviewingScheduleDate": null,
        "interviewingScheduleTimeZone": null,
        "numberOfResponses": 5,
        "numberOfPartials": 0,
        "responsesLastChanged": "2025-08-05T15:25:32.267",
        "shareFilter": "",
        "shareContext": ""
    },
    {
        "id": "de8e8ca3-b7e7-4810-93e6-84c65da7e7aa",
        "ownerId": "644f58a7-8526-4901-af7d-20969e5c68e4", 
        "ownerName": "b@example.com", 
        "name": "Test 1", 
        "path": [ 
            "Your work"
        ], 
        "title": "", 
        "url": "https://<servername>/snaponline/Home/Index/de8e8ca3-b7e7-4810-93e6-84c65da7e7aa", 
        "interviewUrl": "https://<servername>/interview/de8e8ca3-b7e7-4810-93e6-84c65da7e7aa", 
        "interviewPreviewUrl": "https://<servername>/interview/de8e8ca3-b7e7-4810-93e6-84c65da7e7aa?preview=true", 
        "isPublished": false, 
        "lastPublishedDate": "2025-08-05T09:15:43.92",
        "interviewingState": "Started",
        "startInterviewingScheduleDate": null,
        "endInterviewingScheduleDate": null,
        "interviewingScheduleTimeZone": null,
        "numberOfResponses": 10,
        "numberOfPartials": 0,
        "responsesLastChanged": "2025-08-05T15:25:32.267",
        "shareFilter": "",
        "shareContext": ""
    }
]

Response Definitions

Response Item	Description	Data Type
id	The survey Id.	String: containing a GUID
ownerId	The owner Id of the survey.	String: containing a GUID
ownerName	The owner name of the survey.	String
name	The display name of the survey.	String
path	The path to the survey.	List: containing strings
title	The title used in the questionnaire.	String
url	The url of the survey in Snap Online.	String
interviewUrl	The interview url.	String
interviewPreviewUrl	The preview interview url.	String
isPublished	Whether the survey is published.	Boolean
lastPublishedDate	The date time of when the survey was last published.	String: containing DateTime
interviewingState	The current interviewing state.	String: “Scheduled”, “NotStarted”, “Started” – when live, “Paused”, “Stopped” – when closed, “TooManyRespondents”
startInterviewingScheduleDate	The interviewing start date and time.	String: containing DateTime or null
endInterviewingScheduleDate	The interviewing end date and time.	String: containing DateTime or null
interviewingScheduleTimeZone	The interviewing start/end timezone.	String or null
numberOfResponses	The number of responses submitted.	Integer
numberOfPartials	The number of partial responses.	Integer
responsesLastChanged	The date and time that the list of responses for the survey was last changed, i.e. response added, deleted or edited.	String: containing DateTime
shareFilter	Filter applied to the survey for this user.	String: “” if no share filter.
shareContext	Context applied to the survey for this user.	String: “” if no share filter.

HTTP Status Codes

200 OK

Get Survey

Get details of a survey.

Endpoint

Method	URL
GET	https://<servername>/snaponline/api/surveys/{surveyId}

Gets the details of a specific survey identified by 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

None

Sample Request

curl --location --request GET 'https://<servername>/snaponline/api/surveys/2c4be70c-fe6d-4883-9fd3-629943bec836' \
--header 'X-USERNAME: {USERNAME}' \
--header 'X-API-KEY: {APIKEY}' \
--header 'X-VERSION: 3.0'

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

Sample Response

200 OK with body:

{
     "id": "2c4be70c-fe6d-4883-9fd3-629943bec836",
     "ownerId": "644f58a7-8526-4901-af7d-20969e5c68e4", 
     "ownerName": "a@example.com", 
     "name": "APIv3 Example Survey", 
     "path": [ 
         "Your work", 
         "APIv3"
     ], 
     "title": "APIv3 Example Survey", 
     "url": "https://<servername>/snaponline/Home/Index/2c4be70c-fe6d-4883-9fd3-629943bec836", 
     "interviewUrl": "https://<servername>/interview/2c4be70c-fe6d-4883-9fd3-629943bec836", 
     "interviewPreviewUrl": "https://<servername>/interview/2c4be70c-fe6d-4883-9fd3-629943bec836?preview=true", 
     "isPublished": true, 
     "lastPublishedDate": "2025-08-05T09:15:43.92",
     "interviewingState": "Started",
     "startInterviewingScheduleDate": null,
     "endInterviewingScheduleDate": null,
     "interviewingScheduleTimeZone": null,
     "numberOfResponses": 5,
     "numberOfPartials": 0,
     "responsesLastChanged": "2025-08-05T15:25:32.267",
     "shareFilter": "",
     "shareContext": ""
}

Response Definitions

Response Item	Description	Data Type
id	The survey Id.	String: containing a GUID
ownerId	The owner Id of the survey.	String: containing a GUID
ownerName	The owner name of the survey.	String
name	The display name of the survey.	String
path	The path to the survey.	List: containing strings
title	The title used in the questionnaire.	String
url	The url of the survey in Snap Online.	String
interviewUrl	The interview url.	String
interviewPreviewUrl	The preview interview url.	String
isPublished	Whether the survey is published.	Boolean
lastPublishedDate	The date time of when the survey was last published.	String: containing DateTime
interviewingState	The current interviewing state.	String: “Scheduled” “NotStarted”, “Started” – when live, “Paused”, “Stopped” – when closed, “TooManyRespondents”
startInterviewingScheduleDate	The interviewing start date and time.	String: containing DateTime or null
endInterviewingScheduleDate	The interviewing end date and time.	String: containing DateTime or null
interviewingScheduleTimeZone	The interviewing start/end timezone.	String or null
numberOfResponses	The number of responses submitted.	Integer
numberOfPartials	The number of partial responses.	Integer
responsesLastChanged	The date and time that the list of responses for the survey was last changed, i.e. response added, deleted or edited.	String: containing DateTime
shareFilter	Filter applied to the survey for this user.	String: “” if no share filter.
shareContext	Context applied to the survey for this user.	String: “” if no share context.

HTTP Status Codes

200 OK

Get Survey Variables

Get details of all of the variables for a survey.

Endpoint

Method	URL
GET	https://<servername>/snaponline/api/surveys/{surveyId}/variables

Get details of all of the variables of the specific survey identified by 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
includeCodes	Optional	Whether to return code information for the variable in the response.	Boolean	N/A	true

Sample Request

curl --location --request GET 'https://<servername>/snaponline/api/surveys/6834a5f1-46e5-4b12-9e0c-a38a3d9be12c/variables' \
--header 'X-USERNAME: {USERNAME}' \
--header 'X-API-KEY: {APIKEY}' \
--header 'X-VERSION: 3.0'

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

Sample Response

200 OK with body (when ‘includeCodes’ is false):

{
    "surveyId": "6834a5f1-46e5-4b12-9e0c-a38a3d9be12c",
    "variables": [        
        {
            "order": 14,
            "variableId": "V46",
            "label": "What was the main form of transport used to get to the at...",
            "name": "Q1",
            "questionText": "What was the main form of transport used to get to the attraction?",
            "variableTypeId": 6,
            "paraDataTypeId": -2,
            "responseTypeId": 1,
            "variableType": "Question",
            "paraDataType": "NOT_PARA_DATA",
            "responseType": "Single",
            "codeCount": 7
        },
        {
            "order": 15,
            "variableId": "V48",
            "label": "Which facilities did you visit?",
            "name": "Q2",
            "questionText": "Which facilities did you visit?",
            "variableTypeId": 6,
            "paraDataTypeId": -2,
            "responseTypeId": 2,
            "variableType": "Question",
            "paraDataType": "NOT_PARA_DATA",
            "responseType": "Multiple",
            "codeCount": 3
        },
        {
            "order": 16,
            "variableId": "V52",
            "label": "Please tell us if there were any issues, otherwise leave ...",
            "name": "Q3",
            "questionText": "Please tell us if there were any issues, otherwise leave blank.",
            "variableTypeId": 6,
            "paraDataTypeId": -2,
            "responseTypeId": 4,
            "variableType": "Question",
            "paraDataType": "NOT_PARA_DATA",
            "responseType": "Literal",
            "codeCount": 0
        }
    ]
}

200 OK with body (when ‘includeCodes’ is true):

{
    "surveyId": "6834a5f1-46e5-4b12-9e0c-a38a3d9be12c",
    "variables": [        
        {
            "order": 14,
            "variableId": "V46",
            "label": "What was the main form of transport used to get to the at...",
            "name": "Q1",
            "questionText": "What was the main form of transport used to get to the attraction?",
            "variableTypeId": 6,
            "paraDataTypeId": -2,
            "responseTypeId": 1,
            "variableType": "Question",
            "paraDataType": "NOT_PARA_DATA",
            "responseType": "Single",
            "codeCount": 7,
            "codes": [
                {
                    "codeIndex": 1,
                    "codeValue": 3,
                    "codeLabel": "Walk"
                },
                {
                    "codeIndex": 2,
                    "codeValue": 5,
                    "codeLabel": "Bike"
                },
                {
                    "codeIndex": 3,
                    "codeValue": 8,
                    "codeLabel": "Motorbike"
                },
                {
                    "codeIndex": 4,
                    "codeValue": 4,
                    "codeLabel": "Car"
                },
                {
                    "codeIndex": 5,
                    "codeValue": 6,
                    "codeLabel": "Bus"
                },
                {
                    "codeIndex": 6,
                    "codeValue": 9,
                    "codeLabel": "Train"
                },
                {
                    "codeIndex": 7,
                    "codeValue": 10,
                    "codeLabel": "Plane"
                }
            ]
        },
        {
            "order": 15,
            "variableId": "V48",
            "label": "Which facilities did you visit?",
            "name": "Q2",
            "questionText": "Which facilities did you visit?",
            "variableTypeId": 6,
            "paraDataTypeId": -2,
            "responseTypeId": 2,
            "variableType": "Question",
            "paraDataTypeId": "NOT_PARA_DATA",
            "responseType": "Multiple",
            "codeCount": 3,
            "codes": [
                {
                    "codeIndex": 1,
                    "codeValue": 1,
                    "codeLabel": "Restaurant / Cafe"
                },
                {
                    "codeIndex": 2,
                    "codeValue": 2,
                    "codeLabel": "Gift Shop"
                },
                {
                    "codeIndex": 3,
                    "codeValue": 3,
                    "codeLabel": "Customer Services"
                }
            ]
        },
        {
            "order": 16,
            "variableId": "V52",
            "label": "Please tell us if there were any issues, otherwise leave ...",
            "name": "Q3",
            "questionText": "Please tell us if there were any issues, otherwise leave blank.",
            "variableTypeId": 6,
            "paraDataTypeId": -2,
            "responseTypeId": 4,
            "variableType": "Question",
            "paraDataType": "NOT_PARA_DATA",
            "responseType": "Literal",
            "codeCount": 0,
            "codes": []
        }
    ]
}

Response Definitions

Response Item	Description	Data Type
surveyId	The survey Id.	String: containing GUID
variables	The list of variables.	List: containing objects
variables/order	The positional order of the variable.	Integer
variables/variableId	The V number of the variable	String
variables/label	The label of the variable.	String
variables/name	The name of the variable.	String
variables/questionText	The question text of the variable. i.e. the question shown to the respondent.	String
variables/variableTypeId	The numeric code for the variable type.	Integer: Unknown = 0, Precoded = 1, Numeric = 2, Alphanumeric = 3, Derived = 5, Question = 6, Note = 7
variables/paraDataTypeId	The numeric code for the para data variable.	Integer: SITE=0, NAME=1, DATE=2, START=3, END=4, DURATION=5, CASE=6, RESET=7, ENDDATE=8, INTERVIEWER=9, PASSWORD=10, LANGUAGE=11, FORMAT=12, URL=13, SURV_INDEX=14, LOCATION=15, RECORDING=16, PAGE=17, PANEL=18, SERVERDATE=19, SERVERTIME=20, UNKNOWN=-1, NOT_PARA_DATA = -2
variables/responseTypeId	The numeric code for the response type.	Integer: Unknown = 0, Single = 1, Multiple = 2, Quantity = 3, Literal = 4, None = 5, Date = 6, Time = 7
variables/variableType	The type of the variable.	String: “Unknown”, “Precoded”, “Numeric”, “Alphanumeric”, “Derived”, “Question”, “Note”.
variables/paraDataType	The type of the para data variable.	String: “SITE”, “NAME”, “DATE”, “START”, “END”, “DURATION”, “CASE”, “RESET”, “ENDDATE”, “INTERVIEWER”, “PASSWORD”, “LANGUAGE”, “FORMAT”, “URL”, “SURV_INDEX”, “LOCATION”, “RECORDING”, “PAGE”, “PANEL”, “SERVERDATE”, “SERVERTIME”, “UNKNOWN”, “NOT_PARA_DATA”
variables/responseType	The response type of the answer.	String: “Unknown”, “Single”, “Multiple”, “Quantity”, “Literal”, “None”, “Date”, “Time”
variables/codeCount	If a choice question this states the number of codes. If not a choice question then this will be 0.	Integer
variables/codes	A list of variable codes. This section will only appear if the includeCodes query parameter is true or omitted AND the variable is a choice question.	List: containing Objects
variables/codes/codeIndex	The index of the variable code.	Integer
variables/codes/codeValue	The value of the variable code.	Integer
variables/codes/codeLabel	The label of the variable code.	String

HTTP Status Codes

200 OK

Get Survey Variable

Get the details of a variable of a survey.

Endpoint

Method	URL
GET	https://<servername>/snaponline/api/surveys/{surveyId}/variables/{variableId}

Get the details of the specific variable identified by the variableId path variable of the specific survey identified by 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.
{variableId}	The unique V number of the variable. This is the variable Id property returned in the Get Survey Variables end-point.

Query string parameters

None

Sample Request

curl --location --request GET 'https://localhost/snaponline/api/surveys/e819df57-0a01-4592-a7aa-8918dbe54e00/variables/V46' \
--header 'X-USERNAME: {USERNAME}' \
--header 'X-API-KEY: {APIKEY}' \
--header 'X-VERSION: 3.0'

(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",
    "variable": {
        "order": 15,
        "variableId": "V48",
        "label": "Which facilities did you visit?",
        "name": "Q2",
        "questionText": "Which facilities did you visit?",
        "variableTypeId": 6,
        "paraDataTypeId": -2,
        "responseTypeId": 2,
        "variableType": "Question",
        "paraDataType": "NOT_PARA_DATA",
        "responseType": "Multiple",
        "codeCount": 3,
        "codes": [
            {
                "codeIndex": 1,
                "codeValue": 1,
                "codeLabel": "Restaurant / Cafe"
            },
            {
                "codeIndex": 2,
                "codeValue": 2,
                "codeLabel": "Gift Shop"
            },
            {
                "codeIndex": 3,
                "codeValue": 3,
                "codeLabel": "Customer Services"
            }
        ]
    }
}

Response Definitions

Response Item	Description	Data Type
surveyId	The survey Id.	String: containing GUID
variable	The variable.	Object
variable/order	The positional order of the variable.	Integer
variable/variableId	The V number of the variable	String
variable/label	The label of the variable.	String
variable/name	The name of the variable.	String
variable/questionText	The question text of the variable. i.e. the question shown to the respondent.	String
variable/variableTypeId	The numeric code for the variable type.	Integer: Unknown = 0, Precoded = 1, Numeric = 2, Alphanumeric = 3, Derived = 5, Question = 6, Note = 7
variable/paraDataTypeId	The numeric code for the para data variable.	Integer: SITE=0, NAME=1, DATE=2, START=3, END=4, DURATION=5, CASE=6, RESET=7, ENDDATE=8, INTERVIEWER=9, PASSWORD=10, LANGUAGE=11, FORMAT=12, URL=13, SURV_INDEX=14, LOCATION=15, RECORDING=16, PAGE=17, PANEL=18, SERVERDATE=19, SERVERTIME=20, UNKNOWN=-1, NOT_PARA_DATA = -2
variable/responseTypeId	The numeric code for the response type.	Integer: Unknown = 0, Single = 1, Multiple = 2, Quantity = 3, Literal = 4, None = 5, Date = 6, Time = 7
variable/variableType	The type of the variable.	String: “Unknown”, “Precoded”, “Numeric”, “Alphanumeric”, “Derived”, “Question”, “Note”.
variable/paraDataType	The type of the para data variable.	String: “SITE”, “NAME”, “DATE”, “START”, “END”, “DURATION”, “CASE”, “RESET”, “ENDDATE”, “INTERVIEWER”, “PASSWORD”, “LANGUAGE”, “FORMAT”, “URL”, “SURV_INDEX”, “LOCATION”, “RECORDING”, “PAGE”, “PANEL”, “SERVERDATE”, “SERVERTIME”, “UNKNOWN”, “NOT_PARA_DATA”
variable/responseType	The response type of the answer.	String: “Unknown”, “Single”, “Multiple”, “Quantity”, “Literal”, “None”, “Date”, “Time”
variable/codeCount	If a choice question this states the number of codes. If not a choice question then this will be 0.	Integer
variable/codes	A list of codes.	List: containing objects
variable/codes/codeIndex	The index of the variable code.	Integer
variable/codes/codeValue	The value of the variable code.	Integer
variable/codes/codeLabel	The label of the variable code.	String

HTTP Status Codes

200 OK
404 Not Found – if survey variable does not exist.

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.

Endpoint

Method	URL
GET	https://<servername>/snaponline/api/surveys/{surveyId}/responses

Get the 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	We 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	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	“”
useVariableNames	Optional	If false the variables are identified by an id property and the value will be the variable V number. If true the variables are identified by a name property instead of an id property and the value will be the actual variable name.	Boolean	N/A	false
latestCasesOnly	Optional	If false, the output will include a response for every edit. If true, the output edits will be rolled into fewer responses.	Boolean	N/A	false
excludeDeletedCases	Optional	Excludes cases that have been deleted. You will never see a response/status of deleted.	Boolean	N/A	fasle

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

1. 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: 3.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": "c23a0fd8-6219-4130-a6a7-f312829e56eb",
    "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: 3.0' \
--data-raw ''

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. Only appears if the filter query parameter was provided.	String
startingFrom	The startingFrom token in the request. This is recommended.	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.	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 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 and the excludeDeletedCases parameter to false).	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	If the useVariablesName parameter is false or not provided: The variable Id (V number).	String
responses/variables/name	If the useVariablesName parameter is true: The variable Id (name).	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 variables 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

Get Participant List

Get the details of the current participants of a survey.

Endpoint

Method	Url
GET	https://snaponline/api/surveys/{surveyId}/participants

Get the details of current participants of the specific survey identified by 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
maxParticipants	Optional	The number of participants to return.	Integer	1-5000	5000
startingFrom	Optional	Returns participants from the startingFrom token. This value is “0” to start at the beginning or a token to start from a particular point in the participants collection. Example: #IBCGEGG. To get the next set of participants (if the output UpToDate property is false) feed the progress token of the output into the startingFrom token and make the call again.	String	N/A	“0”

Sample Request

curl --location --request GET 'https:// <servername>/snaponline/api/surveys/20dbe888-ec99-4895-b094-e34084f9408f/participants?startingFrom=0&maxParticipants=2' \
--header 'X-USERNAME: {USERNAME}' \
--header 'X-API-KEY: {APIKEY}' \
--header 'X-VERSION: 3.0'

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

Sample Response

200 OK with body:

{
    "surveyId": "20dbe888-ec99-4895-b094-e34084f9408f",
    "startingFrom": "0",
    "progress": "#ECDEHDIHBB",
    "upToDate": false,
    "participants": [
        {
            "id": "e8623247-5aa9-4bbb-864b-5c76b1749c7a",
            "enabled": true,
            "invitationSection": {
                "optedOut": false,
                "sendInvitations": true,
                "emailAddress": "a@example.com"
            },
            "loginSection": {
                "login": "A",
                "password": null,
                "interviewer": null,
                "status": "NotStarted"
            }
        },
        {
            "id": "e8623247-5aa9-4bbb-864b-5c76b1749c7b",
            "enabled": true,
            "invitationSection": {
                "optedOut": false,
                "sendInvitations": true,
                "emailAddress": "b@example.com"
            },
            "loginSection": {
                "login": "B",
                "password": null,
                "interviewer": null,
                "status": "NotStarted"
            }
        }
    ]
}

Response Definitions

Response Item	Description	Data Type
surveyId	The survey Id you selected based on the survey Id in the request.	String: containing GUID
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 participant is included.	String: containing Boolean
participants	The participants. The number of participants will be based on the maxParticipants request parameter.	List: containing objects
participants/id	The id of the participant.	String: containing GUID
participants/enabled	Whether the participant is enabled.	Boolean
participants/loginSection	The login section for a logged on survey participant. Section will be omitted if not a logged on survey.	Object
participants/loginSection/login	If a logged on survey this will be the login name otherwise null.	String or null
participants/loginSection/password	If a logged on survey and a password is required this will be the password otherwise null or “”.	String or null
participants/loginSection/interviewer	If the survey allows synchronisation of participants with SOI but the API user does not have Manage participants for SOI permission this will be null. If survey does not allow synchronisation of participants to SOI this will be null. If the survey allows synchronisation of participants to SOI and the API user has Manage participants for SOI permission this will be either “” signifying that all interviewers will have access or an email address of the interviewer.	String or null
participants/loginSection/status	If the survey is a logged on but not a group questionnaire then this is the status of the participant. If the survey is a logged on and group questionnaire then this is the overall status for the participant across all the questionnaires. If the survey is invite only then the status will be null.	String or null: For non group questionnaire: “NotStarted” – the participant has not started the questionnaire. “Started” the participant has started the questionnaire. “Partial” – a partial response has been taken. “Saved” – the participant has saved the questionnaire. “Completed” – the participant has completed the questionnaire. “Submitted” – the researcher has submitted a partial response. For group questionnaire: “NotStarted” – the participant has not started any of the questionnaires. “Started” – the participant has started at least one of the questionnaires. “Completed” – the participant has completed all of the questionnaires. This includes whether a researcher submitted a partial.
participants/invitationSection	The invitation section for an invited survey participant. Section will be omitted if not an invited survey.	Object
participants/ invitationSection/emailAddress	If an invited survey this will be the email address of the participant or empty string if not an invite survey.	String
participants/invitationSection/ sendInvitations	Whether invitations are to be sent.	Boolean
participants/invitationSection/ optedOut	Whether the user is opted out from emails.	Boolean

HTTP Status Codes

200 OK

Get Participant

Get the details of a participant of a survey.

Endpoint

Method	Url
GET	https://snaponline/api/surveys/{surveyId}/participants/{participantUniqueId}

Get details of the specific participant identified by the participantUniqueId path variable of the specific survey identified by 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.
{participantUniqueId}	This is either the login name if a logged in survey or else the email address.

Query string parameters

None

Sample Request

curl --location --request GET 'https:// <servername>/snaponline/api/surveys/20dbe888-ec99-4895-b094-e34084f9408f/participants/A' \
--header 'X-USERNAME: {USERNAME}' \
--header 'X-API-KEY: {APIKEY}' \
--header 'X-VERSION: 3.0'

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

Sample Responses

The response structure is determined by the participant feature configuration of the survey. This is shown in the participant import wizard of Snap Online.

If the configuration has Allow Snap Online to track respondents ticked it is a logged on survey and a loginSection will be included. If the configuration has Send email invites / reminders ticked then an invitationSection will be included.

The invitationSection will always include an inviteSeeding section even if there isn’t any seeding.

The loginSection will always have a questionnaireSeeding section even if there isn’t any seeding.

If the configuration has Group Questionnaire ticked then there will be one or more subjects inside the loginSection section and each subjectName property will be a non empty string.

If the configuration does not have Group Questionnaire ticked then there will be exactly one subject inside the loginSection section and the subjectName property will be an empty string.

200 OK with body (invite only participant with some invite seeding):

{
    "invitationSection": {
        "optedOut": false,
        "sendInvitations": true,
        "emailAddress": "a@example.com",
        "invitationSeeding": {
            "forenames": "A",
            "surname": "A"
        }
    }, 
    "id": "e8623247-5aa9-4bbb-864b-5c76b1749c7a",   
    "enabled": true
}

200 OK with body (log on and invite participant – group questionnaire):

{
    "invitationSection": {
        "optedOut": false,
        "sendInvitations": true,
        "emailAddress": "a@example.com",
        "invitationSeeding": {
            "forenames": "A",
            "surname": "A"
        }
    },
    "loginSection": {
        "login": "A",
        "password": null,
        "interviewer": null,
        "status": "NotStarted",
        "subjects": [
            {
                "subjectName": "L1",
                "questionnaireSeeding": {
                    "v53": "L1",
                    "v48": "2;3",
                    "v50": "A",
                    "v51": "A",
                    "v46": "4"
                },
                "status": "NotStarted"
            }
        ]
    },
    "id": "e8623247-5aa9-4bbb-864b-5c76b1749c7a",
    "enabled": true
}

Response Definitions

Response Item	Description	Data Type
id	The participant id.	String: containing GUID
enabled	Whether the participant is enabled.	Boolean
invitationSection	The invitation section for an invited survey participant. Section will be omitted if not an invited survey.	Object
invitationSection/optedOut	Whether invitations are to be sent.	Boolean
invitationSection/sendInvitations	Whether the user is opted out from emails.	Boolean
invitationSection/emailAddress	The email address.	String
invitationSection/inviteSeeding	The invite seeding. This is a dictionary of properties in the form “<invite key>” : “<value>”	Object
loginSection	The login section for a logged on survey participant. Section will be omitted if not a logged on survey.	Object
loginSection/login	If a logged on survey this will be the login name otherwise null.	String or null
loginSection/password	If a logged on survey and a password is required this will be the password otherwise null or “”.	String or null
loginSection/interviewer	If the survey allows synchronisation of participants with SOI but the API user does not have Manage participants for SOI permission this will be null. If survey does not allow synchronisation of participants to SOI this will be null. If the survey allows synchronisation of participants to SOI and the API user has Manage participants for SOI permission this will be either “” signifying that all interviewers will have access or an email address of the interviewer.	String or null
loginSection/status	This is the overall status. If the survey is a logged on but not a group questionnaire, then this is the status of the participant. If the survey is a logged on and group questionnaire, then this is the overall status for the participant across all the questionnaires. If the survey is invite only then the status will be null.	String or null: For non group questionnaire: “NotStarted” – the participant has not started the questionnaire. “Started” the participant has started the questionnaire. “Partial” – a partial response has been taken. “Saved” – the participant has saved the questionnaire. “Completed” – the participant has completed the questionnaire. “Submitted” – the researcher has submitted a partial response. For group questionnaire: “NotStarted” – the participant has not started any of the questionnaires. “Started” – the participant has started at least one of the questionnaires. “Completed” – the participant has completed all of the questionnaires. This includes whether a researcher submitted a partial.
loginSection/subjects	The subjects for the participant. For a group questionnaire there will be one or more. For a non-group questionnaire there will just be one.	List
loginSection/subjects/subjectName	For a group questionnaire subjectName will not be an empty string. For a non group questionnaire the subjectName must be an empty string.	String
loginSection/subjects/ questionnaireSeeding	The questionnaire seeding for the subject. This is a dictionary of properties in the form “<variable V number>” : “<value>”.	Object
loginSection/subjects/status	This is the subject status.	String or null: “NotStarted” – the participant has not started the questionnaire. “Started” the participant has started the questionnaire. “Partial” – a partial response has been taken. “Saved” – the participant has saved the questionnaire. “Completed” – the participant has completed the questionnaire. “Submitted” – the researcher has submitted a partial response.

HTTP Status Codes

200 OK

404 Not Found

Add Participant

Add a new participant to a survey.

Endpoint

Method	Url
POST	https://snaponline/api/surveys/{surveyId}/participants

Add a new participant to the specific survey identified by 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

None

Request body data

Requires request body of JSON object e.g.:

{
    "invitationSection": {
        "optedOut": false,
        "sendInvitations": true,
        "emailAddress": "a@example.com",
        "invitationSeeding": {
            "forenames": "A",
            "surname": "A"
        }
    },
    "loginSection": {
        "login": "A",
        "password": null,
        "interviewer": null,
        "status": "NotStarted",
        "subjects": [
            {
                "subjectName": "L1",
                "questionnaireSeeding": {
                    "v53": "L1",
                    "v48": "2;3",
                    "v50": "A",
                    "v51": "A",
                    "v46": "4"
                },
                "status": "NotStarted"
            }
        ]
    },
    "enabled": true
}

Note. The above example is creating a participant in a survey where the participant feature requires that the participant be invited and that the participant has to provide credentials to view the questionnaire. Therefore, you must specify both the invitationSection section and the loginSection section in the call. The example is also for a group questionnaire and it will create one subject for the participant. In a non-group questionnaire, you must provide one subject and the subjectName property should be an empty string.

For an invite only survey do not include a loginSection section. For a logged on only survey do not include an invitationSection section.

The status properties are read-only so will be ignored if specified.

If the survey allows interviewers for SOI then you specify the interviewer in the interviewer property. The interviewer must be the email address of a user that has SOI access to the survey. If you don’t want to specify an interviewer set it to an empty string. If the survey does not allow interviewers set it to null.

Sample Request

curl --location --request POST 'https:// <servername>/snaponline/api/surveys/20dbe888-ec99-4895-b094-e34084f9408f/participants' \
--header 'X-USERNAME: {USERNAME}' \
--header 'X-API-KEY: {APIKEY}' \
--header 'X-VERSION: 3.0' \
--header 'Content-Type: application/json' \
--data-raw '{
    "invitationSection": {
        "optedOut": false,
        "sendInvitations": true,
        "emailAddress": "a@example.com",
        "invitationSeeding": {
            "forenames": "E",
            "surname": "E"
        }
    },
    "loginSection": {
        "login": "E",
        "password": null,
        "interviewer": null,
        "status": "NotStarted",
        "subjects": [
            {
                "subjectName": "L1",
                "questionnaireSeeding": {
                    "v53": "L1",
                    "v48": "2;3",
                    "v50": "A",
                    "v51": "A",
                    "v46": "4"
                },
                "status": "NotStarted"
            }
        ]
    },
    "enabled": true
}'

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

Note. The status field is read-only. If you send it into the request body as in the sample request above it will be ignored.

Sample Response

{
    "invitationSection": {
        "optedOut": false,
        "sendInvitations": true,
        "emailAddress": "a@example.com",
        "invitationSeeding": {}
    },
    "loginSection": {
        "login": "E",
        "password": null,
        "interviewer": null,
        "status": "NotStarted",
        "subjects": [
            {
                "subjectName": "L1",
                "questionnaireSeeding": {
                    "v48": "2;3",
                    "v50": "A",
                    "v53": "L1",
                    "v51": "A",
                    "v46": "4"
                },
                "status": "NotStarted"
            }
        ]
    },
    "id": "91188b33-0149-48ed-bf65-b9ecbc741f8d",
    "enabled": true
}

Response Definitions

Response Item	Description	Data Type
id	The participant id.	String: containing GUID
enabled	Whether the participant is enabled.	Boolean
invitationSection	The invitation section for an invited survey participant. Section will be omitted if not an invited survey.	Object
invitationSection/optedOut	Whether invitations are to be sent.	Boolean
invitationSection/sendInvitations	Whether the user is opted out from emails.	Boolean
invitationSection/emailAddress	The email address.	String
invitationSection/inviteSeeding	The invite seeding. This is a dictionary of properties in the form “<invite key>” : “<value>”	Object
loginSection	The login section for a logged on survey participant. Section will be omitted if not a logged on survey.	Object
loginSection/login	If a logged on survey this will be the login name otherwise null.	String or null
loginSection/password	If a logged on survey and a password is required this will be the password otherwise null or “”.	String or null
loginSection/interviewer	If the survey allows synchronisation of participants with SOI but the API user does not have Manage participants for SOI permission this will be null. If survey does not allow synchronisation of participants to SOI this will be null. If the survey allows synchronisation of participants to SOI and the API user has Manage participants for SOI permission this will be either “” signifying that all interviewers will have access or an email address of the interviewer.	String or null
loginSection/status	This is the overall status. If the survey is a logged on but not a group questionnaire then this is the status of the participant. If the survey is a logged on and group questionnaire then this is the overall status for the participant across all the questionnaires. If the survey is invite only then the status will be null.	String or null: For non group questionnaire: “NotStarted” – the participant has not started the questionnaire. “Started” the participant has started the questionnaire. “Partial” – a partial response has been taken. “Saved” – the participant has saved the questionnaire. “Completed” – the participant has completed the questionnaire. “Submitted” – the researcher has submitted a partial response. For group questionnaire: “NotStarted” – the participant has not started any of the questionnaires. “Started” – the participant has started at least one of the questionnaires. “Completed” – the participant has completed all of the questionnaires. This includes whether a researcher submitted a partial.
loginSection/subjects	The subjects for the participant. For a group questionnaire there will be one or more. For a non-group questionnaire there will just be one.	List
loginSection/subjects/subjectName	For a group questionnaire subject name will not be an empty string. For a non group questionnaire the subject name must be an empty string.	String
loginSection/subjects/ questionnaireSeeding	The questionnaire seeding for the subject. This is a dictionary of properties in the form “<variable V number>” : “<value>”.	Object
loginSection/subjects/status	This is the subject status.	String or null: “NotStarted” – the participant has not started the questionnaire. “Started” the participant has started the questionnaire. “Partial” – a partial response has been taken. “Saved” – the participant has saved the questionnaire. “Completed” – the participant has completed the questionnaire. “Submitted” – the researcher has submitted a partial response.
enabled	Whether the participant is enabled.	Boolean

HTTP Status Codes

201 Created

The response headers will include a Location key where the value is the URL to call to get the participant.

400 Bad Request – various including:

{
    "message": "Participants require a login section."
}

"message": "You must provide a login name."
"message": "Participants require an invitation section."
"message": "Participants should not have an invitation section."
"message": "Participants should not have a login section."
"message": "The unique participant id provided in the URL must be the same as in the request body."
"message": "Not allowed to add, update or delete an interviewer."
"message": "Must provide an interviewer property and value cannot be null."
"message": "Interviewer does not have access to the survey."
"message": Participants for this survey must have one subject."
"message": "Participants for this survey must only have one subject and the subject name must be an empty string."
"message": "Participants for this survey must have at least one subject."
"message": "Subject name cannot be blank for a group questionnaire."
"message": "Participant cannot be opted out and have send invitations enabled at the same time."
"message": "The unique participant id provided in the URL must be the same as in the request body."
"message": "You must provide a valid email address."
"message": "If an email address is provided, it must be valid."
"message": "Another participant already has this login name."
"message": "Participants for this survey must have unique subjects."
"message": "Participant to update does not exist."
"message": "Participant subjects do not match."
"message": "Another participant already has this email address."
"message": "Survey does not support participants."
"message": "Participants cannot be added, updated or deleted whilst an import is scheduled or running."
"message": "Participant invite seeding does not have a '<invite item>' seeding property."
"message": "Participant questionnaire seeding does not have a '<questionnaire item>}' seeding property."
"message": "Survey does not have a '<questionnaire item>' variable."
"message": "Survey variable '<questionnaire item>' is single choice. Multiple values are not allowed."
"message": "Survey variable '<questionnaire item>' cannot contain duplicate code values."
"message": "Survey variable '<questionnaire item>' does not contain code value '<code value>'."

Update Participant

Update an existing participant of a survey.

Endpoint

Method	Url
PUT	https://snaponline/api/surveys/{surveyId}/participants/{participantUniqueId}

Update the existing specific participant identified by the participantUniqueId path variable of the specific survey identified by 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.
{participantUniqueId}	This is either the login name if a logged in survey or else the email address.

Query string parameters

None

Request body data

Requires request body of JSON object e.g.:

{
    "invitationSection": {
        "optedOut": false,
        "sendInvitations": true,
        "emailAddress": "a@example.com",
        "inviteSeeding": {
            "surname": "D",
            "forenames": "David"
        }
    },
    "loginSection": {
        "login": "A4",
        "password": null,
        "interviewer": "",
        "status": "NotStarted",
        "subjects": [
            {
                "subjectName": "Alton Towers",
                "questionnaireSeeding": {
                    "v45": "David",
                    "v46": "D"
                },
                "status": "NotStarted"
            },
            {
                "subjectName": "Chester Zoo",
                "questionnaireSeeding": {
                    "v45": "David",
                    "v46": "D"
                },
                "status": "NotStarted"
            }
        ]
    },
    "enabled": true
}

Note. The above example is updating a participant in a survey where the participant feature requires that the participant be invited and that the participant has to provide credentials to view the questionnaire. Therefore, you must specify both the invitationSection section and the logonSection section in the call. The example is also for a group questionnaire and it will create two subjects for the participant. In a non-group questionnaire you must provide one subject and the subjectName property should be an empty string.

For an invite only survey do not include a loginSection section. For a logged on only survey do not include an invitationSection section.

The status properties are read-only so will be ignored if specified.

If the survey allows interviewers for SOI then you specify the interviewer in the interviewer property. The interviewer must be the email address of a user that has SOI access to the survey. If you don’t want to specify an interviewer set it to an empty string. If the survey does not allow interviewers set it to null.

Sample Request

curl --location --request PUT 'https:// <servername>/snaponline/api/surveys/20dbe888-ec99-4895-b094-e34084f9408f/participants/E' \
--header 'X-USERNAME: {USERNAME}' \
--header 'X-API-KEY: {APIKEY}' \
--header 'X-VERSION: 3.0' \
--header 'Content-Type: application/json' \
--data-raw '{
    "invitationSection": {
        "optedOut": false,
        "sendInvitations": true,
        "emailAddress": "a@example.com",
        "invitationSeeding": {}
    },
    "loginSection": {
        "login": "E",
        "password": null,
        "interviewer": null,
        "status": "NotStarted",
        "subjects": [
            {
                "subjectName": "L1",
                "questionnaireSeeding": {
                    "v48": "2;3",
                    "v50": "A",
                    "v53": "L1",
                    "v51": "A",
                    "v46": "6"
                },
                "status": "NotStarted"
            }
        ]
    },
    "enabled": true
}'

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

Note. The status field is read-only. If you send it into the request body as in the sample request above it will be ignored

Sample Response

{
    "invitationSection": {
        "optedOut": false,
        "sendInvitations": true,
        "emailAddress": "a@example.com",
        "invitationSeeding": {}
    },
    "loginSection": {
        "login": "E",
        "password": null,
        "interviewer": null,
        "status": "NotStarted",
        "subjects": [
            {
                "subjectName": "L1",
                "questionnaireSeeding": {
                    "v48": "2;3",
                    "v50": "A",
                    "v53": "L1",
                    "v51": "A",
                    "v46": "6"
                },
                "status": "NotStarted"
            }
        ]
    },
    "id": "91188b33-0149-48ed-bf65-b9ecbc741f8d",
    "enabled": true
}

Response Definitions

Response Item	Description	Data Type
id	The participant id.	String: containing GUID
enabled	Whether the participant is enabled.	Boolean
invitationSection	The invitation section for an invited survey participant. Section will be omitted if not an invited survey.	Object
invitationSection/optedOut	Whether invitations are to be sent.	Boolean
invitationSection/sendInvitations	Whether the user is opted out from emails.	Boolean
invitationSection/emailAddress	The email address.	String
invitationSection/inviteSeeding	The invite seeding. This is a dictionary of properties in the form “<invite key>” : “<value>”	Object
loginSection	The login section for a logged on survey participant. Section will be omitted if not a logged on survey.	Object
loginSection/login	If a logged on survey this will be the login name otherwise null.	String or null
loginSection/password	If a logged on survey and a password is required this will be the password otherwise null or “”.	String or null
loginSection/interviewer	If the survey allows synchronisation of participants with SOI but the API user does not have Manage participants for SOI permission this will be null. If survey does not allow synchronisation of participants to SOI this will be null. If the survey allows synchronisation of participants to SOI and the API user has Manage participants for SOI permission this will be either “” signifying that all interviewers will have access or an email address of the interviewer.	String or null
loginSection/status	This is the overall status. If the survey is a logged on but not a group questionnaire then this is the status of the participant. If the survey is a logged on and group questionnaire then this is the overall status for the participant across all the questionnaires. If the survey is invite only then the status will be null.	String or null: For non group questionnaire: “NotStarted” – the participant has not started the questionnaire. “Started” the participant has started the questionnaire. “Partial” – a partial response has been taken. “Saved” – the participant has saved the questionnaire. “Completed” – the participant has completed the questionnaire. “Submitted” – the researcher has submitted a partial response. For group questionnaire: “NotStarted” – the participant has not started any of the questionnaires. “Started” – the participant has started at least one of the questionnaires. “Completed” – the participant has completed all of the questionnaires. This includes whether a researcher submitted a partial.
loginSection/subjects	The subjects for the participant. For a group questionnaire there will be one or more. For a non-group questionnaire there will just be one.	List
loginSection/subjects/subjectName	For a group questionnaire subjectName will not be an empty string. For a non group questionnaire the subjectName must be an empty string.	String
loginSection/subjects/ questionnaireSeeding	The questionnaire seeding for the subject. This is a dictionary of properties in the form “<variable V number>” : “<value>”.	Object
loginSection/subjects/status	This is the subject status.	String or null: “NotStarted” – the participant has not started the questionnaire. “Started” the participant has started the questionnaire. “Partial” – a partial response has been taken. “Saved” – the participant has saved the questionnaire. “Completed” – the participant has completed the questionnaire. “Submitted” – the researcher has submitted a partial response.
enabled	Whether the participant is enabled.	Boolean

HTTP Status Codes

200 OK

404 Not Found with:

{
    "message": "Participant not found."
}

400 Bad Request – various including:

{
    "message": "Participants require a login section."
}

"message": "You must provide a login name."
"message": "Participants require an invitation section."
"message": "Participants should not have an invitation section."
"message": "Participants should not have a login section."
"message": "The unique participant id provided in the URL must be the same as in the request body."
"message": "Not allowed to add, update or delete an interviewer."
"message": "Must provide an interviewer property and value cannot be null."
"message": "Interviewer does not have access to the survey."
"message": Participants for this survey must have one subject."
"message": "Participants for this survey must only have one subject and the subject name must be an empty string."
"message": "Participants for this survey must have at least one subject."
"message": "Subject name cannot be blank for a group questionnaire."
"message": "Participant cannot be opted out and have send invitations enabled at the same time."
"message": "The unique participant id provided in the URL must be the same as in the request body."
"message": "You must provide a valid email address."
"message": "If an email address is provided, it must be valid."
"message": "Participant with this login name does not exist."
"message": "Participant with this login name already exists."
"message": "Participants for this survey must have unique subjects."
"message": "Participant to update does not exist."
"message": "Participant subjects do not match."
"message": "Participant with this email address does not exist."
"message": "Survey does not support participants."
"message": "Participants cannot be added, updated or deleted whilst an import is scheduled or running."
"message": "Participant invite seeding does not have a '<invite item>' seeding property."
"message": "Participant questionnaire seeding does not have a '<questionnaire item>}' seeding property."
"message": "Survey does not have a '<questionnaire item>' variable."
"message": "Survey variable '<questionnaire item>' is single choice. Multiple values are not allowed."
"message": "Survey variable '<questionnaire item>' cannot contain duplicate code values."
"message": "Survey variable '<questionnaire item>' does not contain code value '<code value>'."

Delete Participant

Delete an existing participant of a survey.

Endpoint

Method	Url
DELETE	https://snaponline/api/surveys/{surveyId}/participants/{participantUniqueId}

Delete the existing participant identified by the participantUniqueId path variable of the specific survey identified by 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.
{participantUniqueId}	This is either the login name if a logged in survey or else the email address.

Query string parameters

None

Sample Request

curl --location --request DELETE 'https:// <servername>/snaponline/api/surveys/20dbe888-ec99-4895-b094-e34084f9408f/participants/E' \
--header 'X-USERNAME: {USERNAME}' \
--header 'X-API-KEY: {APIKEY}' \
--header 'X-VERSION: 3.0'

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

Sample Response

No response

Response Definitions

No response definition

HTTP Status Codes

200 OK

404 Not Found

Get Participant Subjects

Get the details of the subjects of a participant of a survey.

Endpoint

Method	Url
GET	https://snaponline/api/surveys/{surveyId}/participants/{participantUniqueId}/subjects

Get the details of the subjects of the specific participant identified by the participantUniqueId path variable of the specific survey identified by 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.
{participantUniqueId}	This is either the login name if a logged in survey or else the email address.

Query string parameters

None

Sample Request

curl --location --request GET 'https:// <servername>/snaponline/api/surveys/20dbe888-ec99-4895-b094-e34084f9408f/participants/A/subjects' \
--header 'X-USERNAME: {USERNAME}' \
--header 'X-API-KEY: {APIKEY}' \
--header 'X-VERSION: 3.0' \
--data-raw ''

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

Sample Response

[
    {
        "subjectName": "L1",
        "questionnaireSeeding": {
            "v53": "L1",
            "v48": "2;3",
            "v50": "A",
            "v51": "A",
            "v46": "4"
        },
        "status": "NotStarted"
    }
]

Response Definitions

Response Item	Description	Data Type
subjectName	For a group questionnaire, the subject name will not be an empty string. For a non-group questionnaire, the subject name will always be an empty string.	String
questionnaireSeeding	The questionnaire seeding for the subject. This is a dictionary of properties in the form “<variable V number>” : “<value>”.	Object
status	This is the subject status.	String or null: “NotStarted” – the participant has not started the questionnaire. “Started” the participant has started the questionnaire. “Partial” – a partial response has been taken. “Saved” – the participant has saved the questionnaire. “Completed” – the participant has completed the questionnaire. “Submitted” – the researcher has submitted a partial response.

HTTP Status Codes

200 OK

404 Not Found

Get Participant Subject

Get the details of a subject of a participant of a survey.

Endpoint

Method	Url
GET	https://snaponline/api/surveys/{surveyId}/participants/{participantUniqueId}/subjects/{subjectName}

Get the details of the specific subject identified by the subjectName path variable of the specific participant identified by the participantUniqueId path variable of the specific survey identified by 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.
{participantUniqueId}	This is either the login name if a logged in survey or else the email address.
{subjectName}	The name of the subject.

Query string parameters

None

Sample Request

curl --location --request GET 'https:// <servername>/snaponline/api/surveys/20dbe888-ec99-4895-b094-e34084f9408f/participants/A/subjects/L1' \
--header 'X-USERNAME: {USERBNAME}' \
--header 'X-API-KEY: {APIKEY}' \
--header 'X-VERSION: 3.0' \
--data-raw ''

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

Sample Response

{
    "subjectName": "L1",
    "questionnaireSeeding": {
        "v53": "L1",
        "v48": "2;3",
        "v50": "A",
        "v51": "A",
        "v46": "4"
    },
    "status": "NotStarted"
}

Response Definitions

Response Item	Description	Data Type
subjectName	For a group questionnaire, the subject name will not be an empty string. For a non-group questionnaire, the subject name will always be an empty string.	String
questionnaireSeeding	The questionnaire seeding for the subject. This is a dictionary of properties in the form “<variable V number>” : “<value>”.	Object
status	This is the subject status.	String or null: “NotStarted” – the participant has not started the questionnaire. “Started” the participant has started the questionnaire. “Partial” – a partial response has been taken. “Saved” – the participant has saved the questionnaire. “Completed” – the participant has completed the questionnaire. “Submitted” – the researcher has submitted a partial response.

HTTP Status Codes

200 OK

404 Not Found

Add Participant Subject

Add a new subject to a participant of a survey.

Endpoint

Method	Url
POST	https://snaponline/api/surveys/{surveyId}/participants/{participantUniqueId}/subjects

Add the new subject of the specific participant identified by the participantUniqueId path variable of the specific survey identified by 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.
{participantUniqueId}	This is either the login name if a logged in survey or else the email address.

Query string parameters

None

Request body data

Requires request body of JSON object e.g.:

{
    "subjectName": "Chester Zoo2",
    "questionnaireSeeding": {
        "v46": "D",
        "v45": "David"
    },
    "status": "NotStarted"
}

Note. For a group questionnaire the subjectName must be a non-empty string. It is not possible to add a subject to a non-group questionnaire as there is only one subject with a subjectName of empty string. In the example above we are setting two of the seeding values for the subject. The status property is ignored if included. This means that you can take the output of a get subject call, modify the seeding and pass it in the add subject call without having to remove the status property.

Sample Request

curl --location --request POST 'https:// <servername>/snaponline/api/surveys/20dbe888-ec99-4895-b094-e34084f9408f/participants/A/subjects' \
--header 'X-USERNAME: {USERNAME}' \
--header 'X-API-KEY: {APIKEY}' \
--header 'X-VERSION: 3.0' \
--header 'Content-Type: application/json' \
--data-raw '{
    "subjectName": "L5",
    "questionnaireSeeding": {
        "v53": "L5",
        "v48": "2;3",
        "v50": "A",
        "v51": "A",
        "v46": "4"
    },
    "status": "NotStarted"
}'

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

Sample Response

{
    "subjectName": "L5",
    "questionnaireSeeding": {
        "v48": "2;3",
        "v50": "A",
        "v53": "L5",
        "v51": "A",
        "v46": "4"
    },
    "status": "NotStarted"
}

Response Definitions

Response Item	Description	Data Type
subjectName	For a group questionnaire subject name will not be an empty string. For a non-group questionnaire, the subject name must be an empty string.	String
questionnaireSeeding	The questionnaire seeding for the subject. This is a dictionary of properties in the form “<variable V number>” : “<value>”.	Object
status	This is the subject status.	String or null: “NotStarted” – the participant has not started the questionnaire. “Started” the participant has started the questionnaire. “Partial” – a partial response has been taken. “Saved” – the participant has saved the questionnaire. “Completed” – the participant has completed the questionnaire. “Submitted” – the researcher has submitted a partial response.

HTTP Status Codes

200 OK

404 Not Found with:

{
    "message": "Participant not found."
}

400 Bad Request with:

{
    "message": "Must provide a subject."
}

"message": "Survey is not a group questionnaire. Cannot add subjects."
"message": "Participant questionnaire seeding does not have a '<questionnaire seeding>' seeding property."
"message": "Participant already has that subject."
"message": "Could not add subject."
"message": "Participant invite seeding does not have a '<invite key>' seeding property."
"message": "Survey variable '<questionnaire item>' does not contain code value '<code value>'."
"message": "Participant questionnaire seeding does not have a '<questionnaire item>' seeding property."
"message": "Survey does not have a '<questionnaire item>' variable."
"message": "Survey variable '<questionnaire item>' is single choice. Multiple values are not allowed."
"message": "Survey variable '<questionnaire item>' cannot contain duplicate code values."

Update Participant Subject

Update an existing subject of a participant of a survey.

Endpoint

Method	Url
PUT	https://snaponline/api/surveys/{surveyId}/participants/{participantUniqueId}/subjects/{subjectName}

Update the existing specific subject identified by the subjectName path variable of the specific participant identified by the participantUniqueId path variable of the specific survey identified by 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.
{participantUniqueId}	This is either the login name if a logged in survey or else the email address.
{subjectName}	The name of the subject.

Query string parameters

None.

Request body data

Requires request body of JSON object e.g.:

{
    "subjectName": "Chester Zoo2",
    "questionnaireSeeding": {
        "v46": "D",
        "v45": "David"
    },
    "status": "NotStarted"
}

Note. The subjectName property must be the same as the subjectName path variable. It is not possible to rename a subject with this call. In the case of a non-group questionnaire the subjectName path variable should be null.

In the example above we are changing two of the seeding values for the subject. The status property is ignored if included. This means that you can take the output of a get subject call, modify the seeding and pass it in the add subject call without having to remove the status property.

Sample Request

curl --location --request PUT 'https:// <servername>/snaponline/api/surveys/20dbe888-ec99-4895-b094-e34084f9408f/participants/A/subjects/L5' \
--header 'X-USERNAME: {USERNAME}' \
--header 'X-API-KEY: {APIKEY}' \
--header 'X-VERSION: 3.0' \
--header 'Content-Type: application/json' \
--data-raw '{
    "subjectName": "L5",
    "questionnaireSeeding": {
        "v48": "2;3",
        "v50": "A",
        "v53": "L5",
        "v51": "A",
        "v46": "6"
    },
    "status": "NotStarted"
}'

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

Sample Response

{
    "subjectName": "L5",
    "questionnaireSeeding": {
        "v48": "2;3",
        "v50": "A",
        "v53": "L5",
        "v51": "A",
        "v46": "6"
    },
    "status": "NotStarted"
}

Response Definitions

Response Item	Description	Data Type
subjectName	For a group questionnaire subject name will not be an empty string. For a non-group questionnaire, the subject name must be an empty string.	String
questionnaireSeeding	The questionnaire seeding for the subject. This is a dictionary of properties in the form “<variable V number>” : “<value>”.	Object
status	This is the subject status.	String or null: “NotStarted” – the participant has not started the questionnaire. “Started” the participant has started the questionnaire. “Partial” – a partial response has been taken. “Saved” – the participant has saved the questionnaire. “Completed” – the participant has completed the questionnaire. “Submitted” – the researcher has submitted a partial response.

HTTP Status Codes

200 OK

404 Not Found with:

{
    "message": "Participant not found."
}

400 Bad Request with:

{
    "message": "Subject name must match subject details."
}

"message": "Survey is not a group questionnaire. Cannot add subjects."
"message": "Participant does not have this subject."
"message": "Could not update subject."
"message": "Participant invite seeding does not have a '<invite key>' seeding property."
"message": "Survey variable '<questionnaire item>' does not contain code value '<code value>'."
"message": "Participant questionnaire seeding does not have a '<questionnaire item>' seeding property."
"message": "Survey does not have a '<questionnaire item>' variable."
"message": "Survey variable '<questionnaire item>' is single choice. Multiple values are not allowed."
"message": "Survey variable '<questionnaire item>' cannot contain duplicate code values."

Delete Participant Subject

Delete a subject from a participant of a survey.

Endpoint

Method	Url
DELETE	https://snaponline/api/surveys/{surveyId}/participants/{participantUniqueId}/subjects/{subjectName}

Delete the specific subject identified by the subjectName path variable from the specific participant identified by the participantUniqueId path variable of the specific survey identified by the surveyId path variable.

Note: You cannot delete the subject of a non-group questionnaire. On a group questionnaire you cannot delete a subject if there would be no subjects remaining.

Parameters

Path parameters

Path parameter	Description
{surveyId}	The id of the survey. This is the survey GUID and not the Interview URL.
{participantUniqueId}	This is either the login name if a logged in survey or else the email address.
{subjectName}	The name of the subject.

Query string parameters

None

Sample Request

curl --location --request DELETE 'https:// <servername>/snaponline/api/surveys/20dbe888-ec99-4895-b094-e34084f9408f/participants/A/subjects/L5' \
--header 'X-USERNAME: {USERNAME}' \
--header 'X-API-KEY: {APIKEY}' \
--header 'X-VERSION: 3.0' \
--data-raw ''

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

Sample Response

No response

Response Definitions

No response definition

HTTP Status Codes

200 OK

400 Bad Request

If trying to delete a subject from non-group questionnaire.
If trying to delete last remaining subject from a group questionnaire.

404 Not Found

Bulk Participant Import

Add multiple participants to a survey with each request. The number allowed is a system setting managed by the System administrator. Our subscription servers current limit is 100 participants which may change over time. Please see the “HTTP Status code of overall call” section below for more information

Endpoint

Method	Url
POST	https://snaponline/api/surveys/{surveyId}/participants/bulkimport

Add new participants to the specific survey identified by 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

None

Request body data

Requires request body of JSON objects e.g.:

[
    {
        "invitationSection": {
            "optedOut": false,
            "sendInvitations": true,
            "emailAddress": "a@example.com",
            "invitationSeeding": {
                "forenames": "A",
                "surname": "A"
            }
        },
        "loginSection": {
            "login": "A",
            "password": null,
            "interviewer": null,
            "status": "NotStarted",
            "subjects": [
                {
                    "subjectName": "L1",
                    "questionnaireSeeding": {
                        "v53": "L1",
                        "v48": "2;3",
                        "v50": "A",
                        "v51": "A",
                        "v46": "4"
                    },
                    "status": "NotStarted"
                }
            ]
        },
        "enabled": true
    },
    {
        "invitationSection": {
            "optedOut": false,
            "sendInvitations": true,
            "emailAddress": "b@example.com",
            "invitationSeeding": {
                "forenames": "B",
                "surname": "B"
            }
        },
        "loginSection": {
            "login": "B",
            "password": null,
            "interviewer": null,
            "status": "NotStarted",
            "subjects": [
                {
                    "subjectName": "L1",
                    "questionnaireSeeding": {
                        "v53": "L1",
                        "v48": "2;3",
                        "v50": "B",
                        "v51": "B",
                        "v46": "4"
                    },
                    "status": "NotStarted"
                }
            ]
        },
        "enabled": true
    }
]

Note. The above example is creating participants in a survey where the participant feature requires that the participant be invited and that the participant has to provide credentials to view the questionnaire. Therefore, you must specify both the invitationSection section and the loginSection section in the call. The example is also for a group questionnaire and it will create one subject for the participant. In a non-group questionnaire, you must provide one subject and the subjectName property should be an empty string.

For an invite only survey do not include a loginSection section. For a logged on only survey do not include an invitationSection section.

The status properties are read-only so will be ignored if specified.

Sample Request

curl --location 'https://<servername>/snaponline/api/surveys/0048ed9b-38b6-45ce-9d0c-106dd4929aac/participants/bulkimport' \
--header 'X-USERNAME: {USERNAME}' \
--header 'X-API-KEY: {APIKEY}' \
--header 'X-VERSION: 3.0' \
--header 'Content-Type: application/json' \
--data-raw '[
    {
        "invitationSection": {
            "optedOut": false,
            "sendInvitations": true,
            "emailAddress": "a@example.com",
            "invitationSeeding": {
                "forenames": "A",
                "surname": "A"
            }
        },
        "loginSection": {
            "login": "A",
            "password": null,
            "interviewer": null,
            "status": "NotStarted",
            "subjects": [
                {
                    "subjectName": "L1",
                    "questionnaireSeeding": {
                        "v53": "L1",
                        "v48": "2;3",
                        "v50": "A",
                        "v51": "A",
                        "v46": "4"
                    },
                    "status": "NotStarted"
                }
            ]
        },
        "enabled": true
    },
    {
        "invitationSection": {
            "optedOut": false,
            "sendInvitations": true,
            "emailAddress": "b@example.com",
            "invitationSeeding": {
                "forenames": "B",
                "surname": "B"
            }
        },
        "loginSection": {
            "login": "B",
            "password": null,
            "interviewer": null,
            "status": "NotStarted",
            "subjects": [
                {
                    "subjectName": "L1",
                    "questionnaireSeeding": {
                        "v53": "L1",
                        "v48": "2;3",
                        "v50": "B",
                        "v51": "B",
                        "v46": "4"
                    },
                    "status": "NotStarted"
                }
            ]
        },
        "enabled": true
    }
]'

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

Note. The status field is read-only. If you send it into the request body as in the sample request above it will be ignored.

Sample Response

[
    {
        "participantUniqueId": "A",
        "id": "",
        "status": 400,
        "message": "Another participant already has this login name."
    },
    {
        "participantUniqueId": "B",
        "id": "6f70015a-7a58-4a66-b8ab-51a785b87599",
        "status": 200,
        "message": ""
    }
]

Response Definitions

Response Item	Description	Data Type
participantUniqueId	The unique id of the participant.	String
id	The participant id.	String: containing GUID
status	The HTTP Status code for this attempted participant add. 200 for a successful add.	Number
message	If the add was successful then the property will be “” otherwise the description of why the participant could not be added. Similar possibilities to the add participant endpoint.	String

HTTP Status Code of overall call

200

General checks have passed and the response lists the result of each separate participant add.

400 Bad Request:

{
    "message": "Maximum number of participants in bulk import cannot exceed: 100."
}

Note. The value is a system property. It can be changed and may not be 100.

Updated1st December 2025