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 the built-in fetch available in Node.js 18 or newer.

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 program'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 program 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 program 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 signUp = async (user) => {
  const response = await fetch(
    "https://api.growsurf.com/v2/campaign/4pdlhb/participant",
    {
      method: "POST",
      headers: {
        Authorization: "Bearer <YOUR_API_KEY>",
        "Content-Type": "application/json"
      },
      body: JSON.stringify(user)
    }
  );
  const body = await response.json();

  if (!response.ok) {
    throw new Error(body.message || `GrowSurf request failed (${response.status})`);
  }

  const growsurfId = body.id;

  // Save the new user to your database (optional).
  saveUser(user, growsurfId);
};

The response's id is saved as growsurfId.

saveUser(user, growsurfId) is an example function for saving the GrowSurf participant ID with the new user in your database. We use this growsurfId later to trigger a referral.

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

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

The user argument passed into signUp(user) is an object that looks like this:

{
  email: '[e-mail]',
  firstName: 'Gavin', // Optional participant name
  lastName: 'Belson', // Optional participant name
  ipAddress: '203.0.113.10', // Optional participant IP address
  fingerprint: 'dwah12iu3hi1u2h', // Optional browser identifier
  referredBy: '1cca8d', // The referrer's unique GrowSurf ID. Can also be the referrer's unique email address
  metadata: {
    phoneNumber: '[phone]',
    country: 'USA',
    zipCode: '94303'
  }
}

• firstName and lastName identify the participant and appear in referred friend motivator elements, if enabled.

• ipAddress records the participant IP address when available.

• fingerprint records a browser identifier when available. You can use a library like FingerprintJS to get this value.

• referredBy associates the new user with a referrer. It can be the referrer's email address or unique GrowSurf ID. You can use growsurf.getReferrerId() to retrieve the referrer ID.

• metadata saves a shallow object to the 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 program'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 purchase = async (growsurfId) => {
  // ...code that makes the purchase...

  const url = `https://api.growsurf.com/v2/campaign/4pdlhb/participant/${encodeURIComponent(growsurfId)}/ref`;
  const response = await fetch(url, {
    method: "POST",
    headers: {
      Authorization: "Bearer <YOUR_API_KEY>"
    }
  });
  const body = await response.json();

  if (!response.ok) {
    throw new Error(body.message || `GrowSurf request failed (${response.status})`);
  }

  const { success, message } = body;
  if (success) {
    console.log("Referral trigger success!");
  } else {
    console.log("Referral trigger failed:", message);
  }
};

The growsurfId argument is the participant's unique ID. You can use the participant's email instead.

Want to honor a refund or cancellation window?

You can hold the referral credit for a set number of days before it is awarded by including an optional delayInDays value (an integer between 1 and 90) in the request body of the POST Trigger referral call. If the purchase is refunded during that window, cancel the pending trigger with the DELETE Cancel delayed referral trigger method before the credit is awarded.

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 program'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 Notes:

• If your program is configured to add participants automatically through a form on your website (see image), skip this step.

• Make sure your program'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 program as a participant with the POST Add participant method.

The example below is what that code could look like.

Code Example

signup.js

const signUp = async (user) => {
  const response = await fetch(
    "https://api.growsurf.com/v2/campaign/4pdlhb/participant",
    {
      method: "POST",
      headers: {
        Authorization: "Bearer <YOUR_API_KEY>",
        "Content-Type": "application/json"
      },
      body: JSON.stringify(user)
    }
  );
  const body = await response.json();

  if (!response.ok) {
    throw new Error(body.message || `GrowSurf request failed (${response.status})`);
  }

  // Save the new user to your database (optional).
  saveUser(user, body.id);
};

The user argument passed into signUp(user) is an object that looks like this:

{
  email: '[e-mail]',
  firstName: 'Gavin', // Optional participant name
  lastName: 'Belson', // Optional participant name
  ipAddress: '203.0.113.10', // Optional participant IP address
  fingerprint: 'dwah12iu3hi1u2h', // Optional browser identifier
  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'
  }
}

• firstName and lastName identify the participant and appear in referred friend motivator elements, if enabled.

• ipAddress records the participant IP address when available.

• fingerprint records a browser identifier when available. You can use a library like FingerprintJS to get this value.

• referredBy associates the new user with a referrer. It can be the referrer's email address or unique GrowSurf ID. You can use growsurf.getReferrerId() to retrieve the referrer ID.

• referralStatus: "CREDIT_AWARDED" awards referral credit when the participant is added and overrides the program's configured referral trigger. It is ignored unless referredBy is also provided.

