API Reference
This reference documents the GrowSurf REST API, including all available public methods and examples of each.
Open in Postman
Easily test these API methods dynamically by using our Postman Collection. Just change the Token in the Authorizations tab, and the campaign_id variable to the campaign you're working on.
CAMPAIGNS ↓
Get Campaign
GET https://api.growsurf.com/v2/campaign/:id
Retrieves a campaign for the given ID.
Path Parameters
id*
string
The ID of the campaign to retrieve
{
"id": "abc123",
"name": "Middle Out Compression Campaign",
"referralCount": 121,
"participantCount": 199,
"impressionCount": 199,
"inviteCount": 237,
"winnerCount": 1,
"status": "IN_PROGRESS",
"rewards": [
{
"id": "xyz789",
"type": "DOUBLE_SIDED",
"description": "Refer a friend and get a Pied Piper T-Shirt",
"referralDescription": "Join and receive middle out compression algorithm",
"isUnlimited": false,
"limit": 1,
"conversionsRequired": 1,
"numberOfWinners": 3,
"imageUrl": "http://res.cloudinary.com/growsurf/image/upload/v1552764861/development/hxdcjrayfhksvxu5u6oz.png"
}
]
}Get Campaigns
GET https://api.growsurf.com/v2/campaigns
Retrieves a list of your campaigns. Campaigns that have been deleted will not be returned in this response.
{
"campaigns": [
{
"id": "abc123",
"name": "Middle Out Compression Campaign",
"referralCount": 20500,
"participantCount": 40000,
"impressionCount": 100000,
"winnerCount": 1500,
"inviteCount": 100,
"status": "IN_PROGRESS",
"rewards": [
{
"id": "xyz789",
"type": "DOUBLE_SIDED",
"description": "Refer a friend and get a Pied Piper T-Shirt",
"referralDescription": "Join and receive middle out compression algorithm",
"isUnlimited": false,
"limit": 1,
"conversionsRequired": 1,
"numberOfWinners": 3,
"imageUrl": "http://res.cloudinary.com/growsurf/image/upload/v1552764861/development/hxdcjrayfhksvxu5u6oz.png"
}
]
},
{
"id": "ljtqn5",
"name": "Monthly Newsletter Referral Campaign",
"referralCount": 30500,
"participantCount": 60000,
"impressionCount": 110000,
"winnerCount": 750,
"inviteCount": 25,
"status": "IN_PROGRESS",
"rewards": [
{
"id": "qiar1r",
"type": "SINGLE_SIDED",
"description": "First 3 referrers receive one month free.",
"isUnlimited": false,
"limit": 1,
"conversionsRequired": 1,
"numberOfWinners": 3,
"imageUrl": "https://res.cloudinary.com/growsurf/image/upload/v1593807417/development/wg7xzingezfbmrh7zg7m.png"
}
]
}
]
}PARTICIPANTS ↓
Get Participant by ID
GET https://api.growsurf.com/v2/campaign/:id/participant/:participantId
Retrieves a single participant from a campaign using the given participant ID.
Path Parameters
id*
string
The ID of the campaign to retrieve the participant from
participantId*
string
The ID of the participant to retrieve
{
"id": "f8g9nl",
"firstName": "Gavin",
"lastName": "Belson",
"referralCount": 2,
"monthlyReferralCount": 2,
"prevMonthlyReferralCount": 0,
"rank": 10001,
"monthlyRank": 20001,
"monthlyRank": -1,
"shareUrl": "https://piedpiper.com?grsf=gavin-f8g9nl",
"email": "[email protected]",
"createdAt": 1552404738928,
"fraudRiskLevel": "LOW",
"fraudReasonCode": "UNIQUE_IDENTIY",
"isWinner": true,
"shareCount": {
"email": 10,
"facebook": 1,
"pinterest": 1,
"twitter": 11
},
"impressionCount": 2,
"uniqueImpressionCount": 2,
"inviteCount": 3,
"referrals": [
"i9g2bh",
"xua4sq"
],
"monthlyReferrals": [
"i9g2bh",
"xua4sq"
],
"referralSource": "PARTICIPANT",
"referralStatus": "CREDIT_AWARDED",
"referrer": {
"id": "h8kp6l",
"firstName": "Richard",
"lastName": "Hendricks",
"referralCount": 5,
"monthlyReferralCount": 2,
"prevMonthlyReferralCount": 100,
"rank": 100,
"monthlyRank": 110,
"prevMonthlyRank": 10,
"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,
"uniqueImpressionCount": 11,
"inviteCount": 12,
"referrals": [
"0dveu7",
"f8g9nl",
"j0hbym",
"m5xm9l",
"w01fil"
],
"monthlyReferrals": [
"m5xm9l",
"w01fil"
],
"ipAddress": "113.2.2.9",
"fingerprint": "dau221bd47ba661c51ca933d531e47f5",
"metadata": {},
"unsubscribed": false
},
"ipAddress": "127.0.0.1",
"fingerprint": "cfb163bd47ba666c52cb932c521e47f4",
"metadata": {
"company": "Hooli, Inc",
"companySize": 10000
},
"unsubscribed": false,
"rewards": [
{
"id": "dgaiuk",
"rewardId": "oe1cjt",
"status": "FULFILLED",
"unread": true,
"isReferrer": true,
"isAvailable": true,
"approved": true,
"isFulfilled": true
"referredId": "xh345d",
"referrerId": "f8g9nl"
}
]
"vanityKeys": [
"gavin-f8g9nl"
]
}Get Participant by Email
GET https://api.growsurf.com/v2/campaign/:id/participant/:participantEmail
Retrieves a single participant from a campaign using the given participant email.
Path Parameters
id*
string
The ID of the campaign to retrieve the participant from
participantEmail*
string
The email of the participant to retrieve
{
"id": "f8g9nl",
"firstName": "Gavin",
"lastName": "Belson",
"referralCount": 2,
"monthlyReferralCount": 2,
"prevMonthlyReferralCount": 0,
"rank": 10001,
"monthlyRank": 50,
"prevMonthlyRank": -1,
"shareUrl": "https://piedpiper.com?grsf=gavin-f8g9nl",
"email": "[email protected]",
"createdAt": 1552404738928,
"fraudRiskLevel": "LOW",
"fraudReasonCode": "UNIQUE_IDENTIY",
"isWinner": true,
"shareCount": {
"email": 10,
"facebook": 1,
"pinterest": 1,
"twitter": 11
},
"impressionCount": 2,
"uniqueImpressionCount": 2,
"inviteCount": 3,
"referrals": [
"i9g2bh",
"xua4sq"
],
"monthlyReferrals": [
"i9g2bh",
"xua4sq"
],
"referralSource": "PARTICIPANT",
"referralStatus": "CREDIT_AWARDED",
"referrer": {
"id": "h8kp6l",
"firstName": "Richard",
"lastName": "Hendricks",
"referralCount": 5,
"monthlyReferralCount": 2,
"prevMonthlyReferralCount": 100,
"rank": 100,
"monthlyRank": 110,
"prevMonthlyRank": 10,
"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,
"uniqueImpressionCount": 11,
"inviteCount": 12,
"referrals": [
"0dveu7",
"f8g9nl",
"j0hbym",
"m5xm9l",
"w01fil"
],
"monthlyReferrals": [
"m5xm9l",
"w01fil"
],
"ipAddress": "113.2.2.9",
"fingerprint": "dau221bd47ba661c51ca933d531e47f5",
"metadata": {},
"unsubscribed": false,
},
"ipAddress": "127.0.0.1",
"fingerprint": "cfb163bd47ba666c52cb932c521e47f4",
"metadata": {
"company": "Hooli, Inc",
"companySize": 10000
},
"unsubscribed": false,
"rewards": [
{
"id": "dgaiuk",
"rewardId": "oe1cjt",
"status": "FULFILLED",
"unread": true,
"isReferrer": true,
"isAvailable": true,
"approved": true,
"isFulfilled": true,
"referredId": "xh345d",
"referrerId": "f8g9nl"
}
],
"vanityKeys": [
"gavin-f8g9nl"
]
}Get Participants
GET https://api.growsurf.com/v2/campaign/:id/participants
Retrieves a list of participants in the campaign.
Path Parameters
id*
string
The ID of the campaign
Query Parameters
nextId
string
The ID of the participant to start the next result set with. This can be used to skip through the list or to page the list results. Each response will provide a nextId value if there are more participants otherwise the nextId value will be null.
limit
integer
The number of participants to return. Must be a value less than or equal to 100 which is currently the maximum we allow with this request.
{
"participants": [
{
"id": "3vxff9",
"firstName": "Gavin",
"lastName": "Belson",
"referralCount": 0,
"monthlyReferralCount": 0,
"prevMonthlyReferralCount": 0,
"rank": 10001,
"monthlyRank": 50,
"prevMonthlyRank": -1,
"shareUrl": "https://hoolie.com?grsf=gavin-3vxff9",
"rewards": [],
"email": "[email protected]",
"createdAt": 1558665537426,
"referralSource": "DIRECT",
"isWinner": false,
"shareCount": {
"email": 0,
"facebook": 0,
"linkedin": 0,
"pinterest": 0,
"twitter": 0
},
"impressionCount": 0,
"uniqueImpressionCount": 0,
"inviteCount": 3,
"referrals": [],
"referrer": null,
"metadata": {},
"rewards": [],
"vanityKeys": [
"gavin-3vxff9"
],
"metadata": {},
"unsubscribed": false,
},
{
"id": "f8g9nl",
"firstName": "Gavin",
"lastName": "Belson",
"referralCount": 2,
"monthlyReferralCount": 2,
"prevMonthlyReferralCount": 721,
"rank": 10002,
"monthlyRank": 110,
"prevMonthlyRank": 1,
"shareUrl": "https://piedpiper.com?grsf=gavin-f8g9nl",
"email": "[email protected]",
"createdAt": 1552404738928,
"fraudRiskLevel": "LOW",
"fraudReasonCode": "UNIQUE_IDENTIY",
"isWinner": true,
"shareCount": {
"email": 10,
"facebook": 1,
"pinterest": 1,
"twitter": 11
},
"impressionCount": 2,
"uniqueImpressionCount": 2,
"inviteCount": 3,
"referrals": [
"i9g2bh",
"xua4sq"
],
"referralSource": "PARTICIPANT",
"referralStatus": "CREDIT_AWARDED",
"referrer": {
"id": "h8kp6l",
"firstName": "Richard",
"lastName": "Hendricks",
"referralCount": 5,
"monthlyReferralCount": 5,
"prevMonthlyReferralCount": 100,
"rank": 100,
"monthlyRank": 100,
"prevMonthlyRank": 13,
"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,
"uniqueImpressionCount": 12,
"inviteCount": 12,
"referrals": [
"0dveu7",
"f8g9nl",
"j0hbym",
"m5xm9l",
"w01fil"
],
"metadata": {},
"unsubscribed": false,
},
"metadata": {},
"unsubscribed": false,
"rewards": [],
"vanityKeys": [
"gavin-f8g9nl"
]
}
],
"limit": 2,
"nextId": "1u7v0q"
}Get Leaderboard
GET https://api.growsurf.com/v2/campaign/:id/leaderboard
Retrieves a list of participants in the campaign ordered by referral count in ascending order.
Monthly Referral Count Leaderboard
You can retrieve the campaign leaderboard ordered by the monthly referral count by providing a query parameter leaderboardType with a value of CURRENT_MONTH. This will retrieve a list of participants ordered by monthly referral count.
Monthly referral counts are automatically reset at the end of each month for each participant within your campaign, therefore results of the monthly referral count may vary.
Previous Monthly Referral Count Leaderboard
Similar to the monthly campaign leaderboard, providing a query parameter of leaderboardType with a value of PREV_MONTH will retrieve a list of participants order by the previous monthly referral count.
Participants that did not exist within the campaign during the previous month will not be returned within the previous monthly leaderboard response.
Path Parameters
id*
string
The ID of the campaign
Query Parameters
nextId
string
The ID of the participant to start the next result set with. This can be used to skip through the list or to page the list of results. Each response will provide a nextId value if there are more participants otherwise, nextId will be null.
limit
string
The number of participants to return. Must be a value less than or equal to 100 and greater than 1. 100 is currently the maximum limit per reach request.
isMonthly
boolean
If true will return the leaderboard for monthly referral counts. Default is false.
Deprecated
This currently works but will be removed in future versions of the GrowSurf RESTful API. Please use leaderboardType instead.
leaderboardType
string
Returns the leaderboard for the specified type if provided.
Options
ALL_TIME - Returns the all-time leaderboard, based on all-time referral counts. Default
CURRENT_MONTH - Returns the current month's leaderboard, based on the current month's referral counts.
PREV_MONTH - Returns the previous month's leaderboard, based on the previous month's referral counts (With this option, participants that did not exist within the campaign during the previous month will not be returned).
TOTAL_IMPRESSION_COUNT - Returns the leaderboard based on total impression counts.
UNIQUE_IMPRESSION_COUNT - Returns the leaderboard based on unique impression counts.
{
"participants": [
{
"id": "3vxff9",
"firstName": "Gavin",
"lastName": "Belson",
"referralCount": 1000,
"monthlyReferralCount": 10,
"prevMonthlyReferralCount": 990,
"rank": 1,
"monthlyRank": 10,
"prevMonthlyRank": 10,
"shareUrl": "https://hoolie.com?grsf=gavin-3vxff9",
"rewards": [],
"email": "[email protected]",
"createdAt": 1558665537426,
"fraudRiskLevel": "LOW",
"fraudReasonCode": "UNIQUE_IDENTIY",
"referralSource": "DIRECT",
"isWinner": false,
"shareCount": {
"email": 0,
"facebook": 0,
"linkedin": 0,
"pinterest": 0,
"twitter": 0
},
"impressionCount": 0,
"uniqueImpressionCount": 0,
"inviteCount": 0,
"referrals": [],
"referrer": null,
"ipAddress": "127.0.0.1",
"fingerprint": "cfb163bd47ba666c52cb932c521e47f4",
"metadata": {},
"unsubscribed": false,
"rewards": [],
"vanityKeys": [
"gavin-3vxff9"
]
},
{
"id": "f8g9nl",
"firstName": "Gavin",
"lastName": "Belson",
"referralCount": 900,
"monthlyReferralCount": 9,
"prevMonthlyReferralCount": 800,
"rank": 2,
"monthlyRank": 11,
"prevMonthlyRank": 20,
"shareUrl": "https://piedpiper.com?grsf=gavin-f8g9nl",
"email": "[email protected]",
"createdAt": 1552404738928,
"fraudRiskLevel": "LOW",
"fraudReasonCode": "UNIQUE_IDENTIY",
"isWinner": true,
"shareCount": {
"email": 10,
"facebook": 1,
"pinterest": 1,
"twitter": 11
},
"impressionCount": 2,
"uniqueImpressionCount": 2,
"inviteCount": 2,
"referrals": [
"i9g2bh",
"xua4sq"
],
"referralSource": "PARTICIPANT",
"referralStatus": "CREDIT_AWARDED",
"referrer": {
"id": "h8kp6l",
"firstName": "Richard",
"lastName": "Hendricks",
"referralCount": 5,
"monthlyReferralCount": 0,
"prevMonthlyReferralCount": 0,
"rank": 100,
"monthlyRank": 100,
"prevMonthlyRank": 99,
"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,
"uniqueImpressionCount": 14,
"inviteCount": 14,
"ipAddress": "148.3.3.1",
"fingerprint": "p33a71bd661c547ba1ca933d997f51e9",
"metadata": {},
"unsubscribed": false,
"referrals": [
"0dveu7",
"f8g9nl",
"j0hbym",
"m5xm9l",
"w01fil"
]
},
"ipAddress": "113.2.2.9",
"fingerprint": "dau221bd47ba661c51ca933d531e47f5",
"metadata": {},
"unsubscribed": false,
"rewards": [],
"vanityKeys": [
"gavin-f8g9nl"
]
}
],
"limit": 2,
"nextId": "1u7v0q"
}Add Participant
POST https://api.growsurf.com/v2/campaign/:id/participant
Adds a new participant to the campaign.
If the participant with the same email address already exists, then the existing participant will be returned.
Path Parameters
id*
string
The ID of the campaign to add the new participant to
Request Body
email*
string
The email of the new participant
referredBy
string
Set a referrer for this participant by providing the referrer's unique ID or email.
To get the referrer's unique ID, you can call growsurf.getReferrerId() from the front-end.
referralStatus
string
Set the referral credit status of this new participant's referrer to CREDIT_PENDING or CREDIT_AWARDED . If a referredBy value is provided, the default value will be set to CREDIT_AWARDED unless another referralStatus value is specified.
To award referral credit immediately to the referrer, set this referralStatus value to CREDIT_AWARDED, otherwise it will be set based on the referral trigger configured for your campaign.
firstName
string
(Optional, but recommended) The first name of the new participant. If provided, this property will be used for anti-fraud measurements.
lastName
string
(Optional, but recommended) The last name of the new participant. If provided, this property will be used for anti-fraud measurements.
ipAddress
string
(Optional, but recommended) The IP address of the new participant. If provided, this property will be used for anti-fraud measurements.
fingerprint
string
(Optional, but recommended) The browser fingerprint of the new participant. If provided, this property will be used for anti-fraud measurements.
We recommend using a front-end library like fingerprintjs to get the fingerprint value. Example value: cfb163bd47ba666c52cb932c521e47f4.
metadata
object
A shallow Object containing custom key/values to include with the participant data.
The following keys are restricted: gdprAgreements
{
"id": "3vxff9",
"firstName": "Gavin",
"lastName": "Belson",
"referralCount": 0,
"monthlyReferralCount": 0,
"prevMonthlyReferralCount": 0,
"rank": 10001,
"monthlyRank": 10001,
"shareUrl": "https://hoolie.com?grsf=3vxff9",
"rewards": [],
"email": "[email protected]",
"createdAt": 1558665537426,
"referralSource": "DIRECT",
"isWinner": false,
"shareCount": {
"email": 0,
"facebook": 0,
"linkedin": 0,
"pinterest": 0,
"twitter": 0
},
"impressionCount": 0,
"uniqueImpressionCount": 0,
"inviteCount": 0,
"referrals": [],
"monthlyReferrals": [],
"referrer": null,
"metadata": {
"company": "Hooli, Inc",
"companySize": 10000
},
"fraudRiskLevel": "LOW",
"fraudReasonCode": "UNIQUE_IDENTITY",
"ipAddress": "127.0.0.1",
"fingerprint": "cfb163bd47ba666c52cb932c521e47f4",
"unsubscribed": false,
"vanityKeys": [
"gavin-f8g9nl"
]
Metadata: Please see our API Guidelines for more information about metadata.
Trigger Referral by Participant ID
POST https://api.growsurf.com/v2/campaign/:id/participant/:participantId/ref
Triggers a referral using an existing referred participant's ID, awarding referral credit to their referrer.
Path Parameters
id*
string
The ID of the campaign
participantId*
string
The ID of the referred participant
{
"success": true,
"message": "Successfully awarded referral credit."
}Important Notes:
Referral credit will only be awarded to the referrer if the participant
referralStatushas a value ofCREDIT_PENDINGMake sure your campaign's referral trigger is set to Sign Up + Qualifying Action (see image). If the referral trigger is set to Sign Up Event, triggering referrals will not work since referral credit has already been provided.
If your campaign has a referral credit expiration window set up, triggering a referral will still return a successful response even if the threshold has been exceeded, but the referrer will not receive credit and no rewards will be unlocked.
Trigger Referral by Participant Email
POST https://api.growsurf.com/v2/campaign/:id/participant/:participantEmail/ref
Triggers a referral using an existing referred participant's email address, awarding referral credit to their referrer.
Path Parameters
id*
string
The ID of the campaign
participantEmail*
string
The email address of the referred participant
{
"success": true,
"message": "Successfully awarded referral credit."
}Important Notes:
Referral credit will only be awarded to the referrer if the participant
referralStatushas a value ofCREDIT_PENDINGMake 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.
If your campaign has a referral credit expiration window set up, triggering a referral will still return a successful response even if the threshold has been exceeded, but the referrer will not receive credit and no rewards will be unlocked.
Update Participant by ID
POST https://api.growsurf.com/v2/campaign/:id/participant/:participantId
Updates a participant within the campaign using the ID of the participant.
Note: This endpoint is useful for use-cases like updating the participant's information (email address, first name, etc.) or assigning the participant a referrer by setting { referredBy, referralStatus }. Although you can use this endpoint to trigger referral credit for the participant's referrer by setting { referredBy, referralStatus }, we recommend using the /POST Trigger Referral by Participant ID endpoint for triggering referrals.
Path Parameters
id*
string
The ID of the campaign
participantId*
string
The ID of the participant
Request Body
referredBy
string
Set a referrer for this participant by providing the referrer's unique ID or email. If provided and a referrer has already been assigned, the referrer will not be updated and a error response will be returned.
string
The new email to assign to this participant. If the given email is already assigned to another participant within the campaign, an error response will be returned.
firstName
string
The first name of the participant.
lastName
string
The last name of the participant
metadata
object
A shallow Object containing custom values to include in the participant data.
If any existing metadata exists for the participant, any new values provided will be appended to the existing metadata, any existing values provided will overwrite and replace the existing metadata.*
To remove any existing metadata set its value to null.
referralStatus
string
Set the referral status of this participant's referrer to CREDIT_PENDING , CREDIT_AWARDED, or CREDIT_EXPIRED.
If provided and the referral status has already been awarded (CREDIT_AWARDED) the status cannot be updated and an error response will be returned.
vanityKeys
array
A list containing vanity IDs of the participant. This is useful for personalizing referral links for the participant.
The following rules apply:
- vanityKeys must be an array with no more than 5 vanity IDs.
- Vanity IDs must be between 1-20 characters.
- Vanity IDs can only contain numbers, letters, underscores, and hyphens.
- Vanity IDs must be unique and cannot be identical to another participant's GrowSurf or vanity ID.
unsubscribed
boolean
The participant's unsubscribed status. If true, they will not receive any campaign emails.
{
"id": "f8g9nl",
"firstName": "Gavin",
"lastName": "Belson",
"referralCount": 2,
"monthlyReferralCount": 2,
"prevMonthlyReferralCount": 0,
"rank": 10001,
"monthlyRank": 10001,
"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,
"uniqueImpressionCount": 2,
"inviteCount": 2,
"referrals": [
"i9g2bh",
"xua4sq"
],
"monthlyReferrals": [
"i9g2bh",
"xua4sq"
],
"referralSource": "PARTICIPANT",
"referralStatus": "CREDIT_AWARDED",
"referrer": {
"id": "h8kp6l",
"firstName": "Richard",
"lastName": "Hendricks",
"referralCount": 5,
"monthlyReferralCount": 2,
"rank": 100,
"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,
"uniqueImpressionCount": 11,
"inviteCount": 11,
"referrals": [
"0dveu7",
"f8g9nl",
"j0hbym",
"m5xm9l",
"w01fil"
],
"monthlyReferrals": [
"m5xm9l",
"w01fil"
],
"ipAddress": "113.2.2.9",
"fingerprint": "dau221bd47ba661c51ca933d531e47f5",
"metadata": {}
},
"ipAddress": "127.0.0.1",
"fingerprint": "cfb163bd47ba666c52cb932c521e47f4",
"metadata": {
"company": "Hooli, Inc",
"companySize": 10000
},
"unsubscribed": false,
"rewards": [
{
"id": "dgaiuk",
"rewardId": "oe1cjt",
"status": "PENDING",
"unread": true,
"isReferrer": true,
"isAvailable": false,
"approved": false,
"isFulfilled": false,
"referredId": "xh345d",
"referrerId": "f8g9nl"
}
],
"vanityKeys": [
"gavin-f8g9nl"
]
}*Please see our API Guidelines for more information about metadata.
Update Participant by Email
POST https://api.growsurf.com/v2/campaign/:id/participant/:participantEmail
Updates a participant within the campaign using the email of the participant.
Note: This endpoint is useful for use-cases like updating the participant's information (email address, first name, etc.) or assigning the participant a referrer by setting { referredBy, referralStatus }. Although you can use this endpoint to trigger referral credit for the participant's referrer by setting { referredBy, referralStatus }, we recommend using the /POST Trigger Referral by Participant Email endpoint for triggering referrals.
Path Parameters
id*
string
The campaign ID
participantEmail*
string
The participant email
Request Body
referredBy
string
Set a referrer for this participant by providing the referrer's unique ID or email. If provided and a referrer has already been assigned, the referrer will not be updated and a error response will be returned.
string
The new email to assign to the participant. If the given email is already assigned to another participant within the campaign, an error response will be returned.
firstName
string
The first name of the participant
lastName
string
The last name of the participant
metadata
object
A shallow Object containing custom values to include in the participant data.
If any existing metadata exists for the participant, any new values provided will be appended to the existing participant metadata, any existing values provided will overwrite and replace the existing metadata.*
To remove existing metadata set its value to null.
referralStatus
string
Set the referral status of this participant's referrer to CREDIT_PENDING, CREDIT_AWARDED, or CREDIT_EXPIRED.
If provided and the referral status has already been awarded (CREDIT_AWARDED) the status cannot be updated and an error response will be returned.
vanityKeys
array
A list containing vanity IDs of the participant. This is useful for personalizing referral links for the participant.
The following rules apply:
- vanityKeys must be an array with no more than 5 vanity IDs.
- Vanity IDs must be between 1-20 characters.
- Vanity IDs can only contain numbers, letters, underscores, and hyphens.
- Vanity IDs must be unique and cannot be identical to another participant's GrowSurf or vanity ID.
unsubscribed
boolean
The participant's unsubscribed status. If true, they will not receive any campaign emails.
{
"id": "f8g9nl",
"firstName": "Gavin",
"lastName": "Belson",
"referralCount": 2,
"monthlyReferralCount": 2,
"prevMonthlyReferralCount": 0,
"rank": 10001,
"monthlyRank": 10001,
"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,
"uniqueImpressionCount": 2,
"inviteCount": 2,
"referrals": [
"i9g2bh",
"xua4sq"
],
"monthlyReferrals": [
"i9g2bh",
"xua4sq"
],
"referralSource": "PARTICIPANT",
"referralStatus": "CREDIT_AWARDED",
"referrer": {
"id": "h8kp6l",
"firstName": "Richard",
"lastName": "Hendricks",
"referralCount": 5,
"monthlyReferralCount": 2,
"rank": 100,
"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,
"uniqueImpressionCount": 11,
"inviteCount" 11,
"referrals": [
"0dveu7",
"f8g9nl",
"j0hbym",
"m5xm9l",
"w01fil"
],
"monthlyReferrals": [
"m5xm9l",
"w01fil"
],
"ipAddress": "113.2.2.9",
"fingerprint": "dau221bd47ba661c51ca933d531e47f5",
"metadata": {},
"unsubscribed": false,
},
"ipAddress": "127.0.0.1",
"fingerprint": "cfb163bd47ba666c52cb932c521e47f4",
"metadata": {
"company": "Hooli, Inc",
"companySize": 10000
},
"unsubscribed": false,
"rewards": [
{
"id": "dgaiuk",
"rewardId": "oe1cjt",
"status": "PENDING",
"unread": true,
"isReferrer": true,
"isAvailable": false,
"approved": false,
"isFulfilled": false,
"referredId": "xh345d",
"referrerId": "f8g9nl"
}
],
"vanityKeys": [
"gavin-f8g9nl"
]
}*Please see our API Guidelines for more information about metadata.
Remove Participant by ID
DELETE https://api.growsurf.com/v2/campaign/:id/participant/:participantId
Removes a participant within the campaign using the ID of the participant.
(Looking to remove a bulk list of participants using a CSV file? View this tutorial).
Path Parameters
id*
string
The ID of the campaign
participantId*
string
The ID of the participant
{
"success": true
}Remove Participant by Email
DELETE https://api.growsurf.com/v2/campaign/:id/participant/:participantEmail
Removes a participant within the campaign using the email of the participant.
(Looking to remove a bulk list of participants using a CSV file? View this tutorial).
Path Parameters
id*
string
The campaign ID
participantEmail*
string
The participant email
{
"success": true
}PARTICIPANT REWARDS ↓
Get Participant Rewards by Participant ID
GET https://api.growsurf.com/v2/campaign/:id/participant/:participantId/rewards
Retrieves a list of rewards earned by a participant.
Path Parameters
id*
string
The campaign ID
participantId*
string
The participant's unique ID or email
Query Parameters
nextId
string
The id of the participant reward to start the next result set with. This can be used to skip through the list or to page the list of results. Each response will provide a nextId value if there are more rewards otherwise the nextId will be null.
limit
string
The number of rewards to return. Must be a value less than or equal to 100, which is currently the maximum allowed per request.
{
"limit": 2,
"nextId": "v2qtfq",
"rewards": [
{
"id": "rr35mg",
"rewardId": "c6w1qo",
"status": "PENDING",
"unread": true,
"approved": false,
"approvedAt": null,
"fulfilledAt": null,
"isReferrer": true,
"isAvailable": false,
"isFulfilled": false,
"referredId": "xh345d",
"referrerId": "f8g9nl"
},
{
"id": "oltj0s",
"rewardId": "c6w1qo",
"status": "FULFILLED",
"unread": false,
"approved": true,
"approvedAt": 1659453091744,
"fulfilledAt": 1659453418901,
"isReferrer": false,
"isAvailable": true,
"isFulfilled": true,
"referredId": "zyx765",
"referrerId": "f8g9nl"
}
]
}Get Participant Rewards by Participant Email
GET https://api.growsurf.com/v2/campaign/:id/participant/:participantEmail/rewards
Retrieves a list of rewards earned by a participant.
Paging this response
Each response will contain a nextId, that value is the id of the next participant and not the email therefore, you must use this endpoint in conjunction of our Get Participant Rewards by ID endpoint if you wish to page results starting with this endpoint. To page you would provide the nextId as the participantId path parameter within the Get Participant Rewards by ID request.
Path Parameters
id*
string
The id of the campaign.
participantEmail*
string
The participant email
Query Parameters
nextId
string
The id of the participant reward to start the next result set with. This can be used to skip through the list or to page the list of results. Each response will provide a nextId value if there are more rewards otherwise the nextId will be null.
limit
string
The number of rewards to return. Must be a value less than or equal to 100, which is currently the maximum allowed per request.
{
"limit": 2,
"nextId": "v2qtfq",
"rewards": [
{
"id": "rr35mg",
"rewardId": "c6w1qo",
"status": "PENDING",
"unread": true,
"approved": false,
"approvedAt": null,
"fulfilledAt": null,
"isReferrer": true,
"isAvailable": false,
"isFulfilled": false,
"referredId": "xh345d",
"referrerId": "f8g9nl"
},
{
"id": "oltj0s",
"rewardId": "c6w1qo",
"status": "FULFILLED",
"unread": false,
"approved": true,
"approvedAt": 1659453091744,
"fulfilledAt": 1659453418901,
"isReferrer": false,
"isAvailable": true,
"isFulfilled": true,
"referredId": "zyx765",
"referrerId": "f8g9nl"
}
]
}Approve Participant Reward
POST https://api.growsurf.com/v2/campaign/:id/reward/:rewardId/approve
Approve a reward that was earned by a participant.
You should only use this endpoint if your reward automation level is set to Manually approve rewards (learn more here). This means ParticipantRewards will be generated with status: "PENDING", approved: false, and isFulfilled: false.
Calling this endpoint to approve a reward will cause New Participant Reward emails to be sent out and automations/integrations to be triggered. If you are using Webhooks to automate rewards, a new PARTICIPANT_REACHED_A_GOAL event will be emitted with data.reward.approved as false.
Path Parameters
id*
string
The campaign ID
rewardId*
string
The ID of the participant reward to approve
Request Body
fulfill
boolean
Set true to mark the reward as fulfilled.
Fulfilling a reward does not trigger any emails or automations. It helps you stay organized when managing rewards from your GrowSurf admin dashboard (e.g, you won't see any red notifications reminding you to fulfill rewards -- see video here).
{
"success": true
}Fulfill Participant Reward
POST https://api.growsurf.com/v2/campaign/:id/reward/:rewardId/fulfill
Fulfill a reward that was earned by a participant (this can only be done if the reward is already approved). When you call this endpoint, the ParticipantReward should have the following key-values: status: "PENDING", approved: true, and isFulfilled: false.
Fulfilling a reward does not trigger any emails or automations. It helps you stay organized when managing rewards from your GrowSurf admin dashboard (e.g, you won't see any red notifications reminding you to fulfill rewards -- see video here).
Path Parameters
id*
string
The campaign ID
rewardId*
string
The ID of the participant reward to fulfill
{
"success": true
}Remove Participant Reward
DELETE https://api.growsurf.com/v2/campaign/:id/reward/:rewardId
Remove a reward that was earned by a participant. This only applies if your campaign was configured with manual reward approval and if the provided participant reward has not been approved.
Path Parameters
id*
string
The campaign ID
rewardId*
string
The ID of the participant reward to remove
{
"success": true
}REFERRALS AND INVITES ↓
Get Referrals and Invites
GET https://api.growsurf.com/v2/campaign/:id/referrals
Retrieves a list of all referrals and email invites made by participants in a campaign. Response Cache In some cases, responses from this endpoint will be cached for up to but no longer than 5 minutes. Anytime a new referral or invite is triggered within your campaign that cache will be purged.
Path Parameters
id
string
The ID of the campaign
Query Parameters
sortBy
string
If provided, will sort the results by the provided field. Valid sortBy options are updatedAt, createdAt, email, referralTriggeredAt.
By default, results are sorted by the updatedAt timestamp in descending (most recent first) order.
desc
boolean
Defaults to true, returning results in descending (most recent first) order.
Set desc to false to return results in ascending order.
limit
number
Limit the number of referral results to return. Must be a value less than or equal to 100 which is currently the maximum allowed per request.
offset
number
The offset number to start the result set at. This can be used to skip through the list or to page the list of results.
string
If provided, filters results by the given email value.
Any email value that is provided must be URL-encoded.
For data privacy and security purposes, invite (INVITE_SENT) referral results cannot be filtered by email addresses.
firstName
string
If provided, filters results by the given first name value
lastName
string
If provided, filters results by the given last name value
referralStatus
string
If provided, filters results by the given referral status. Valid values for this filter are CREDIT_PENDING, CREDIT_AWARDED, CREDIT_EXPIRED, INVITE_SENT
Any values other than the ones listed above will be ignored.
nextId
string
The ID of the result to start the next result set with. This can be used to skip through the list or to page the list results. Each response will provide a nextId value, based on the provided sortBy value, if there are more results otherwise the nextId value will be null.
A boolean field more will always be present for determining if there are more results.
{
"referrals": [{
"id": "f2bukr",
"email": "[email protected]",
"firstName": "Gavin",
"lastName": "Belson",
"referralStatus": "CREDIT_AWARDED",
"referredBy": "2khaha",
"createdAt": 1591546112223,
"updatedAt": 1591546285013
},
{
"id": "qbp153",
"email": "[email protected]",
"firstName": "Richard",
"lastName": "Hendricks",
"referralStatus": "CREDIT_PENDING",
"referredBy": "abckj2",
"createdAt": 1591542657835,
"updatedAt": 1591542658457
},
{
"id": "ghw131",
"email": "[email protected]",
"firstName": "Danish",
"lastName": "Chugtai",
"referralStatus": "CREDIT_EXPIRED",
"referredBy": "zz212f",
"createdAt": 1591548886835,
"updatedAt": 1591542677457
},
{
"id": "ugqeq9",
"email": "***************",
"firstName": null,
"lastName": null,
"referralStatus": "INVITE_SENT",
"referredBy": "xde212",
"createdAt": 1591469527740,
"updatedAt": 1591469527740
}
],
"limit": 4,
"nextOffset": 4,
"nextId": "[email protected]",
"more": true
}Get Participant Referrals and Invites by ID
GET https://api.growsurf.com/v2/campaign/:id/participant/:participantId/referrals
Retrieves a list of all referrals and email invites made by a participant in a campaign. Response Cache In some cases responses from this endpoint will be cached for up to but no longer than 5 minutes. Anytime a new referral or invite is triggered within your campaign that cache will be purged.
Path Parameters
id
string
The campaign ID
participantId
string
The participant ID
Query Parameters
sortBy
string
If provided, will sort results by the provided field.
Valid options are updatedAt, createdAt, email, referralTriggeredAt.
By default, the results are sorted by the updatedAt timestamp in descending (most recent first) order.
desc
string
Defaults to true, returning results in descending (most recent first) order.
Set desc to false to return results in ascending order.
limit
string
Limit the number of referral results to return. Must be a value less than or equal to 100 which is currently the maximum allowed per request.
offset
string
The offset number to start the result set at. This can be used to skip the list or page the list of results.
string
If provided, filters results by the provided email value. Any email value that is provided must be URL encoded.
For data privacy and security purposes, invite (INVITE_SENT) referral results cannot be filtered by email addresses.
firstName
string
If provided, filters results by the given first name value
lastName
string
If provided, filters results by the given last name value
referralStatus
string
If provided, filters results by the given referral status. Valid values for this filter are CREDIT_PENDING, CREDIT_AWARDED, CREDIT_EXPIRED, INVITE_SENT.
Any values other than the ones listed above will be ignored.
nextId
string
The ID of the result to start the next result set with. This can be used to skip through the list or to page the list results. Each response will provide a nextId value, based on the provided sortBy value, if there are more results otherwise the nextId value will be null.
A boolean field more will always be present for determining if there are more results.
{
"referrals": [{
"id": "f2bukr",
"email": "[email protected]",
"firstName": "Gavin",
"lastName": "Belson",
"referralStatus": "CREDIT_AWARDED",
"referredBy": "2khaha",
"createdAt": 1591546112223,
"updatedAt": 1591546285013
},
{
"id": "qbp153",
"email": "[email protected]",
"firstName": "Richard",
"lastName": "Hendricks",
"referralStatus": "CREDIT_PENDING",
"referredBy": "2khaha",
"createdAt": 1591542657835,
"updatedAt": 1591542658457
},
{
"id": "ghw131",
"email": "[email protected]",
"firstName": "Danish",
"lastName": "Chugtai",
"referralStatus": "CREDIT_EXPIRED",
"referredBy": "2khaha",
"createdAt": 1591548886835,
"updatedAt": 1591542677457
},
{
"id": "ugqeq9",
"email": "***************",
"firstName": null,
"lastName": null,
"referralStatus": "INVITE_SENT",
"referredBy": "2khaha",
"createdAt": 1591469527740,
"updatedAt": 1591469527740
}
],
"limit": 4,
"nextOffset": 4,
"nextId": "[email protected]",
"more": true
}Get Participant Referrals and Invites by Email
GET https://api.growsurf.com/v2/campaign/:id/participant/:participantEmail/referrals
Retrieves a list of all referrals and email invites made by a participant in a campaign. Response Cache In some cases responses from this endpoint will be cached for up to but no longer than 5 minutes. Anytime a new referral or invite is triggered within your campaign that cache will be purged.
Path Parameters
id
string
The campaign ID
participantEmail
string
The email of the participant to retrieve the referrals for
Query Parameters
sortBy
string
If provided, will sort results by the provided field.
Valid options are updatedAt, createdAt, email, referralTriggeredAt.
By default, the results are sorted by the updatedAt timestamp in descending (most recent first) order.
desc
string
Defaults to true, returning results in descending (most recent first) order.
Set desc to false to return results in ascending order.
limit
string
Limit the number of referral results to return. Must be a value less than or equal to 100 which is currently the maximum allowed per request.
offset
string
The offset number to start the result set at. This can be used to skip the list or page the list of results.
string
If provided, filters results by the provided email value. Any email value that is provided must be URL encoded.
For data privacy and security purposes, invite (INVITE_SENT) referral results cannot be filtered by email addresses.
firstName
string
If provided, filters results by the given first name value
lastName
string
If provided, filters results by the given last name value
referralStatus
string
If provided, filters results by the given referral status. Valid values for this filter are CREDIT_PENDING, CREDIT_AWARDED, CREDIT_EXPIRED, INVITE_SENT.
Any values other than the ones listed above will be ignored.
nextId
string
The ID of the result to start the next result set with. This can be used to skip through the list or to page the list results. Each response will provide a nextId value, based on the provided sortBy value, if there are more results otherwise the nextId value will be null.
A boolean field more will always be present for determining if there are more results.
{
"referrals": [{
"id": "f2bukr",
"email": "[email protected]",
"firstName": "Gavin",
"lastName": "Belson",
"referralStatus": "CREDIT_AWARDED",
"referredBy": "2khaha",
"createdAt": 1591546112223,
"updatedAt": 1591546285013
},
{
"id": "qbp153",
"email": "[email protected]",
"firstName": "Richard",
"lastName": "Hendricks",
"referralStatus": "CREDIT_PENDING",
"referredBy": "2khaha",
"createdAt": 1591542657835,
"updatedAt": 1591542658457
},
{
"id": "ghw131",
"email": "[email protected]",
"firstName": "Danish",
"lastName": "Chugtai",
"referralStatus": "CREDIT_EXPIRED",
"referredBy": "2khaha",
"createdAt": 1591548886835,
"updatedAt": 1591542677457
},
{
"id": "ugqeq9",
"email": "***************",
"firstName": null,
"lastName": null,
"referralStatus": "INVITE_SENT",
"referredBy": "2khaha",
"createdAt": 1591469527740,
"updatedAt": 1591469527740
}
],
"limit": 4,
"nextOffset": 4,
"nextId": "[email protected]",
"more": true
}Send Participant Invites by ID
POST https://api.growsurf.com/v2/campaign/:id/participant/:participantId/invites
Sends email invites on behalf of a participant to a list of email addresses.
NOTE: Your campaign must have a custom 'From' email address in order for email invites to be sent out. Learn more here.
Path Parameters
id*
string
The campaign ID
participantId*
string
The participant ID
Request Body
emailAddresses*
array
A list of email addresses to send invites to
messageText*
string
The email message body.
Make sure to include {{referrerMessage}} in the contents, which will be interpolated with the participant's personalized message.
You can also pass in the following values:
{{referrerFirstName}}
{{referrerLastName}}
{{referrerEmail}}
{{referrerShareUrl}}
subjectText*
string
The email subject line.
You can pass in the following values:
{{referrerFirstName}}
{{referrerLastName}}
{{referrerEmail}}
{{referrerMessage}}
{{referrerShareUrl}}
{
"success": true,
"messageType": "sent",
"invitesSent": 1
}Send Participant Invites by Email
POST https://api.growsurf.com/v2/campaign/:id/participant/:participantEmail/invites
Sends email invites on behalf of a participant to a list of email addresses.
NOTE: Your campaign must have a custom 'From' email address in order for email invites to be sent out. Learn more here.
Path Parameters
id*
string
The campaign ID
participantEmail*
string
The participant's email address
Request Body
emailAddresses*
array
A list of email addresses to send invites to
messageText*
string
The email message body.
Make sure to include {{referrerMessage}} in the contents, which will be interpolated with the participant's personalized message.
You can also pass in the following values:
{{referrerFirstName}}
{{referrerLastName}}
{{referrerEmail}}
{{referrerShareUrl}}
subjectText*
string
The email subject line.
You can pass in the following values:
{{referrerFirstName}}
{{referrerLastName}}
{{referrerEmail}}
{{referrerMessage}}
{{referrerShareUrl}}
{
"success": true,
"messageType": "sent",
"invitesSent": 1
}ANALYTICS ↓
Get Campaign Analytics
GET https://api.growsurf.com/v2/campaign/:id/analytics
Retrieves the analytics for a campaign.
Path Parameters
id*
string
The ID of the campaign to retrieve analytics for.
days
integer
(Optional)
The last number of days to retrieve analytics for. Defaults to 365 if no value is provided. Maximum limit is 1825.
startDate
integer
(Optional but required if days is not set)
The start date of the analytics timeframe as a Unix timestamp in milliseconds. Example value: 1592359793538.
endDate
integer
(Optional but required if days is not set)
The end date of the analytics timeframe as a Unix timestamp in milliseconds. Example value: 1747879793538.
{
"analytics": {
"invites": 13,
"impressions": 213,
"uniqueImpressions": 34,
"participants": 400,
"referrals": 113,
"referralCreditPendings": 298,
"referralCreditExpireds": 15,
"emailShares": 1,
"facebookShares": 8,
"twitterShares": 53,
"threadsShares": 7,
"blueskyShares": 10,
"pinterestShares": 9,
"linkedInShares": 0,
"smsShares": 4,
"messengerShares": 5,
"whatsAppShares": 1,
"wechatShares": 4,
"telegramShares": 5,
"qrcodeShares": 49,
"redditShares": 4,
"tumblrShares": 0
},
"startDate": 1592359793538,
"endDate": 1747879793538
}Last updated
Was this helpful?