API Reference
Easily test these API methods dynamically by using our Postman Collection
getGet Campaign
get
https://api.growsurf.com/v2/campaign/:id
Retrieves a campaign for the given ID.
Request
Response
Request
Path Parameters
id
required
string
The ID of the campaign to retrieve
Response
200: OK
Returns the campaign object
{"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"}]}
getGet 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.
Request
Response
Request
Response
200: OK
{"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"}]}]}
getGet 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.
Request
Response
Request
Path Parameters
id
required
string
The ID of the campaign to retrieve the participant from
participantId
required
string
The ID of the participant to retrieve
Response
200: OK
Returns the participant object.
{"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": "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"]},"rewards": [{"id": "dgaiuk","rewardId": "oe1cjt","status": "FULFILLED","unread": true,"isReferrer": true,"isAvailable": true,"approved": true,"isFulfilled": true"referredId": "xh345d","referrerId": "f8g9nl"}]}
getGet 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.
Request
Response
Request
Path Parameters
id
required
string
The ID of the campaign to retrieve the participant from
participantEmail
required
string
The email of the participant to retrieve
Response
200: OK
Returns the participant object.
{"id": "f8g9nl","firstName": "Gavin","lastName": "Belson","referralCount": 2,"monthlyReferralCount": 2,"prevMonthlyReferralCount": 0,"rank": 10001,"monthlyRank": 50,"prevMonthlyRank": -1,"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": 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"]},"rewards": [{"id": "dgaiuk","rewardId": "oe1cjt","status": "FULFILLED","unread": true,"isReferrer": true,"isAvailable": true,"approved": true,"isFulfilled": true,"referredId": "xh345d","referrerId": "f8g9nl"}]}
getGet Participants
get
https://api.growsurf.com/v2/campaign/:id/participants
Retrieves a list of participants in the campaign.
Request
Response
Request
Path Parameters
id
required
string
The ID of the campaign
Query Parameters
nextId
optional
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
optional
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.
Response
200: OK
{"participants": [{"id": "3vxff9","firstName": "Gavin","lastName": "Belson","referralCount": 0,"monthlyReferralCount": 0,"prevMonthlyReferralCount": 0,"rank": 10001,"monthlyRank": 50,"prevMonthlyRank": -1,"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": 3,"referrals": [],"referrer": null,"rewards": []},{"id": "f8g9nl","firstName": "Gavin","lastName": "Belson","referralCount": 2,"monthlyReferralCount": 2,"prevMonthlyReferralCount": 721,"rank": 10002,"monthlyRank": 110,"prevMonthlyRank": 1,"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": 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"]},"rewards": []}],"limit": 2,"nextId": "1u7v0q"}
getGet 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.Request
Response
Request
Path Parameters
id
required
string
The ID of the campaign
Query Parameters
nextId
optional
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
optional
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
optional
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
optional
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).Response
200: OK
Example response of the standard leaderboard with returned participants order by their referral count. If the
leaderboardType=CURRENT_MONTH query parameter is provided, the resulting list would be ordered by monthly referral count.
Similarly, if leaderboardType=PREV_MONTH is provided, the resulting list would be ordered by the previous monthly referral count.{"participants": [{"id": "3vxff9","firstName": "Gavin","lastName": "Belson","referralCount": 1000,"monthlyReferralCount": 10,"prevMonthlyReferralCount": 990,"rank": 1,"monthlyRank": 10,"prevMonthlyRank": 10,"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": [],"referrer": null,"rewards": []},{"id": "f8g9nl","firstName": "Gavin","lastName": "Belson","referralCount": 900,"monthlyReferralCount": 9,"prevMonthlyReferralCount": 800,"rank": 2,"monthlyRank": 11,"prevMonthlyRank": 20,"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"],"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,"referrals": ["0dveu7","f8g9nl","j0hbym","m5xm9l","w01fil"]},"rewards": []}],"limit": 2,"nextId": "1u7v0q"}
postAdd Participant
post
https://api.growsurf.com/v2/campaign/:id/participant
Adds a participant to the campaign.
Request
Response
Request
Path Parameters
id
required
string
The ID of the campaign to add the new participant to
Body Parameters
email
required
string
The email of the new participant
referredBy
optional
string
Set a referrer for this participant by providing the referrer's unique ID or email
referralStatus
optional
string
Set the referral credit status of this new participant's referrer to
CREDIT_PENDING or CREDIT_AWARDED (Note: referralStatus must be used with referredBy).
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
optional
string
The first name of the new participant
lastName
optional
string
The last name of the new participant
ipAddress
optional
string
The IP address of the new participant (if provided, this property will be used for anti-fraud measurements)
metadata
optional
object
A shallow Object containing custom key/values to include with the participant data.
Response
200: OK
Example response of participant that was added to the campaign.
Returns the participant object.
{"id": "3vxff9","firstName": "Gavin","lastName": "Belson","referralCount": 0,"monthlyReferralCount": 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}
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 Custom Event, then
referralStatuswill default toCREDIT_PENDINGIf the referral trigger is Signup Event, then
referralStatuswill default toCREDIT_AWARDED
postTrigger Referral by Participant ID
post
https://api.growsurf.com/v2/campaign/:id/participant/:participantId/ref
Triggers a referral, awarding referral credit to the referrer of an existing participant.
Request
Response
Request
Path Parameters
id
required
string
The ID of the campaign
participantId
required
string
The ID of the referred participant
Response
200: OK
Returns an object with a
successattribute equal to true if referral credit was awarded otherwise false.
Referral Credit Has Already Been Rewarded
If you call this endpoint after referral credit has already been credited to the referrer, success will be returned as false and the message will be "Referral credit has already been awarded" in the returned response.
Participant Was not Referred
If you call this endpoint and the participant was not referred, success will be returned as false and the message will be "Participant was not referred" in the returned response.
We do not respond with an error or a error status code so that this endpoint can be invoked without needing to know the current referral state of the participant. Please make sure the check the values within the response body.{"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 Custom Event (see image). If the referral trigger is set to Signup Event, triggering referrals will not work since referral credit has already been provided.
postTrigger Referral by Participant Email
post
https://api.growsurf.com/v2/campaign/:id/participant/:participantEmail/ref
Triggers a referral using an existing participant's email, awarding referral credit to the referrer of the existing participant.
Request
Response
Request
Path Parameters
id
required
string
The ID of the campaign
participantEmail
required
string
The email of the referred participant
Response
200: OK
Returns an object with a success attribute equal to true if referral credit was awarded otherwise false.
Referral Credit Has Already Been Rewarded
If you call this endpoint after referral credit has already been credited to the referrer you
success will be false and the message will be "Referral credit has already been awarded" in the returned response.
Participant Was not Referred
If you call this endpoint and the participant was not referred success will be false and the message will be "Participant was not referred" in the returned response.
We do not respond with an error or an error status code so that this endpoint can be invoked without needing to know the current state of the participant. Please make sure the check the values within the response body.{"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 Custom Event (see image). If the referral trigger is set to Signup Event, triggering referrals will not work since referral credit has already been provided.
postUpdate 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.
Request
Response
Request
Path Parameters
id
required
string
The ID of the campaign
participantId
required
string
The ID of the participant
Body Parameters
referredBy
optional
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
optional
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
optional
string
The first name of the participant.
lastName
optional
string
The last name of the participant
metadata
optional
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.*
referralStatus
optional
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.Response
200: OK
Returns the updated participant object
{"id": "f8g9nl","firstName": "Gavin","lastName": "Belson","referralCount": 2,"monthlyReferralCount": 2,"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"]},"rewards": [{"id": "dgaiuk","rewardId": "oe1cjt","status": "PENDING","unread": true,"isReferrer": true,"isAvailable": false,"approved": false,"isFulfilled": false,"referredId": "xh345d","referrerId": "f8g9nl"}]}
*Please see our API Guidelines for more information about metadata.
postUpdate 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.
Request
Response
Request
Path Parameters
id
required
string
The campaign ID
participantEmail
required
string
The participant email
Body Parameters
referredBy
optional
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
optional
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
optional
string
The first name of the participant
lastName
optional
string
The last name of the participant
metadata
optional
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.*
referralStatus
optional
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.Response
200: OK
Returns the updated participant object
{"id": "f8g9nl","firstName": "Gavin","lastName": "Belson","referralCount": 2,"monthlyReferralCount": 2,"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"]},"rewards": [{"id": "dgaiuk","rewardId": "oe1cjt","status": "PENDING","unread": true,"isReferrer": true,"isAvailable": false,"approved": false,"isFulfilled": false,"referredId": "xh345d","referrerId": "f8g9nl"}]}
*Please see our API Guidelines for more information about metadata.
deleteRemove 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.
Request
Response
Request
Path Parameters
id
required
string
The ID of the campaign
participantId
required
string
The ID of the participant
Response
200: OK
Returns a success object
{"success": true}
deleteRemove 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.
Request
Response
Request
Path Parameters
id
required
string
The campaign ID
participantEmail
required
string
The participant email
Response
200: OK
Returns a success object
{"success": true}
getGet 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.
Request
Response
Request
Path Parameters
id
optional
string
The campaign ID
participantId
optional
string
The participant's unique ID or email
Query Parameters
nextId
optional
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
optional
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.
Response
200: OK
In this example we are showing two rewards earned by the participant.
isReferrer
The isReferrer value will be true if the participant earned the reward by referring another participant.
status
The status value will be PENDING if the reward has not yet been fulfilled otherwise, it will be FULFILLED.
isAvailable
The isAvailable value will be true if the reward has been approved either manually or automatically, depending on the campaign settings and fulfilled. Otherwise it will be set to false.
referredId
The participant id of the person that was referred and that triggered this reward.
referrerId
The id of the participant that made the referral.{"limit": 2,"nextId": "v2qtfq","rewards": [{"id": "rr35mg","rewardId": "c6w1qo","status": "PENDING","unread": true,"approved": false,"isReferrer": true,"isAvailable": false,"isFulfilled": false,"referredId": "xh345d","referrerId": "f8g9nl"},{"id": "oltj0s","rewardId": "c6w1qo","status": "FULFILLED","unread": false,"approved": true,"isReferrer": false,"isAvailable": true,"isFulfilled": true,"referredId": "zyx765","referrerId": "f8g9nl"}]}
400: Bad Request
Error response returned if the
limit query parameter that is provided exceeds the maximum allowed amount.{"name": "BadRequestError","code": "BAD_REQUEST_ERROR","message": "Invalid request. Request params are missing or are invalid","status": 400,"supportUrl": "http://localhost:3000/settings#contact_support","errors": [{"location": "query","param": "limit","value": "20","msg": "Limit cannot be more than 10."}],"level": "error","timestamp": "2019-12-31T22:07:49.957Z"}
getGet 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.Request
Response
Request
Path Parameters
id
optional
string
The id of the campaign.
participantEmail
optional
string
The participant email
Query Parameters
nextId
optional
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
optional
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.
Response
200: OK
See Get Participant Rewards by ID endpoint for a more detailed description of the response.
{"limit": 2,"nextId": "v2qtfq","rewards": [{"id": "rr35mg","rewardId": "c6w1qo","status": "PENDING","unread": true,"approved": false,"isReferrer": true,"isAvailable": false,"isFulfilled": false,"referredId": "xh345d","referrerId": "f8g9nl"},{"id": "oltj0s","rewardId": "c6w1qo","status": "FULFILLED","unread": false,"approved": true,"isReferrer": false,"isAvailable": true,"isFulfilled": true,"referredId": "zyx765","referrerId": "f8g9nl"}]}
postApprove Participant Reward
post
https://api.growsurf.com/v2/campaign/:id/reward/:rewardId/approve
Approve 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 is pending approval.
Request
Response
Request
Path Parameters
id
required
string
The campaign ID
rewardId
required
string
The ID of the participant reward to approve
Body Parameters
fulfill
optional
boolean
Set
true to mark the reward as fulfilledResponse
200: OK
Returns a success response.
{"success": true}
406: Not Acceptable
Error response returned if a reward has already been approved for a participant.
{"name": "InvalidRewardState","code": "INVALID_REWARD_STATE","message": "Invalid reward state. Reward has already been approved.","status": 406,"supportUrl": "https://growsurf.com/settings#contact_support","level": "error","timestamp": "2019-10-13T16:43:05.902Z"}
postFulfill Participant Reward
post
https://api.growsurf.com/v2/campaign/:id/reward/:rewardId/fulfill
Fulfill 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 been approved.
Request
Response
Request
Path Parameters
id
required
string
The campaign ID
rewardId
required
string
The ID of the participant reward to fulfill
Response
200: OK
{"success": true}
406: Not Acceptable
Error response returned if a reward has not been approved or has already been fulfilled.
{"name": "InvalidRewardState","code": "INVALID_REWARD_STATE","message": "Invalid reward state. Reward has already been fulfilled.","status": 406,"supportUrl": "https://growsurf.com/settings#contact_support","level": "error","timestamp": "2019-10-13T16:43:05.902Z"}
deleteRemove 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.
Request
Response
Request
Path Parameters
id
required
string
The campaign ID
rewardId
required
string
The ID of the participant reward to remove
Response
200: OK
{"success": true}
406: Not Acceptable
{"name": "InvalidRewardState","code": "INVALID_REWARD_STATE","message": "Invalid reward state. This reward has already been approved and cannot be removed.","status": 406,"supportUrl": "https://growsurf.com/settings#contact_support","level": "error","timestamp": "2019-10-17T16:43:05.902Z"}
getGet Referrals
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.
Request
Response
Request
Path Parameters
id
required
string
The ID of the campaign
Query Parameters
sortBy
optional
string
If provided, will sort the results by the provided field. Valid sortBy options are
updatedAt, createdAt, email, firstName, lastName, referralStatus.
By default, results are sorted by the updatedAt timestamp in descending (most recent first) order.desc
optional
boolean
Defaults to
true, returning results in descending (most recent first) order.
Set desc to false to return results in ascending order.limit
optional
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
optional
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.
email
optional
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
optional
string
If provided, filters results by the given first name value
lastName
optional
string
If provided, filters results by the given last name value
referralStatus
optional
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.Response
200: OK
This is an example response for this request. You will notice that invites are fully masked for data privacy and security purposes. Once the invite has been accepted and the invitee signs up or opts in as a participant for your campaign their email will be available.
{"referrals": [{"id": "f2bukr","email": "gavin@hooli.com","firstName": "Gavin","lastName": "Belson","referralStatus": "CREDIT_AWARDED","referredBy": "2khaha","createdAt": 1591546112223,"updatedAt": 1591546285013},{"id": "qbp153","email": "richard@piedpiper.com","firstName": "Richard","lastName": "Hendricks","referralStatus": "CREDIT_PENDING","referredBy": "abckj2","createdAt": 1591542657835,"updatedAt": 1591542658457},{"id": "ghw131","email": "danish@piedpiper.com","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}
getGet Participant Referrals 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 cached will be purged.
Request
Response
Request
Path Parameters
id
required
string
The campaign ID
participantId
required
string
The participant ID
Query Parameters
sortBy
optional
string
If provided, will sort results by the provided field.
Valid options are
updatedAt, createdAt, email, firstName, lastName, referralStatus.
By default, the results are sorted by the updatedAt timestamp in descending (most recent first) order.desc
optional
string
Defaults to true, returning results in descending (most recent first) order.
Set
desc to false to return results in ascending order.limit
optional
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
optional
string
The offset number to start the result set at. This can be used to skip the list or page the list of results.
email
optional
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
optional
string
If provided, filters results by the given first name value
lastName
optional
string
If provided, filters results by the given last name value
referralStatus
optional
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.Response
200: OK
This is an example response for this request.
{"referrals": [{"id": "f2bukr","email": "gavin@hooli.com","firstName": "Gavin","lastName": "Belson","referralStatus": "CREDIT_AWARDED","referredBy": "2khaha","createdAt": 1591546112223,"updatedAt": 1591546285013},{"id": "qbp153","email": "richard@piedpiper.com","firstName": "Richard","lastName": "Hendricks","referralStatus": "CREDIT_PENDING","referredBy": "2khaha","createdAt": 1591542657835,"updatedAt": 1591542658457},{"id": "ghw131","email": "danish@piedpiper.com","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}
getGet Participant Referrals 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.
Request
Response
Request
Path Parameters
id
required
string
The campaign ID
participantEmail
required
string
The email of the participant to retrieve the referrals for
Query Parameters
sortBy
optional
string
If provided, will sort results by the provided field.
Valid options are
updatedAt, createdAt, email, firstName, lastName, referralStatus.
By default, the results are sorted by the updatedAt timestamp in descending (most recent first) order.