API Reference

This reference documents the GrowSurf JavaScript Web API, 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 (GrowSurf uses cookies to detect if a referral link was used)

• 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, and lastName 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

Using Callbacks

// Email only using a Callback
growsurf.addParticipant('[e-mail]', (participant) => {
  // handle participant
});

// Object using a Callback
growsurf.addParticipant({
  email: '[e-mail]', 
  firstName: 'Gavin', 
  lastName: 'Belson',
  company: 'Hooli, Inc',
  companySize: 10000
}, (participant) => {
  // handle participant
});

Using Promises

// Email only using a Promise
growsurf.addParticipant('[e-mail]').then(participant => {
  // handle participant
});

// Object using a Promise
growsurf.addParticipant({
  email: '[e-mail]', 
  firstName: 'Gavin', 
  lastName: 'Belson',
  company: 'Hooli, Inc',
  companySize: 10000
}).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. 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

Using Callbacks

// Email only using a Callback
growsurf.triggerReferral('[e-mail]', (participant) => {
  // handle participant
});

// Object using a Callback
growsurf.triggerReferral({
  email: '[e-mail]', 
  firstName: 'Gavin', 
  lastName: 'Belson',
  company: 'Hooli, Inc',
  companySize: 10000  
}, (participant) => {
  // handle participant
});

Using Promises

// Email only using a Promise
growsurf.triggerReferral('[e-mail]').then(participant => {
  // handle participant
});

// Object using a Promise
growsurf.triggerReferral({
  email: '[e-mail]', 
  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.

Returns a Promise that resolves with an Object containing limited campaign data.

Example use

Using Callbacks

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

Using Promises

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

Example response

{
    id: "bpsxg4"
}

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 Callbacks

// Using a callback
growsurf.getParticipantByEmail('[e-mail]', (participant) => {
    // Handle participant data
});

Using Promises

// Using a promise
growsurf.getParticipantByEmail('[e-mail]').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.

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 Callbacks

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

Using Promises

// 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"

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.

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

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 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 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).

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

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 (clear's 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 if you have set participant authentication as required for your campaign and you would like to automatically authenticate your participants after they log in.

growsurf.init(settings);

Example use

Using Callbacks

// Using a Callback
growsurf.init({ email: "[e-mail]", hash: "HASH_VALUE" }, () => {
    // GrowSurf is Ready
});

Using Promises

// Using a promise
growsurf.init({ email: "[e-mail]", 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 email- 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 Callbacks

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

Using Promises

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

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 Callbacks

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

Using Promises

// 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: signup share referral invite
callback	Function	The callback function that will be invoked when the event occurs.

Example use

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

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

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

// 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.

'signup' Event

The 'signup' Event returns limited data of the newly added participant.

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

'share' Event

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

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

'referral' Event

The 'referral' Event returns limited data of the newly referred participant.

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

'invite' Event

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

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