Tutorials

How to implement the LoyaltySurf REST API in common use-case scenarios.

Table of contents

The following examples use NodeJS.

Example 1: Trigger a loyalty action
Example 2: Get a participant's details

Example 1: Trigger a loyalty action

Box as an example

"Upload a file and receive an additional free trial day."

Step 1: Make sure you have authentication set up

Step 2: Trigger loyalty action

Trigger a loyalty action by calling the endpoint POST Trigger Loyalty Action by Email.

Let's imagine that you want to reward a user with a free trial day if they use a feature in your product for uploading a file. This allows the user to get acquainted with your product and you can reward them for the interaction.

You can accomplish this by triggering a loyalty action for your user. The example below is what that code could look like when using NodeJS.

Code Example

upload-file.js

const request = require("request");

const options = {
  method: 'POST',
  url: 'https://api.loyaltysurf.io/v1/campaign/4pdlhb/loyalty-action', // Replace '4pdlhb' with your LoyaltySurf campaign ID
  headers: { 
    Authorization: 'Bearer <YOUR_API_KEY>' // Replace '<YOUR_API_KEY>' with your API key -- get this from https://app.loyaltysurf.io/settings
  },
  json: true
};

const uploadFile = () => {
  // ...code that allows the user to upload a file...

  options.body = {
    participantEmail: '[e-mail]', // Replace '[e-mail]' with your user's email address
    rewardId: 'jw83va', // Replace 'jw83va' with a reward ID from your LoyaltySurf campaign
  };

  // Send the API request to trigger the loyalty action
  request(options, (error, response, body) => {
    if (error) {
      throw new Error(error);
    }
    // Check to see if the loyalty action was triggered successfully
    const { success, message } = body.success;
    if (success) {
      console.log('loyalty action trigger success!');
    } else {
      console.log('loyalty action trigger failed :( ', message);
    }
  });
};

At line 5, replace 4pdlhb with your LoyaltySurf campaign ID. This can be found within the browser's URL bar of any webpage that you are viewing your LoyaltySurf campaign from.

At line 7, replace <YOUR_API_KEY> with your API key, which you can get from your account settings page.

At line 16, set participantEmail with your user's email address (the person who just completed the loyalty action).

At line 17, set rewardId with the Reward ID that you want to trigger a loyalty action for. You can find this value in the Rewards tab or the Installation tab of the LoyaltySurf campaign editor.

Once you trigger a loyalty action, your user will get added to your LoyaltySurf campaign if they do not already exist. Any future loyalty actions that are triggered by the same email address will increment the existing participant's loyalty action count.

Set up reward fulfillment

Once the loyalty action is triggered, and if the campaign reward's loyalty action conversion threshold is 1, then a reward will be generated for the participant. You can set up Webhooks to automate the reward of giving out the free trial day.

Alternatively, you may also use Zapier, PayPal, Tango Card, Stripe, Chargebee, or Recurly to automate rewards.

Example 2: Get a participant's details

With the REST API, you can retrieve a participant's LoyaltySurf rewards or loyalty action count to display on your website or mobile app using the GETParticipant by email or GETParticipant by ID endpoints.

Step 1: Make sure you have authentication setup

Step 2: Retrieve a participant by email

The example below is what that code could look like in NodeJS.

Code Example

signup.js

const request = require("request");

let options = {
  method: 'GET',
  url: 'https://api.loyaltysurf.io/v1/campaign/4pdlhb/participant/[e-mail]', // Replace '4pdlhb' with your LoyaltySurf campaign ID and replace '[e-mail]' with your user's email address
  headers: { 
    Authorization: 'Bearer <YOUR_API_KEY>' // Replace '<YOUR_API_KEY>' with your API key -- get this from https://app.loyaltysurf.io/settings
  },
  json: true
};

const getUserDetails = () => {
  // ...code that gets your users' details...

  // Get the LoyaltySurf participant's details
  request(options, (error, response, body) => {
    if (error) {
      throw new Error(error);
    }
    // Output the response that is returned
    console.log(body);
  });
};

At line 5:

• Replace 4pdlhb with your LoyaltySurf campaign ID. This can be found within the browser's URL bar of any webpage that you are viewing your LoyaltySurf campaign from.

• Replace [e-mail] with your user's email address (the person you want to retrieve loyalty program details for).

At line 7, replace <YOUR_API_KEY> with your API key, which you can get from your account settings page.

At line 21, the console.log(body) will output a response that looks like the below example:

{
  "id": "0o6zk7",
  "firstName": "Gavin",
  "lastName": "Belson",
  "loyaltyActionCount": 64,
  "monthlyLoyaltyActionCount": 64,
  "prevMonthlyLoyaltyActionCount": 0,
  "rank": 1,
  "monthlyRank": 1,
  "rewards": [
    {
      "id": "gbmggn",
      "rewardId": "4bvj34",
      "status": "FULFILLED",
      "unread": true,
      "isFulfilled": true,
      "isAvailable": true,
      "approved": true,
      "approvedAt": 1673512243809,
      "fulfilledAt": 1673512243809,
      "participantId": "0o6zk7"
    },
    {
      "id": "c9ruja",
      "rewardId": "4bvj34",
      "status": "FULFILLED",
      "unread": true,
      "isFulfilled": true,
      "isAvailable": true,
      "approved": true,
      "approvedAt": 1673513384713,
      "fulfilledAt": 1673513384713,
      "participantId": "0o6zk7"
    },
    {
      "id": "ri4fqm",
      "rewardId": "eaqcym",
      "status": "FULFILLED",
      "unread": true,
      "isFulfilled": true,
      "isAvailable": true,
      "approved": true,
      "approvedAt": 1673514372041,
      "fulfilledAt": 1673514372041,
      "participantId": "0o6zk7"
    },
    {
      "id": "ye9wtm",
      "rewardId": "eaqcym",
      "status": "FULFILLED",
      "unread": true,
      "isFulfilled": true,
      "isAvailable": true,
      "approved": true,
      "approvedAt": 1673514689008,
      "fulfilledAt": 1673514689008,
      "participantId": "0o6zk7"
    },
    {
      "id": "as64qz",
      "rewardId": "eaqcym",
      "status": "FULFILLED",
      "unread": true,
      "isFulfilled": true,
      "isAvailable": true,
      "approved": true,
      "approvedAt": 1673516703039,
      "fulfilledAt": 1673516703039,
      "participantId": "0o6zk7"
    }
  ],
  "email": "[e-mail]",
  "createdAt": 1670839357123,
  "loyaltyActionSource": "MANUAL",
  "fraudRiskLevel": "LOW",
  "fraudReasonCode": "UNIQUE_IDENTITY",
  "isWinner": true,
  "loyaltyActionCountPerReward": {
    "xfj7ic": 24,
    "b3iq3m": 18,
    "p046cu": 8,
    "0256ri": 1,
    "4bvj34": 9,
    "2k8jln": 1,
    "eaqcym": 3
  },
  "monthlyLoyaltyActionCountPerReward": {
    "xfj7ic": 24,
    "b3iq3m": 18,
    "p046cu": 8,
    "0256ri": 1,
    "4bvj34": 9,
    "2k8jln": 1,
    "eaqcym": 3
  },
  "prevLoyaltyActionCount": 0,
  "metadata": {
    "zipCode": 55555
  }
}