User Redemption

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

curl -X POST https://api.crowdtwist.com/v2/users/customer123/redemption?api_key=QWERTYUIOP&id_type=username


Sample Request Body

{ "reward_id": "123456", "quantity": 1, "shipping_phone_number": "123456" }


Sample Response Body

{ "ending_balance": "4376" }


Sample Error Response

{ "error": "over_redeem_limit", "message": "User can only redeem 5 of this reward." }