Tutorials

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

Customer Example: How Bolt.new Powered Their Viral Referral Program with GrowSurf’s API

See our in-depth technical blog post on how a GrowSurf customer implemented the API, webhooks, and reward metadata to scale their referral program to millions of users.

Table of contents

The following examples use Node.js.

Scenario
Example 1: Trigger a referral on qualifying action (e.g, on conversion, purchase or upgrade)
Example 2: Trigger a referral on signup event
Example 3: Get a participant's details
Example 4: Delete a list of participants

Example 1: Trigger a referral on qualifying action (e.g, on conversion, purchase or upgrade)

Airbnb as an example

"Send a friend $40 in Airbnb credit. You’ll get $20 when they travel and $75 when they host."

Follow this tutorial if your campaign's referral trigger is Qualifying Action, where a referrer only receives credit when the person they referred signs up AND performs a certain qualifying action.

This requires two API calls to GrowSurf.

Step 1: Make sure you have authentication set up

Step 2: Add the participant

Important Note: If your campaign is configured to add participants automatically through a form on your website (see image), skip this step.

First, in the code where you capture the new user's email, add them to your GrowSurf campaign as a participant with the POST Add participant method. Alternatively, you can use the JavaScript method growsurf.addParticipant() instead to add participants.

The example below is what that code could look like when using the REST API.

Code Example

signup.js

const request = require("request");

let options = {
  method: 'POST',
  url: 'https://api.growsurf.com/v2/campaign/4pdlhb/participant',
  headers: { 
    Authorization: 'Bearer <YOUR_API_KEY>'
  },
  json: true
};

const signUp = user => {    
    // Set the body of the GrowSurf API request
    options.body = user;
    
    // Send the API request to add the user as a new participant in your GrowSurf campaign
    request(options, (error, response, body) => {
      if (error) {
        throw new Error(error);
      }
      const growsurfId = body.id;
      // Save the new user to your database (optional)
      saveUser(user, growsurfId);
    });
};

At line 21, we set the GrowSurf participant ID as a variable called growsurfId.

At line 23, saveUser(user, growsurfId) is an example function you would use to save the GrowSurf participant ID to the new user in your database. We will use this growsurfId value later for triggering a referral.

Don't want to save the growsurfId to your database?

The participant'semail can be used instead of the growsurfId to trigger a referral later. If you have access to the participant's email then there is no need to persist the growsurfId into your database.

At line 11, the user argument passed into signUp(user) is an Object that looks like this:

{
  email: '[e-mail]',
  firstName: 'Sally', // Optional, but recommended for anti-fraud purposes
  lastName: 'Mayweathers', // Optional, but recommended for anti-fraud purposes
  ipAddress: 1.2.1.827, // Optional, but recommended for anti-fraud purposes
  fingerprint: 'dwah12iu3hi1u2h', // Optional, but recommended for anti-fraud purposes
  referredBy: '1cca8d', // The referrer's unique GrowSurf ID. Can also be the referrer's unique email address
  metadata: {
    phoneNumber: '[phone]',
    country: 'USA',
    zipCode: '94303'
  } 
}

• At lines 2 and 3, we pass in firstName and lastName. These will be used for anti-fraud purposes, as well as in referred friend motivator elements, if enabled.

• At line 4, we pass in the user's IP address, which will be used for anti-fraud purposes.

• At line 5, we pass in the user's browser fingerprint, which will be used for anti-fraud purposes. You can use a library like fingerprintjs to get this value.
• At line 6, we use referredBy to associate this new user with a referrer. This value can be the referrer's email address or unique GrowSurf ID (you may want to use growsurf.getReferrerId() to retrieve the referrer ID).
• At line 7, we save a shallow metadata Object to the GrowSurf Participant. This is optional, but is useful for viewing specific participant information in your GrowSurf dashboard (see image).

Step 3: Trigger the referral

Important Note: Make sure your campaign's referral trigger is set to Sign Up + Qualifying Action (see image). If the referral trigger is set to Sign Up, triggering referrals will not work since referral credit has already been provided.

Now at any future date within the referral credit window, if this new participant performs the goal event, then referral credit will be awarded to their referrer. To trigger the referral, use the POST Trigger referral by participant ID method.

The example below is what that code could look like.

Code Example

purchase.js

const request = require("request");

let options = {
  method: 'POST',
  headers: { 
    Authorization: 'Bearer <YOUR_API_KEY>'
  },
  json: true
};

