Tutorials
How to implement the GrowSurf REST API in common use-case scenarios.
The following examples use Node.js.
"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.
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.At line 11, the
user
argument passed into signUp(user)
is an Object that looks like this:{
email: '[email protected]',
firstName: 'Sally',
lastName: 'Mayweathers',
referredBy: '1cca8d', // The referrer's unique GrowSurf ID. Can also be the referrer's unique email address
metadata: {
phoneNumber: '+1 415-123-4567',
country: 'USA',
zipCode: '94303'
}
}
- At line 5, 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 usegrowsurf.getReferrerId()
to retrieve the referrer ID). - At line 6, 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).
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."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.
Important Note: If your campaign is configured to add participants automatically through a form on your website (see image), skip this step.
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: '[email protected]',
firstName: 'Sally',
lastName: 'Mayweathers',
referredBy: '1cca8d', // The referrer's unique GrowSurf ID. Can also be the referrer's unique email address
referralStatus: 'CREDIT_AWARDED',
metadata: {
phoneNumber: '+1 415-123-4567',
country: 'USA',
zipCode: '94303'
}
}
- At line 5, 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 usegrowsurf.getReferrerId()
to retrieve the referrer ID) - At line 6, we set
referralStatus
to beCREDIT_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 withreferredBy
, or else it will be ignored.
- 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).
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
Participant
s and ParticipantReward
s by using either of the following API methods: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": "[email protected]",
"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": "[email protected]",
"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"
]
}
}
Last modified 1yr ago