Rewards (legacy)

Request Details

Item Value
Description Returns rewards that are available within the program. The default behavior is to return all rewards. However, query string parameters may be added to filter specific rewards for various criteria that are detailed below. Additionally if multiple rewards are part of the same rewards group (such as a variations in size or color), these can easily be identified by the shared group_id value.
Method GET
Endpoint https://[environment]api[client_id].crowdtwist.com/v2/rewards?api_key=[api_key]

Request

Field Name Sample Value Required Format Notes
URL PARAMETERS – none
QUERY PARAMETERS
api_key QWERTYUIOP Yes String  
category Digital No String Filters to rewards in the specified category (by name, case insensitive, leading and trailing whitespace trimmed).
active_only 1 No Boolean Filters to “active” rewards, meaning rewards which meet the following conditions:
  1) is enabled
  2) having passed its start date
  3) having no end date or not having passed its end date
  4) not having been deactivated
for_points 1000 No String Filters to rewards that are available for a user who has the specified number of redeemable points, must be a non-negative integer
featured 1 No Boolean Filters to rewards that are marked as featured
redeemable_by 4628931 No String Filters to rewards that are available to be redeemed by that user. active_only is redundant with this option. If also specifying for_points, the user is treated as if they had the specified number of points for all purposes, including determining their fan level for rewards that have a minimum fan level.
for_display 1 No Boolean Specifies that the retrieval is for display rather than redemption purposes. This currently means that rewards that are locked or hidden to a user will not be excluded from the results.
sort_by points No String Sorts the items in the response, must be used in conjunction with the order parameter. Available options are: points, rewardTitle, startDate.
order desc No String Determines the sort method of the items in the response, must be used in conjunction with the sort_by parameter. Available options are asc, desc.

Response

Response Body

Field Name Sample Value Required Format Description
id 64 Yes String Internal CrowdTwist reward id.
title Visit our site Yes String The title of the reward.
description Receive a 10% off coupon when you redeem 1000 points. Yes String The description of the reward.
current_quantity 100 No Integer Current number of this reward available.
num_points 1000 Yes Integer The number of points a user must redeem to be issued the reward.
date_start 1425404945 No Integer Date reward initially becomes available.
date_end 1425404945 No Integer Date reward stops being available.
date_end_redeemable null No Integer Date reward stops being available for redemption.
is_enabled 1 Yes Integer Boolean value indicating if reward is enabled.
category_id 16 No String ID of category reward is in.
group_id 2946 No String Group the reward is in. When a reward has multiple sizes/colors, they will all share the same group_id.
no_end_date 1 No Integer Boolean value indicating if there is no end date.
total_quantity 200 No Integer Total number of this reward available.
max_select_quantity 3 No Integer Maximum number of this reward a user can select.
max_per_user 5 No Integer Maximum number of this reward a user can redeem.
is_shipping_required 1 No Integer Boolean value indicating if shipping is required.
is_phone_number_required 1 No Integer Boolean value indicating phone number is required.
is_min_age_required 1 No Integer Boolean value indicating phone number is required.
min_age 13 No Integer Minimum age a user must be to redeem this reward.
is_digital_download 1 No Integer Boolean value indicating if reward is digital download.
sweepstakes_winners 100 No Integer If Sweepstakes – total number of potential sweepstakes winners.
extra_data {email_template : "redemption", stock_id : “392-dkd”} No JSON Extra data set via Control Center
total_coupons 10000 No Integer If code reward – total number of codes uploaded.
remaining_coupons 10000 No Integer If code reward- total number of codes remaining unredeemed.
image http://www.imagestorage.com/image Yes URL The reward image
additional_images
[ "http://crowdtwist.com/img/v2/a1fd59769aa51b7163b36a5c797c24d4fef5996c/w/h/0/image.jpg", "http://crowdtwist.com/img/v2/f8ffd787cd6e8ae15724167809969bb1c149228c/w/h/0/image.jpg" ]
 Yes URL The reward image
reference_id 46a6sd No String Optional custom identifier that can be set in Control Center per reward/reward variation.
color blue No String Reward color
size Size 10 No String Reward Size
reward_terms http://cdn.crowdtwist.com/file
/67d/reward_terms.pdf		 No String If a sweepstakes reward with a terms & conditions file, the URL of the PDF. Note agreement of this must be controlled via the redemption method.
min_tier_id null No String The minimum tier that a user needs to be at in order to perform this activity. List of ID values will be provided by the CrowdTwist team.
freq_cap 1 No Integer The number of redemptions that can table place based on the freq_period_id and freq_period_name.
freq_period_id 2 No Integer The id of the freq_period_name value.
freq_period_name Calendar Day No String The time period for which redemptions can take place.
segment No Object Object that contains the segment information
— name “New York Members” No String Name of the segment
— subscription_id 2 No Integer Identifier of the segment