const purchase = growsurfId => {
    // ...code that makes the purchase...

    // Set the GrowSurf API request URL with the participant's ID
    options.url = `https://api.growsurf.com/v2/campaign/4pdlhb/participant/${growsurfId}/ref`;

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

At line 11, we passed a growsurfId argument, which is the GrowSurf participant's unique ID and is required in the API call. If you do not have access to the growsurfId of the participant, the participant email can be used instead.

Remember to set up reward fulfillment automation

Make sure you have Webhooks or Zapier set up so that rewards automatically get fulfilled to the participant once they reach a reward goal.

Example 2: Trigger a referral on signup event

Dropbox as an example

"For every friend you refer, you’ll both receive an extra 250MB in cloud storage."

Follow this tutorial if your campaign's referral trigger is Signup Event, where a referrer receives credit when the person they referred signs up with their email address.

This requires just one API call to GrowSurf.

Step 1: Make sure you have authentication set up

Step 2: Add the participant (and trigger the referral at the same time)

Important Note: If your campaign is configured to add participants automatically through a form on your website (see image), skip this step.

Important Note: Make sure your campaign's referral trigger is set to Signup Event (see image).

In the code where you capture the new user's email, add them to your GrowSurf campaign as a participant with the POST Add participant method.

The example below is what that code could look like.

Code Example

signup.js

const request = require("request");

let options = {
  method: 'POST',
  url: 'https://api.growsurf.com/v2/campaign/4pdlhb/participant',
  headers: { 
    Authorization: 'Bearer <YOUR_API_KEY>'
  },
  json: true
};

const signUp = user => {    
    // Set the body of the GrowSurf API request
    options.body = user;
    
    // Send the API request to add the user as a new participant in your GrowSurf campaign
    request(options, (error, response, body) => {
      if (error) {
        throw new Error(error);
      }
      
      // Save the new user to your database (Optional)
      saveUser();
    });
};

At line 12, the user argument passed into signUp(user) is an Object that looks like this:

{
  email: '[e-mail]',
  firstName: 'Sally', // Optional, but recommended for anti-fraud purposes
  lastName: 'Mayweathers', // Optional, but recommended for anti-fraud purposes
  ipAddress: 1.2.1.827, // Optional, but recommended for anti-fraud purposes
  fingerprint: 'dwah12iu3hi1u2h', // Optional, but recommended for anti-fraud purposes
  referredBy: '1cca8d', // The referrer's unique GrowSurf ID. Can also be the referrer's unique email address  
  referralStatus: 'CREDIT_AWARDED',
  metadata: {
    phoneNumber: '[phone]',
    country: 'USA',
    zipCode: '94303'
  } 
}

• At lines 2 and 3, we pass in firstName and lastName. These will be used for anti-fraud purposes, as well as in referred friend motivator elements, if enabled.

• At line 4, we pass in the user's IP address, which will be used for anti-fraud purposes.

• At line 5, we pass in the user's browser fingerprint, which will be used for anti-fraud purposes. You can use a library like fingerprintjs to get this value.
• At line 6, we use referredBy to associate this new user with a referrer. This value can be the referrer's email address or unique GrowSurf ID (you may want to use growsurf.getReferrerId() to retrieve the referrer ID)
• At line 7, we set referralStatus to be CREDIT_AWARDED. This triggers the referral credit at the same time that this new participant is added (and it overrides the campaign referral trigger (what's a referral trigger?) that was set from the Installation step of the Campaign Editor (see image).

  • Note: referralStatus must be used with referredBy, or else it will be ignored.

• At line 8, we save a shallow metadata Object to the GrowSurf Participant. This is optional, but is useful for viewing specific participant information in your GrowSurf dashboard (see image).

Remember to set up reward fulfillment automation

Make sure you have Webhooks or Zapier set up so that rewards automatically get fulfilled to the participant once they reach a reward goal.

Example 3: Get a participant's details

Let's say you want to display a participant's referral progress/stats/rewards in your website or mobile app. With the REST API, you can fetch Participants and ParticipantRewards by using either of the following API methods:

• GET Get participant by email
• GET Get participant by ID

Step 1: Make sure you have authentication set up

Step 2: Retrieve a participant by email

Let's say your server calls your database to retrieve user details and in that same call you want to send their participant information by using their unique email.

The example below is what that code could look like.

Code Example

const request = require("request");

let options = {
	method: 'GET',
	headers: {
  		Authorization: 'Bearer <YOUR_API_KEY>'
  	}
};

const getUserDetails = userEmail => {
	// ...Call your database to get user details...
	// ...code here...

	// Get the GrowSurf participant's details
	request(options, (error, response, body) => {
		options.url = `https://api.growsurf.com/v2/campaign/4pdlhb/participant/${userEmail}`;
	 	if (error) {
			throw new Error(error);
		}
		console.log(body);
	});
};

At line 10, we passed userEmail so we could set it in the GrowSurf API URL at line 16.

At line 20, console.log would print something like this:

{
    "id": "f8g9nl",
    "firstName": "Gavin",
    "lastName": "Belson",
    "referralCount": 2,
    "shareUrl": "https://piedpiper.com?grsf=f8g9nl",
    "email": "[e-mail]",
    "createdAt": 1552404738928,
    "fraudRiskLevel": "LOW",
    "fraudReasonCode": "UNIQUE_IDENTIY",
    "isWinner": true,
    "shareCount": {
        "email": 10,
        "facebook": 1,
        "pinterest": 1,
        "twitter": 11
    },
    "impressionCount": 2,
    "referrals": [
        "i9g2bh",
        "xua4sq"
    ],
    "referralSource": "PARTICIPANT",
    "referralStatus": "CREDIT_AWARDED",
    "referrer": {
        "id": "h8kp6l",
        "firstName": "Richard",
        "lastName": "Hendricks",
        "referralCount": 5,
        "shareUrl": "https://piedpiper.com?grsf=h8kp6l",
        "email": "[e-mail]",
        "createdAt": 1552402661449,
        "referralSource": "DIRECT",
        "fraudRiskLevel": "LOW",
        "fraudReasonCode": "UNIQUE_IDENTIY",
        "isWinner": true,
        "shareCount": {
            "email": 20,
            "facebook": 11,
            "linkedin": 0,
            "pinterest": 3,
            "twitter": 12
        },
        "impressionCount": 14,
        "referrals": [
            "0dveu7",
            "f8g9nl",
            "j0hbym",
            "m5xm9l",
            "w01fil"
        ]
    }
}

Example 4: Delete a list of participants

Let's say you want to delete a list of participants in your GrowSurf Campaign. With the REST API, you can use the DELETE Remove Participant by Email endpoint to loop through a CSV list of participants to accomplish this.

Code Example (Node.js)

In this example, we've provided two sample files you may download and use. Follow the instructions below:

1. Replace API_KEY and CAMPAIGN_ID at lines 1 and 2 in the script.js file, respectfully.

2. Replace the email addresses in the emails.csv file with your own list of participants that you want to delete (keep the column header labeled as "Email")

3. Run npm install request require csv-parser to install dependencies

4. Run node script.js to run the script

script.js

script.js

const API_KEY = "ABC123FS9GM2FBJFZ68T7JNAMRCZ" // Replace with your own API key
const CAMPAIGN_ID = "2x3b5c";                  // Replace with your campaign ID

const request = require('request');
const csv = require("csv-parser");
const fs = require("fs");

async function removeParticipant(participantEmail) {
  const headers = {
    "Authorization": `Bearer ${API_KEY}`,
    'Content-Type': 'application/json'
  };
  const url = `https://api.growsurf.com/v2/campaign/${CAMPAIGN_ID}/participant/${participantEmail}`;
  const options = {
    'method': 'DELETE',
    'url': url,
    'headers': headers
  };
  request(options, function (error, response) {
    if (error) {
      throw new Error(error);
    } else {
      const responseBody = JSON.parse(response.body);
      if (responseBody.success) {
        console.log(`✅ ${participantEmail} removed successfully`);
      } else {
        console.log(`❌ Error removing ${participantEmail} (${responseBody.message})`);
      }
    }
  });
}

async function main() {
  const reader = fs.createReadStream("emails.csv").pipe(csv());
  for await (const row of reader) {
    if (row["Email"]) {
      const participantEmail = row["Email"];
      await removeParticipant(participantEmail);
      await new Promise(resolve => setTimeout(resolve, 1000)); // Slow down by 1 second per request
    }
  }
}

main();

emails.csv

emails.csv

Email
[e-mail]
[e-mail]
[e-mail]

Some other notes:

• The script will begin deleting participants one by one, waiting 1 second between each request to comply with our rate limit policy.
• The script will display progress and status updates for each deletion operation.

• Depending on the number of participants, the deletion process may take some time. Please be patient.