There are 2 approaches to retrieving the survey responses:

• Our recommended approach, which is to use the startingFrom token so you only get the responses that have been submitted or modified since your last call.
• Get all the responses each call and you will be charged for each response for every call.

Use of the API is chargeable. The charge is 0.1 unit each time the API delivers a survey response.  This applies if you use the API to retrieve the same survey response multiple times.

Comparing unit usage

This table compares the number of units that when getting all the responses with getting the responses using the progress token, which is our recommended approach. This comparison shows the results for a survey that receives 100 responses per day, and the organisation gets the responses once per day.

Using the progress token uses far fewer units, reduces network traffic and provide a faster response.

Recommended approach

Using our recommended approach, you can retrieve only the latest responses since the last call was made. This is done by using the startingFrom parameter in the Get Survey Responses call. When you make a call to get the responses, this returns a progress token, which will need to be stored. This is a mark in the data file for where the call got up to. The next time you make the call, pass this progress token in as the startingFrom point, and then only new data is returned.

Step 1: Make the first request for the survey’s responses

When you make the first call to request the survey’s responses, set the startingFrom parameter to 0.

This retrieves all the requested survey responses.

Optional parameter settings will affect the requested survey responses. For example:

• If you include a filter, this will be all the survey responses that match the filter.
• If you set a maximum number of responses, e.g. maxResponses=100, this will be the first 100 responses.
• If you set restricted variables, this will return only the specified variables rather than all the variables in the survey.

This is an example of a request that retrieves the specified data from all the survey responses by using startingFrom=0. (In the code, you need to replace {APIKEY} with your actual API key and {USERNAME} with your actual username.)

curl --location --request GET 'https://<servername>/snaponline/api/surveys/c23a0fd8-6219-4130-a6a7-f312829e56eb/responses?maxResponses=100&restrictedVariables= V16,V45~V47&returnUniqueIds=true&useCodeLabels=true&startingFrom=0' \
--header 'X-USERNAME: {USERNAME}' \
--header 'X-API-KEY: {APIKEY}' \
--header 'X-VERSION: 2.0' \
--data-raw ''

Step 2: Receive the response containing the survey’s responses

This is an example of the response to the request for the survey responses. This contains the survey responses in the responses return item, and the progress token in the progress return item.

200 OK with body:

{
    "surveyId": "6834a5f1-46e5-4b12-9e0c-a38a3d9be12c",
    "filter": "Q1>1",
    "startingFrom": "0",
    "progress": "#IBCGEGG",
    "upToDate": "false",
    "responses": [
        {
            "status": "new",
            "caseId": "8e4591b0-c1e3-4612-88b4-7b96cd28dd2d",
            "variables": [
                {
                    "id": "V46",
                    "v": "Plane"
                },
                {
                    "id": "V48",
                    "v": "\"Restaurant / Cafe\",\"Gift Shop\",\"Customer Services\""
                },
                {
                    "id": "V52",
                    "s": "NR"
                }
            ]
        },
        {
            "status": "new",
            "caseId": "5458bfcb-97df-4326-879d-4868406761ae",
            "variables": [
                {
                    "id": "V46",
                    "v": "Bike"
                },
                {
                    "id": "V48",
                    "v": "\"Gift Shop\""
                },
                {
                    "id": "V52",
                    "v": "Very busy."
                }
            ]
        }
    ]
}

Step 3: Store the progress token for the next call

In the sample response in Step 2, ‘progress’ represents where you have got to in the data file.

“progress”: “#IBCGEGG”

Store the progress token to use in the next survey response request.

Step 4: Use the progress token in the next request

The progress token from the previous response is then used as the startingFrom value in the next Get Survey Responses request, to retrieve responses that have been submitted or modified since your last call.

This is an example that uses the progress token in the startingFrom parameter.

curl --location --request GET 'https://<servername>/snaponline/api/surveys/c23a0fd8-6219-4130-a6a7-f312829e56eb/responses?maxResponses=100&restrictedVariables= V16,V45~V47&returnUniqueIds=true&useCodeLabels=true&startingFrom=#IBCGEGG' \
--header 'X-USERNAME: {USERNAME}' \
--header 'X-API-KEY: {APIKEY}' \
--header 'X-VERSION: 2.0' \
--data-raw ''

