Rewards

The reward object

Attributes

id integer
Unique identifier for a reward issued to a user.
descriptor string
Descriptor corresponding to the the reward issued. This is not meant to be displayed to the user, but instead used to identify which reward the user received.
name string
Description of the reward, meant to be displayable to the user.
type string
Type of reward, which is one of: SingleSided, DoubleSided, Milestone.
user_role string
Applicable in the case of a double-sided reward, the role will tell you whether this reward is for the referrer or for their referred friend.
  • referrer - This reward was earned by the referring user.
  • friend - This reward was earned by the referred user.
In the case of single-sided or milestone rewards, this value will always be referrer.
user_id integer
Unique identifier of the user who earned the reward.
status string
Status of this reward, which is one of:
  • earned - The reward has been earned by the user and is pending delivery.
  • delivered - The reward has been marked as delivered.
  • revoked - The reward has been marked as revoked.
earned_at timestamp
Time at which the user earned the reward.
delivered_at timestamp
Time at which the reward was marked as delivered.
revoked_at timestamp
Time at which the reward was marked as revoked.

LIST all rewards GET /api/v2/betas/{beta_id}/rewards

Receive a list of all Rewards.

Please Don't Poll — Instead, use our Webhooks feature, which lets us push data to you when rewards are created (earned) or updated (delivered or revoked). You can set up Webhooks from within the Prefinery UI. If you do decide to poll please note that we impose a rate limit of 60 requests per minute for this API endpoint.

Parameters

email optional
Get all rewards earned by a specific user.
status optional
Get all rewards in a specific status, where status can be earned, delivered, or revoked.

Request

    
      curl -u api_key: https://api.prefinery.com/api/v2/betas/1/rewards.json \
        -d email=leonard@bigbangtheory.com \
        -d status=delivered \
        -G

Response

    
  HTTP/1.1 200 OK

  [
    {
      "id": 1,
      "descriptor": "250MB-BONUS",
      "name": "bonus 250MB in cloud storage",
      "type": "SingleSided",
      "user_role": "referrer",
      "user_id": 1,
      "status": "delivered",
      "earned_at": "2020-08-15T13:15:01Z",
      "delivered_at": "2020-08-22T14:25:10Z",
      "revoked_at": null
    }
  ]

SHOW a reward GET /api/v2/betas/{beta_id}/rewards/{reward_id}

Get a single reward by its ID.

Request

    
      curl -u api_key: https://api.prefinery.com/api/v2/betas/1/rewards/1.json

Response

    
HTTP/1.1 200 OK
{
  "id": 1,
  "descriptor": "250MB-BONUS",
  "name": "bonus 250MB in cloud storage",
  "type": "SingleSided",
  "user_role": "referrer",
  "user_id": 1,
  "status": "delivered",
  "earned_at": "2020-08-15T13:15:01Z",
  "delivered_at": "2020-08-22T14:25:10Z",
  "revoked_at": null,
}

UPDATE a reward status PATCH /api/v2/betas/{beta_id}/rewards/{reward_id}

Mark a reward as delivered or revoked.

Request

      
        curl -u api_key: -X PATCH https://api.prefinery.com/api/v2/betas/1/rewards/1.json \
          -d status=delivered

Response

      
  HTTP/1.1 200 OK
  {
    "id": 1,
    "descriptor": "250MB-BONUS",
    "name": "bonus 250MB in cloud storage",
    "type": "SingleSided",
    "user_role": "referrer",
    "user_id": 1,
    "status": "delivered",
    "earned_at": "2020-08-15T13:15:01Z",
    "delivered_at": "2020-08-22T14:25:10Z",
    "revoked_at": null,
  }

Errors

Code Description
2601 A general error has occurred.
2607 Invalid status.
2608 Reward cannot transition to this status.

CREATE a reward POST /api/v2/betas/{beta_id}/rewards

Manually reward a user.

In most cases you will want to use the TRIGGER endpoint instead, which automatically issues rewards when a person performs a goal-based action. Only use this CREATE endpoint if you want to manually issue a specific reward to someone.

Parameters

email required
The user you are rewarding.
descriptor required
The unique descriptor which identifies the reward you want to issue to the user. Set this attribute to issue a specific reward to a user.
skip_quantity_check optional boolean
Set to true in order to force the reward to be issued to the user, even if they have already received the maximum quantity. Defaults to false.

Request

    
    {
      "email": "leonard@bigbangtheory.com",
      "descriptor": "250MB-BONUS"
    }

Or, using curl: 

    
      curl -u api_key: https://api.prefinery.com/api/v2/betas/1/rewards.json \
        -d email=leonard@bigbangtheory.com \
        -d descriptor=250MB-BONUS

Response

    
HTTP/1.1 201 Created
{
  "id": 1,
  "descriptor": "250MB-BONUS",
  "name": "bonus 250MB in cloud storage",
  "type": "SingleSided",
  "user_role": "referrer",
  "user_id": 1,
  "status": "delivered",
  "earned_at": "2020-08-15T13:15:01Z",
  "delivered_at": "2020-08-22T14:25:10Z",
  "revoked_at": null,
}

Errors

Code Description
2601 A general error has occurred.
2602 Email is required.
2603 Email not found.
2604 Descriptor is required.
2605 Descriptor not found.
2609 Limit reached.

TRIGGER rewards POST /api/v2/betas/{beta_id}/rewards/trigger

Evaluate a custom event and create all necessary rewards.

When you set up a reward in your Prefinery dashboard, you can specify that the reward be earned when a person completes a goal-based action (see What Triggers a Reward? for more information). This API endpoint allows you to let us know that a person has completed an action. If having performed that action causes any rewards to be earned by any users, then those rewards will be created and the list will be returned here.

Parameters

email required
The user who performed the custom event.
event required
The name of the custom event.

Request

In the following example, we have set up an Uber-style double-sided reward in your Prefinery dashboard whereby the referring user and their referred friend both receive a free ride up to $20 when the friend takes their first ride. When the friend takes their first ride we will use the API to trigger rewards associated with the "first-uber-ride" event. The result is that two earned rewards are created. 

    
    {
      "email": "leonard@bigbangtheory.com",
      "event": "first-uber-ride"
    }

Or, using curl: 

    
      curl -u api_key: https://api.prefinery.com/api/v2/betas/1/rewards/trigger.json \
        -d email=leonard@bigbangtheory.com \
        -d event=first-uber-ride

Response

    
  HTTP/1.1 200 OK
  
  [
    {
      "id": 100,
      "descriptor": "20-CREDIT",
      "name": "a free ride up to $20",
      "type": "DoubleSided",
      "user_role": "referrer",
      "user_id": 1,
      "status": "earned",
      "earned_at": "2020-08-15T13:15:01Z",
      "delivered_at": null,
      "revoked_at": null
    },
    {
      "id": 101,
      "descriptor": "20-CREDIT",
      "name": "a free ride up to $20",
      "type": "DoubleSided",
      "user_role": "friend",
      "user_id": 2,
      "status": "earned",
      "earned_at": "2020-08-15T13:15:01Z",
      "delivered_at": null,
      "revoked_at": null
    }
  ]

Errors

Code Description
2601 A general error has occurred.
2602 Email is required.
2603 Email not found.
2606 Event is required.