Snap XMP Help

Add Participant Subject

You are here:
< All Topics

Add a new subject to a participant of a survey.

Endpoint

Method               Url
POSTsurveys/{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}The participantUniqueId 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: 2.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
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
questionnaireSeedingThe questionnaire seeding for the subject. This is a dictionary of properties in the form “<variable V number>” : “<value>”.Object
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 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."

Other API calls

Contents