GrowSurf Docs
Help CenterSystem StatusContact SupportYour Dashboard →
  • Welcome
  • Getting Started for Web
    • Google Tag Manager
    • Participant Auto Authentication
  • Getting Started for Native Mobile
  • Developer Tools
    • Embeddable Elements
    • JavaScript SDK
      • Tutorials
      • Single Page Applications
      • API Reference
    • REST API
      • Tutorials
      • Objects
      • API Reference
      • API Guidelines
      • API Response Codes
    • Webhooks
      • Securing Your Webhooks (optional)
      • Examples
      • Events Reference
    • Metadata
  • Integrations
    • ActiveCampaign
      • Tutorials
    • Amplitude
    • AWeber
      • Tutorials
    • Brevo (formerly Sendinblue)
      • Tutorials
    • Cal.com
    • Calendly
    • Campaign Monitor
      • Tutorials
    • Chargebee
    • Constant Contact
      • Tutorials
    • ConvertKit
      • Tutorials
    • Customer.io
      • Tutorials
    • Drip
      • Tutorials
    • EmailOctopus
      • Tutorials
    • Fullstory
    • GetResponse
      • Tutorials
    • Google Ads
    • Google Analytics
    • Heap
    • Help Scout
    • HubSpot
      • Tutorials
    • Intercom
      • Tutorials
    • Klaviyo
      • Tutorials
    • LinkedIn Ads
    • Mailchimp
      • Tutorials
    • MailerLite
      • Tutorials
    • Mailjet
      • Tutorials
    • Make
      • Tutorials
    • Marketo
      • Tutorials
    • Meta (Facebook) Ads
    • Mixpanel
    • Pabbly Connect
      • Tutorials
    • PayPal
    • Pendo
    • PostHog
    • Recurly
    • Salesforce
      • Tutorials
    • Segment
    • SendGrid
      • Tutorials
    • Slack
    • Stripe
    • Tango Card
    • Typeform
    • X (Twitter) Ads
    • Zapier
      • Tutorials
      • Using Filters
      • Troubleshooting
Powered by GitBook
On this page
  • Add participant
  • Trigger referral
  • Get campaign
  • Get participant by email
  • Get participant by ID
  • Get referrer ID
  • Get participant ID
  • Get unread rewards count
  • Mark rewards as read
  • Initialize unread badge
  • Update social share message
  • Update email invite message
  • Log out
  • Initialize / Reinitialize GrowSurf
  • Open GrowSurf window
  • Close GrowSurf window
  • Subscribe to event

Was this helpful?

  1. Developer Tools
  2. JavaScript SDK

API Reference

This reference documents the GrowSurf JavaScript SDK, including all available public methods and examples of each.

Last updated 21 days ago

Was this helpful?

Add participant

Adds a participant to the referral campaign. Use this method for the following use-cases:

  • Add referral tracking to your current signup form. If a referral link was used, GrowSurf automatically submits the referrer ID behind the scenes. (We recommend adding only referred participants — view for more info)

  • Generate referral links for your signed-in users on the fly (or return existing data if they are an existing participant)

Tips: Though they are optional, we recommend passing in the fields firstName and lastName . These fields are used for anti-fraud purposes and they show up in referred friend motivator elements, if enabled. Behind the scenes, this method also passes in other properties like IP address and fingerprint, which will also be used for anti-fraud purposes.

Note: A 401 error will be returned if the following conditions are met: (1) the campaign has participant authentication enabled, (2) there is no authentication cookie present on the participant's browser, (3) the given email is the same as an existing participant.

growsurf.addParticipant(data, callback);

Parameter

Data Type

Description

data

String or Object

(Required) A String containing the participant email or an Object containing the participant email and any other data to include for the participant.

callback

Function

(Optional) A callback function that will be invoked with the added participant data if successful.

Returns a that resolves with an containing limited participant data.

Example use

// Email only using a Callback
growsurf.addParticipant('gavin@hooli.com', (participant) => {
  // handle participant
});

