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.

Campaigns

Get Campaign

GET https://api.growsurf.com/v2/campaign/:id

Retrieves a campaign for the given ID.

Path Parameters

NameTypeDescription

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

NameTypeDescription

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": "gavin@hoolie.com",
    "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": "richard@piedpiper.com",
        "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"
    ]
}

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

NameTypeDescription

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": "gavin@hoolie.com",
    "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": "richard@piedpiper.com",
        "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"
    ]
}

Get Participants

GET https://api.growsurf.com/v2/campaign/:id/participants

Retrieves a list of participants in the campaign.

Path Parameters

NameTypeDescription

id*

string

The ID of the campaign

Query Parameters

NameTypeDescription

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": "gavin@hooli.com",
            "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"
            ]
        },
        {
            "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": "gavin@hoolie.com",
            "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": "richard@piedpiper.com",
                "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": {},
            "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

NameTypeDescription

id*

string

The ID of the campaign

Query Parameters

NameTypeDescription

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": "gavin@hooli.com",
            "createdAt": 1558665537426,
            "referralSource": "DIRECT",
            "isWinner": false,
            "shareCount": {
                "email": 0,
                "facebook": 0,
                "linkedin": 0,
                "pinterest": 0,
                "twitter": 0
            },
            "impressionCount": 0,
            "uniqueImpressionCount": 0,            
            "inviteCount": 0,                        
            "referrals": [],
            "referrer": null,
            "metadata": {},
            "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": "gavin@hoolie.com",
            "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": "richard@piedpiper.com",
                "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,
                "metadata": {},                                        
                "referrals": [
                    "0dveu7",
                    "f8g9nl",
                    "j0hbym",
                    "m5xm9l",
                    "w01fil"
                ]
            },
            "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

NameTypeDescription

id*

string

The ID of the campaign to add the new participant to

Request Body

NameTypeDescription

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

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

The first name of the new participant

lastName

string

The last name of the new participant

ipAddress

string

The IP address of the new participant (if provided, this property will be used for anti-fraud measurements)

metadata

object

A shallow Object containing custom key/values to include with the participant data.

{
    "id": "3vxff9",
    "firstName": "Gavin",
    "lastName": "Belson",
    "referralCount": 0,
    "monthlyReferralCount": 0,
    "prevMonthlyReferralCount": 0,
    "rank": 10001,
    "monthlyRank": 10001,
    "shareUrl": "https://hoolie.com?grsf=3vxff9",
    "rewards": [],
    "email": "gavin@hooli.com",
    "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
    },
    "vanityKeys": [
        "gavin-f8g9nl"
    ]

Metadata: Please see our API Guidelines for more information about metadata.

What's a campaign referral trigger?

You can update the campaign referral trigger in the Installation step of the Campaign Editor (see image). Depending on what you select, the API will automatically set a default value for the participant:

  • If the referral trigger is Sign up + Qualifying Action, then referralStatus will default to CREDIT_PENDING

  • If the referral trigger is Sign Up, then referralStatus will default to CREDIT_AWARDED

Trigger Referral by Participant ID

POST https://api.growsurf.com/v2/campaign/:id/participant/:participantId/ref

Triggers a referral using an existing participant's ID, awarding referral credit to the referrer of the existing participant.

Path Parameters

NameTypeDescription

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 referralStatus has a value of CREDIT_PENDING

  • 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 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 participant's email address, awarding referral credit to the referrer of the existing participant.

Path Parameters

NameTypeDescription

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 referralStatus has a value of CREDIT_PENDING

  • 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.

  • 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

NameTypeDescription

id*

string

The ID of the campaign

participantId*

string

The ID of the participant

Request Body

NameTypeDescription

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.

email

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.

{
    "id": "f8g9nl",
    "firstName": "Gavin",
    "lastName": "Belson",
    "referralCount": 2,
    "monthlyReferralCount": 2,
    "prevMonthlyReferralCount": 0,
    "rank": 10001,
    "monthlyRank": 10001,
    "shareUrl": "https://piedpiper.com?grsf=f8g9nl",
    "email": "gavin@hoolie.com",
    "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": "richard@piedpiper.com",
        "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"
        ]        
    },
    "metadata": {
       "company": "Hooli, Inc",
       "companySize": 10000
    },    
    "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

NameTypeDescription

id*

string

The campaign ID

participantEmail*

string

The participant email

Request Body

NameTypeDescription

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.

email

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.

{
    "id": "f8g9nl",
    "firstName": "Gavin",
    "lastName": "Belson",
    "referralCount": 2,
    "monthlyReferralCount": 2,
    "prevMonthlyReferralCount": 0,
    "rank": 10001,
    "monthlyRank": 10001,
    "shareUrl": "https://piedpiper.com?grsf=f8g9nl",
    "email": "gavin@hoolie.com",
    "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": "richard@piedpiper.com",
        "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"
        ]        
    },
    "metadata": {
       "company": "Hooli, Inc",
       "companySize": 10000
    },    
    "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

NameTypeDescription

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

NameTypeDescription

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