Add Participant

Add a new participant to a survey.

Endpoint

Method               Url
POSTsurveys/{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 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 POST 'https:// <servername>/snaponline/api/surveys/20dbe888-ec99-4895-b094-e34084f9408f/participants' \
--header 'X-USERNAME: {USERNAME}' \
--header 'X-API-KEY: {APIKEY}' \
--header 'X-VERSION: 2.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"
            }
        ]
    },
    "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.  
enabledWhether 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>'."

Other API calls

Updated
Contents

Cookie settings

You can decide which cookies you wish to allow and can change your settings at any time. You cannot prevent our use of strictly necessary cookies. For more information about the cookies we use, please see our cookie policy.

With the slider, you can enable or disable different types of cookies:

This website will:

  • Remember which cookies group you accepted
  • Strictly necessary: remember your cookie permission setting
  • Strictly necessary: allow session cookies
  • Strictly necessary: authenticate that you are logged into your user account

This website won't:

  • Functionality: remember your online chat ID
  • Analytics: keep track of your visited pages and interaction taken
  • Analytics: keep track of your location and region based on your partial IP number
  • Analytics: keep track of the time spent on each page and the videos you watch
  • Analytics: identify the device you are using
  • Targeting: identify if you contacted or called us as a result of one of our adverts

This website will:

  • Remember which cookies group you accepted
  • Strictly necessary: remember your cookie permission setting
  • Strictly necessary: allow session cookies
  • Strictly necessary: authenticate that you are logged into your user account
  • Functionality: remember your online chat ID

This website won't:

  • Analytics: keep track of your visited pages and interaction taken
  • Analytics: keep track of your location and region based on your partial IP number
  • Analytics: keep track of the time spent on each page and the videos you watch
  • Analytics: identify the device you are using
  • Targeting: identify if you contacted or called us as a result of one of our adverts

This website will:

  • Remember which cookies group you accepted
  • Strictly necessary: remember your cookie permission setting
  • Strictly necessary: allow session cookies
  • Strictly necessary: authenticate that you are logged into your user account
  • Functionality: remember your online chat ID
  • Analytics: keep track of your visited pages and interaction taken
  • Analytics: keep track of your location and region based on your partial IP number
  • Analytics: keep track of the time spent on each page and the videos you watch
  • Analytics: identify the device you are using

This website won't:

  • Targeting: identify if you contacted or called us as a result of one of our adverts

This website will:

  • Remember which cookies group you accepted
  • Strictly necessary: remember your cookie permission setting
  • Strictly necessary: allow session cookies
  • Strictly necessary: authenticate that you are logged into your user account
  • Functionality: remember your online chat ID
  • Analytics: keep track of your visited pages and interaction taken
  • Analytics: keep track of your location and region based on your partial IP number
  • Analytics: keep track of the time spent on each page and the videos you watch
  • Analytics: identify the device you are using
  • Targeting: identify if you contacted or called us as a result of one of our adverts

This website won't:

Save & Close