// Object using a Callback
growsurf.addParticipant({
  email: 'gavin@hooli.com', 
  firstName: 'Gavin', // optional, but recommended for anti-fraud purposes
  lastName: 'Belson', // optional, but recommended for anti-fraud purposes
  company: 'Hooli, Inc', // Fields that are not email, firstName, or lastName will be saved as custom metadata
  companySize: 10000 // Fields that are not email, firstName, or lastName will be saved as custom metadata
}, (participant) => {
  // handle participant
});
// Email only using a Promise
growsurf.addParticipant('gavin@hooli.com').then(participant => {
  // handle participant
});

// Object using a Promise
growsurf.addParticipant({
  email: 'gavin@hooli.com', 
  firstName: 'Gavin', // optional, but recommended for anti-fraud purposes
  lastName: 'Belson', // optional, but recommended for anti-fraud purposes
  company: 'Hooli, Inc', // Fields that are not email, firstName, or lastName will be saved as custom metadata
  companySize: 10000 // Fields that are not email, firstName, or lastName will be saved as custom metadata
}).then(participant => {
  // handle participant
});

Example response

{
    "id": "kafewp",
    "firstName": "Gavin",
    "lastName": "Belson",
    "referralCount": 0,
    "monthlyReferralCount": 0,
    "shareUrl": "https://piedpiper.com?grsf=gavin-kafewp",
    "rewards": [],
    "vanityKeys": [
        "gavin-kafewp"
    ]
}

Trigger referral

Triggers a referral, awarding referral credit to the referrer of an existing or new participant. If the campaign participant does not exist, they will be newly added.

Note: A 401 error will be returned but the referral will still be triggered if the following conditions are met: (1) the campaign has participant authentication enabled, (2) there is no authentication cookie present on the participant's browser, (3) the given email is the same as an existing participant.

growsurf.triggerReferral(data, callback);

Parameter

Data Type

Description

data

String or Object

(Optional) A String containing the participant email or an Object containing the participant email and any other data to include for the participant.

callback

Function

(Optional) A callback function that will be invoked with the added or updated participant data if successful.

Example use

// Email only using a Callback
growsurf.triggerReferral('gavin@hooli.com', (participant) => {
  // handle participant
});

// Object using a Callback
growsurf.triggerReferral({
  email: 'gavin@hooli.com', 
  firstName: 'Gavin', // optional, but recommended for anti-fraud purposes
  lastName: 'Belson', // optional, but recommended for anti-fraud purposes
  company: 'Hooli, Inc', // Fields that are not email, firstName, or lastName will be saved as custom metadata
  companySize: 10000 // Fields that are not email, firstName, or lastName will be saved as custom metadata
}, (participant) => {
  // handle participant
});
// Email only using a Promise
growsurf.triggerReferral('gavin@hooli.com').then(participant => {
  // handle participant
});

// Object using a Promise
growsurf.triggerReferral({
  email: 'gavin@hooli.com', 
  firstName: 'Gavin', 
  lastName: 'Belson',
  company: 'Hooli, Inc',
  companySize: 10000
}).then(participant => {
  // handle participant
});

Example response

{
    "id": "kafewp",
    "firstName": "Gavin",
    "lastName": "Belson",
    "referralCount": 0,
    "shareUrl": "https://piedpiper.com?grsf=gavin-kafewp",
    "rewards": [],
    "vanityKeys" [
        "gavin-kafewp"
    ]
}

Get campaign

Retrieves limited details of a campaign.

growsurf.getCampaign(callback);

Parameter

Data Type

Description

callback

Function

(Optional) A callback function that will be invoked with the campaign data.

Example use

// Using a Callback
growsurf.getCampaign((campaign) => {
    // Handle Campaign
    console.log(campaign);
});
// Using a Promise
growsurf.getCampaign().then(campaign =>  {
    // Handle Campaign
    console.log(campaign);    
});

Example response

