Objects

Campaign
The Campaign Object contains detailed information about a GrowSurf campaign.
Attributes
​
​
id 
string
The unique identifier of the campaign
name 
string
The campaign name
referralCount 
integer
The total referral count
participantCount 
integer
The total participant count
impressionCount
integer
The total number of impressions†
winnerCount
integer
The total number of winners††
inviteCount
integer
The total number of invites sent by participants
status
string
The campaign status: DRAFT,IN_PROGRESS,COMPLETE,DELETED
rewards
array
The list of Rewards associated with the campaign
† Impressions = the collective amount of times participants' unique referral links have been viewed.

†† Winners = all participants with at least one approved reward (includes referrers and referred friends).
Campaign Object Example
{
    "id": "abc123",
    "name": "Middle Out Compression Campaign",
    "referralCount": 121,
    "participantCount": 199,
    "impressionCount": 199,
    "winnerCount": 1,    
    "inviteCount": 237,
    "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"
        }
    ]
}
Reward
The Reward Object contains detailed reward information about a single reward that was setup for a campaign.
Note: This Reward Object is different from a ParticipantReward Object, which is a reward earned by a participant.
Attributes
​
​
id
string
The unique identifier of the reward
type
string
The reward type: SINGLE_SIDED,DOUBLE_SIDED,MILESTONE, LEADERBOARD
description
string
The reward description for the referrer (see image)
referralDescription
string
The reward description for the referred friend (only applicable for double-sided reward types -- see image)
isUnlimited
boolean
true if this reward can be earned by a single participant an unlimited amount of times
limit
integer
The number of times a participant can earn this reward (this property is overridden if isUnlimited is true) 
conversionsRequired 
integer
The number of referrals a participant must make to earn this reward
numberOfWinners 
integer
The maximum number of total participants that can earn this reward
imageUrl
string
The reward image URL
metadata
object
The reward metadata
Reward Object Example
{
    "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"
    "metadata": {
      "rewardForTierA": 50,
      "rewardForTierB": 100
    }
}
Participant
The Participant Object contains detailed information about a campaign participant.
Attributes
​
​
id
integer
The unique identifier of the participant
firstName
string
The first name of the participant
lastName
string
The last name of the participant
referralCount
integer
The total number of referrals made by the participant
monthlyReferralCount
integer
The total number of referrals made this month by the participant (resets at the end of the month)
prevMonthlyReferralCount
integer
The total number of referrals made the previous month by the participant.
shareUrl
string
The unique share URL of the participant
email
string
The email of the participant
createdAt
timestamp
The date the participant was added to the campaign (UTC milliseconds)
fraudRiskLevel
string
A value that represents the integrity of the participant: LOW, MEDIUM,HIGH
fraudReasonCode
string
A value representing the reason for the fraudRiskLevel: UNIQUE_IDENTITY, DUPLICATE_EMAIL, DUPLICATE_IDENTITY
isWinner
boolean
true if the participant has earned one or more rewards
shareCount
object
An Object containing various counts representing the number of times the participant has shared their referral link: email,facebook,pinterest,twitter
impressionCount
integer
The total number of impressions the participant has made
uniqueImpressionCount
integer
The total number of unique impressions the participant has made
referrals
array
A list of Participant IDs who were successfully referred by the participant. The array will be limited to a size of 100 and will contain the IDs of the most recently referred friends (The last 100 referrals made). 
monthlyReferrals
array
A list of Participant IDs who successfully referred by the participant this month (resets at the end of the month). The array will be limited to a size of 100 and will contain the IDs of the most recently referred friends (The last 100 referrals made). 
referralSource
string
The source of how the participant joined the campaign: PARTICIPANT, DIRECT,IMPORT,MANUAL, DELETED_PARTICIPANT.
referralStatus
string
If the participant was referred, this value represents their referrer's status in receiving the referral credit: CREDIT_PENDING, CREDIT_AWARDED, CREDIT_EXPIRED.
​
This property is only applicable if the participant was referred into the campaign.
referrer
object
A shallow Object containing the participant's referrer information.
​
This property is only applicable if the participant was referred into the campaign.
referredBy
string
The ID of the referrer.
​
This property is only applicable if the participant was referred into the campaign.
rewards
array
A list of campaign Reward IDs that the participant has earned
notes
string
A value containing internal notes about the participant, added via the GrowSurf Dashboard​
metadata
object
An Object containing any custom key-value data, useful when you want to save additional data for the participant (e.g, company, companySize)

