Reward Create

Request Details

Item Value
Description The Create Reward API allows clients to create rewards in their loyalty program. The create reward API supports standard, sweepstake, code and download rewards types.
Method POST
Endpoint https://[environment]api[client_id].crowdtwist.com/v2/reward?api_key=[api_key]
Content Type application/json

Request

Field Name Sample Value Required Format Description
URL PARAMETERS – none
QUERY PARAMETERS – none
Note: This request does not support URL or query parameters.


Request Body

Field Name Sample Value Required Format Description
title Free Cap Yes String The title of reward.
description Free Accessories Yes String The description of reward.
type STANDARD Yes String

Reward types that can be created:

  • STANDARD
  • SWEEPSTAKES
  • CODE
  • DOWNLOAD
category_id 4536 Yes Integer Reward category id.
points_to_redeem 100 Yes Integer The number of points required to redeem this reward.
total_quantity 25 No Integer Total quantity of the reward which is set. Updating the quantity does not add to initial quantity, but will set the quantity to the new value. This will not be required when reward has variations as each variation will have its own quantity. This attribute is not present for Sweepstake.
This will not be required when reward has variations as each variation will have its own quantity

This field is not present for Sweepstake
reference_id First software-rewards No String Reference ID used for matching external reward fields.
max_lifetime_redemptions 1 No Integer If set, then the value is the maximum allowed. If not set, then unlimited.
is_shipping_required true Yes Boolean If shipping information is required for redemption
is_phone_number_required true Yes Boolean If phone number is required for redemption
date_start 2012-04-23T18:25:43z Yes Date Start date of the reward. This date must be an ISO-8601 compliant date field with offset appended to it.
date_end 2018-04-23T18:25:43z No Date End date of the reward. This date must be an ISO-8601 compliant date field with offset appended to it. It is mandatory if reward type is sweepstake.
freq_cap 2 No Integer Check is going to be made for fan center client/s who do not have the feature enabled for them. The API will not support frequency capping for Fan center clients how many times a reward can be redeemed within a given time period.
freq_period_id 1 No Integer

Given time period for reward. 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
code_expiration Null No Integer

The offset of number of days of expiration for the reward.

Note: Only present for CODE reward type.
segment_link_id 123 No Integer ID of the segment or segment group linked to the reward . This is the same ID returned in the User Profile API.
segment_link_type include No String

"include" or "exclude", required if segment_link_id is provided.

  • include: Only members of the linked segment can see or redeem the reward.
  • exclude: Only members not in the linked segment can see or redeem the reward.
variations See the VARIATION ARRAY section. No Array  
extra_data See the EXTRA DATA OBJECT section. No Object This is client defined additional data, max limit of 20.
date_until_entries_accepted 2012-04-23T18:25:43z No Date Date/Time until which a user can enter a sweepstake. It is mandatory if reward type is sweepstake.
num_winners 3 No Integer Number of winners assigned for the Sweepstake reward. It is mandatory if reward type is sweepstake.
min_age 18 No Integer Minimum age required to enter the sweepstake.
VARIATION ARRAY
display_order 1 Yes Integer Order in which the reward variations will appear.
quantity 64256446 Yes Integer Quantity of the variation.
reference_id ABFTGDB34352 No String Reference ID of the reward.
color Red Yes String The color of the shirt.
size Small Yes String Size of the shirt.
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.

Response

Response Body

Field Name Sample Value Required Format Description
reward_ids [5089, 694568] Yes Array (Strings) This is the Array of Internal CrowdTwist reward id(s).
reward_group_id 64256446 Yes Integer This is the group ID of the reward.


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 reward_title_taken Reward with the same name exists.
400 required_property_missing Missing [fieldname] required field.
400 exceeds_max_size Property [filename] cannot exceed [max].
400 below_min_size Property [filename] cannot be less than [min].
400 end_date_before_start_date End date/time cannot be before start date/time.
400 invalid_date Invalid data format, [field] should be [data_type] but entered [data_type].
400 non_unique_variation Color and size combination have to be unique.
400 invalid_category_id Category ID is invalid
400 invalid_reward_type Only type STANDARD/SWEEPSTAKE is allowed in type field.
400 entry_dead_line_date_before_start_date_or_after_end_date Entry deadline date/time cannot be before start date of after end date.
400 reward_property_type_not_allowed Property [propertyName}] is not allowed for supported for [RewardType] reward.

Samples

Sample Request Body - Standard Rewards

{ "title": "T-Shirts of different sizes", "description": "Reward with variations", "type": "STANDARD", "category_id": 2631, "points_to_redeem": 20, "total_quantity": 4, "reference_id": null, "max_lifetime_redemptions": 2, "is_shipping_required": true, "is_phone_number_required": true, "date_start": "2022-01-23T18:25:43z", "date_end": null, "extra_data": { "city": "New York", "state": "NY", "country": "USA", "postal code": "10010" }, "variations": [ { "display_order": 1, "quantity": 4, "reference_id": "abc", "color": "red", "size": "Medium" }, { "display_order": 2, "quantity": 5, "reference_id": "xyz", "color": "White", "size": "Medium" } ], "freq_cap": null, "freq_period_id": null }


Sample Request Body - Sweepstakes

{ "title": "T-Shirts of different sizes", "description": "Reward with variations", "type": "SWEEPSTAKE", "category_id": 2631, "points_to_redeem": 20, "reference_id": null, "max_lifetime_redemptions": 2, "is_shipping_required": true, "is_phone_number_required": true, "date_start": "2022-01-23T18:25:43z", "date_end": "2022-02-23T18:25:43z", "extra_data": { "city": "New York", "state": "NY", "country": "USA", "postal code": "10010" }, "freq_cap": null, "freq_period_id": null, "date_until_entries_accepted": "2012-02-11T18:25:43z", "num_winners": 1, "min_age": 18 }


Sample Response Body

{ "reward_ids": [ 5609099, 5609100 ], "reward_group_id": 4385938 }


Sample Error Response

{ "error": "reward_property_type_not_allowed", "message": "Property [total_quantity] is not allowed for [SWEEPSTAKE] Reward Type." }