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. Just change the Token in the Authorizations tab, and the campaign_id variable to the program you're working on.
CAMPAIGNS ↓
Get Campaign
GET https://api.growsurf.com/v2/campaign/:id
Retrieves a program for the given program ID.
Path Parameters
id*
string
The ID of the program to retrieve
Response
Returns the program.
{
"id": "abc123",
"name": "Middle Out Compression Campaign",
"type": "REFERRAL",
"referralCount": 121,
"participantCount": 199,
"impressionCount": 199,
"inviteCount": 237,
"winnerCount": 1,
"currencyISO": "USD",
"status": "IN_PROGRESS",
"rewards": [
{
"id": "crew_xyz789",
"type": "DOUBLE_SIDED",
"description": "Refer a friend and get a Pied Piper T-Shirt",
"referralDescription": "Join and receive middle out compression algorithm",
"isUnlimited": false,
"limit": 1,
"conversionsRequired": 1,
"numberOfWinners": 3,
"imageUrl": "http://res.cloudinary.com/growsurf/image/upload/v1552764861/development/hxdcjrayfhksvxu5u6oz.png",
"metadata": {}
}
]
}Get Campaigns
GET https://api.growsurf.com/v2/campaigns
Retrieves a list of your programs. Programs that have been deleted will not be returned in this response.
Response
Returns the programs.
PARTICIPANTS ↓
Get Participant by ID
GET https://api.growsurf.com/v2/campaign/:id/participant/:participantId
Retrieves a single participant from a program using the given participant ID.
Path Parameters
id*
string
The ID of the program to retrieve the participant from
participantId*
string
The ID of the participant to retrieve
Response
Returns the participant object.
Get Participant by Email
GET https://api.growsurf.com/v2/campaign/:id/participant/:participantEmail
Retrieves a single participant from a program using the given participant email.
Path Parameters
id*
string
The ID of the program to retrieve the participant from
participantEmail*
string
The email address of the participant to retrieve
Response
Returns the participant object.
Get Participants
GET https://api.growsurf.com/v2/campaign/:id/participants
Retrieves a list of participants in the program.
Path Parameters
id*
string
The ID of the program
Query Parameters
nextId
string
(Optional)
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
(Optional) 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
Returns the participant objects.
Get Leaderboard
GET https://api.growsurf.com/v2/campaign/:id/leaderboard
Retrieves a list of participants in the program ordered by referral count in ascending order.
Monthly Referral Count Leaderboard You can retrieve the program leaderboard ordered by the monthly referral count by providing a query parameter
leaderboardTypewith a value ofCURRENT_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 program, therefore results of the monthly referral count may vary.Previous Monthly Referral Count Leaderboard Similar to the monthly program leaderboard, providing a query parameter of
leaderboardTypewith a value ofPREV_MONTHwill retrieve a list of participants order by the previous monthly referral count. Participants that did not exist within the program during the previous month will not be returned within the previous monthly leaderboard response.
Path Parameters
id*
string
The ID of the program
Query Parameters
nextId
string
(Optional)
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
(Optional) 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
(Optional)
If true will return the leaderboard for monthly referral counts. Default is false.
Deprecated Notice:
This currently works but will be removed in future API versions. 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 program during the previous month will not be returned).
TOTAL_IMPRESSION_COUNT - Returns the leaderboard based on all-time total impression counts.
UNIQUE_IMPRESSION_COUNT - Returns the leaderboard based on all-time unique impression counts.
BY_COMMISSIONS - [Only applies to affiliate programs] Returns the leaderboard based on all-time total commission amount earned.
BY_REVENUE - [Only applies to affiliate programs] Returns the leaderboard based on all-time total revenue amount driven.
BY_REFERRALS - [Only applies to affiliate programs] Returns the leaderboard based on total all-time referrals (qualified/converted referrals).
BY_LEADS - [Only applies to affiliate programs] Returns the leaderboard based on total all-time leads (pending referrals)
Response
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.
Add Participant
POST https://api.growsurf.com/v2/campaign/:id/participant
Adds a new participant to the program. This includes both referrers and referred friends.
If the participant with the same email address already exists, then the existing participant will be returned.
Path Parameters
id*
string
The ID of the program to add the new participant to
Request Body
email*
string
The email address of the new participant
referredBy
string
(Optional)
Set a referrer for this participant by providing the referrer's unique ID or email.
To get the referrer's unique ID, you can call growsurf.getReferrerId() from the front-end.
referralStatus
string
(Optional)
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 program.
firstName
string
(Optional, but recommended) The first name of the new participant. If provided, this property will be used for anti-fraud measurements.
lastName
string
(Optional, but recommended)
The last name of the new participant. If provided, this property will be used for anti-fraud measurements.
ipAddress
string
(Optional, but recommended) The IP address of the new participant. If provided, this property will be used for anti-fraud measurements.
fingerprint
string
(Optional, but recommended)
The browser fingerprint of the new participant. If provided, this property will be used for anti-fraud measurements.
We recommend using a front-end library like fingerprintjs to get the fingerprint value. Example value: cfb163bd47ba666c52cb932c521e47f4.
metadata
object
(Optional) A shallow Object containing custom key/values to include with the participant data.
The following keys are restricted: gdprAgreements
Request Examples
Here are example cURL commands you can use to call this API endpoint. Remember to replace YOUR_PROGRAM_ID with your program ID, [email protected] with the email address of the new participant you're adding, and YOUR_API_KEY with your API key.
We pass in firstName, lastName, ipAddress and fingerprint for anti-fraud purposes. metadata is used to save any custom data that can be retrieved later.
If you want to add a new referred participant, make sure to pass in referredBy.
Response
Returns the participant object that was added to the program.
A 400 will be returned if validation fails on an input.
A 409 error will be returned if the request is a duplicate.
If the new participant is detected to be a high-level fraudster, and if anti-fraud settings are configured on the program, the participant will be blocked from joining with a status code of 422.
View the list of available fraudRiskLevel and fraudReasonCode options on the Participant Object. matchedParticipantIds will contain a list of matching fraudsters, but will be empty if an antifraud blacklist rule gets a match first.
Metadata: Please see our API Guidelines for more information about metadata.
Trigger Referral by Participant ID
POST https://api.growsurf.com/v2/campaign/:id/participant/:participantId/ref
Triggers a referral using an existing referred participant's ID, awarding referral credit to their referrer.
Path Parameters
id*
string
The ID of the program
participantId*
string
The ID of the referred participant
Response
Returns an object with a success attribute equal to true if referral credit was awarded, otherwise false.
If referral credit has already been awarded, success will be false and the message will be "Referral credit has already been awarded".
If the participant was not referred, success will be false and the message will be "Participant was not referred".
Important Notes:
Referral credit will only be awarded to the referrer if the participant
referralStatushas a value ofCREDIT_PENDINGMake sure your referral program'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 program 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.
Responses do not contain errors or error status codes so that the endpoint can be invoked without needing to know the current state of the participant. Please make sure to check the values within the response body.
Trigger Referral by Participant Email
POST https://api.growsurf.com/v2/campaign/:id/participant/:participantEmail/ref
Triggers a referral using an existing referred participant's email address, awarding referral credit to their referrer.
Path Parameters
id*
string
The ID of the program
participantEmail*
string
The email address of the referred participant
Response
Returns an object with a success attribute equal to true if referral credit was awarded, otherwise false.
If referral credit has already been awarded, success will be false and the message will be "Referral credit has already been awarded".
If the participant was not referred, success will be false and the message will be "Participant was not referred".
Important Notes:
Referral credit will only be awarded to the referrer if the participant
referralStatushas a value ofCREDIT_PENDINGMake sure your program'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 referral program 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.
Responses do not contain errors or error status codes so that the endpoint can be invoked without needing to know the current state of the participant. Please make sure to check the values within the response body.
Update Participant by ID
POST https://api.growsurf.com/v2/campaign/:id/participant/:participantId
Updates a participant within the program using the ID of the participant.
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
id*
string
The ID of the program
participantId*
string
The ID of the participant
Request Body
referredBy
string
(Optional) 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.
string
(Optional) The new email to assign to this participant. If the given email is already assigned to another participant within the program, an error response will be returned.
firstName
string
(Optional) The first name of the participant.
lastName
string
(Optional) The last name of the participant
metadata
object
(Optional)
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
(Optional)
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
(Optional) 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.
unsubscribed
boolean
(Optional)
The participant's unsubscribed status. If true, they will not receive any program emails.
Response
Returns the updated participant object.
*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 program using the email address 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
id*
string
The program ID
participantEmail*
string
The participant email
Request Body
referredBy
string
(Optional) 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.
string
(Optional) The new email to assign to the participant. If the given email is already assigned to another participant within the program, an error response will be returned.
firstName
string
(Optional) The first name of the participant
lastName
string
(Optional) The last name of the participant
metadata
object
(Optional)
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
(Optional)
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
(Optional) 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.
unsubscribed
boolean
(Optional)
The participant's unsubscribed status. If true, they will not receive any program emails.
Response
Returns the updated participant object.
*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 program using the ID of the participant.
(Looking to remove a bulk list of participants using a CSV file? View this tutorial).
Path Parameters
id*
string
The ID of the program
participantId*
string
The ID of the participant
Response
Returns a success response.
Remove Participant by Email
DELETE https://api.growsurf.com/v2/campaign/:id/participant/:participantEmail
Removes a participant within the program using the email address of the participant.
(Looking to remove a bulk list of participants using a CSV file? View this tutorial).
Path Parameters
id*
string
The program ID
participantEmail*
string
The participant email
Response
Returns a success response.
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
id*
string
The ID of the program
participantId*
string
The participant's unique ID or email
Query Parameters
nextId
string
(Optional)
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
string
(Optional) 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
In this example we are showing two rewards earned by the participant.
isReferrer will be true if the participant earned the reward by referring another participant.
status will be "PENDING" if the reward has not yet been fulfilled, otherwise it will be "FULFILLED".
isAvailable will be true if the reward has been approved either manually or automatically (depending on the program settings) and fulfilled, otherwise it will be set to false.
referredId is the participant ID of the referred friend (this person caused the referral to be triggered by performing a qualifying action).
referrerId is the participant ID of the referrer.
Error response returned if the limit query parameter that is provided exceeds the maximum allowed amount.
Get 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.
Path Parameters
id*
string
The ID of the program
participantEmail*
string
The email address of the participant
Query Parameters
nextId
string
(Optional)
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
string
(Optional) 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
In this example we are showing two rewards earned by the participant.
isReferrer will be true if the participant earned the reward by referring another participant.
status will be "PENDING" if the reward has not yet been fulfilled, otherwise it will be "FULFILLED".
isAvailable will be true if the reward has been approved either manually or automatically (depending on the program settings) and fulfilled, otherwise it will be set to false.
referredId is the participant ID of the referred friend (this person caused the referral to be triggered by performing a qualifying action).
referrerId is the participant ID of the referrer.
Error response returned if the limit query parameter that is provided exceeds the maximum allowed amount.
Approve Participant Reward
POST https://api.growsurf.com/v2/campaign/:id/reward/:rewardId/approve
Approve a reward that was earned by a participant.
You should only use this endpoint if your reward automation level is set to Manually approve rewards (learn more here). This means ParticipantRewards will be generated with status: "PENDING", approved: false, and isFulfilled: false.
Calling this endpoint to approve a reward will cause New Participant Reward emails to be sent out and automations/integrations to be triggered. If you are using Webhooks to automate rewards, a new PARTICIPANT_REACHED_A_GOAL event will be emitted with data.reward.approved as false.
Path Parameters
id*
string
The program ID
rewardId*
string
The ID of the participant reward to approve
Request Body
fulfill
boolean
(Optional)
Set true to mark the reward as fulfilled.
Fulfilling a reward does not trigger any emails or automations. It helps you stay organized when managing rewards from your GrowSurf admin dashboard (e.g, you won't see any red notifications reminding you to fulfill rewards -- see video here).
Response
Returns a success response.
Error response returned if a reward has already been approved for a participant.
Fulfill Participant Reward
POST https://api.growsurf.com/v2/campaign/:id/reward/:rewardId/fulfill
Fulfill a reward that was earned by a participant (this can only be done if the reward is already approved). When you call this endpoint, the ParticipantReward should have the following key-values: status: "PENDING", approved: true, and isFulfilled: false.
Fulfilling a reward does not trigger any emails or automations. It helps you stay organized when managing rewards from your GrowSurf admin dashboard (e.g, you won't see any red notifications reminding you to fulfill rewards -- see video here).
Path Parameters
id*
string
The program ID
rewardId*
string
The ID of the participant reward to fulfill
Response
Returns a success response.
Error response returned if a reward has not been approved or has already been fulfilled.
Remove 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 program was configured with manual reward approval and if the provided participant reward has not already been approved.
Path Parameters
id*
string
The program ID
rewardId*
string
The ID of the participant reward to remove
Response
Returns a success response.
Error response returned if a reward has already been approved and thus cannot be deleted.
REFERRALS AND INVITES ↓
Get Referrals and Invites
GET https://api.growsurf.com/v2/campaign/:id/referrals
Retrieves a list of all referrals and email invites made by participants in a program. 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 program that cache will be purged.
Path Parameters
id*
string
The ID of the program
Query Parameters
sortBy
string
(Optional)
If provided, will sort the results by the provided field. Valid sortBy options are updatedAt, createdAt, email, referralTriggeredAt.
By default, results are sorted by the updatedAt timestamp in descending (most recent first) order.
desc
boolean
(Optional)
Defaults to true, returning results in descending (most recent first) order.
Set desc to false to return results in ascending order.
limit
number
(Optional) 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
number
(Optional) 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.
string
(Optional)
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
string
(Optional) If provided, filters results by the given first name value
lastName
string
(Optional) If provided, filters results by the given last name value
referralStatus
string
(Optional)
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.
nextId
string
(Optional)
The ID of the result 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, based on the provided sortBy value, if there are more results otherwise the nextId value will be null.
A boolean field more will always be present for determining if there are more results.
Response
This is an example response for this endpoint. 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 program their email will be available.
Get Participant Referrals and Invites 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 program. 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 program that cache will be purged.
Path Parameters
id*
string
The program ID
participantId*
string
The participant ID
Query Parameters
sortBy
string
(Optional)
If provided, will sort results by the provided field.
Valid options are updatedAt, createdAt, email, referralTriggeredAt.
By default, the results are sorted by the updatedAt timestamp in descending (most recent first) order.
desc
string
(Optional)
Defaults to true, returning results in descending (most recent first) order.
Set desc to false to return results in ascending order.
limit
string
(Optional) 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
string
(Optional) The offset number to start the result set at. This can be used to skip the list or page the list of results.
string
(Optional)
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
string
(Optional) If provided, filters results by the given first name value
lastName
string
(Optional) If provided, filters results by the given last name value
referralStatus
string
(Optional)
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.
nextId
string
(Optional)
The ID of the result 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, based on the provided sortBy value, if there are more results otherwise the nextId value will be null.
A boolean field more will always be present for determining if there are more results.
Response
This is an example response for this endpoint.
Get Participant Referrals and Invites 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 program. 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 program that cache will be purged.
Path Parameters
id*
string
The program ID
participantEmail*
string
The email address of the participant to retrieve the referrals for
Query Parameters
sortBy
string
(Optional)
If provided, will sort results by the provided field.
Valid options are updatedAt, createdAt, email, referralTriggeredAt.
By default, the results are sorted by the updatedAt timestamp in descending (most recent first) order.
desc
string
(Optional)
Defaults to true, returning results in descending (most recent first) order.
Set desc to false to return results in ascending order.
limit
string
(Optional) 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
string
(Optional) The offset number to start the result set at. This can be used to skip the list or page the list of results.
string
(Optional)
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
string
(Optional) If provided, filters results by the given first name value
lastName
string
(Optional) If provided, filters results by the given last name value
referralStatus
string
(Optional)
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.
nextId
string
(Optional)
The ID of the result 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, based on the provided sortBy value, if there are more results otherwise the nextId value will be null.
A boolean field more will always be present for determining if there are more results.
Response
This is an example response for this endpoint.
Send Participant Invites by ID
POST https://api.growsurf.com/v2/campaign/:id/participant/:participantId/invites
Sends email invites on behalf of a participant to a list of email addresses.
NOTE: Your program must have a custom 'From' email address in order for email invites to be sent out. Learn more here.
Path Parameters
id*
string
The program ID
participantId*
string
The participant ID
Request Body
emailAddresses*
array
A list of email addresses to send invites to
messageText*
string
The email message body.
Make sure to include {{referrerMessage}} in the contents, which will be interpolated with the participant's personalized message.
You can also pass in the following values:
{{referrerFirstName}}
{{referrerLastName}}
{{referrerEmail}}
{{referrerShareUrl}}
subjectText*
string
The email subject line.
You can pass in the following values:
{{referrerFirstName}}
{{referrerLastName}}
{{referrerEmail}}
{{referrerMessage}}
{{referrerShareUrl}}
Response
This is an example response for this request.
Send Participant Invites by Email
POST https://api.growsurf.com/v2/campaign/:id/participant/:participantEmail/invites
Sends email invites on behalf of a participant to a list of email addresses.
Important Note: Your program must have a custom 'From' email address in order for email invites to be sent out. Learn more here.
Path Parameters
id*
string
The program ID
participantEmail*
string
The participant's email address
Request Body
emailAddresses*
array
A list of email addresses to send invites to
messageText*
string
The email message body.
Make sure to include {{referrerMessage}} in the contents, which will be interpolated with the participant's personalized message.
You can also pass in the following values:
{{referrerFirstName}}
{{referrerLastName}}
{{referrerEmail}}
{{referrerShareUrl}}
subjectText*
string
The email subject line.
You can pass in the following values:
{{referrerFirstName}}
{{referrerLastName}}
{{referrerEmail}}
{{referrerMessage}}
{{referrerShareUrl}}
Response
This is an example response for this request.
ANALYTICS ↓
Get Campaign Analytics
GET https://api.growsurf.com/v2/campaign/:id/analytics
Retrieves the analytics for a program.
Path Parameters
id*
string
The ID of the program to retrieve analytics for.
days
integer
(Optional)
The last number of days to retrieve analytics for. Defaults to 365 if no value is provided. Maximum limit is 1825.
startDate
integer
(Optional but required if days is not set)
The start date of the analytics timeframe as a Unix timestamp in milliseconds. Example value: 1592359793538.
endDate
integer
(Optional but required if days is not set)
The end date of the analytics timeframe as a Unix timestamp in milliseconds. Example value: 1747879793538.
Response
Returns an analytics object for the program.
AFFILIATE PROGRAMS ↓
Add Transaction by Participant Email
POST https://api.growsurf.com/v2/campaign/:id/participant/:participantEmail/transaction
[Only applies to affiliate programs] Records a sale made by a referred customer (identified by their GrowSurf participant email) and generates affiliate commissions for their referrer when applicable.
Path Parameters
id*
string
The ID of the program
participantEmail*
string
The email address of the GrowSurf participant. This is your customer that sent you a payment.
Request Body
grossAmount*
integer
Total sale amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). Must be a positive integer and is the baseline amount recorded for the sale.
Example values:
$5.00 is 500
$899.00 is 89900
$25,581.99 is 2558199
¥500 is 500
¥89,900 is 89900
¥2,558,199 is 2558199
invoiceId,
chargeId, paymentIntentId,
transactionId, externalId,
orderId,
paymentId
string
(Optional)
Providing at least one of these fields ensures idempotency for each payment. This ensures the same sale isn’t recorded twice (thus avoiding a duplicate commission being generated).
We recommend using invoiceId, chargeId, paymentId, or paymentIntentId as these will check against duplicate sales from other providers (e.g, Stripe). Otherwise, idempotency checks will only check for duplicates from sales that were recording using the API [and not a provider integration like Stripe].
netAmount
integer
(Optional)
Net-of-tax amount in minor units. If supplied, it becomes the preferred base for commission calculations without further derivation.
taxAmount
integer
(Optional)
Total tax collected in minor units. Used when netAmount is absent so we can back into a net figure (grossAmount - taxAmount).
amountCashNet
integer
(Optional) Explicit post-tax cash amount in minor units. Overrides any derived net amount; send this if you already know the exact commissionable base.
amountPaid
integer
(Optional) Amount the payment processor confirms was actually paid (minor units). Optional pass-through for reconciliation.
paidAt†
integer
(Optional) Unix timestamp in milliseconds when the payment actually occurred. GrowSurf uses this value to evaluate commission duration and intro windows; if you omit it, we fall back to the time the API call is received.
description
string
(Optional) Free-form description (max 500 chars). Useful for internal notes.
Request Examples
Here is an example cURL command that calls this API endpoint. Remember to replace YOUR_PROGRAM_ID with your program ID, [email protected] with the email address of your referred customer who made a payment, and YOUR_API_KEY with your API key.
Response
If the sale is successfully recorded, the response will contain sucess as true.
If it is the first-time that an affiliate will have a commission generated from their referral making a payment,
firstSalewill betrue.Note that affiliate commission(s) are generated asynchronously and won’t be included in the response. If you need to receive commission details, we recommend using Webhooks.
If the sale is detected as a duplicate transaction, success will be false.
If this sale was detected as a duplicate,
duplicatewill betrueandcommissionsCreatedwill be0, andmessagewill also indicate why the sale is a duplicate.Use
duplicateFieldsto see which identifiers were duplicate(s).Use
matchingCommissionIdsto see which commission(s) have matching payments that were identified as duplicate(s).
Error response if the provided sale currency does not match the campaign currency.
Error response if the provided participant [who made the payment] does not have a referrer.
Add Transaction by Participant ID
POST https://api.growsurf.com/v2/campaign/:id/participant/:participantId/transaction
[Only applies to affiliate programs] Records a sale made by a referred customer (identified by their GrowSurf participant ID) and generates affiliate commissions for their referrer when applicable.
Path Parameters
id*
string
The ID of the program
participantId*
string
The GrowSurf participant ID. This is your customer that sent you a payment.
Request Body
grossAmount*
integer
Total sale amount in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). Must be a positive integer and is the baseline amount recorded for the sale.
Example values:
$5.00 is 500
$899.00 is 89900
$25,581.99 is 2558199
¥500 is 500
¥89,900 is 89900
¥2,558,199 is 2558199
invoiceId,
chargeId, paymentIntentId,
transactionId, externalId,
orderId,
paymentId
string
(Optional)
Providing at least one of these fields ensures idempotency for each payment. This ensures the same sale isn’t recorded twice (thus avoiding a duplicate commission being generated).
We recommend using invoiceId, chargeId, paymentId, or paymentIntentId as these will check against duplicate sales from other providers (e.g, Stripe). Otherwise, idempotency checks will only check for duplicates from sales that were recording using the API [and not a provider integration like Stripe].
netAmount
integer
(Optional)
Net-of-tax amount in minor units. If supplied, it becomes the preferred base for commission calculations without further derivation.
taxAmount
integer
(Optional)
Total tax collected in minor units. Used when netAmount is absent so we can back into a net figure (grossAmount - taxAmount).
amountCashNet
integer
(Optional) Explicit post-tax cash amount in minor units. Overrides any derived net amount; send this if you already know the exact commissionable base.
amountPaid
integer
(Optional) Amount the payment processor confirms was actually paid (minor units). Optional pass-through for reconciliation.
paidAt†
integer
(Optional) Unix timestamp in milliseconds when the payment actually occurred. GrowSurf uses this value to evaluate commission duration and intro windows; if you omit it, we fall back to the time the API call is received.
description
string
(Optional) Free-form description (max 500 chars). Useful for internal notes.
Request Examples
Here is an example cURL command that calls this API endpoint. Remember to replace YOUR_PROGRAM_ID with your program ID, xyz789 with the GrowSurf participant ID of your referred customer who made a payment, and YOUR_API_KEY with your API key.
Response
If the sale is successfully recorded, the response will contain sucess as true.
If it is the first-time that an affiliate will have a commission generated from their referral making a payment,
firstSalewill betrue.Note that affiliate commission(s) are generated asynchronously and won’t be included in the response. If you need to receive commission details, we recommend using Webhooks.
If the sale is detected as a duplicate transaction, success will be false.
If this sale was detected as a duplicate,
duplicatewill betrueandcommissionsCreatedwill be0, andmessagewill also indicate why the sale is a duplicate.Use
duplicateFieldsto see which identifiers were duplicate(s).Use
matchingCommissionIdsto see which commission(s) have matching payments that were identified as duplicate(s).
Error response if the provided sale currency does not match the campaign currency.
Error response if the provided participant [who made the payment] does not have a referrer.
Get Participant Commissions
GET https://api.growsurf.com/v2/campaign/:id/commissions
Retrieves a list of all participant commissions in the program.
id*
string
The ID of the program to retrieve participant commissions from
Query Parameters
nextId
string
(Optional)
The ID of the participant commission 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 commissions otherwise the nextId will be null.
limit
string
(Optional) The number of commissions to return. Must be a value less than or equal to 100, which is currently the maximum allowed per request.
status
string
(Optional)
Filter by commission status. Options: PENDING, APPROVED, PAID, REVERSED.
Response
In this example we are showing two commissions earned by participants in USD (from currencyISO). They earned $1,000 USD each (from amount) from their referrals' payment of $10,000 (from saleAmount). These commissions are still pending (from status), and will automatically become approved and eligible to be paid out once the hold duration period (holdDuration) period has ended.
To see more details about each field, view ParticipantCommission.
Get Participant Commissions by ID
GET https://api.growsurf.com/v2/campaign/:id/participant/:participantId/commissions
Retrieves a list of commissions earned by a participant using the given participant ID.
id*
string
The ID of the program to retrieve participant commissions from
participantId*
string
The ID of the participant to retrieve commissions for
Query Parameters
nextId
string
(Optional)
The ID of the participant commission 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 commissions otherwise the nextId will be null.
limit
string
(Optional) The number of commissions to return. Must be a value less than or equal to 100, which is currently the maximum allowed per request.
status
string
(Optional)
Filter by commission status. Options: PENDING, APPROVED, PAID, REVERSED.
Response
In this example we are showing one commission earned by the participant in USD (from currencyISO). They earned $1,000 USD (from amount) from their referral's payment of $10,000 (from saleAmount). This commission is still pending (from status), and will automatically become approved and eligible to be paid out once the hold duration period (holdDuration) period has ended.
To see more details about each field, view ParticipantCommission.
Error response returned if the limit query parameter that is provided exceeds the maximum allowed amount.
Get Participant Commissions by Email
GET https://api.growsurf.com/v2/campaign/:id/participant/:participantEmail/commissions
Retrieves a list of commissions earned by a participant using the given participant email address.
Path Parameters
id*
string
The ID of the program to retrieve participant commissions from
participantEmail*
string
The email address of the participant to retrieve commissions for
Query Parameters
nextId
string
(Optional)
The ID of the participant commission 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 commissions otherwise the nextId will be null.
limit
string
(Optional) The number of commissions to return. Must be a value less than or equal to 100, which is currently the maximum allowed per request.
status
string
(Optional)
Filter by commission status. Options: PENDING, APPROVED, PAID, REVERSED.
Response
In this example we are showing one commission earned by the participant in USD (from currencyISO). They earned $1,000 USD (from amount) from their referral's payment of $10,000 (from saleAmount). This commission is still pending (from status), and will automatically become approved and eligible to be paid out once the hold duration period (holdDuration) period has ended.
To see more details about each field, view ParticipantCommission.
Error response returned if the limit query parameter that is provided exceeds the maximum allowed amount.
Approve Participant Commission
POST https://api.growsurf.com/v2/campaign/:id/commission/:commissionId/approve
Approves a participant's commission so it can be eligible to be paid out.
This only applies for pending participant commissions.
Path Parameters
id*
string
The ID of the program.
Response
Returns a success response.
Error response returned if a commission has already been paid and thus cannot be approved.
You'll also get an error if the commission was already reversed or deleted.
Remove Participant Commission
DELETE https://api.growsurf.com/v2/campaign/:id/commission/:commissionId
Remove a commission that was earned by a participant. This only applies for pending participant commissions.
Path Parameters
id*
string
The program ID
Response
Returns a success response.
Error response returned if a commission has already been approved and thus cannot be deleted.
You'll also get an error if the commission was already paid or reversed.
Get Participant Payouts
GET https://api.growsurf.com/v2/campaign/:id/payouts
Retrieves a list of all participant payouts in the program.
id*
string
The ID of the program to retrieve participant payouts from
Query Parameters
nextId
string
(Optional)
The ID of the participant payout 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 payouts otherwise the nextId will be null.
limit
string
(Optional) The number of payouts to return. Must be a value less than or equal to 100, which is currently the maximum allowed per request.
status
string
(Optional)
Filter by payout status. Options: UPCOMING, QUEUED, ISSUED, FAILED.
Response
In this example we are showing two payouts that were issued to participants in USD (from currencyISO). They were paid out $3,600 USD each (from amount) from their commissions (from commissionIds).
To see more details about each field, view ParticipantPayout.
Get Participant Payouts by ID
GET https://api.growsurf.com/v2/campaign/:id/participant/:participantId/payouts
Retrieves a list of payouts that belong to a participant using the given participant ID.
id*
string
The ID of the program to retrieve participant payouts from
participantId*
string
The ID of the participant to retrieve payouts for
Query Parameters
nextId
string
(Optional)
The ID of the participant payout 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 payouts otherwise the nextId will be null.
limit
string
(Optional) The number of payouts to return. Must be a value less than or equal to 100, which is currently the maximum allowed per request.
status
string
(Optional)
Filter by payout status. Options: UPCOMING, QUEUED, ISSUED, FAILED.
Response
In this example we are showing one payout that was issued to the participant in USD (from currencyISO). They were paid out $3,600 USD (from amount) from their commissions (from commissionIds).
To see more details about each field, view ParticipantPayout.
Error response returned if the limit query parameter that is provided exceeds the maximum allowed amount.
Get Participant Payouts by Email
GET https://api.growsurf.com/v2/campaign/:id/participant/:participantEmail/payouts
Retrieves a list of payouts that belong to a participant using the given participant email address.
Path Parameters
id*
string
The ID of the program to retrieve participant payouts from
participantEmail*
string
The email address of the participant to retrieve payouts for
Query Parameters
nextId
string
(Optional)
The ID of the participant payout 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 payouts otherwise the nextId will be null.
limit
string
(Optional) The number of payouts to return. Must be a value less than or equal to 100, which is currently the maximum allowed per request.
status
string
(Optional)
Filter by payout status. Options: UPCOMING, QUEUED, ISSUED, FAILED.
Response
In this example we are showing one payout that was issued to the participant in USD (from currencyISO). They were paid out $3,600 USD (from amount) from their commissions (from commissionIds).
To see more details about each field, view ParticipantPayout.
Error response returned if the limit query parameter that is provided exceeds the maximum allowed amount.
Last updated
Was this helpful?