Get survey responses

Get survey responses

Contents

• Overview
• Version-specific information
• Permissions and authentication
• HTTP parameters
• Headers
• Response
• Possible error responses
• Sample request

Overview

• Call name: get-survey-responses
• Endpoint URL: https://{API hostname}/internal/get-survey-responses
• Request methods: GET
• Response Content-Type: application/json
• Auth required: yes

Returns the completed survey responses of a survey campaign, most recently completed first, with the answers stored for each response.

The campaign_id must belong to a composable campaign with context set to survey. Any other campaign is rejected with parameter_invalid.

Version-specific information

The following version-specific changes apply to this endpoint. See the versioning page for more details.

Version	Change details
>= 1.6.8	This endpoint was added in this version

Permissions and authentication

This API call requires a valid Spaaza session generated by an administrator login. The performing user needs read access to the chain of the campaign. End-user, delegated and privileged authentication are not supported by this endpoint.

HTTP parameters

The following HTTP parameters can be passed to the API:

Parameter	Description
campaign_id mandatory	(integer) The ID in Spaaza of the survey campaign whose responses are being requested.
limit optional	(integer) The maximum number of survey responses to return. Must be between 1 and 100. Defaults to 50.
offset optional	(integer) The number of survey responses to skip, used to page through the responses. Must be 0 or greater. Defaults to 0.

A limit or offset which is not an integer, or which falls outside those ranges, is rejected with parameter_invalid.

Headers

The following headers can/must be passed to the API call:

Parameter	Description
X-Spaaza-API-Version	(recommended) The API version, for example 1.6.8.

Response

Field	Description
survey_responses	(array) The requested page of survey responses, ordered by completion date descending. Each element has the same structure as survey_response in the submit-survey response.
total_count	(integer) The total number of survey responses for the campaign, regardless of limit and offset.
limit	(integer) The limit applied to this request.
offset	(integer) The offset applied to this request.

Answers belonging to deleted survey questions are omitted from each response. See Question lifecycle and response storage.

Each stored answer includes its question ID, question key, question type, submitted value, and the presentation snapshots needed to interpret the answer as it was shown to the shopper.

Possible error responses

The following represents a list of possible error responses for the get-survey-responses endpoint:

Code	Name and Description	HTTP Status Code
6	no_valid_session The user needs to be logged in and a valid session key needs to be sent	401
68	permission_denied_or_non_existent This user has insufficient permissions for this object or the object does not exist.	403
244	campaign_id_invalid The campaign_id passed must be an integer	400
245	campaign_id_not_present The campaign_id must be passed as a parameter	400
246	campaign_id_not_found The campaign_id supplied could not be found	404
419	parameter_invalid One of the parameters is invalid and should be in a different format. Returned when the campaign is not a survey campaign and when limit or offset is invalid.	400
424	access_denied Access is denied	400

Sample request

GET /internal/get-survey-responses?campaign_id=300&limit=50&offset=0

An example response

{
  "result": {
    "code": 1,
    "status": "ok"
  },
  "results": {
    "survey_responses": [
      {
        "id": 501,
        "campaign_id": 300,
        "user_id": 90210,
        "member_number": "1234567890",
        "status": "completed",
        "reward_status": "issued",
        "completed_date": "2026-08-17 11:04:22",
        "answers": [
          {
            "id": 8801,
            "question_id": 41,
            "question_key": "favourite_department",
            "question_type": "single_choice",
            "value": "fresh"
          }
        ]
      }
    ],
    "total_count": 1,
    "limit": 50,
    "offset": 0
  }
}