Get survey

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

Overview

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

Returns the active survey definition of a survey campaign together with the completion state of that survey for one shopper. Use it to render a survey in an app or website, and to establish whether the shopper has already completed it.

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

Only active, non-deleted survey campaigns are served. If the campaign is inactive or deleted, the endpoint returns campaign_not_active (code 449, HTTP 400).

Answers are submitted with submit-survey.

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. The session can be as follows:

User authentication: a session generated by an end-user login. The survey is returned for the logged-in shopper.
Admin authentication: the performing user needs to be logged in and have read access to the chain of the campaign.
Privileged authentication: the use of privileged authentication is permitted for this endpoint.

The shopper and the campaign must belong to the same chain, otherwise entity_mismatch is returned.

If the campaign has one or more active segment restrictions, the shopper must satisfy them. A shopper who does not match receives user_does_not_match_segment, so a survey which is not intended for that shopper cannot be retrieved.

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.
chain_id optional	(integer) The ID of the chain. When omitted, the chain of the campaign is used.
user_id OR member_number OR authentication_point_identifier mandatory with admin or privileged authentication	The Spaaza unique ID (user_id), member_number (user code) or identity in a third-party authentication system (authentication_point_identifier) of the shopper for whom the survey is being requested.

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`.
X-Spaaza-MyPrice-App-Hostname	(mandatory in the case of user authentication, not required otherwise) The hostname of the app for which the survey is requested.

Response

Field	Description
survey_definition	The active survey definition of the campaign, containing `schema_version` and the array of active `questions`. See Survey definition.
completion	An object describing whether this shopper has already completed the survey.
completion.completed	(boolean) `true` when the shopper has a completed response for this campaign.
completion.survey_response_id	(integer or null) The ID of the completed survey response, or `null` when the survey has not been completed.
completion.reward_status	(string or null) The reward status of the completed response - `issued`, `no_reward` or `pending` - or `null` when the survey has not been completed.

Questions in survey_definition.questions are returned in page-major order: ascending page, then ascending display_order, then ascending question id. Single-page surveys use page 1 by default. See Survey definition for the question fields and lifecycle rules.

Possible error responses

The following represents a list of possible error responses for the survey 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
154	user_id_invalid The user_id passed must be an integer up to 10 digits long	400
217	chain_id_not_found No record has been found for that chain_id	400
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
270	user_not_found No user was found	404
405	entity_mismatch The entities or chains supplied do not match	400
419	parameter_invalid One of the parameters is invalid and should be in a different format. Returned when the `campaign_id` is not a survey composable campaign.	400
449	campaign_not_active The requested survey campaign is inactive or deleted.	400
505	user_does_not_match_segment The user must be in the correct segment to perform this action	400

Sample request

GET /survey?campaign_id=300

An example response

{
  "result": {
    "code": 1,
    "status": "ok"
  },
  "results": {
    "survey_definition": {
      "schema_version": 1,
      "questions": [
        {
          "id": 41,
          "key": "favourite_department",
          "type": "single_choice",
          "prompt": "Which department do you visit most?",
          "required": true,
          "options": [
            { "id": 88, "key": "fresh", "label": "Fresh" },
            { "id": 89, "key": "bakery", "label": "Bakery" }
          ]
        }
      ]
    },
    "completion": {
      "completed": false,
      "survey_response_id": null,
      "reward_status": null
    }
  }
}

Get survey​

Contents​

Overview​

Version-specific information​

Permissions and authentication​

HTTP parameters​

Headers​

Response​

Possible error responses​

Sample request​