Request Details

Item	Value
Description	The User Redemption API redeems a reward for a user.
Method	POST
Endpoint	https://[environment]api[client_id].crowdtwist.com/v2/users/[user_id]/redemption?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	User ID of the user for whom the reward will be redeemed. The user ID can be::   – Email address   – Facebook user ID   – Twitter User ID   – CrowdTwist ID   – Third party ID   – Username   – Mobile Phone Number
QUERY PARAMETERS
api_key	QWERTYUIOP	Yes	String
id_type	email	No	String	Type of ID being sent, defaults to ID if not specified. The type of ID can be:   – email   – facebook_user_id   – twitter_user_id   – id (CrowdTwist ID, default if not specified)   – third_party_id   – username   – mobile_phone_number

Request Body

Field Name	Sample Value	Required	Format	Description
reward_id	64	Yes	String	The reward variation ID to be redeemed.
quantity	1	Yes	Integer	The quantity of the reward to be redeemed.
shipping_phone_number	2125551234	No	String	If required by reward – phone number of user redeeming reward.
shipping_first_name	John	No	String	If required by reward – first name to whom the reward will be shipped.
shipping_last_name	Doe	No	String	If required by reward – last name to whom the reward will be shipped.
shipping_street_address_1	25 1st Avenue	No	String	If required by reward – street address of destination the reward will be shipped.
shipping_street_address_2	Apt 7C	No	String	If required by reward – additional address info of destination the reward will be shipped.
shipping_country	USA	No	String	If required by reward – country of destination the reward will be shipped.
shipping_state	NY	No	String	If required by reward – state of destination the reward will be shipped.
shipping_city	New York	No	String	If required by reward – city of destination the reward will be shipped.
shipping_postal_code	10001	No	String	If required by reward – postal code of destination the reward will be shipped.
custom_data	See the CUSTOM DATA OBJECT section.	No	Object	Client-defined attributes can be sent via the custom_data request object. For a list of configured attributes, please work with your CrowdTwist representative.
CUSTOM DATA OBJECT
store_loc	store1	No	String	Store location associated with purchase.
cashier_id	cashier1	No	String	ID of cashier that helped with purchase.

Response

Response Body

Field Name	Sample Value	Required	Format	Description
ending_balance	6000	Yes	Integer	Number of points remaining available to user.
codes	See the CODE ARRAY section.	No	Array (String)	If code reward – array of code(s) or url(s) for code(s).
digital_download	http://programurl.com/download	No	String	If digital download – url to download.
CODE ARRAY
codes	[ "123456", "123789" ]	No	Array (Strings)	This is the list of codes available.

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
404	page_not_found	User does not exist.
403	insufficient_points	User does not have enough points to redeem reward.
403	access_denied	User is not in the right segment to access this reward.
404	invalid_reward	Reward does not exist, is expired or inactive.
403	over_redeem_limit	User can only redeem x of this reward.
403	sweep_entry_over	This sweepstakes is either over or entries are no longer being accepted.
403	forbidden	User does not meet the minimum age requirement. User's age is. Minimum age is x.
403	forbidden	Redemption exceed current quantity of rewards.

Samples

Sample Request

Sample Request Body

Sample Response Body

Sample Error Response