Using Max Responses

Max responses is optional and can be used in combination with the progress token. Use the ‘upToDate’ value to decide if you have more responses to get, then use the progress token to get the next group of survey responses. If you know the number of survey responses for each call is never going to exceed the limit of 5000, then you can exclude this parameter.

The post Recommended use of the API progress token appeared first on SnapSurveys.

Endpoint

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

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

HTTP Status Codes

200 OK

404 Not Found

Other API calls

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

The post Get Participant appeared first on SnapSurveys.

Endpoint

Get the details of latest participants of the specific survey identified by the surveyId path variable.

Parameters

Path parameters

Query string parameters

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

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

The post Get Participant List appeared first on SnapSurveys.

Endpoint

Delete the specific subject identified by the subjectName path variable from the specific participant identified by the participantUniqueId path variable of the specific survey identified by the suurveyId path variable.

Note: You cannot delete the subject of a non-group questionnaire. On a group questionnaire you cannot delete a subject if there would be no subjects remaining.

Parameters

Path parameters

Query string parameters

None

Sample Request

curl --location --request DELETE 'https:// <servername>/snaponline/api/surveys/20dbe888-ec99-4895-b094-e34084f9408f/participants/A/subjects/L5' \
--header 'X-USERNAME: {USERNAME}' \
--header 'X-API-KEY: {APIKEY}' \
--header 'X-VERSION: 2.0' \
--data-raw ''

(In the above code, replace {APIKEY} with your actual API key and {USERNAME} with your actual username.)

Sample Response

No response

Response Definitions

No  response definition

HTTP Status Codes

200 OK

400 Bad Request

• If trying to delete a subject from non-group questionnaire.
• If trying to delete last remaining subject from a group questionnaire.

404 Not Found

Other API calls

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

The post Delete Participant Subject appeared first on SnapSurveys.

Endpoint

Update the existing specific subject identified by the subjectName path variable of the specific participant identified by the participantUniqueId path variable of the specific survey identified by the surveyId path variable.

Parameters

Path parameters

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. The subjectName property must be the same as the subjectName path variable. It is not possible to rename a subject with this call. In the case of a non-group questionnaire the subjectName path variable should be null.

In the example above we are changing 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 PUT 'https:// <servername>/snaponline/api/surveys/20dbe888-ec99-4895-b094-e34084f9408f/participants/A/subjects/L5' \
--header 'X-USERNAME: {USERNAME}' \
--header 'X-API-KEY: {APIKEY}' \
--header 'X-VERSION: 2.0' \
--header 'Content-Type: application/json' \
--data-raw '{
    "subjectName": "L5",
    "questionnaireSeeding": {
        "v48": "2;3",
        "v50": "A",
        "v53": "L5",
        "v51": "A",
        "v46": "6"
    },
    "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": "6"
    },
    "status": "NotStarted"
}

Response Definitions

HTTP Status Codes

200 OK

404 Not Found with:

{
    "message": "Participant not found."
}

400 Bad Request with:

{
    "message": "Subject name must match subject details."
}

"message": "Survey is not a group questionnaire. Cannot add subjects."
"message": "Participant does not have this subject."
"message": "Could not update 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

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

The post Update Participant Subject appeared first on SnapSurveys.

Endpoint

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

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

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

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

The post Add Participant Subject appeared first on SnapSurveys.

Endpoint

Get the details of the specific subject identified by the subjectName path variable of the specific participant identified by the participantUniqueId path variable of the specific survey identified by the surveyId path variable.

Parameters

Path parameters

Query string parameters

None

Sample Request

curl --location --request GET 'https:// <servername>/snaponline/api/surveys/20dbe888-ec99-4895-b094-e34084f9408f/participants/A/subjects/L1' \
--header 'X-USERNAME: {USERBNAME}' \
--header 'X-API-KEY: {APIKEY}' \
--header 'X-VERSION: 2.0' \
--data-raw ''

(In the above code, replace {APIKEY} with your actual API key and {USERNAME} with your actual username.)

Sample Response