{
    "id": "bpsxg4",
    "rewards": [
        {
            "id": "xyz789",
            "type": "DOUBLE_SIDED",
            "description": "Refer a friend and get $20",
            "referralDescription": "Sign up and get $10 off your first invoice",
            "isUnlimited": false,
            "limit": 1,
            "conversionsRequired": 1,
            "numberOfWinners": 3,
            "imageUrl": "http://res.cloudinary.com/growsurf/image/upload/v1552764861/development/hxdcjrayfhksvxu5u6oz.png",
            "metadata": {
                "rewardValueForReferrer": 20,
                "rewardValueForReferred": 10     
            }
        }    
    ]
}

Get participant by email

Retrieves limited details of an existing participant. You will need to supply the unique email of the participant.

Note: A 403 error will be returned if the following conditions are met: (1) the campaign has participant authentication enabled, (2) there is no authentication cookie present on the participant's browser.

growsurf.getParticipantByEmail(participantEmail, callback);

Parameter

Data Type

Description

participantEmail

String

(Required) The email of the participant to retrieve.

callback

Function

(Optional) A callback function that will be invoked with the participant data if successful or undefined if the participant does not exist.

Example use

// Using a callback
growsurf.getParticipantByEmail('gavin@hooli.com', (participant) => {
    // Handle participant data
});
// Using a promise
growsurf.getParticipantByEmail('gavin@hooli.com').then(participant => {
    // Handle participant data
});

Example response

{
    "id": "kafewp",
    "firstName": "Gavin",
    "lastName": "Belson",
    "referralCount": 0,
    "monthlyReferralCount": 0,
    "shareUrl": "https://piedpiper.com?grsf=gavin-kafewp",
    "rewards": [],
    "vanityKeys" [
        "gavin-kafewp"
    ]
}

Get participant by ID

Retrieves limited details of an existing participant. You will need to supply the GrowSurf unique identifier that was returned upon participant creation.

Note: A 403 error will be returned if the following conditions are met: (1) the campaign has participant authentication enabled, (2) there is no authentication cookie present on the participant's browser.

growsurf.getParticipantById(participantId, callback);

Parameter

Data Type

Description

participantId

String

(Required) The GrowSurf identifier of the participant to retrieve.

callback

Function

(Optional) A callback function that will be invoked with the participant data if successful or undefined if the participant does not exist.

Example use

// Using a Callback
growsurf.getParticipantById('kafewp', (participant) => {
    // Handle participant data
});
// Using a promise
growsurf.getParticipantById('kafewp').then(participant => {
    // Handle participant data
});

Example response

{
    "id": "kafewp",
    "firstName": "Gavin",
    "lastName": "Belson",
    "referralCount": 0,
    "monthlyReferralCount": 0,
    "shareUrl": "https://piedpiper.com?grsf=gavin-kafewp",
    "rewards": [],
    "vanityKeys" [
        "gavin-kafewp"
    ]
}

Get referrer ID

Returns the ID of the participant that referred the visitor or null if the visitor was not referred. This method will first check to see if a grsf URL parameter exists, then will check for the presence of a referrer ID as a browser cookie (which was set from the initial visit).

Example: Someone refers their friend, and the friend visits http://yoursite.com?grsf=1h97da. Calling this method will return 1h97da (which is the referrer ID).

growsurf.getReferrerId();

Example use

growsurf.getReferrerId();

Example response

"1h97da"

Get participant ID

Returns the ID of the authenticated participant or null if there is no participant authentication cookie present.

Example: Someone signed up as a participant in your referral program from your website. Calling this method will return aj7auu1 (which is the participant ID).

growsurf.getParticipantId();

Example use

growsurf.getParticipantId();

Example response

"aj7auu1"

Get unread rewards count

Returns the number of unread rewards of the authenticated participant or null if there is no participant authentication cookie present. This method is useful for highlighting an unread badge to your users from within your own user portal.

growsurf.getUnreadRewardsCount();

Example use

growsurf.getUnreadRewardsCount();

Example response

2

Mark rewards as read

growsurf.markRewardsAsRead();

Example use

// Using a Callback
growsurf.markRewardsAsRead(response => {
  // handle success response
});
// Using a Promise
growsurf.markRewardsAsRead().then(response => {
  // handle success response
});

