# Tutorials

## Table of contents

The following examples use **NodeJS**.

| [Example 1: Trigger a loyalty action](/developer-tools/rest-api/tutorials.md#example-1-trigger-a-loyalty-action)      |
| --------------------------------------------------------------------------------------------------------------------- |
| [Example 2: Get a participant's details](/developer-tools/rest-api/tutorials.md#example-2-get-a-participants-details) |

## Example 1: Trigger a loyalty action

{% hint style="info" %}

### **Box as an example**

> ***"***Upload a file and receive an additional free trial day*."*
> {% endhint %}

### [Step 1: Make sure you have authentication set up](https://docs.loyaltysurf.io/integrate/rest-api#getting-started)

### Step 2: Trigger loyalty action

Trigger a loyalty action by calling the endpoint [**POST** Trigger Loyalty Action by Email](https://docs.loyaltysurf.io/integrations/rest-api/api-reference#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**

{% code title="upload-file.js" lineNumbers="true" %}

```javascript
const request = require("request");

const options = {
  method: 'POST',
  url: 'https://api.loyaltysurf.io/v1/campaign/4pdlhb/loyalty-action', // Replace '4pdlhb' with your LoyaltySurf program 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: 'gavin@hooli.com', // Replace 'gavin@hooli.com' with your user's email address
    rewardId: 'crew_jw83va', // Replace 'crew_jw83va' with a reward ID from your LoyaltySurf program
  };

  // 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);
    }
  });
};
```

{% endcode %}

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

**At line 7**, replace  `<YOUR_API_KEY>` with your API key, which you can get from your [account settings page](https://app.loyaltysurf.io/settings).

**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 program editor.

Once you trigger a loyalty action, your user will get added to your LoyaltySurf program 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 program reward's loyalty action conversion threshold is 1, then a reward will be generated for the participant. You can set up [Webhooks](https://docs.loyaltysurf.io/automate-rewards/webhooks) to automate the reward of giving out the free trial day.

{% hint style="info" %}
Alternatively, you may also use [Zapier](https://docs.loyaltysurf.io/automate-rewards/zapier), [PayPal](https://docs.loyaltysurf.io/integrations/paypal), [Tango Card](https://docs.loyaltysurf.io/integrations/tango-card), [Stripe](https://docs.loyaltysurf.io/integrations/stripe), [Chargebee](https://docs.loyaltysurf.io/integrations/chargebee), or [Recurly](https://docs.loyaltysurf.io/integrations/recurly) to automate rewards.
{% endhint %}

## 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 [**`GET`**`Participant by email`](https://docs.loyaltysurf.io/integrations/rest-api/api-reference#get-participant-by-email) or [**`GET`**`Participant by ID`](https://docs.loyaltysurf.io/integrations/rest-api/api-reference#get-participant-by-id) endpoints.

### [Step 1: Make sure you have authentication setup](https://docs.loyaltysurf.io/integrate/rest-api#getting-started)

### Step 2: Retrieve a participant by email

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

**Code Example**

{% code title="signup.js" lineNumbers="true" %}

```javascript
const request = require("request");

let options = {
  method: 'GET',
  url: 'https://api.loyaltysurf.io/v1/campaign/4pdlhb/participant/gavin@hooli.com', // Replace '4pdlhb' with your LoyaltySurf program ID and replace 'gavin@hooli.com' 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);
  });
};
```

{% endcode %}

**At line 5:**

* Replace `4pdlhb` with your LoyaltySurf program ID. This can be found within the browser's URL bar of any webpage that you are viewing your LoyaltySurf program from.
* Replace `gavin@hooli.com` 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](https://app.loyaltysurf.io/settings).

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

```javascript
{
  "id": "0o6zk7",
  "firstName": "Gavin",
  "lastName": "Belson",
  "loyaltyActionCount": 64,
  "monthlyLoyaltyActionCount": 64,
  "prevMonthlyLoyaltyActionCount": 0,
  "rank": 1,
  "monthlyRank": 1,
  "rewards": [
    {
      "id": "prew_gbmggn",
      "rewardId": "crew_4bvj34",
      "status": "FULFILLED",
      "unread": true,
      "isFulfilled": true,
      "isAvailable": true,
      "approved": true,
      "approvedAt": 1673512243809,
      "fulfilledAt": 1673512243809,
      "participantId": "0o6zk7"
    },
    {
      "id": "prew_c9ruja",
      "rewardId": "crew_4bvj34",
      "status": "FULFILLED",
      "unread": true,
      "isFulfilled": true,
      "isAvailable": true,
      "approved": true,
      "approvedAt": 1673513384713,
      "fulfilledAt": 1673513384713,
      "participantId": "0o6zk7"
    },
    {
      "id": "prew_ri4fqm",
      "rewardId": "crew_eaqcym",
      "status": "FULFILLED",
      "unread": true,
      "isFulfilled": true,
      "isAvailable": true,
      "approved": true,
      "approvedAt": 1673514372041,
      "fulfilledAt": 1673514372041,
      "participantId": "0o6zk7"
    },
    {
      "id": "prew_ye9wtm",
      "rewardId": "crew_eaqcym",
      "status": "FULFILLED",
      "unread": true,
      "isFulfilled": true,
      "isAvailable": true,
      "approved": true,
      "approvedAt": 1673514689008,
      "fulfilledAt": 1673514689008,
      "participantId": "0o6zk7"
    },
    {
      "id": "prew_as64qz",
      "rewardId": "crew_eaqcym",
      "status": "FULFILLED",
      "unread": true,
      "isFulfilled": true,
      "isAvailable": true,
      "approved": true,
      "approvedAt": 1673516703039,
      "fulfilledAt": 1673516703039,
      "participantId": "0o6zk7"
    }
  ],
  "email": "gavin.belson@hoolie.com",
  "createdAt": 1670839357123,
  "loyaltyActionSource": "MANUAL",
  "fraudRiskLevel": "LOW",
  "fraudReasonCode": "UNIQUE_IDENTITY",
  "isWinner": true,
  "loyaltyActionCountPerReward": {
    "crew_xfj7ic": 24,
    "crew_b3iq3m": 18,
    "crew_p046cu": 8,
    "crew_0256ri": 1,
    "crew_4bvj34": 9,
    "crew_2k8jln": 1,
    "crew_eaqcym": 3
  },
  "monthlyLoyaltyActionCountPerReward": {
    "crew_xfj7ic": 24,
    "crew_b3iq3m": 18,
    "crew_p046cu": 8,
    "crew_0256ri": 1,
    "crew_4bvj34": 9,
    "crew_2k8jln": 1,
    "crew_eaqcym": 3
  },
  "prevLoyaltyActionCount": 0,
  "metadata": {
    "zipCode": 55555
  }
}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.loyaltysurf.io/developer-tools/rest-api/tutorials.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.