{
    "subjectName": "L1",
    "questionnaireSeeding": {
        "v53": "L1",
        "v48": "2;3",
        "v50": "A",
        "v51": "A",
        "v46": "4"
    },
    "status": "NotStarted"
}

Response Definitions

HTTP Status Codes

200 OK

404 Not Found

Other API calls

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

The post Get Participant Subject appeared first on SnapSurveys.

Endpoint

Get the details of the subjects of the specific participant identified by the participantUniqueId path variable of the specific survey identified by the surveyId path variable.

Parameters

Path parameters

Query string parameters

None

Sample Request

curl --location --request GET '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' \
--data-raw ''

(In the above code, replace {APIKEY} with your actual API key and {USERNAME} with your actual username.)

Sample Response

[
    {
        "subjectName": "L1",
        "questionnaireSeeding": {
            "v53": "L1",
            "v48": "2;3",
            "v50": "A",
            "v51": "A",
            "v46": "4"
        },
        "status": "NotStarted"
    }
]

Response Definitions

HTTP Status Codes

200 OK

404 Not Found

Other API calls

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

The post Get Participants Subjects appeared first on SnapSurveys.

Endpoint

Delete the existing participant identified by the participantUniqueId path variable of the specific survey identified by the surveyId path variable.

Parameters

Path parameters

Query string parameters

None

Sample Request

curl --location --request DELETE 'https:// <servername>/snaponline/api/surveys/20dbe888-ec99-4895-b094-e34084f9408f/participants/E' \
--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

No response

Response Definitions

No response definition

HTTP Status Codes

200 OK

404 Not Found

Other API calls

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

The post Delete Participant appeared first on SnapSurveys.

Endpoint

Update the existing specific participant identified by the participantUniqueId path variable of the specific survey identified by the surveyId path variable.

Parameters

Path parameters

Query string parameters

None

Request body data

Requires request body of JSON object e.g.:

{
    "invitationSection": {
        "optedOut": false,
        "sendInvitations": true,
        "emailAddress": "sborg4@titan.local",
        "inviteSeeding": {
            "surname": "D",
            "forenames": "David"
        }
    },
    "loginSection": {
        "login": "A4",
        "password": null,
        "interviewer": "",
        "status": "NotStarted",
        "subjects": [
            {
                "subjectName": "Alton Towers",
                "questionnaireSeeding": {
                    "v45": "David",
                    "v46": "D"
                },
                "status": "NotStarted"
            },
            {
                "subjectName": "Chester Zoo",
                "questionnaireSeeding": {
                    "v45": "David",
                    "v46": "D"
                },
                "status": "NotStarted"
            }
        ]
    },
    "enabled": true
}

Note. The above example is updating 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 logonSection 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 PUT 'https:// <servername>/snaponline/api/surveys/20dbe888-ec99-4895-b094-e34084f9408f/participants/E' \
--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": {}
    },
    "loginSection": {
        "login": "E",
        "password": null,
        "interviewer": null,
        "status": "NotStarted",
        "subjects": [
            {
                "subjectName": "L1",
                "questionnaireSeeding": {
                    "v48": "2;3",
                    "v50": "A",
                    "v53": "L1",
                    "v51": "A",
                    "v46": "6"
                },
                "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": "6"
                },
                "status": "NotStarted"
            }
        ]
    },
    "enabled": true
}

Response Definitions

HTTP Status Codes

200 OK

404 Not Found with:

{
    "message": "Participant not found."
}

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": "Participant with this login name does not exist."
"message": "Participant with this login name already exists."
"message": "Participants for this survey must have unique subjects."
"message": "Participant to update does not exist."
"message": "Participant subjects do not match."
"message": "Participant with this email address does not exist."
"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

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

The post Update Participant appeared first on SnapSurveys.

Endpoint

Add a new participant to the specific survey identified by the surveyId path variable.

Parameters

Path parameters

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

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

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

The post Add Participant appeared first on SnapSurveys.

If you provide a query parameter that does not exist, you will get a 400 Bad Request response and the return body will state “Invalid query string parameters” in the message property followed by the parameters that don’t exist in the parameters property. E.g.

{
    "message": "Invalid query string parameters",
    "parameters": [
       "sortorder"
    ]
}

If the parameters provided exist but are not valid you will receive a message such as:

