User Redemption


Request Details

Item Value
Description Redeems a reward for a user.
Method POST
Endpoint https://api.crowdtwist.com/v2/users/[user_id]/redemption?api_key=[api_key]
Content Type: JSON (application/json)


Request

Field Name Sample Value Required Format Notes
URL PARAMETERS
user_id alice@crowdtwist.com Yes String User ID of the user for whom the reward will be redeemed
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, defaults to ID if not specified.
Options:
  – email
  – facebook_user_id
  – twitter_user_id
  – id (CrowdTwist ID, default if not specified)
  – third_party_id
  – username
  – mobile_phone_number
REQUEST BODY

reward_id

64

Yes

String

The CrowdTwist ID of the reward 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.


Successful Response

Field Name Sample Value Required Format Description

ending_balance

6000

No

Integer

Number of points remaining available to user.

codes

wi4hsjd

No

Array

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.


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.
insufficient_points User does not have enough points to redeem reward.
access_denied User does not have access to this reward or it is locked.
insufficient_inventory Not enough reward inventory to fulfill redemption.
invalid_reward Reward does not exist, is expired or inactive.
over_redeem_limit User can only redeem x of this reward.
sweep_entry_over This sweepstakes is either over or entries are no longer being accepted.


Sample Request

curl -X POST
https://api.crowdtwist.com/v2/users/customer123/redemption?api_key=QWERTYUIOP&id_type=username
{
  "reward_id": 64,
  "quantify": 1
}
curl -X POST
https://api.crowdtwist.com/v2/users/customer123/redemption?api_key=QWERTYUIOP&id_type=username
{
  "reward_id": 64,
  "quantify": 1
}


Sample Successful Response: Status Code 200

{
  ending_balance: 6000
}
{
	ending_balance: 6000
}

Sample Error Response: Status Code 400

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