User Rewards


Request Details

Item Value
Description Returns the list of active rewards available to a specific user.
Method GET
Endpoint https://api.crowdtwist.com/v2/users/[user_id]/rewards?api_key=[api_key]&id_type=[id_type]


Request

Field Name Sample Value Required Format Notes
URL PARAMETERS
user_id alice@crowdtwist.com Yes String Unique ID of the user for whom activities will be returned:
Options:
– Email Address
– Facebook User ID
– Twitter User ID
– CrowdTwist ID
– Third Party ID
– Username
– Mobile Phone Number
QUERY STRING PARAMETERS
api_key QWERTYUIOP Yes String  
id_type email No String Type of ID being Sent:
Options:
– email
– facebook_user_id
– twitter_user_id
– id (CrowdTwist ID) – default ID if id_type is not specified
– third_party_id
– username
– mobile_phone_number


Successful Response

Field Name Sample Value Required Format Description
id 64 Yes String Internal CrowdTwist reward id.
title 10% Off Coupon 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.
num_points 1000 Yes String The number of points a user must redeem to be issued the
reward.
image http://www.imagestorage.com/image Yes URL The reward image.
is_enabled 1 Yes Integer Boolean value indicating if reward is enabled.
category_id 16 No String ID of category rewards is in.
date_start 1490688000 No Unix timestamp Date reward initially becomes available.
date_end 1493193600 No Unix timestamp Date reward stops being available.
date_end_redeemable 1425404945 No Unix timestamp If Sweepstakes – end date redeemable
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.
current_quantity 100 No Integer Current 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 if 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.
total_coupons 10000 No Integer If code reward – Number of coupons uploaded.
remaining_coupons 4678 No Integer If code reward – Number of coupons remaining unredeemed.
sweepstakes_winners 100 No Integer If Sweepstakes – total number of potential sweepstakes
winners.
extra_data {“reference_id” : 12, “internal_name” : “percentoff”} No JSON JSON blob of extra data set by client in Control center.
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.


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.
no_rewards There are no rewards available to this user.


Sample Request

curl -X GET
https://api.crowdtwist.com/v2/users/alice@crowdtwist.com/rewards?api_key=QWERTYUIOP&id_type=email
curl -X GET
https://api.crowdtwist.com/v2/users/alice@crowdtwist.com/rewards?api_key=QWERTYUIOP&id_type=email


Sample Successful Response: Status Code 200

[
  {
    "id": 64,
    "title": "10% off coupon",
    "description": "Receive a 10% off coupon when you redeem 1000 points.",
    "num_points": 1000,
    "image": "http://www.imagestorage.com/image1",
    "is_enabled": 1,
    "category_id": 16,
    "date_start": "1490688000",
    "date_end": "1493193600",
    "no_end_date": 1,
    "total_quantity": 100,
    "current_quantity": 50,
    "max_select_quantity": 3,
    "max_per_user": 4,
    "is_shipping_required": 0,
    "is_phone_number_required": 0,
    "min_age": 13,
    "is_digital_download": 0,
    "total_coupons": 10000,
    "remaining_coupons": 4567,
    "reward_terms": null,
    "min_tier_id": 74
  },
  {
    "id": 65,
    "title": "Free T-shirt",
    "description": "Receive a free t-shirt when you redeem 5000 points.",
    "num_points": 5000,
    "image": "http://www.imagestorage.com/image2",
    "date_start": "1490688000",
    "date_end": "1493193600",
    "no_end_date": 1,
    "total_quantity": 1020,
    "current_quantity": 550,
    "is_shipping_required": 0,
    "is_phone_number_required": 0,
    "is_digital_download": 0,
    "reward_terms": null,
    "min_tier_id": null
  }
]
[
  {
    "id": 64,
    "title": "10% off coupon",
    "description": "Receive a 10% off coupon when you redeem 1000 points.",
    "num_points": 1000,
    "image": "http://www.imagestorage.com/image1",
    "is_enabled": 1,
    "category_id": 16,
    "date_start": "1490688000",
    "date_end": "1493193600",
    "no_end_date": 1,
    "total_quantity": 100,
    "current_quantity": 50,
    "max_select_quantity": 3,
    "max_per_user": 4,
    "is_shipping_required": 0,
    "is_phone_number_required": 0,
    "min_age": 13,
    "is_digital_download": 0,
    "total_coupons": 10000,
    "remaining_coupons": 4567,
    "reward_terms": null,
    "min_tier_id": 74
  },
  {
    "id": 65,
    "title": "Free T-shirt",
    "description": "Receive a free t-shirt when you redeem 5000 points.",
    "num_points": 5000,
    "image": "http://www.imagestorage.com/image2",
    "date_start": "1490688000",
    "date_end": "1493193600",
    "no_end_date": 1,
    "total_quantity": 1020,
    "current_quantity": 550,
    "is_shipping_required": 0,
    "is_phone_number_required": 0,
    "is_digital_download": 0,
    "reward_terms": null,
    "min_tier_id": null
  }
]

Sample Error Response: Status Code 400

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