{
    "message": "The request is invalid.",
    "modelState": {
        "includeCodes": [
            "The value 'yes' is not valid for Boolean."
        ]
    }
}

The post API Validation appeared first on SnapSurveys.

Please note that from Monday 5th December 2022 usage of the API becomes chargeable. The charge is that 0.1 unit will be consumed each time a survey response is delivered by the API.  This applies if the same survey response is delivered by the API multiple times. The survey responses are delivered using the Get Survey Responses endpoint.

List of API endpoints in v2.0

The post API Reference appeared first on SnapSurveys.

Endpoint

Get information for the authenticated user.

Parameters

Path parameters

None

Query string parameters

None



Sample Request

curl --location --request GET 'http://<servername>/snaponline/api/account' \
--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:

{
 "username": "jbloggs@snapsurveys.com", 
 "fullname": "Joe Bloggs",
 "emailAddress": "jbloggs@snapsurveys.com"
}

Response Definitions

HTTP Status Codes

• 200 OK

Other API calls

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

The post Get User Info appeared first on SnapSurveys.

You can

• use our recommended approach, which is to use the startingFrom token so you only get the responses that have been submitted or modified since your last call.
• get all the responses each call and will be charged for each response for every call.

Please note that from Monday 5th December 2022 usage of the API becomes chargeable. The charge is that 0.1 unit will be consumed each time a survey response is delivered by the API.  This applies if the same survey response is delivered by the API multiple times. The survey responses are delivered using the Get Survey Responses endpoint.

Changes from v1.0

• A ‘filter’ property has been added.
• The ‘variableId’ property has been renamed ‘id’.
• The ‘value’ property has been renamed ‘v’.
• The ‘status’ property has been renamed ‘s’.
• Additional validation: invalid filter or startingFrom parameter now leads to a 400 response code rather than 500.

Endpoint

Get the responses of the specific survey identified with the surveyId path variable

Parameters

Path parameters

Query string parameters

Note: There are two ways to identify the V number required in the restrictedVariables parameter:

1. Postman: Make the Get Survey Variables call and examine the result.

2. Snap Desktop: Tick the UniqueIDs checkbox in the Variable Tailoring dialog. A new Id column will then be visible in the Variables screen.

Sample Request

curl --location --request GET 'https://<servername>/snaponline/api/surveys/c23a0fd8-6219-4130-a6a7-f312829e56eb/responses?maxResponses=100&restrictedVariables= 
V16,V45~V47&returnCaseIds=true&useCodeLabels=true&startingFrom=0' \
--header 'X-USERNAME: {USERNAME}' \
--header 'X-API-KEY: {APIKEY}' \
--header 'X-VERSION: 2.0' \
--data-raw ''

(In the above code, replace {APIKEY} with your actual API key and {USERNAME} with your actual username.)

Sample Response

200 OK with body:

{
    "surveyId": "6834a5f1-46e5-4b12-9e0c-a38a3d9be12c",
    "filter": "Q1>1",
    "startingFrom": "0",
    "progress": "#IBCGEGG",
    "upToDate": "false",
    "responses": [
        {
            "status": "new",
            "caseId": "8e4591b0-c1e3-4612-88b4-7b96cd28dd2d",
            "variables": [
                {
                    "id": "V46",
                    "v": "Plane"
                },
                {
                    "id": "V48",
                    "v": "\"Restaurant / Cafe\",\"Gift Shop\",\"Customer Services\""
                },
                {
                    "id": "V52",
                    "s": "NR"
                }
            ]
        },
        {
            "status": "new",
            "caseId": "5458bfcb-97df-4326-879d-4868406761ae",
            "variables": [
                {
                    "id": "V46",
                    "v": "Bike"
                },
                {
                    "id": "V48",
                    "v": "\"Gift Shop\""
                },
                {
                    "id": "V52",
                    "v": "Very busy."
                }
            ]
        }
    ]
}

Follow on Sample Request using the progress response item

In the sample response above, ‘progress’ represents where you have got to in the data file. This token is then used as the startingFrom value in the next /Responses request, to retrieve responses that have been submitted or modified since your last call.

“progress”: “#IBCGEGG”,

