API Reference
This reference documents the GrowSurf JavaScript SDK, including all available public methods and examples of each.
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 this tutorial for more info)
Generate referral links for your signed-in users on the fly (or return existing data if they are an existing participant)
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.
If providing an Object, any Object keys other than email
, firstName
, lastName
, and gdprAgreements
will be treated as metadata
by GrowSurf.
For more information about metadata please see our API Guidelines.
callback
Function
(Optional) A callback function that will be invoked with the added participant data if successful.
Returns a Promise that resolves with an Object containing limited participant data.
Example use
// Email only using a Callback
growsurf.addParticipant('[email protected]', (participant) => {
// handle participant
});
// Object using a Callback
growsurf.addParticipant({
email: '[email protected]',
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
});
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.
If providing an Object, any Object keys other than email
, firstName
, and lastName
will be treated as metadata
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 API Guidelines.
callback
Function
(Optional) A callback function that will be invoked with the added or updated participant data if successful.
Returns a Promise that resolves with an Object containing limited participant data.
Example use
// Email only using a Callback
growsurf.triggerReferral('[email protected]', (participant) => {
// handle participant
});
// Object using a Callback
growsurf.triggerReferral({
email: '[email protected]',
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
});
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.
Returns a Promise that resolves with an Object containing limited campaign data of id
and rewards
.
Example use
// Using a Callback
growsurf.getCampaign((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.
Returns a Promise that resolves with an Object containing the participant data. If the participant does not exist in the campaign, then undefined
is returned.
Example use
// Using a callback
growsurf.getParticipantByEmail('[email protected]', (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.
Returns a Promise that resolves with an Object containing the participant data. If the participant does not exist in the campaign, then undefined
is returned.
Example use
// Using a Callback
growsurf.getParticipantById('kafewp', (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).
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.
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
Mark unread rewards of the authenticated participant. This method is useful if you are using growsurf.initUnreadRewardsBadge()
instead of the GrowSurf window to show your users their unread reward count and want to clear out the unread badge.
growsurf.markRewardsAsRead();
Returns a Promise that resolves with an Object with a success response.
Example use
// Using a Callback
growsurf.markRewardsAsRead(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.
We recommend that the target element be a button that opens the GrowSurf window (via growsurf.open()
), because the unread badge will be cleared when the participant views the "My Rewards" section in the GrowSurf window. Alternatively, you can use growsurf.markRewardsAsRead()
to clear the unread badge.
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>
Note: You'll need to make sure you have the GrowSurf Universal Code installed.
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
Updates the pre-populated email invite message. This method will only apply updates to GrowSurf Embedded Invite elements (the email invite section within the GrowSurf window will not be updated).
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.
growsurf.init(settings);
Example use
// Using a Callback
growsurf.init({ email: "[email protected]", hash: "HASH_VALUE" }, () => {
// 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 campaignemail
- The email of the participant you wish to auto authenticate (only applies if authentication is enabled for your campaign).hash
- The hash token generated by your server. Used to auto authenticate a participant (only applies if authentication is enabled for your 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
Returns a Promise that resolves once complete.
Example use
// Using a Callback
growsurf.open(function() {
// 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>
Note: You'll need to make sure you have the GrowSurf Universal Code installed.
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
Returns a Promise that resolves once complete.
Example use
// Using a Callback
growsurf.close(() => {
// 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": "[email protected]",
"firstName": "Gavin",
"lastName": "Belson",
"referredBy": "xyz789",
"referralCount": 0,
"shareUrl": "https://piedpiper.com?grsf=kafewp",
"rewards": [],
"campaign": {
"id": "abc123"
}
}
Last updated
Was this helpful?