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. v2.1 of the Rewards API also has the ability to paginate the response.
Method	GET
Endpoint	https://[environment]api[client_id].crowdtwist.com/v2.1/rewards?api_key=[api_key]
Content Type	application/json

Request

Field Name	Sample Value	Required	Format	Description
QUERY PARAMETERS
api_key	QWERTYUIOP	Yes	String
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 25.
page_size	10	No	Integer	The size of page that is returned in the response (max of 25). If no page_size is specified, we default with 25 rewards in the response.
category	Digital	No	String	This filters to rewards in the specified category (by name, case insensitive, leading and trailing whitespace trimmed).
active_only	1	No	Boolean	This filters to “active” rewards, meaning rewards which meet the following conditions: is enabled having passed its start date having no end date or not having passed its end date having no end date or not having passed its end date
for_points	1000	No	String	This 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	This filters to rewards that are marked as featured.
redeemable_by	4628931	No	String	This 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	This 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	points	No	String	This 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	This determines the sort method of the items in the response, must be used in conjunction with the sort parameter. Available options are asc, desc.

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.
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.
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.
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.
show_as_locked	1	Yes	Boolean	This shows reward as locked or hide the reward from a user, if user has not met the unlock criteria.
featured_order_num	453	No	Integer	The order in which a reward appears in a list of featured rewards.
reference_id	46a6sd	No	String	This is the custom identifier that can be set in Control Center per reward/reward variation.
color	Red	No	String	Reward color for reward with variations.
size	Medium	No	String	Reward size for reward with variations.
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.
freq_period_name	Calendar Day	No	String	The time period for which redemptions can take place.
additional_images	See the ADDITIONAL IMAGES ARRAY section.	No	Array (Strings)	This is the array of string for additional images URL that is uploaded.
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.
ADDITIONAL IMAGES ARRAY
additional_images	http://www.example.com/image1	Yes	String	Any additional reward images, in addition to the one image that is required for every reward.
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.

Samples

Sample Request Body

Sample Response Body

Sample Error Response