Snap XMP Help

Get Participant

You are here:
< All Topics

Get the details of a participant of a survey.

Endpoint

Method               Url
GETsurveys/{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}The participantUniqueId 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: 2'

(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"
        }
    },    
    "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"
            }
        ]
    },
    "enabled": true
}

Response Definitions

Response Item Description Data Type
enabledWhether the participant is enabled.Boolean
invitationSectionThe invitation section for an invited survey participant. Section will be omitted if not an invited survey.Object
invitationSection/optedOutWhether invitations are to be sent.Boolean
invitationSection/sendInvitationsWhether the user is opted out from emails.Boolean
invitationSection/emailAddressThe email address.String
invitationSection/inviteSeedingThe invite seeding.   This is a dictionary of properties in the form “<invite key>” : “<value>”Object
loginSectionThe login section for a logged on survey participant. Section will be omitted if not a logged on survey.Object
loginSection/loginIf a logged on survey this will be the login name otherwise null.String or null
loginSection/passwordIf a logged on survey and a password is required this will be the password otherwise null or “”.String or null
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
loginSection/statusThis 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/subjectsThe 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/subjectNameFor 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/ questionnaireSeedingThe questionnaire seeding for the subject.   This is a dictionary of properties in the form “<variable V number>” : “<value>”.Object
loginSection/subjects/statusThis 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

Other API calls

Contents