Metadata is never used by GrowSurf and usage is optional. Metadata is returned only in REST API calls, and never returned in JavaScript Web API calls. For more information, please see API Guidelines.
rank
integer
The rank of the participant.
monthlyRank
integer
The monthly rank of the participant. 
​
This rank resets to 0 at the end of each month.
prevMonthlyRank
integer
The previous monthly rank of the participant. 

This rank will not be be returned if the participant did not exist within your campaign during the previous month.
vanityKeys
array
The list of vanity keys that the participant has.
Participant Object Example
{
    "id": "f8g9nl",
    "firstName": "Gavin",
    "lastName": "Belson",
    "referralCount": 2,
    "monthlyReferralCount": 2,
    "prevMonthlyReferralCount": 0,
    "rank": 10001,
    "monthlyRank": 20001,
    "monthlyRank": -1,
    "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": 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"
        ]        
    },
    "metadata": {
       "company": "Hooli, Inc",
       "companySize": 10000
    },    
    "rewards": [
        {
            "id": "dgaiuk",
            "rewardId": "oe1cjt",
            "status": "FULFILLED",
            "unread": true,
            "isReferrer": true,
            "isAvailable": true,
            "approved": true,
            "isFulfilled": true
            "referredId": "xh345d",
            "referrerId": "f8g9nl"
        }
    ],
    "vanityKeys": [
      "gavin-f8g9nl"
    ]
}
ParticipantReward
The ParticipantReward Object represents a reward that the participant has earned.
Note: This ParticipantReward Object is different from a Reward Object and contains information that is only pertinent to the participant that earned the reward.
Attributes
​
​
id
string
The unique identifier of the participant's reward
rewardId
string
The ID of the Reward the participant earned
status
string
The status of the reward: PENDING,FULFILLED
isReferrer
boolean
true if the participant earned the reward as the referrer.
false if the participant earned the reward as the referred friend (only applicable in double-sided reward types).
isAvailable
boolean
true if the reward is available for participant to claim or redeem
approved
boolean
true if the reward has been approved
approvedAt
timestamp
The date and time the reward was approved for this participant (UTC milliseconds).  It is null for unapproved rewards.
isFulfilled
boolean
true if the reward has been fulfilled.
fulfilledAt
timestamp
The date and time the reward was fulfilled for this participant (UTC milliseconds).  It is null for either unapproved or unfulfilled rewards.
referredId
string
The id of the friend that was referred
referrerId
string
The id of the participant that made the referral
unread
boolean
 false if the participant has not seen the reward in a GrowSurf window otherwise false.  
ParticipantReward Object Example
{
    "id": "rr35mg",
    "rewardId": "c6w1qo",
    "status": "PENDING",
    "unread": true,
    "approved": false,
    "approvedAt": null,
    "fulfilledAt": null,            
    "isReferrer": true,
    "isAvailable": false,
    "isFulfilled": false,
    "referredId": "xh345d",
    "referrerId": "f8g9nl"
}

Tutorials

API Reference

Last modified 6mo ago

Attributes
id	`string`	The unique identifier of the campaign
name	`string`	The campaign name
referralCount	`integer`	The total referral count
participantCount	`integer`	The total participant count
impressionCount	`integer`	The total number of impressions†
winnerCount	`integer`	The total number of winners††
inviteCount	`integer`	The total number of invites sent by participants
status	`string`	The campaign status: `DRAFT`,`IN_PROGRESS`,`COMPLETE`,`DELETED`
rewards	`array`	The list of Rewards associated with the campaign

Attributes
id	`string`	The unique identifier of the reward
type	`string`	The reward type: `SINGLE_SIDED`,`DOUBLE_SIDED`,`MILESTONE`, `LEADERBOARD`
description	`string`	The reward description for the referrer (see image)
referralDescription	`string`	The reward description for the referred friend (only applicable for double-sided reward types -- see image)
isUnlimited	`boolean`	`true` if this reward can be earned by a single participant an unlimited amount of times
limit	`integer`	The number of times a participant can earn this reward (this property is overridden if `isUnlimited` is `true`)
conversionsRequired	`integer`	The number of referrals a participant must make to earn this reward
numberOfWinners	`integer`	The maximum number of total participants that can earn this reward
imageUrl	`string`	The reward image URL
metadata	`object`	The reward metadata