Use this token as the startingFrom parameter in order to retrieve responses that have been submitted or modified since your last call.

Sample Request example using the progress token

curl --location --request GET 'https://<servername>/snaponline/api/surveys/c23a0fd8-6219-4130-a6a7-f312829e56eb/responses?maxResponses=100&restrictedVariables= 
V16,V45~V47&returnCaseIds=true&useCodeLabels=true&startingFrom=#IBCGEGG' \
--header 'X-USERNAME: {USERNAME}' \
--header 'X-API-KEY: {APIKEY}' \
--header 'X-VERSION: 2.0' \
--data-raw ''

Response Definitions

HTTP Status Codes

• 200 OK
• 400 Bad Request
  • If maxResponses parameter is not between 1 and 5000.
  • If restrictedVariables parameter is invalid or a variable does not exist.
  • If startingFrom parameter is invalid.
  • If the filter parameter is invalid.
• 500
  • If something else went wrong while trying to extract the responses from the survey

Other API calls

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

The post Get Survey Responses appeared first on SnapSurveys.

Changes from v1.0

• The response now shows the ‘surveyId’ property at the top and has the variable inside a ‘variable’ property.
• The ‘id’ property has been removed from the response.

Endpoint

Get the details of the specific variable identified by the variableId path variable of the specific survey identified by the surveyId path variable.

Parameters

Path parameters

Query string parameters

None

Sample Request

curl --location --request GET 'http://localhost/snaponline/api/surveys/e819df57-0a01-4592-a7aa-8918dbe54e00/variables/V46' \
--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": "6834a5f1-46e5-4b12-9e0c-a38a3d9be12c",
    "variable": {
        "order": 15,
        "variableId": "V48",
        "label": "Which facilities did you visit?",
        "name": "Q2",
        "questionText": "Which facilities did you visit?",
        "variableTypeId": 6,
        "responseTypeId": 2,
        "variableType": "Question",
        "responseType": "Multiple",
        "codeCount": 3,
        "codes": [
            {
                "codeIndex": 1,
                "codeValue": 1,
                "codeLabel": "Restaurant / Cafe"
            },
            {
                "codeIndex": 2,
                "codeValue": 2,
                "codeLabel": "Gift Shop"
            },
            {
                "codeIndex": 3,
                "codeValue": 3,
                "codeLabel": "Customer Services"
            }
        ]
    }
}

Response Definitions

HTTP Status Codes

• 200 OK
• 404 Not Found – if survey variable does not exist.

Other API calls

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

The post Get Survey Variable appeared first on SnapSurveys.

Changes from v1.0

• A new ‘includeCodes’ query parameter has been added. If the ‘includeCodes’ query parameter is omitted, or if it is set to true, then the response body will include a list of codes for the variable. Each code will contain a ‘codeIndex’, ‘codeValue’ and ‘codeLabel’ property.
• The response now shows the ‘surveyId’ property at the top and has the variables inside a ‘variable’ property.
• The ‘id’ property has been removed from the response.

Endpoint

Gets the details for a specific survey ID.

Parameters

Path parameters

Query string parameters

Sample Request

curl --location --request GET 'http://<servername>/snaponline/api/surveys/e819df57-0a01-4592-a7aa-8918dbe54e00/variables' \
--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 (when ‘includeCodes’ is false):

{
    "surveyId": "6834a5f1-46e5-4b12-9e0c-a38a3d9be12c",
    "variables": [        
        {
            "order": 14,
            "variableId": "V46",
            "label": "What was the main form of transport used to get to the at...",
            "name": "Q1",
            "questionText": "What was the main form of transport used to get to the attraction?",
            "variableTypeId": 6,
            "responseTypeId": 1,
            "variableType": "Question",
            "responseType": "Single",
            "codeCount": 7
        },
        {
            "order": 15,
            "variableId": "V48",
            "label": "Which facilities did you visit?",
            "name": "Q2",
            "questionText": "Which facilities did you visit?",
            "variableTypeId": 6,
            "responseTypeId": 2,
            "variableType": "Question",
            "responseType": "Multiple",
            "codeCount": 3
        },
        {
            "order": 16,
            "variableId": "V52",
            "label": "Please tell us if there were any issues, otherwise leave ...",
            "name": "Q3",
            "questionText": "Please tell us if there were any issues, otherwise leave blank.",
            "variableTypeId": 6,
            "responseTypeId": 4,
            "variableType": "Question",
            "responseType": "Literal",
            "codeCount": 0
        }
    ]
}

