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

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 person (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

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 participants (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 participants (The last 100 referrals made).

referralSource

string

The source of how the participant joined the campaign: PARTICIPANT, DIRECT,IMPORT,MANUAL

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.

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.

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 this reward as the referrer.

false if the participant earned this reward as the referred person (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

isFulfilled

boolean

true if the reward has been fulfilled.

referredId

string

The id of the person that was referred

referrerId

string

The id of the participant that made the referral