Attributes
id	`integer`	The unique identifier of the participant
firstName	`string`	The first name of the participant
lastName	`string`	The last name of the participant
referralCount	`integer`	The total number of referrals made by the participant
monthlyReferralCount	`integer`	The total number of referrals made this month by the participant (resets at the end of the month)
prevMonthlyReferralCount	`integer`	The total number of referrals made the previous month by the participant.
shareUrl	`string`	The unique share URL of the participant
email	`string`	The email of the participant
createdAt	`timestamp`	The date the participant was added to the campaign (UTC milliseconds)
fraudRiskLevel	`string`	A value that represents the integrity of the participant: `LOW`, `MEDIUM`,`HIGH`
fraudReasonCode	`string`	A value representing the reason for the `fraudRiskLevel`: `UNIQUE_IDENTITY`, `DUPLICATE_EMAIL`, `DUPLICATE_IDENTITY`
isWinner	`boolean`	`true` if the participant has earned one or more rewards
shareCount	`object`	An Object containing various counts representing the number of times the participant has shared their referral link: `email`,`facebook`,`pinterest`,`twitter`
impressionCount	`integer`	The total number of impressions the participant has made
uniqueImpressionCount	`integer`	The total number of unique impressions the participant has made
referrals	`array`	A list of `Participant` IDs who were successfully referred by the participant. The array will be limited to a size of 100 and will contain the IDs of the most recently referred friends (The last 100 referrals made).
monthlyReferrals	`array`	A list of `Participant` IDs who successfully referred by the participant this month (resets at the end of the month). The array will be limited to a size of 100 and will contain the IDs of the most recently referred friends (The last 100 referrals made).
referralSource	`string`	The source of how the participant joined the campaign: `PARTICIPANT`, `DIRECT`,`IMPORT`,`MANUAL`, `DELETED_PARTICIPANT`.
referralStatus	`string`	If the participant was referred, this value represents their referrer's status in receiving the referral credit: `CREDIT_PENDING`, `CREDIT_AWARDED`, `CREDIT_EXPIRED`. This property is only applicable if the participant was referred into the campaign.
referrer	`object`	A shallow Object containing the participant's referrer information. This property is only applicable if the participant was referred into the campaign.
referredBy	`string`	The ID of the referrer. This property is only applicable if the participant was referred into the campaign.
rewards	`array`	A list of campaign `Reward` IDs that the participant has earned
notes	`string`	A value containing internal notes about the participant, added via the GrowSurf Dashboard
metadata	`object`	An Object containing any custom key-value data, useful when you want to save additional data for the participant (e.g, `company`, `companySize`) Metadata is never used by GrowSurf and usage is optional. Metadata is returned only in REST API calls, and never returned in JavaScript Web API calls. For more information, please see API Guidelines.
rank	`integer`	The rank of the participant.
monthlyRank	`integer`	The monthly rank of the participant. *This rank resets to 0 at the end of each month.*
prevMonthlyRank	`integer`	The previous monthly rank of the participant. *This rank will not be be returned if the participant did not exist within your campaign during the previous month.*
vanityKeys	`array`	The list of vanity keys that the participant has.

Attributes
id	`string`	The unique identifier of the participant's reward
rewardId	`string`	The ID of the `Reward` the participant earned
status	`string`	The status of the reward: `PENDING`,`FULFILLED`
isReferrer	`boolean`	`true` if the participant earned the reward as the referrer. `false` if the participant earned the reward as the referred friend (only applicable in double-sided reward types).
isAvailable	`boolean`	`true` if the reward is available for participant to claim or redeem
approved	`boolean`	`true` if the reward has been approved
approvedAt	`timestamp`	The date and time the reward was approved for this participant (UTC milliseconds). It is `null` for unapproved rewards.
isFulfilled	`boolean`	`true` if the reward has been fulfilled.
fulfilledAt	`timestamp`	The date and time the reward was fulfilled for this participant (UTC milliseconds). It is `null` for either unapproved or unfulfilled rewards.
referredId	`string`	The id of the friend that was referred
referrerId	`string`	The id of the participant that made the referral
unread	`boolean`	`false` if the participant has not seen the reward in a GrowSurf window otherwise `false`.

Objects

`Campaign`

`Reward`

`Participant`

`ParticipantReward`