Campaign interactions

Interact with campaign

An example response for successful interaction with any campaign

{
  "result": {
    "code": 1,
    "status": "ok"
  },
  "results": {
    "success": true,
    "result_type": "interact-campaign"
  }
}

Overview

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

The interact-campaign API endpoint carries out a configured campaign interaction for an end-user (customer). This might result in one of many possible actions, such as the issuing of points or vouchers for a campaign.

The campaign logic itself dictates the result of the interaction. The role of the interact-campaign endpoint is not to describe this result, but only to respond with whether the interaction was successful or not.

This endpoint is used by composable campaigns with context: "interaction" to trigger campaign flows without requiring a basket. When a composable campaign with random_draw behaviour is triggered, a single reward method is randomly selected from the eligible candidates and its reward is issued directly to the user. When independent behaviour is used, each eligible reward method is processed independently.

A composable campaign must satisfy the following to be used with this endpoint:

• context is interaction. Composable campaigns with context basket or internal cannot be triggered via interact-campaign and will be rejected with campaign_not_active.

Note that, in the case a reward has already been redeemed, a 200 OK response is sent along with a warning campaign_fully_redeemed.

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.
• Admin authentication: the performing user needs to be logged in and have read access to the entity (business or chain) to which the user is connected.
• Privileged authentication: the use of privileged authentication is permitted for this endpoint.

HTTP Parameters

The following HTTP parameters can be passed to the API:

Parameter	Description
campaign_id mandatory	(integer) The ID in the Spaaza system of the campaign with which the customer/user is interacting.
chain_id mandatory with admin authentication	(integer) The id of the chain for which the information is being requested.
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 user for whom the campaign interaction is being requested.

Headers

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

Parameter	Description
X-Spaaza-MyPrice-App-Hostname	(mandatory in the case of user authentication, not required otherwise) The hostname of the app for which the user is requesting the card.

Possible error responses

The following represents a list of possible error responses for the interact-campaign 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.	500
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
228	auth_method_invalid The given auth_method parameter has an invalid value.	500
238	myprice_app_not_found The MyPrice app you requested was not found.	500
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
247	campaign_id_invalid The campaign_rule_id passed must be an integer.	400
264	myprice_app_without_entity The requested MyPrice app does not have an entity associated with it.	400
265	authorization_invalid The given authorization header is invalid.	400
266	access_token_invalid The given access token is invalid.	401
267	no_valid_user A valid username needs to be specified.	401
269	no_myprice_app Myprice app is required.	400
270	user_not_found No user was found.	404
405	entity_mismatch The entities or chains supplied do not match.	400
416	multiple_parameter_mismatch Multiple parameters supplied when fewer are required.	400
419	parameter_invalid One of the parameters is invalid and should be in a different format.	400
424	access_denied Access is denied.	400
449	campaign_not_active The requested campaign is not active.	400
450	campaign_fully_redeemed The rewards of this campaign have been fully redeemed.	400
451	insufficient_points_for_interaction Not enough points available to continue.	400