200 OK with body (when ‘includeCodes’ is true):

{
    "surveyId": "6834a5f1-46e5-4b12-9e0c-a38a3d9be12c",
    "variables": [        
        {
            "order": 14,
            "variableId": "V46",
            "label": "What was the main form of transport used to get to the at...",
            "name": "Q1",
            "questionText": "What was the main form of transport used to get to the attraction?",
            "variableTypeId": 6,
            "responseTypeId": 1,
            "variableType": "Question",
            "responseType": "Single",
            "codeCount": 7,
            "codes": [
                {
                    "codeIndex": 1,
                    "codeValue": 3,
                    "codeLabel": "Walk"
                },
                {
                    "codeIndex": 2,
                    "codeValue": 5,
                    "codeLabel": "Bike"
                },
                {
                    "codeIndex": 3,
                    "codeValue": 8,
                    "codeLabel": "Motorbike"
                },
                {
                    "codeIndex": 4,
                    "codeValue": 4,
                    "codeLabel": "Car"
                },
                {
                    "codeIndex": 5,
                    "codeValue": 6,
                    "codeLabel": "Bus"
                },
                {
                    "codeIndex": 6,
                    "codeValue": 9,
                    "codeLabel": "Train"
                },
                {
                    "codeIndex": 7,
                    "codeValue": 10,
                    "codeLabel": "Plane"
                }
            ]
        },
        {
            "order": 15,
            "variableId": "V48",
            "label": "Which facilities did you visit?",
            "name": "Q2",
            "questionText": "Which facilities did you visit?",
            "variableTypeId": 6,
            "responseTypeId": 2,
            "variableType": "Question",
            "responseType": "Multiple",
            "codeCount": 3,
            "codes": [
                {
                    "codeIndex": 1,
                    "codeValue": 1,
                    "codeLabel": "Restaurant / Cafe"
                },
                {
                    "codeIndex": 2,
                    "codeValue": 2,
                    "codeLabel": "Gift Shop"
                },
                {
                    "codeIndex": 3,
                    "codeValue": 3,
                    "codeLabel": "Customer Services"
                }
            ]
        },
        {
            "order": 16,
            "variableId": "V52",
            "label": "Please tell us if there were any issues, otherwise leave ...",
            "name": "Q3",
            "questionText": "Please tell us if there were any issues, otherwise leave blank.",
            "variableTypeId": 6,
            "responseTypeId": 4,
            "variableType": "Question",
            "responseType": "Literal",
            "codeCount": 0,
            "codes": []
        }
    ]
}

Response Definitions

HTTP Status Codes

• 200 OK

Other API calls

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

The post Get Survey Variables appeared first on SnapSurveys.

Changes from v1.0

• The ‘displayName’ property is now called ‘name’.
• The ‘questionnaireTitle’ property is now called ‘title’.
• An ‘ownerId’ property has been added. This gives the owner’s id (GUID)
• An ‘ownerName’ property has been added. This is the owner’s user name.
• A ‘path’ property has been added. This is the path up to the survey as an array. E.g. A survey called ‘Survey001’ in folder ‘New Surveys’ in the user’s account will show as “Your work”, New Surveys” and the name will be ‘Survey001’.
• The interviewingState property has a different set of possible values. In v1 they were: “NotStarted”, “Live”, “Paused” and “Stopped”. In v2 they are: “NotStarted”, “Started”, “Paused”, “Stopped”, “TooManyRespondents” and “Unknown”.

Endpoint

Gets the details of a specific survey identified by the surveyId path variable.

Parameters

Path parameters

Query string parameters

None

Sample Request

curl --location --request GET 'http://<servername>/snaponline/api/surveys/e819df57-0a01-4592-a7aa-8918dbe54e00' \
--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:

{
        "id": "6834a5f1-46e5-4b12-9e0c-a38a3d9be12c", 
        "ownerId": "644f58a7-8526-4901-af7d-20969e5c68e4", 
        "ownerName": "sb4@titan.local", 
        "name": "APIv2 Example Survey", 
        "path": [ 
            "Your work", 
            "APIv2"
        ], 
        "title": "APIv2 Example Survey", 
        "url": "https:// <servername>/snaponline/Home/Index/6834a5f1-46e5-4b12-9e0ca38a3d9be12c", 
        "interviewUrl": "https:// <servername>/interview/6834a5f1-46e5-4b12-9e0ca38a3d9be12c", 
        "interviewPreviewUrl": "https:// <servername>/interview/6834a5f1-46e5-4b12-
9e0c-a38a3d9be12c?preview=true", 
        "isPublished": true, 
        "interviewingState": "Live", 
        "numberOfResponses": 4, 
        "numberOfPartials": 0, 
        "responsesLastChanged": "2022-06-09T13:40:25.7"
}

Response Definitions

HTTP Status Codes

• 200 OK

Other API calls

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

The post Get Survey appeared first on SnapSurveys.

Changes from v1.0

• Response JSON is now in name property order.
• The ‘displayName’ property is now called ‘name’.
• The ‘questionnaireTitle’ property is now called ‘title’.
• An ‘ownerId’ property has been added. This gives the owner’s id (GUID).
• An ‘ownerName’ property has been added. This is the owner’s username.
• A ‘path’ property has been added. This is the path up to the survey as an array. E.g. A survey called ‘Survey001’ in folder ‘New Surveys’ in the user’s account will show as “Your work”, New Surveys” and the name will be ‘Survey001’.
• The interviewingState property has a different set of possible values. In v1 they were: “NotStarted”, “Live”, “Paused” and “Stopped”. In v2 they are: “NotStarted”, “Started”, “Paused”, “Stopped”, “TooManyRespondents” and “Unknown”.

Endpoint

Get a list of surveys that are accessible by the user.

Parameters

Path parameters

None

Query string parameters

None

Sample Request

curl --location --request GET 'http://<servername>/snaponline/api/surveys' \
--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:

[
    {
        "id": "2c4be70c-fe6d-4883-9fd3-629943bec836",
        "ownerId": "644f58a7-8526-4901-af7d-20969e5c68e4", 
        "ownerName": "sb4@titan.local", 
        "name": "APIv2 Example Survey", 
        "path": [ 
            "Your work", 
            "APIv2"
        ], 
        "title": "APIv2 Example Survey", 
        "url": "https:// <servername>/snaponline/Home/Index/6834a5f1-46e5-4b12-9e0c-a38a3d9be12c", 
        "interviewUrl": "https:// <servername>/interview/6834a5f1-46e5-4b12-9e0ca38a3d9be12c", 
        "interviewPreviewUrl": "https:// <servername>/interview/6834a5f1-46e5-4b12-9e0c-a38a3d9be12c?preview=true", 
        "isPublished": true, 
        "interviewingState": "Live", 
        "numberOfResponses": 4, 
        "numberOfPartials": 0
    },
    {
        "id": "de8e8ca3-b7e7-4810-93e6-84c65da7e7aa",
        "ownerId": "644f58a7-8526-4901-af7d-20969e5c68e4", 
        "ownerName": "sb4@titan.local", 
        "name": "Test 1", 
        "path": [ 
            "Your work"
        ], 
        "title": "", 
        "url": "https:// <servername>/snaponline/Home/Index/faae664a-0287-459b83f8-782cafae8622", pg. 18 issue 2.3
        "interviewUrl": "https:// <servername>/interview/faae664a-0287-459b-83f8-782cafae8622", 
        "interviewPreviewUrl": "https:// <servername>/interview/faae664a-0287-459b83f8-782cafae8622?preview=true", 
        "isPublished": false, 
        "interviewingState": "NotStarted", 
        "numberOfResponses": 0, 
        "numberOfPartials": 0, 
        "responsesLastChanged": "2022-06-09T13:40:25.7"
    }
]

Response Definitions

HTTP Status Codes

• 200 OK

Other API calls

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

The post Get Survey List appeared first on SnapSurveys.

The post Recommendation appeared first on SnapSurveys.

