Rewards


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://api.crowdtwist.com/v2/rewards?api_key=[api_key]


Request

Field Name Sample Value Required Format Notes
URL PARAMETERSnone
QUERY STRING 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) can also be filtered by category_id
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.


Successful Response

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.
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.
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 {reference_id : “46a6sd”, 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"
    ]
[
      "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
color blue No String Reward color
size Size 10 No String Reward Size


Error Response

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.


Sample Request

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

Sample Requestwith active_only filter

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


Sample Successful Response: Status Code 200with 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,
  "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",
  "color": "blue"
  "size": "Size 10"
} 
{
  "id": "2958",
  "title": "Reward",
  "description": "Lorem ipsum dolor sum",
  "current_quantity": 50,
  "num_points": 1,
  "date_start": 1478685600,
  "date_end": 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",
  "color": "blue"
  "size": "Size 10"
} 

Sample Successful Response: Status Code 200without group info

{
  "id": "2958",
  "title": "Reward",
  "description": "Lorem ipsum dolor sum",
  "current_quantity": 50,
  "num_points": 1,
  "date_start": 1478685600,
  "date_end": 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",
  "color": null
  "size": null
}
{
  "id": "2958",
  "title": "Reward",
  "description": "Lorem ipsum dolor sum",
  "current_quantity": 50,
  "num_points": 1,
  "date_start": 1478685600,
  "date_end": 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",
  "color": null
  "size": null
}

Sample Successful Response: Status Code 200with 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,
  "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,
  "color": null,
  "size": null,
  "total_coupons": 0,
  "remaining_coupons": 0,
  "image": "http://crowdtwist.com/img/v2/9105ba5937e340fb6bac58e2edd6359e5180b90b/w/h/0/image.jpg"
}
{
  "id": "2959",
  "title": "Reward with variations - variation 1",
  "description": "qa",
  "current_quantity": 11,
  "num_points": 1,
  "date_start": 1480586400,
  "date_end": 1483178400,
  "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,
  "color": "red",
  "size": "medium",
  "total_coupons": 0,
  "remaining_coupons": 0,
  "image": "http://crowdtwist.com/img/v2/9105ba5937e340fb6bac58e2edd6359e5180b90b/w/h/0/image.jpg"
}
{
  "id": "2961",
  "title": "Reward with variations - variation 2",
  "description": "qa",
  "current_quantity": 11,
  "num_points": 1,
  "date_start": 1480586400,
  "date_end": 1483178400,
  "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,
  "color": "white",
  "size": "medium",
  "total_coupons": 0,
  "remaining_coupons": 0,
  "image": "http://crowdtwist.com/img/v2/9105ba5937e340fb6bac58e2edd6359e5180b90b/w/h/0/image.jpg"
}
{
  "id": "2958",
  "title": "Reward with 2 variations,
  "description": "qa",
  "current_quantity": 9999999,
  "num_points": 1,
  "date_start": 1480586400,
  "date_end": 1483178400,
  "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,
  "color": null,
  "size": null,
  "total_coupons": 0,
  "remaining_coupons": 0,
  "image": "http://crowdtwist.com/img/v2/9105ba5937e340fb6bac58e2edd6359e5180b90b/w/h/0/image.jpg"
}
{
  "id": "2959",
  "title": "Reward with variations - variation 1",
  "description": "qa",
  "current_quantity": 11,
  "num_points": 1,
  "date_start": 1480586400,
  "date_end": 1483178400,
  "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,
  "color": "red",
  "size": "medium",
  "total_coupons": 0,
  "remaining_coupons": 0,
  "image": "http://crowdtwist.com/img/v2/9105ba5937e340fb6bac58e2edd6359e5180b90b/w/h/0/image.jpg"
}
{
  "id": "2961",
  "title": "Reward with variations - variation 2",
  "description": "qa",
  "current_quantity": 11,
  "num_points": 1,
  "date_start": 1480586400,
  "date_end": 1483178400,
  "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,
  "color": "white",
  "size": "medium",
  "total_coupons": 0,
  "remaining_coupons": 0,
  "image": "http://crowdtwist.com/img/v2/9105ba5937e340fb6bac58e2edd6359e5180b90b/w/h/0/image.jpg"
}

Sample Successful Response: Status Code 200without additonal images

{
  "id": "3182",
  "title": "Test reward",
  "description": "qa",
  "current_quantity": 100,
  "num_points": 1,
  "date_start": 1480586400,
  "date_end": 1483178400,
  "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,
  "color": null,
  "size": null,
  "total_coupons": 0,
  "remaining_coupons": 0,
  "additional_images": [],
  "image": "http://crowdtwist.com/img/v2/f8ffd787cd6e8ae15724167809969bb1c149228c/w/h/0/image.jpg"
}
{
  "id": "3182",
  "title": "Test reward",
  "description": "qa",
  "current_quantity": 100,
  "num_points": 1,
  "date_start": 1480586400,
  "date_end": 1483178400,
  "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,
  "color": null,
  "size": null,
  "total_coupons": 0,
  "remaining_coupons": 0,
  "additional_images": [],
  "image": "http://crowdtwist.com/img/v2/f8ffd787cd6e8ae15724167809969bb1c149228c/w/h/0/image.jpg"
}

Sample Successful Response: Status Code 200with additonal images

{
  "id": "3182",
  "title": "Test reward",
  "description": "qa",
  "current_quantity": 100,
  "num_points": 1,
  "date_start": 1480586400,
  "date_end": 1483178400,
  "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,
  "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"
}
{
  "id": "3182",
  "title": "Test reward",
  "description": "qa",
  "current_quantity": 100,
  "num_points": 1,
  "date_start": 1480586400,
  "date_end": 1483178400,
  "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,
  "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"
}

Sample Error Response: Status Code 400

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