When you have created a campaign with the Refer a Friend template, you have several options for rewarding your superfans for referring their friends.

One of the rewarding options of the Refer a Friend template is API rewarding, where rewarding is handled automatically by your web app. 

This is useful in cases where the rewards are (usually but not necessarily) intangible and specific to your business. 

For example, if you are Dropbox, you will want to be providing 500 MB to each user that refers one friend to sign-up and 500 MB to each invitee as well. 

How it works

When someone has been referred to your campaign and you have set the Invitee Reward (eg. 500 MB) then when this person signs-up to your campaign, a pending reward is created for them.

A pending reward is a reward that has not yet been provided by your web app. 

The same goes for their referrer. When the invitee signs-up, a pending reward is created for the referrer as well.

Now, all you need to do is to actually provide these rewards. Here's how.

Checking for pending rewards 

Use this API call to check for pending rewards:

method	: GET
endpoint: https://app.viral-loops.com/api/v2/pending_rewards
headers: "Content-Type: application/json"

Example request:

https://app.viral-loops.com/api/v2/pending_rewards?apiToken=MySecretToken&user={"email":"zisis@viral-loops.com"}&filter={"limit":10,"skip":25}
  • Replace MySecretToken with your API Token. Find it in the Installation step of your Campaign Wizard.
  • The filter object is optional. It can be used for pagination using limit (default=25, max=25) and skip (default=0).
  • The user object is optional. If provided, only rewards for that specific user will be returned (pagination rules apply here as well). The user object needs the email or referralCode of the user.

Here's an example response to a request without filters:

{
  "pending": [
    {
     "user": {
"firstname": "Zisis",
"lastname": "",
"email": "zisis@viral-loops.com",
"referralCode": "SkuVQmS9W",
"referralCountTotal": 1,
"risk": 0
      },
      "rewards": [
        {
            "id": "reward_NGU0NzA5OTNiOGU1MDJiODM1ZWM",
            "metadata": {
                "reward": {
                    "user": {
                        "email": "zisis@viral-loops.com",
                        "firstname": "Zisis",
                        "lastname": ""
                    },
                    "details": {
                        "rewardName": "Megabytes",
                        "rewardAmount": 500,
                        "rewardType": "programmatic"
                    }
                }
            }
        }
      ]
    },
    ...
  ]
}

Marking rewards as redeemed

Use this API call to mark rewards as redeemed, after your web app has fulfilled them.

method: POST
endpoint: https://app.viral-loops.com/api/v2/rewarded
headers: "Content-Type: application/json"

Example request body:

{
  "rewardId": "reward_NjAwNGZmZDFiYmZhMWEyOWRhNTg",
  "user": {
    "email": "dimitris@viral-loops.com"
  },
  "apiToken": "MySecretToken"
}

You can either mark a specific reward as redeemed or all of a user's rewards as redeemed.

  • Provide a rewardId to mark a single reward as redeemed.
  • Provide a user object to mark all of their rewards as redeemed. The user object needs the email or referralCode of the user.

Example response:

{
  "redeemed": {
    "total": 1,
    "rewards": [
      "reward_NjAwNGZmZDFiYmZhMWEyOWRhNTg"
    ]
  }
}


That's all.
Do you need more help? Let us know! 

Did this answer your question?