The post HTTP Status Codes appeared first on SnapSurveys.

Versioning is achieved by use of request and response headers.

If you don’t specify a version in your request, then you will be using the v1.0 version of the API.

The following response header tells you which versions are available:

• api-supported-versions

The value is a comma-separated list of versions.

To use a new version you have to supply the following header parameter in the request:

• X-VERSION

Set the value to the version that you require.

You should check to see whether use of the new version is advised and what changes (if any) you
need to make to your code in order to use a new version.

Note. At some point it may become necessary to deprecate a version. We will strive to avoid this but sometimes it is unavoidable. We will give you plenty of notice.

Breaking changes

A breaking change is a change that may require you to make changes to your integration. The following are examples of changes we consider to be breaking changes:

• Removal of a parameter, request field or response field
• Addition of a required parameter or request field without default values
• Changes to the intended functionality of an endpoint
• Introduction of additional validation

A non-breaking change is a change that should not require you to make changes to your integration. In most cases, we will communicate non-breaking changes after they have been released.

Please ensure that your application is designed to be able to handle the following types of non-breaking
changes:

• Addition of new endpoints
• Addition of new methods to existing endpoints
• Addition of new fields in the following scenarios:
  • New fields in responses
  • New optional request fields or parameters
  • New required request fields that have default values
• Addition of a new value returned for an existing text field
• Changes to the order of fields returned within a response
• Addition of an optional request header
• Removal of redundant request header
• Changes to the length of data returned within a field
• Changes to the overall response size
• Changes to error messages. We do not recommend parsing error messages to perform business logic. Instead, you should only rely on HTTP response codes and error codes.
• Fixes to HTTP response codes and error codes from incorrect code to correct code

The post Versioning appeared first on SnapSurveys.

You should ensure that you don’t attempt to make more than one call per second or more than ten calls per minute. One way to achieve this is to perform a “sleep” in between calls.

We reserve the right to change the throttling limits at any time.

Current throttling metrics are returned in the following response headers:

Ideally, when a 429 status code is received your code should automatically change its “sleep” behaviour based on these metrics. Alternatively, you may decide to wait say 15 seconds between calls which should satisfy all future per second and per minute requirements.

The post Handling Throttling appeared first on SnapSurveys.

• X-USERNAME containing the Snap XMP Online email address for the user
• X-API-KEY containing the API key for the user

Creating the key

To create the key for the user’s account do the following:

1. Log onto Snap XMP Online.
2. Go to the Your account section.

3. Click on the Integrations link.

4. Click the Generate key button.

5. Click the Copy to clipboard button.

Your API key is now in the clipboard and you can paste this into your API calls.

Failure to include the X-USERNAME and X-API-KEY header parameters, or an incorrect X-API-KEY or use of a revoked API token will result in a 401 – Unauthorised response code, from all API calls.

Note: You should never reveal your API key to anyone or add it to code that is publicly accessible – this includes code in JavaScript files that is easily viewed using the Developer tools in a web browser.

Failure to secure your API key could result in your data being accessible by someone else.

If you think your API key has become known, then you should revoke your key (with the Revoke now button on the Integrations page) or replace the key (with the Replace key button which will make the previous key no longer usable). You will then have to change your client code to use the new key.

The post Security appeared first on SnapSurveys.

Note that if you give anyone else API access to your account you will be giving them access to all of your surveys and all of your survey responses and (depending on the share permissions) access to all surveys and survey responses shared to you by others. Do not give anyone API access if this will be a problem for you.

The API is a RESTful API (Representational State Transfer). It utilises the HTTP transport mechanism and is stateless. Data submitted in the body of a request and data returned in the body of the response is in the JSON format. The API only supports the JSON representation at present. We may allow other representations such as XML in future versions.

Each call made to the API is stateless and as such each call must include the authorisation information. The return from each call consists of a standard HTTP response which consists of a HTTP response code, response body and response headers.

Please note that from Monday 5th December 2022 usage of the API becomes chargeable. The charge is that 0.1 unit will be consumed each time a survey response is delivered by the API.  This applies if the API delivers the same survey response multiple times. Use the Get Survey Responses endpoint to deliver the survey responses.

The post Introduction appeared first on SnapSurveys.