Request Details

Item	Value
Description	Returns the list of active rewards available to a specific user. v2.1 of the User Rewards API also has the ability to paginate the response.
Method	GET
Endpoint	https://[environment]api[client_id].crowdtwist.com/v2.1/users/[user_id]/rewards?api_key=[api_key]&id_type=[id_type]
Content Type	application/json

Request

Field Name	Sample Value	Required	Format	Description
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 PARAMETERS
api_key	QWERTYP	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
page	1	No	Integer	Clients have the option to send request for a specific page number. If no page number is requested we will return the first page. If page requested is not a valid value we will return the first page. If page is out of range – Eg if page number is 0 or lesser, we will return empty rewards array and next page will have a link to page 1. If page number is exceeding the length of pages available we will return empty rewards array and return a link to the previous available page. Max entries per page is 10.
page_size	10	No	Integer	The size of page that is returned in the response (max of 10). If no page_size is specified, we default with 10 rewards in the response
include_soldout	true	No	String	Include rewards that are not able to be redeemed due to being sold out (quantity=0).

Response

Response Body

Field Name	Sample Value	Required	Format	Description
paging	See the PAGING ARRAY section.	Yes	Array (Paging objects)	Array that stores information on the specified page of purchases.
rewards	See the REWARDS ARRAY section.	Yes	Array (Reward objects)	Array of Reward information.
PAGING ARRAY
total	203	Yes	Integer	This is the total number of rewards.
pages	10	Yes	Integer	This is the total page numbers.
next_page	http://example.ct.com/v2.1/rewards?page=3	No	String	This is the URL of the next page.
prev_page	http://example.ct.com/v2.1/rewards?page=1	No	String	This is the URL of the previous page.
REWARDS ARRAY
id	64	Yes	String	The is the internal CrowdTwist reward id.
group_id	3453	Yes	Integer	This is the group of the reward. When a reward has multiple sizes/colors, they will all share the same group_id.
title	10% Off Coupon	Yes	String	This is the title of the reward.
description	Receive a 10% off coupon when you redeem 1000 points.	Yes	String	This is the description of the reward.
current_quantity	750	Yes	Integer	Current number of this reward available.
num_points	100	Yes	Integer	The number of points a user must redeem to be issued the reward.
date_start	1490688000	Yes	Integer	This the unix timestamp of date when reward initially becomes available.
date_end	1493193600	No	Integer	This the unix timestamp of date when reward stops being available.
date_end_redeemable	1425404945	No	Integer	This the unix timestamp of date when reward stops being available for redemption.
is_enabled	1	Yes	Boolean	This is the boolean value indicating if reward is enabled.
category_id	16	Yes	Integer	This is reward category id.
no_end_date	1	Yes	Boolean	This is the boolean value indicating if there is no end date.
total_quantity	200	Yes	Integer	This is the total number of this reward that is available.
max_select_quantity	3	No	Integer	This is the maximum number of this reward a user can select.
max_per_user	5	Yes	Integer	This is the maximum number of this reward a user can redeem.
is_shipping_required	1	Yes	Boolean	This is the boolean value indicating if shipping is required.
is_phone_number_required	1	Yes	Boolean	This is the boolean value indicating if phone number is required.
is_min_age_required	1	Yes	Boolean	This indicates if a minimum age is required and can be 0 or 1.
min_age	13	No	Integer	This is the minimum age required for a use to redeem this reward.
is_digital_download	1	Yes	Boolean	This is the boolean value indicating if reward is digital download.
sweepstakes_winners	100	No	Integer	If Sweepstakes – this indicated total number of potential sweepstakes winners.
extra_data	See the EXTRA DATA OBJECT section.	No	Object	This is client defined additional data, max limit of 20.
reference_id	46a6sd	No	String	This is the custom identifier that can be set in Control Center per reward/reward variation.
total_coupons	1000	Yes	Integer	If code reward – Number of coupons uploaded.
remaining_coupons	100	Yes	Integer	If code reward – Number of coupons remaining unredeemed.
freq_cap	1	No	String	The number of redemptions that can table place based on the freq_period_id and freq_period_name.
freq_period_id	2	No	String	The id of the freq_period_name value. Below periods can be chosen: 1 = 24 hours 2 = Calendar day 3 = 7 days 4 = Calendar week 5 = Lifetime 6 = Calendar month 7 = Calendar year 8 = 365 days 9 = 30 days 10 = 90 days 11 = 180 days
freq_period_name	Calendar Day	No	String	The time period for which redemptions can take place.
image	http://www.example.com/image	Yes	String	This is the reward image URL.
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	45	No	Integer	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.
segment	See the SEGMENT OBJECT section.	No	Object	This object contains the segment information.
partner_info	See the PARTNER OBJECT section.	No	Object	This object contains the partner details.
EXTRA DATA OBJECT
city	New York	No	String	City information.
state	New York	No	String	State information.
country	USA	No	String	Country information.
postal code	10010	No	String	Postal code information.
SEGMENT OBJECT
name	“New York Members”	Yes	String	This is the name of the segment.
subscription_id	2	Yes	Integer	This is the identifier of the segment.
eligibility_type	"inclusion"	Yes	String	f the eligibility type is "inclusion", this reward is only available to members of this segment. If the eligibility type is "exclusion", this reward is available to everyone except members of this segment.
PARTNER OBJECT
id	56577	Yes	Integer	This is the id of the partner.
name	Acme Car Rentals	Yes	String	This is the name of the partner.

Error Responses

Field Name	Sample Value	Required	Format	Description
error	Field value is empty.	Yes	String	This is a short form of the error.
message	Value of field [fieldname] must not be empty.	Yes	String	This is a detailed message around the error specifying, as specifically as possible, what the fields are that are missing or where exactly the error is.

Error Response Codes

Error	Error Code	Description	Reason
Input Error	4xx	Returned whenever the request is missing required fields, including situations in which the body is malformed (e.g. HTTP method not supported, receipt not found, etc.).	– missing_data – not_unique – receipt_not_found – invalid_amount – invalid_currency – invalid_date – invalid_custom_field – invalid
Server Error	5xx	HTTP error status code is returned due to an error that occurred in the backend.	– internal_error: unexpected error occurred in the CrowdTwist backend – missing_field – invalid_data – not_configured: error occurs when an configuration has not been configured yet

Example Response Codes

Response Code	Error	Message
400	param_error	Param category has invalid value.
403	invalid_auth	Invalid access credentials.
400	no_data	There are no rewards available to this client.
400	page_not_found	User does not exist.

Samples

Sample Request Body

Sample Response Body

Sample Error Response