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.

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.

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.