Example response

{
    "success": true
}

Initialize unread badge

This method will inject an unread badge onto a target element.

This method is useful for highlighting an unread badge to your users from within your own user portal.

If a participant cookie doesn't exist, the badge will not be displayed on the target element.

growsurf.initUnreadRewardsBadge(targetElement);

Parameter

Data Type

Description

targetElement

String

(Required) The target element

Example: .my-button

Example use

<a class="my-button">
  Refer and Earn
</a>

<script>
  growsurf.initUnreadRewardsBadge('.my-button');
</script>

CSS Alternative:

Instead of using the JavaScript method growsurf.initUnreadRewardsBadge(), you can simply add a CSS class growsurf-unread-rewards-badge to your target element. This will also inject the unread badge without requiring JavaScript. Here is an example:

<a href="/refer"
   class="my-button growsurf-unread-rewards-badge">
  Refer and Earn
</a>

Update social share message

Updates the pre-populated social share message for the given share type (e.g, email, Facebook, Twitter). This method will update all social share buttons in GrowSurf embedded elements and the GrowSurf window.

growsurf.updateSocialShareMessage(type, message, subjectLine);

Parameter

Data Type

Description

type

String

(Required) The social share type to update.

These are the options:

  • email

  • facebook

  • twitter

  • threads

  • bluesky

  • pinterest

  • sms

  • whatsapp

  • reddit

  • tumblr

message

String

(Required) The new pre-populated social share message.

Use {{shareUrl}} to reference the participant's referral link.

subjectLine

String

(Optional) The new pre-populated subject line (only applies when type is email).

Use {{shareUrl}} to reference the participant's referral link.

Example use

const message = "I have saved 1,540 hours using this service. Highly recommend! {{shareUrl}}";
const subjectLine = "Check this out!";

// Update the pre-populated email social share message
growsurf.updateSocialShareMessage('email', message, subjectLine);

// Update the pre-populated Facebook social share message
growsurf.updateSocialShareMessage('facebook', message);

// Update the pre-populated Twitter social share message
growsurf.updateSocialShareMessage('twitter', message);

// Update the pre-populated Threads social share message
growsurf.updateSocialShareMessage('threads', message);

// Update the pre-populated Bluesky social share message
growsurf.updateSocialShareMessage('bluesky', message);

// Update the pre-populated Pinterest social share message
growsurf.updateSocialShareMessage('pinterest', message);

// Update the pre-populated SMS social share message
growsurf.updateSocialShareMessage('sms', message);

// Update the pre-populated WhatsApp social share message
growsurf.updateSocialShareMessage('whatsapp', message);

// Update the pre-populated Reddit social share message
growsurf.updateSocialShareMessage('reddit', message);

// Update the pre-populated Tumblr social share message
growsurf.updateSocialShareMessage('tumblr', message);

Update email invite message

growsurf.updateEmailInviteMessage(message, subjectLine);

Parameter

Data Type

Description

message

String

(Required) The new pre-populated email invite message.

Use {{shareUrl}} to reference the participant's referral link.

subjectLine

String

(Optional) The new pre-populated subject line.

Use {{shareUrl}} to reference the participant's referral link.

Example use

const message = "I have saved 1,540 hours using this service. Highly recommend! {{shareUrl}}";
const subjectLine = "Check this out!";

// Update the pre-populated email invite message and subject line
growsurf.updateEmailInviteMessage(message, subjectLine);

Log out

