Get a campaign
Fetch a campaign by its ID
An example response for a successful get-campaign request:
{
"result": {
"code": 1,
"status": "ok"
},
"results": {
"campaign": {
"active": true,
"allows_user_to_claim_voucher": true,
"assigned_barcodes": [
"5449000062994",
"5449000062970",
"5449000095572"
],
"assigned_barcodes_earn": [],
"assigned_barcodes_spend": [],
"assigned_business_ids": [
{
"id": 2797,
"name": "ACME Flagship stoere"
}
],
"assigned_channels": [
"in_store"
],
"assigned_currencies": [],
"assignment_count": 4,
"assignment_count_by_type": {
"barcode": 3,
"brand": 0,
"business": 1,
"category": 0,
"currency": 0,
"gender": 0,
"product": 0,
"season": 0,
"type": 0
},
"cashback_ratio": "1.0000",
"chain_id": 1743,
"created_date": "2017-09-22T08:45:47+00:00",
"created_voucher_claimed_by_default": false,
"currency": {
"code": "PTS",
"display_position": "after",
"id": 5,
"name_en": "Points",
"symbol": "pts"
},
"custom_content": null,
"description": "Get 1 point for each €1 spent",
"earn_on_promotional_items": true,
"element_styling": null,
"excluded_user_segment_id": null,
"excludes_assignment_matches": false,
"excludes_referred_users": false,
"field_localisations": null,
"id": 158,
"image_dimension_x": null,
"image_dimension_y": null,
"image_filename": null,
"image_link": null,
"image_url": null,
"is_active": true,
"is_contributor": true,
"is_default": false,
"is_deleted": false,
"last_modified_date": "2022-11-11T14:43:07+00:00",
"last_updated_by": {
"name": "Dave Sevenoaks",
"user_id": 21
},
"last_updated_date": "2022-11-11T14:43:07+00:00",
"max_reward_quantity": null,
"max_reward_quantity_unit": null,
"minimum_basket_total_value_earn": 0,
"maximum_basket_total_value_earn": null,
"minimum_basket_total_value_spend": null,
"maximum_basket_total_value_spend": null,
"operator_type": "or",
"owner_code": null,
"parameters": [],
"recipient_campaign_id": 157,
"recipient_reward_amount": 1,
"recipient_reward_discount_ratio": 0,
"recipient_reward_method": "points",
"return_reclaims_earned_rewards": true,
"reward_priority": 0,
"rounding_precision": 0,
"rounding_strategy": "round_up",
"redemption_grace_period": 0,
"sender_campaign_id": null,
"styling": {
"background_colour": null,
"background_image_filename": null,
"background_image_url": null,
"layout_style": null,
"primary_action_background_colour": null,
"primary_action_text_colour": null,
"secondary_action_background_colour": null,
"secondary_action_text_colour": null,
"text_colour": null
},
"supports_contribution": true,
"supports_user_segments": true,
"tags": null,
"target_count": 0,
"title": "Earn points on every purchase",
"type": "cashback",
"user_progress": {
"award_count": 2,
"total_amount_awarded": 251
},
"user_segment_id": "AXIYnQplKpCtyKmmd8Hn",
"visible_to_all_user_segments": false,
"voucher_description": null,
"voucher_expiry_days": 0,
"voucher_image_url": null,
"voucher_notes": null,
"voucher_text": "Your cashback amount",
"voucher_title": null
},
"result_type": "get-campaign"
}
}
Overview
- Call name: get-campaign
- Endpoint URL: https://{API hostname}/get-campaign
- Request methods: GET
- Response Content-Type: application/json
- Auth required: yes
The get-campaign endpoint is used to fetch a campaign by its ID. The campaign ID is passed as a parameter to the API call. The call returns a campaign object. Note that if there are more than 500 campaign assignments, no assignments are shown in the response and a warning is given, objects_exceed_maximum_quantity.
It is also possible to fetch a campaign on behalf of a user and get the customer's user_progress for the campaign. The user_progress in the get-campaign response will provide a brief summary of a users interaction with a campaign. For a more complete description of user_progress in the campaign response please refer to user progress.
Permissions and authentication
This API call requires a valid Spaaza session. The session can be as follows:
- Admin authentication: the performing user needs to be logged in and have
read accessto the chain to which the user is connected. - Privileged authentication: the use of privileged authentication is permitted for this endpoint.
- User authentication: a session generated by an end-user login.
HTTP Parameters
The following HTTP parameters can be passed to the API:
| Parameter | Description |
|---|---|
| campaign_id mandatory | (integer) The ID of the Campaign the user is querying. |
| chain_id mandatory when querying user specific information | (integer) The id of the chain for which the information is being requested. |
| user_id OR member_number OR username OR referral_code OR authentication_point_identifier OR auxiliary_identifier mandatory when querying user specific information | The Spaaza unique ID (user_id), member_number (user code), username (email) or identity in a third-party authentication system (authentication_point_identifier/ auxiliary_identifier) of the user for whom the campaign 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 |