Error Responses

Field Name Sample Value Required Format Description
error param_error Yes String A machine readable code that describes the error.
message Missing the user_id parameter Yes String A short, descriptive sentence detailing the error.


Error Response Codes

Error Message
input_error The input provided in invalid or formatted incorrectly.
internal_error Something went wrong on our end.
page_not_found The requested page does not exist or has been removed.
param_error A missing or invalid parameter is included in the request.

Samples

Sample Request Body

curl -X GET https://api.crowdtwist.com/v2/rewards?api_key=QWERTYUIOP


Sample Request – with active_only filter

curl -X GET https://api.crowdtwist.com/v2/rewards?api_key=QWERTYUIOP&active_only=1


Sample Successful Response: Status Code 200 – with group info (color and size)

{ "id": "2958", "title": "Reward", "description": "Lorem ipsum dolor sum", "current_quantity": 50, "num_points": 1, "date_start": 1478685600, "date_end": null, "date_end_redeemable": null, "is_enabled": 1, "category_id": 1018, "group_id": 2946, "no_end_date": 1, "total_quantity": 50, "max_select_quantity": null, "max_per_user": null, "is_shipping_required": 0, "is_phone_number_required": 0, "is_min_age_required": "0", "min_age": null, "is_digital_download": 0, "sweepstake_winners": null, "extra_data": null, "total_coupons": 0, "remaining_coupons": 0, "image": "http://crowdtwist.com/img/v2/4be863f9d6be2e6e93b514938c728fd9d739f3ac/w/h/0/image.jpg", "reference_id": "46a6sd ", "color": "blue", "size": "Size 10", "reward_terms": null, "freq_cap":1, "freq_period_id":2, "freq_period_name":"Calendar Day", "segment": { "name":"Canada Members", "subscription_id":1043 } }


Sample Successful Response: Status Code 200 – without group info

{ "id": "2958", "title": "Reward", "description": "Lorem ipsum dolor sum", "current_quantity": 50, "num_points": 1, "date_start": 1478685600, "date_end": null, "date_end_redeemable": null, "is_enabled": 1, "category_id": 1018, "group_id": 2946, "no_end_date": 1, "total_quantity": 50, "max_select_quantity": null, "max_per_user": null, "is_shipping_required": 0, "is_phone_number_required": 0, "is_min_age_required": "0", "min_age": null, "is_digital_download": 0, "sweepstake_winners": null, "extra_data": null, "total_coupons": 0, "remaining_coupons": 0, "image": "http://crowdtwist.com/img/v2/4be863f9d6be2e6e93b514938c728fd9d739f3ac/w/h/0/image.jpg", "reference_id": "46a6sd ", "color": null, "size": null, "reward_terms": null, "freq_cap":null, "freq_period_id":null, "freq_period_name":null, "segment": { "name":"Canada Members", "subscription_id":1043 } }


Sample Successful Response: Status Code 200 – with group info

When a reward has variation, the API response will have one entry for the reward and one entry for each variation. For example, if there are 2 variations, the API response will have 3 entries, 2 for the variation plus one for the reward.