Logs the participant out of the browser (clears the participant's GrowSurf browser cookie and local storage).

growsurf.logout();

Example use

growsurf.logout();

Initialize / Reinitialize GrowSurf

Initializes or reinitializes the window.growsurf Object.

The method is useful for the following use-cases:

growsurf.init(settings);

Example use

// Using a Callback
growsurf.init({ email: "participant@email.com", hash: "HASH_VALUE" }, () => {
    // GrowSurf is Ready
});
// Using a promise
growsurf.init({ email: "participant@email.com", hash: "HASH_VALUE" }).then(() => {
    // GrowSurf is Ready
});

Parameter

Data Type

Description

settings

Object

(Optional) The settings GrowSurf should use when initializing or reinitializing.

  • campaignId- Provide this to initialize another campaign

Open GrowSurf window

Opens the GrowSurf window.

growsurf.open(callback);

Parameter

Data Type

Description

callback

Function

(Optional) A callback function that will be invoked once complete

Example use

// Using a Callback
growsurf.open(function() {
    // Do something here
});
// Using a Promise
growsurf.open().then(() => {
    // Do something here
});

CSS Alternative:

Instead of using the JavaScript method growsurf.open(), you can simply add a CSS class growsurf-open-window to a button.

A benefit of this option is that if the participant has any unread rewards, the unread badge will automatically show up as well. Here is an example:

<a class="growsurf-open-window">
  Refer and Earn
</a>

Close GrowSurf window

Closes the GrowSurf window.

growsurf.close(callback);

Parameter

Data Type

Description

callback

Function

(Optional) A callback function that will be invoked once complete

Example use

// Using a Callback
growsurf.close(() => {
    // Do something here
});
// Using a Promise
growsurf.close().then(() => {
    // Do something here
});

Subscribe to event

Adds an event subscription of the given event type. When an event of the given type occurs, the given callback will be invoked. Below are detailed descriptions of each event type.

growsurf.subscribe(eventType, callback);

Parameter

Data Type

Description

eventType

String

(Required) The event type to subscribe to.

These are the options:

  • referral

  • referralTrigger

  • signup

  • share

  • invite

callback

Function

The callback function that will be invoked when the event occurs.

Example use

/**
 * REFERRED FRIEND EVENTS
 */ 

// Subscribe to a `referral` event type
growsurf.subscribe('referral', (participant) => {
  // A new participant was referred
});

// Subscribe to a `referralTrigger` event type
growsurf.subscribe('referralTrigger', (participant) => {
  // A referred participant triggered a referral (AKA they completed the qualifying action)
});


/**
 * REFERRER EVENTS
 */ 

// Subscribe to a `signup` event type
growsurf.subscribe('signup', (participant) => {
  // A new participant was added (only non-referred signups)
});

// Subscribe to a `share` event type
growsurf.subscribe('share', (data) => {
  // A participant shared their unique referral URL by clicking a social share button
});

// Subscribe to an `invite` event type
growsurf.subscribe('invite', (participant) => {
  // A participant sent out an invite
});

Example response

Dispatched anytime an event happens. The provided callback will be invoked with an Object containing data relevant to the event.

The 'referral' event returns limited data of the new referred participant. The referredBy key represents the referring participant's unique ID.

{
    "id": "kafewp",
    "email": "gavin@hooli.com",
    "firstName": "Gavin",
    "lastName": "Belson",
    "referredBy": "xyz789",
    "referralCount": 0,
    "shareUrl": "https://piedpiper.com?grsf=kafewp",
    "rewards": [],
    "campaign": {
       "id": "abc123"
    }
}

The 'referralTrigger' Event returns limited data of the referred participant that triggered a referral (which means they completed a qualifying action).

{
    "id": "kafewp",
    "email": "gavin@hooli.com",
    "firstName": "Gavin",
    "lastName": "Belson",
    "referralCount": 0,
    "shareUrl": "https://piedpiper.com?grsf=kafewp",
    "rewards": [],
    "campaign": {
       "id": "abc123"
    }    
}

The 'signup' Event returns limited data of the new non-referred participant.

{
    "id": "kafewp",
    "email": "gavin@hooli.com",
    "firstName": "Gavin",
    "lastName": "Belson",
    "referralCount": 0,
    "shareUrl": "https://piedpiper.com?grsf=kafewp",
    "rewards": [],
    "campaign": {
       "id": "abc123"
    }    
}

The 'share' Event returns limited data of the participant and the share type.

The shareType value will either be a social network (e.g., linkedin, reddit) or copyLink if the participant copied their link to share (e.g., they clicked "Copy Link").

{
    "participant": {
        "id": "kafewp",
        "email": "gavin@hooli.com",
        "firstName": "Gavin",
        "lastName": "Belson",
        "referralCount": 0,
        "shareUrl": "https://piedpiper.com?grsf=kafewp",
        "rewards": []
    },
    "shareType": "facebook",
    "campaign": {
       "id": "abc123"
    }    
}

The 'invite' Event returns limited data of the participant and the number of invites sent.

{
    "participant": {
        "id": "kafewp",
        "email": "gavin@hooli.com",
        "firstName": "Gavin",
        "lastName": "Belson",
        "referralCount": 0,
        "shareUrl": "https://piedpiper.com?grsf=kafewp",
        "rewards": []
    },
    "invitesAttempted": 3,
    "invitesSent": 3,
    "campaign": {
       "id": "abc123"
    }    
}

If providing an Object, any Object keys other than email, firstName, lastName , and gdprAgreements will be treated as by GrowSurf. For more information about metadata please see our .

If providing an Object, any Object keys other than email, firstName, and lastName will be treated as by GrowSurf.

*This parameter is only optional if the participant has already signed up for the campaign and GrowSurf is able to determine they are a participant (does not include participants imported or manually added using the dashboard). For more information about metadata please see our .

Returns a that resolves with an containing limited participant data.

Returns a that resolves with an containing limited campaign data of id and rewards.

Returns a that resolves with an containing the participant data. If the participant does not exist in the campaign, then undefined is returned.

Returns a that resolves with an containing the participant data. If the participant does not exist in the campaign, then undefined is returned.

Note: You can verify that the referrer ID is valid by calling

Alternatively, you can use the method for displaying the unread rewards count as a badge on a target element.

Mark unread rewards of the authenticated participant. This method is useful if you are using instead of the GrowSurf window to show your users their unread reward count and want to clear out the unread badge.

Returns a that resolves with an with a success response.

We recommend that the target element be a button that opens the GrowSurf window (via ), because the unread badge will be cleared when the participant views the "My Rewards" section in the GrowSurf window. Alternatively, you can use to clear the unread badge.

Note: You'll need to make sure you have the installed.

Example: This method is useful for optimizing referral asks when your participants complete an "". You would present your participant with the element and then call this method to update social share message(s) to be specific to the "aha moment". See for an example.

Updates the pre-populated email invite message. This method will only apply updates to elements (the email invite section within the GrowSurf window will not be updated).

Example: This method is useful for optimizing referral asks when your participants complete an "". You would present your participant with the element and then call this method to update the email invite message to be specific to the "aha moment". See for an example.

If you have participant authentication enabled for your campaign and you would like to your participants after they log in within your own user portal.

Load multiple campaigns on a single webpage depending on where the traffic is coming from. .

email- The email of the participant you wish to (only applies if authentication is enabled for your campaign).

hash- The hash token generated by your server. Used to a participant (only applies if authentication is enabled for your campaign).

Returns a that resolves once complete.

Note: You'll need to make sure you have the installed.

Returns a that resolves once complete.

Note: This event happens when calling . If you are looking for the referred signup event, use the 'referral' Event that contains a referredBy property.

If your campaign is set up for email invites to be sent by participants, invitesAttempted will always match invitesSent. If email invites are sent by your company, invitesSent will only count successfully delivered emails confirmed by our server. .

this tutorial
Promise
Object
Promise
Object
Promise
Object
Promise
Object
Promise
Object
growsurf.getParticipantById()
growsurf.initUnreadRewardsBadge()
growsurf.initUnreadRewardsBadge()
Promise
Object
growsurf.open()
growsurf.markRewardsAsRead()
GrowSurf Universal Code
aha moment
GrowSurf Embedded Form
this tutorial
GrowSurf Embedded Invite
aha moment
GrowSurf Embedded Invite
this tutorial
automatically authenticate
View a tutorial here
Promise
GrowSurf Universal Code
Promise
growsurf.triggerReferral()
Learn more here
auto authenticate
auto authenticate
API Guidelines
metadata
metadata
API Guidelines
The unread badge will be injected into your target element