Recommended use of the API progress token

You can retrieve a survey’s responses using the Get Survey Responses endpoint.

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.

Day	Responses received per day	Responses delivered by getting all responses each day	Units used per day (0.1 unit per response)	Responses delivered using the API progress token each day	Units used per day(0.1 unit per response)
1	100	100	10	100	10
2	100	200	20	100	10
3	100	300	30	100	10
4	100	400	40	100	10
5	100	500	50	100	10
6	100	600	60	100	10
7	100	700	70	100	10
Totals	700	2800	280	700	70

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.