[ { "id": "2958", "title": "Reward with 2 variations", "description": "qa", "current_quantity": 9999999, "num_points": 1, "date_start": 1480586400, "date_end": 1483178400, "date_end_redeemable": null, "is_enabled": 1, "category_id": 1105, "group_id": 2462, "no_end_date": 0, "total_quantity": 9999999, "max_select_quantity": null, "max_per_user": 11, "is_shipping_required": 0, "is_phone_number_required": 0, "is_min_age_required": "0", "min_age": null, "is_digital_download": 0, "sweepstake_winners": null, "extra_data": null, "reference_id": "46a6sd ", "color": null, "size": null, "total_coupons": 0, "remaining_coupons": 0, "image": "http://crowdtwist.com/img/v2/9105ba5937e340fb6bac58e2edd6359e5180b90b/w/h/0/image.jpg", "reward_terms": null, "min_tier_id": null, "freq_cap":null, "freq_period_id":null, "freq_period_name":null, "segment": { "name":"Canada Members", "subscription_id":1043 } }, { "id": "2959", "title": "Reward with variations - variation 1", "description": "qa", "current_quantity": 11, "num_points": 1, "date_start": 1480586400, "date_end": 1483178400, "date_end_redeemable": null, "is_enabled": 1, "category_id": 1105, "group_id": 2462, "no_end_date": 0, "total_quantity": 9999999, "max_select_quantity": null, "max_per_user": 11, "is_shipping_required": 0, "is_phone_number_required": 0, "is_min_age_required": "0", "min_age": null, "is_digital_download": 0, "sweepstake_winners": null, "extra_data": null, "reference_id": "46a6sd ", "color": "red", "size": "medium", "total_coupons": 0, "remaining_coupons": 0, "image": "http://crowdtwist.com/img/v2/9105ba5937e340fb6bac58e2edd6359e5180b90b/w/h/0/image.jpg", "reward_terms": null, "min_tier_id": null, "freq_cap":null, "freq_period_id":null, "freq_period_name":null, "segment": { "name":"Canada Members", "subscription_id":1043 } }, { "id": "2961", "title": "Reward with variations - variation 2", "description": "qa", "current_quantity": 11, "num_points": 1, "date_start": 1480586400, "date_end": 1483178400, "date_end_redeemable": null, "is_enabled": 1, "category_id": 1105, "group_id": 2462, "no_end_date": 0, "total_quantity": 9999999, "max_select_quantity": null, "max_per_user": 11, "is_shipping_required": 0, "is_phone_number_required": 0, "is_min_age_required": "0", "min_age": null, "is_digital_download": 0, "sweepstake_winners": null, "extra_data": null, "reference_id": "46a6sd ", "color": "white", "size": "medium", "total_coupons": 0, "remaining_coupons": 0, "image": "http://crowdtwist.com/img/v2/9105ba5937e340fb6bac58e2edd6359e5180b90b/w/h/0/image.jpg", "reward_terms": null, "min_tier_id": 74, "freq_cap":null, "freq_period_id":null, "freq_period_name":null, "segment": { "name":"Canada Members", "subscription_id":1043 } } ]


Sample Successful Response: Status Code 200 – without additonal images

{ "id": "3182", "title": "Test reward", "description": "qa", "current_quantity": 100, "num_points": 1, "date_start": 1480586400, "date_end": 1483178400, "date_end_redeemable": null, "is_enabled": 1, "category_id": 1498, "group_id": 2646, "no_end_date": 0, "total_quantity": 100, "max_select_quantity": null, "max_per_user": 9, "is_shipping_required": 0, "is_phone_number_required": 0, "is_min_age_required": "0", "min_age": null, "is_digital_download": 0, "sweepstake_winners": null, "extra_data": null, "reference_id": "46a6sd ", "color": null, "size": null, "total_coupons": 0, "remaining_coupons": 0, "additional_images": [], "image": "http://crowdtwist.com/img/v2/f8ffd787cd6e8ae15724167809969bb1c149228c/w/h/0/image.jpg", "reward_terms": null, "min_tier_id": 73, "freq_cap":1, "freq_period_id":2, "freq_period_name":"Calendar Day", "segment": { "name":"Canada Members", "subscription_id":1043 } }


Sample Successful Response: Status Code 200 – with additonal images

{ "id": "3182", "title": "Test reward", "description": "qa", "current_quantity": 100, "num_points": 1, "date_start": 1480586400, "date_end": 1483178400, "date_end_redeemable": null, "is_enabled": 1, "category_id": 1498, "group_id": 2646, "no_end_date": 0, "total_quantity": 100, "max_select_quantity": null, "max_per_user": 9, "is_shipping_required": 0, "is_phone_number_required": 0, "is_min_age_required": "0", "min_age": null, "is_digital_download": 0, "sweepstake_winners": null, "extra_data": null, "reference_id": "46a6sd ", "color": null, "size": null, "total_coupons": 0, "remaining_coupons": 0, "additional_images": [ "http://crowdtwist.com/img/v2/a1fd59769aa51b7163b36a5c797c24d4fef5996c/w/h/0/image.jpg", "http://crowdtwist.com/img/v2/f8ffd787cd6e8ae15724167809969bb1c149228c/w/h/0/image.jpg" ], "image": "http://crowdtwist.com/img/v2/f8ffd787cd6e8ae15724167809969bb1c149228c/w/h/0/image.jpg", "reward_terms": null, "min_tier_id": null, "freq_cap":null, "freq_period_id":null, "freq_period_name":null, "segment": { "name":"Canada Members", "subscription_id":1043 } }


Sample Error Response: Status Code 400

{ "error": "param_error", "message": "Missing the username parameter." }


Sample Error Response: Status Code 400 – Invalid API Key

{ "error": "invalid_auth", "message": "Invalid access credentials." }


Sample Error Response: Status Code 400 – Invalid id

{ "error": "no_data", "message": "There are no rewards available to this client." }