Snap XMP Help

Get Participant List

You are here:
< All Topics

Get the details of the latest participants of a survey.

Endpoint

Method               Url
GETsurveys/{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
maxParticipantsOptionalThe number of participants to return.Integer1-50005000
startingFromOptionalReturns 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.StringN/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
surveyIdThe survey Id you selected based on the survey Id in the request.String: containing GUID
startingFromThe startingFrom token in the request.String
progressThe ending token. This token can be used as the startingFrom parameter in the next call.String
upToDateWhether the most recent participant is included.String: containing Boolean
participantsThe participants.

The number of participants will be based on the maxParticipants request parameter.
List: containing objects
participants/enabledWhether the participant is enabled.Boolean
participants/ loginSectionThe login section for a logged on survey participant. Section will be omitted if not a logged on survey.Object
participants/loginSection /loginIf a logged on survey this will be the login name otherwise null.String or null
participants/ loginSection passwordIf a logged on survey and a password is required this will be the password otherwise null or “”.String or null
participants/ loginSection interviewerIf 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 statusIf 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/ invitationSectionThe invitation section for an invited survey participant. Section will be omitted if not an invited survey.Object
participants/ invitationSection/emailAddressIf an invited survey this will be the email address of the participant or empty string if not an invite survey.String
participants/ invitationSection sendInvitationsWhether invitations are to be sent.Boolean
participants/ invitationSection optedOutWhether the user is opted out from emails.Boolean
   

HTTP Status Codes

200 OK

Other API calls

Contents