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,
            "limitDuration": "IN_TOTAL",
            "order": 1,
            "couponCode": "PROMO_20_OFF", 
            "imageUrl": "http://res.cloudinary.com/growsurf/image/upload/v1552764861/development/hxdcjrayfhksvxu5u6oz.png",
            "nextMilestonePrefix": "You are only",
            "nextMilestoneSuffix": "referrals away from receiving a nice reward!",    
            "metadata": {
              "rewardForTierA": 50,
              "rewardForTierB": 100,
              "bonusPeriodMessage": "Offering 2x referral bonuses in our promotion period!"  
            }
        }    
    ]
}

---

Reward

The Reward Object (also known as CampaignReward) contains detailed reward information about a single reward 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 campaign reward. You can find this ID from Campaign Editor > 1. Rewards and clicking the reward.
title	string	The title of the campaign reward. Only used for internal purposes and never displayed to participants.
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
limitDuration	string	Whether the reward can be earned in total or on a monthly basis. Options: "IN_TOTAL", "PER_MONTH"
numberOfWinners	integer	The maximum number of total participants that can earn this reward if type is LEADERBOARD. If limitDuration is PER_MONTH, this is the manimum number of total participants who can earn the reward in the given month.
imageUrl	string	The reward image URL
couponCode	string	A coupon code
order	integer	If there are multiple rewards, this represents the order in which the reward should be displayed. This value is null by default, until set within the Design step of the campaign editor.
nextMilestonePrefix	string	The text that can be used for UI purposes that will be displayed in front of a participant's referral count number (e.g, "You are only"). Applicable for milestone rewards (when type === 'MILESTONE').
nextMilestoneSuffix	string	The text that can be used for UI purposes that will be displayed behind a participant's referral count number (e.g, "referrals away from receiving a nice reward!"). Applicable for milestone rewards (when type === 'MILESTONE').
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,
    "limitDuration": "IN_TOTAL",
    "order": 1,
    "couponCode": "PROMO_20_OFF", 
    "imageUrl": "http://res.cloudinary.com/growsurf/image/upload/v1552764861/development/hxdcjrayfhksvxu5u6oz.png",
    "nextMilestonePrefix": "You are only",
    "nextMilestoneSuffix": "referrals away from receiving a nice reward!",    
    "metadata": {
      "rewardForTierA": 50,
      "rewardForTierB": 100,
      "bonusPeriodMessage": "Offering 2x referral bonuses in our promotion period!"
    }
}

---

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	An 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": "[e-mail]",
    "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": "[e-mail]",
        "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.

Notes:

• This ParticipantReward Object is different from a campaign Reward Object and contains information that is only pertinent to the participant that earned the reward.

• In Webhooks, ParticipantReward Objects will also contain campaign Reward Object details.

Attributes
id	string	The unique identifier of the participant's reward. This will be different for every new reward that the participant earns. You can find this ID by going to your admin dashboard and viewing the participant's rewards.
rewardId	string	The ID of the CampaignReward that this participant has earned
status	string	The status of the participant's 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 participant's reward has been approved
approvedAt	timestamp	The date and time the participant's reward was approved for this participant (UTC milliseconds). It is null for unapproved rewards.
isFulfilled	boolean	true if the participant's 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"
}