• metadata saves a shallow object to the 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, or rewards on your website or mobile app. Fetch a Participant; earned rewards are returned in its rewards array.

• 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 getUserDetails = async (userEmail) => {
  // ...Call your database to get user details...

  const url = `https://api.growsurf.com/v2/campaign/4pdlhb/participant/${encodeURIComponent(userEmail)}`;
  const response = await fetch(url, {
    headers: {
      Authorization: "Bearer <YOUR_API_KEY>"
    }
  });
  const body = await response.json();

  if (!response.ok) {
    throw new Error(body.message || `GrowSurf request failed (${response.status})`);
  }

  console.log(body);
};

console.log would print something like this:

{
    "id": "f8g9nl",
    "firstName": "Gavin",
    "lastName": "Belson",
    "referralCount": 2,
    "monthlyReferralCount": 1,
    "rank": 10001,
    "monthlyRank": 20001,
    "shareUrl": "https://piedpiper.com?grsf=f8g9nl",
    "rewards": [],
    "email": "[e-mail]",
    "createdAt": 1552404738928,
    "fraudRiskLevel": "LOW",
    "fraudReasonCode": "UNIQUE_IDENTITY",
    "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_IDENTITY",
        "isWinner": true,
        "shareCount": {
            "email": 20,
            "facebook": 11,
            "linkedin": 0,
            "pinterest": 3,
            "twitter": 12
        },
        "impressionCount": 14,
        "referrals": [
            "0dveu7",
            "f8g9nl",
            "j0hbym",
            "m5xm9l",
            "w01fil"
        ]
    }
}

shareUrl is omitted for affiliate program participants who are not approved affiliates.

Example 4: Delete a list of participants

To remove many participants at once, send them to the POST Bulk delete participants endpoint. One request deletes up to 200 participants, and each entry can be a participant ID or an email address. The response returns a per-row status for every entry, so you can see exactly which ones were removed.

Deleting a participant is permanent. It also removes that participant's referrals, rewards, commissions, and payout records.

Code Example (Node.js)

This example reads emails from a CSV, splits them into batches of 200, and deletes each batch. Follow the steps below:

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

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

3. Run npm install csv-parser to install the one dependency. The script uses the built-in fetch, so you need Node.js 18 or newer.

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 csv = require("csv-parser");
const fs = require("fs");

const BATCH_SIZE = 200; // Max entries the bulk-delete endpoint accepts per request

// Reads emails.csv and returns the list of email addresses.
async function readEmails() {
  const emails = [];
  const reader = fs.createReadStream("emails.csv").pipe(csv());
  for await (const row of reader) {
    if (row["Email"]) {
      emails.push(row["Email"].trim());
    }
  }
  return emails;
}

// Deletes one batch of up to 200 participants and returns the API's report.
async function deleteBatch(participants) {
  const url = `https://api.growsurf.com/v2/campaign/${CAMPAIGN_ID}/participants/bulk-delete`;
  const response = await fetch(url, {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${API_KEY}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({ participants })
  });
  const body = await response.json();
  if (!response.ok) {
    throw new Error(`Request failed (${response.status}): ${body.message || "unknown error"}`);
  }
  return body;
}

async function main() {
  const emails = await readEmails();
  console.log(`Deleting ${emails.length} participant(s) in batches of ${BATCH_SIZE}...`);

  for (let i = 0; i < emails.length; i += BATCH_SIZE) {
    const batch = emails.slice(i, i + BATCH_SIZE);
    const { summary, results } = await deleteBatch(batch);

    for (const row of results) {
      if (row.status === "DELETED") {
        console.log(`✅ ${row.identifier} deleted`);
      } else {
        console.log(`⚠️  ${row.identifier} (${row.status}): ${row.message}`);
      }
    }
    console.log(
      `Batch done: ${summary.deletedCount} deleted, ${summary.notFoundCount} not found, ` +
      `${summary.duplicateCount} duplicate, ${summary.errorCount} error`
    );
  }
}

main();

emails.csv

emails.csv

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

Some other notes:

• Each request replaces up to 200 individual delete calls, so you are far less likely to hit the rate limit. For very large lists, add a short pause between batches.

• A 200 response does not mean every row was deleted. Check each row's status: DELETED, NOT_FOUND (no participant matched the ID or email), DUPLICATE (the entry resolves to the same participant as an earlier one in the batch), or ERROR (the lookup or deletion failed). The summary object totals each outcome.

• A single request can mix participant IDs and email addresses.