Get Participant List

Get the details of the latest participants of a survey.

Endpoint

Method	Url
GET	surveys/{surveyId}/participants

Get the details of latest 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: 2.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": [
        {
            "enabled": true,
            "invitationSection": {
                "optedOut": false,
                "sendInvitations": true,
                "emailAddress": "a@example.com"
            },
            "loginSection": {
                "login": "A",
                "password": null,
                "interviewer": null,
                "status": "NotStarted"
            }
        },
        {
            "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/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

Other API calls

• Get Survey List
• Get Survey
• Get Survey Variables
• Get Survey Variable
• Get Survey Responses
• Get User Info
• Get Participant
• Add Participant
• Update Participant
• Delete Participant
• Get Participants Subjects
• Get Participant Subject
• Add Participant Subject
• Update Participant Subject
• Delete Participant Subject