(Optional) Set this attribute if you want to override your campaign's milestone rewards so that you can define your own milestone rewards as an Array. Each Object should follow this format:

Example: {'goal': 2, 'prefix': 'You are only ', 'suffix': ' referrals away from winning a free shirt!', 'monthly': false}

Affiliate programs only The embedded payouts will display the participant's list of payouts. This element will only be displayed to signed-in participants.

Only participants who are signed in will see the embedded payouts.

**Example usage:** {% tabs %} {% tab title="Basic" %} This is the bare minimum code required to display this element. ```html

``` {% endtab %} {% tab title="With auth" %} If you have users logged into your website or web app, you can pass their email address in so that they always see the element in the participant ("auth") view. {% hint style="info" %} **Note:** If you are already setting `data-grsf-email`, `data-grsf-first-name`, or `data-grsf-last-name` on another GrowSurf embedded element, then you do not need to set them here. {% endhint %} ```html

``` **Here is an equivalent JavaScript implementation:** Here's what you would have in your HTML file: ```html

``` And here's what you would have in your JavaScript (make sure to use the [`grsfReady`](https://docs.growsurf.com/developer-tools/javascript-sdk#grsfready-event-listener) event listener anytime you call any `growsurf` functions): ```javascript // Make sure to replace "gavin@hooli.com", "Gavin", and "Belson" with your logged-in user's email address, first name, and last name, respectively. growsurf.addParticipant({ email: "gavin@hooli.com", firstName: "Gavin", lastName: "Belson" }); ``` {% endtab %} {% tab title="100% customized" %} This is an example that contains all of the available data attributes that can be customized. {% hint style="info" %} **Note:** If you are already setting `data-grsf-email`, `data-grsf-first-name`, or `data-grsf-last-name` on another GrowSurf embedded element, then you do not need to set them here. {% endhint %} ```html

Non-participants will see the public leaderboard

When a participant is signed in, they will see the "You" tag next to them

**Example usage:** {% tabs %} {% tab title="Basic" %} This is the bare minimum code required to display this element. ```html

``` **Here is an equivalent JavaScript implementation:** Here's what you would have in your HTML file: ```html

``` {% endtab %} {% endtabs %} **Data attributes:** | HTML Attribute | Data Type | Description | | ---------------------------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **`data-grsf-block-leaderboard`** | N/A | (Required) This attribute turns any HTML element into an embedded leaderboard. | | **`data-grsf-email`** | String | (Optional) The email of the participant to display the leaderboard element for. If the participant does not yet exist within the campaign, they will be newly added. | | **`data-grsf-button-style`** | Object | (Optional) Adds inline styles to any buttons within the leaderboard. | | **`data-grsf-link-style`** | Object | (Optional) Adds custom styles to any link elements within the embedded leaderboard. | | **`data-grsf-leaderboard-title`** | String | (Optional) Sets the text of the title above the leaderboard. | | **`data-grsf-leaderboard-title-style`** | Object | (Optional) Adds inline styles to the text of the title above the leaderboard. | | **`data-grsf-rank-column-text`** | String | (Optional) Sets the text of the rank column header. | | **`data-grsf-participants-column-text`** | String | (Optional) Sets the text of the participants column header. | | **`data-grsf-winners-icon-style`** | Object | (Optional) Adds inline styles to the winner icon that is displayed next to the winner. | | **`data-grsf-header-style`** | Object | (Optional) Adds inline styles to the header that is displayed above the leaderboard list. | | **`data-grsf-list-item-style`** | Object | (Optional) Adds inline styles to the list items that are displayed within the leaderboard list. | *** ## Embedded How It Works The embedded How It Works will display the How It Works section of your referral/affiliate program. This element will be always be displayed regardless of whether a participant is signed in or not.

The embedded How It Works will display to all participants regardless of whether they are signed in or not

**Example usage:** {% tabs %} {% tab title="Basic" %} This is the bare minimum code required to display this element. ```html

``` {% endtab %} {% endtabs %} *** ## Embedded FAQ The embedded FAQ will display the FAQ section of your referral/affiliate program. This element will be always be displayed regardless of whether a participant is signed in or not.

The embedded FAQ will display to all participants regardless of whether they are signed in or not

**Example usage:** {% tabs %} {% tab title="Basic" %} This is the bare minimum code required to display this element. ```html

``` {% endtab %} {% endtabs %} *** ## Embedded Terms The embedded Terms will display the Terms section of your referral/affiliate program. This element will be always be displayed regardless of whether a participant is signed in or not.

The embedded Terms will display to all participants regardless of whether they are signed in or not

**Example usage:** {% tabs %} {% tab title="Basic" %} This is the bare minimum code required to display this element. ```html

``` {% endtab %} {% endtabs %} # JavaScript SDK Use the JavaScript SDK to interact with your GrowSurf program and participant data. {% hint style="info" %} If you're using an AI tool such as Cursor, Codex, Claude Code, or Antigravity to help you implement GrowSurf, we recommend utilizing our [MCP server](https://docs.growsurf.com/build-with-ai). {% endhint %} ## Getting Started ### Step 1: Make sure the GrowSurf Universal Code is installed When you have the [GrowSurf Universal Code](/getting-started#step-1-choose-where-to-install-growsurf) installed on a webpage, that webpage has access to the JavaScript SDK, and you are ready for development. You can test this by entering [`growsurf.open()`](/developer-tools/javascript-sdk/api-reference#open-growsurf-window) in your browser's Developer Console. The unique program ID from your GrowSurf Universal Code is the program that is the target. [Click here for image](https://blobscdn.gitbook.com/v0/b/gitbook-28427.appspot.com/o/assets%2F-LeklWo0yn03AhWro2Ux%2F-LfU8ACBJhil-h8kFAU6%2F-LfU8CXlMq8GdEnHEwxt%2FScreen%20Shot%20on%202019-05-22%20at%2018%3A43%3A17.png?alt=media\&token=3778b13a-db9b-43d3-bce0-eef707391e8a). {% hint style="warning" %} **Testing in development?** * If you are testing on a development URL (e.g., `http://localhost:3000`), you will need to whitelist that URL in the Installation step of the *Program Editor*. [Click here for image](https://blobscdn.gitbook.com/v0/b/gitbook-28427.appspot.com/o/assets%2F-LeklWo0yn03AhWro2Ux%2F-LfU8FwcsZe9b-yjChHs%2F-LfU8rnazUxtZgHvmI4x%2FScreen%20Shot%20on%202019-05-22%20at%2018%3A47%3A27.png?alt=media\&token=d82bbd8e-bff3-471d-af16-3d9edc45facb). * We recommend creating two different programs for development and production environments. [Learn more here](https://support.growsurf.com/article/262-how-can-i-test-in-a-sandbox-or-development-environment). {% endhint %} ## **`grsfReady` Event Listener** The GrowSurf Universal Code loads asynchronously. Therefore, if you intend to execute any `growsurf` functions on page load, you must wait until the library has completely loaded. When loaded successfully, the GrowSurf Universal Code will dispatch a `grsfReady` event, notifying any event listeners that it is ready for use. Only then will any GrowSurf JavaScript SDK functions work. ### Example of using `grsfReady` ```javascript // Listen and wait for the Growsurf Universal Code to initialize window.addEventListener('grsfReady', () => { console.log('GrowSurf is Ready!'); // Your code goes here... }); ``` In some cases, the GrowSurf Universal script may already be available and the `grsfReady` event may have already fired. This depends on how long it takes your scripts to load and can happen for various other reasons.\ \ If your `grsfReady`callback isn't being invoked on the`grsfReady` event we recommend you check to see if the `growsurf` script is already available before adding the event listener callback with a conditional like this... ```javascript // Check to see if GrowSurf is available if(!window.growsurf) { // Listen and wait for the Growsurf Universal Code to initialize window.addEventListener('grsfReady', () => { console.log('GrowSurf is Ready!'); // Your code goes here... }); } else { console.log('GrowSurf is Already Available'); // Your code goes here... } ``` If you are executing `growsurf` functions *not* on page load, we recommend you wrap them in a conditional like this... ### Example of using a conditional ```javascript // Check if the GrowSurf Universal Code is present if (window.growsurf) { // Then, open the GrowSurf window growsurf.open(); } ``` ## **URL Parameters** On any webpage where you have GrowSurf installed (including the GrowSurf-hosted referral portal), you can use the `grsf_email` URL parameter to ensure that when someone lands on the page, they see their unique referral link right away instead of a signup form. For example, when an existing participant lands on `https://grow.surf/abc123?grsf_email=bob@loblaw.com`, they can instantly access their unique referral link without needing to log in. Conversely, if it's a non-existing participant, they will be added to your program as a participant, skipping the signup process and seeing their unique link immediately. {% hint style="info" %} **Other tips**: * Using `grsf_email` is also useful for adding new participants on the fly (i.e., when a person shows high intent to share, they land on your referral portal, and only then are they added to your GrowSurf program). * Setting `grsf_first_name` and `grsf_last_name` will also set the participant's first name and last name, respectively, if the participant was newly added. {% endhint %} ### List of URL Parameters | **URL Parameter** | **Description** | **Example URL** | | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | `grsf_email` | Set this value if you want to automatically add a new participant, or return an existing participant | `https://grow.surf/abc123/grsf_email=bob@loblaw.com` | | `grsf_first_name` | (Only applies if `grsf_email` is set) Set this value if you want to add a new participant with a first name |

\&grsf\_first\_name=Bob

| | `grsf_last_name` | (Only applies if `grsf_email` is set) Set this value if you want to add a new participant with a last name |

\&grsf\_first\_name=Bob
\&grsf\_last\_name=Loblaw

| | `grsf` | (Read-Only) This value represents the referrer's unique GrowSurf ID. You never have to worry about setting this value, as it gets automatically generated in participant's unique referral links. | `https://yoursite.com?grsf=z7o8au` | ## **Next Steps** * [View Tutorials](/developer-tools/javascript-sdk/tutorials) * [View Embeddable Elements](/developer-tools/embeddable-elements) * [View Single Page Applications](/developer-tools/javascript-sdk/single-page-applications) * [View API Reference](/developer-tools/javascript-sdk/api-reference) # Tutorials How to implement the GrowSurf JavaScript SDK in common use-case scenarios. Table of contents | Scenario | | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [Example 1: Trigger a referral on qualifying action (e.g, on conversion, purchase or upgrade)](#example-1-trigger-a-referral-on-qualifying-action-e.g-on-conversion-purchase-or-upgrade) | | [Example 2: Open the GrowSurf window on button click](#example-2-open-growsurf-window-on-button-click) | | [Example 3: Display a participant's unique share link and referral count inline on a webpage](#example-3-display-a-participants-unique-share-link-and-referral-count-inline-on-a-webpage) | | [Example 4: Redirect to another URL after a successful participant signup](#example-4-redirect-to-another-url-after-a-successful-participant-signup) | | [Example 5: Add a personalized message to your Share URL for a warm welcome](#example-5-add-a-personalized-message-to-your-share-url-for-a-warm-welcome) | | [Example 6: Only add a participant if they were referred](#example-6-only-add-a-participant-if-they-were-referred) | | [Example 7: Hide the GrowSurf Embedded Form until a GrowSurf participant is detected](#example-7-hide-the-growsurf-embedded-form-until-a-growsurf-participant-is-detected) | | [Example 8: Add internationalization support for the GrowSurf Embedded Form and Embedded Invite](#example-8-add-internationalization-support-for-the-growsurf-embedded-form-and-embedded-invite) | | [Example 9: Update pre-populated share and email invite messages to capitalize on a customer "aha moment"](#example-9-update-pre-populated-share-and-email-invite-messages-to-capitalize-on-a-customer-aha-momen) | | [Example 10: Load multiple GrowSurf programs on a single webpage](#example-10-load-multiple-growsurf-campaigns-on-a-single-webpage) | | [Example 11: Display a referral link on your login page](#example-11-display-a-referral-link-on-your-login-page) | | [Example 12: Display "You came through a referral link!" on your signup page](#example-12-display-you-came-through-a-referral-link-on-your-signup-page) | ## Example 1: Trigger a referral on qualifying action (e.g, on conversion, purchase, or upgrade) ### [Step 1: Make sure the GrowSurf Universal Code is installed](/developer-tools/javascript-sdk#step-1-make-sure-the-growsurf-universal-code-is-installed) ### Step 2: Add the participant {% hint style="warning" %} **Important Note:** If your program is configured to add participants automatically through a form on your website ([see image](https://blobscdn.gitbook.com/v0/b/gitbook-28427.appspot.com/o/assets%2F-LeklWo0yn03AhWro2Ux%2F-LgbRcVrYaKYUhQVctKK%2F-LgbS62PrNqHiJm-qwdI%2FScreen%20Shot%202019-06-05%20at%207.42.50%20PM.png?alt=media\&token=85e064ce-4bac-4617-9481-f80215478d51)), skip this step**.** {% endhint %} First, in the code where you capture the referred friend's email address, add them to your GrowSurf program as a participant with [`growsurf.addParticipant()`](/developer-tools/javascript-sdk/api-reference#add-participant). Let's say you have a signup function called `signUpFree()`, here's what that looks like: {% code title="your-script.js" %} ```javascript // In this example, a new person is just signing up for a free account const signUpFree = (user) => { // ...code that registers a new user... // Then add the new user as a participant in your GrowSurf program if (window.growsurf) { growsurf.addParticipant({ email: user.email, firstName: user.firstName, lastName: user.lastName }); } }; ``` {% endcode %} {% hint style="info" %} Behind the scenes, the GrowSurf Universal Code will associate the referrer (if they exist) with the new participant. At any future date [within the referral credit window](https://blobscdn.gitbook.com/v0/b/gitbook-28427.appspot.com/o/assets%2F-LeklWo0yn03AhWro2Ux%2F-LfTU5fPPuEimujYPBlL%2F-LfTUYdelF4Itf1vXW9T%2FScreen%20Shot%20on%202019-05-22%20at%2015%3A42%3A38.png?alt=media\&token=b1bd5196-2825-4229-b280-0c1240b0b30e), if this new participant triggers a referral, GrowSurf will provide credit to the referrer. {% endhint %} ### Step 3: Trigger the referral Then, in the code where the action takes place, trigger the referral with [`growsurf.triggerReferral()`](https://docs.growsurf.com/developer-tools/javascript-sdk/api-reference#trigger-referral) . Let's say you have a function called upgradeToPaidPlan(), here's what that looks like: {% code title="your-script.js" %} ```javascript // In this example, the user upgrades to a paid plan const upgradeToPaidPlan = (user) => { // ...code that upgrades the user... // Then trigger this action as a referral trigger if (window.growsurf) { growsurf.triggerReferral(user.email); } }; ``` {% endcode %} {% hint style="warning" %} **Important Note:** Make sure your program's referral trigger is set to *Sign Up + Qualifying Action* ([see image](https://blobscdn.gitbook.com/v0/b/gitbook-28427.appspot.com/o/assets%2F-LeklWo0yn03AhWro2Ux%2F-LnvqQyyEju4bLT4R5PC%2F-LnvsusHI0xFY2PJcJzB%2FScreen%20Shot%202019-09-04%20at%206.42.06%20PM.png?alt=media\&token=21db3d41-f20b-4887-833c-8109205cbc89)). If the referral trigger is set to *Sign Up*, triggering referrals will not work since referral credit has already been provided. {% endhint %} {% hint style="info" %} #### **Remember to set up reward fulfillment automation** Make sure you have [Webhooks](/developer-tools/webhooks) or [Zapier](/integrations/zapier) set up so that rewards automatically get fulfilled to the participant once they reach a reward goal. {% endhint %} ## Example 2: Open GrowSurf window on button click The GrowSurf window allows your users to retrieve their referral link to share, as well as track the status of their referrals and rewards. Follow this tutorial to learn how to open the GrowSurf window from an element, such as a button. ### [Step 1: Make sure the GrowSurf Universal Code is installed](/developer-tools/javascript-sdk#step-1-make-sure-the-growsurf-universal-code-is-installed) ### Step 2: Add code {% tabs %} {% tab title="Use CSS" %} #### Add a CSS class to your button Add the CSS class `growsurf-open-window` to your button element. When the user clicks the button, it will open the GrowSurf window. ```html ``` However, if the user is not logged in as a participant, they will see a signup form instead of their unique referral link. To ensure they always see their referral link, pass their information using the `data-grsf-email`, `data-grsf-first-name` , and `data-grsf-last-name` data attributes. Here's a code example (remember to replace the values with your logged-in user's details): ```html ``` {% endtab %} {% tab title="Use JavaScript" %} #### Add `onclick="growsurf.open()"` to your button Add `onclick="`[`growsurf.open()`](/developer-tools/javascript-sdk/api-reference#open-growsurf-window)`"` to your button to open the GrowSurf window when clicked. ```html ``` Or use JavaScript: ```html ``` However, when your user opens the GrowSurf window, they will see a signup form instead of their unique referral link unless they are already added as a participant. To ensure they always see their referral link, add or log them in as a participant first by calling [`growsurf.addParticipant()`](https://docs.growsurf.com/developer-tools/javascript-sdk/api-reference#add-participant). Here's a code example (remember to replace the values with your logged-in user's details): ```html ``` Or use JavaScript: ```html ``` {% endtab %} {% endtabs %} ## Example 3: Display a participant's unique share link and referral count inline on a webpage ### [Step 1: Make sure the GrowSurf Universal Code is installed](/developer-tools/javascript-sdk#step-1-make-sure-the-growsurf-universal-code-is-installed) ### Step 2: Add code {% tabs %} {% tab title="Use Embeddable Elements" %} #### Add the [Embedded Form](https://docs.growsurf.com/developer-tools/embeddable-elements#embedded-form) anywhere in your HTML Just paste `

` anywhere in your HTML, and the GrowSurf form will appear. If you want your participant to be already logged in and see their unique referral link (instead of the form), add an attribute `data-grsf-email` and set it to the participant's email address. {% hint style="warning" %} **Important Note:** If you have participant authentication enabled for your program, then the participant's unique share link and social buttons will only display if the participant entered your referral/affiliate program from their browser (either through automatic form detection, the GrowSurf form, or the JavaScript SDK). This is because a browser cookie will be saved that identifies the participant. Otherwise, the signup form will be shown, and the participant can click the *login* link to get sent a one-time login email. {% endhint %} {% code title="index.html" %} ```html

``` {% endcode %} {% endtab %} {% tab title="Use JavaScript" %} #### Call `growsurf.getParticipantByEmail()` Fetch a participant's information using [`growsurf.getParticipantByEmail()`](/developer-tools/javascript-sdk/api-reference#get-participant-by-email). Here's an example of retrieving the participant data, then updating the `#share-url` and `#referral-count` HTML elements to show their unique referral link and referral count. {% code title="index.html" %} ```html Your Referral Stats

``` {% endcode %} {% endtab %} {% endtabs %} ## Example 4: Redirect to another URL after a successful participant signup This is for when you want to redirect to another webpage after a participant successfully signs up for your referral/affiliate program. ### [Step 1: Make sure the GrowSurf Universal Code is installed](/developer-tools/javascript-sdk#step-1-make-sure-the-growsurf-universal-code-is-installed) ### Step 2: Add code {% tabs %} {% tab title="Use Embeddable Elements" %} If you are using the [Embedded Form](https://docs.growsurf.com/developer-tools/embeddable-elements#embedded-form), you can add the following HTML attribute: `data-grsf-redirect-url`. Remember to replace `https://replaceme.com` with your redirect URL. ```html

``` {% endtab %} {% tab title="Use JavaScript" %} If you are using your own form via automatic form detection or JavaScript Web API, then include the following snippet of code within the `` of the HTML source code. This should be the same page(s) where you have included the [GrowSurf Universal Code](https://docs.growsurf.com/developer-tools/javascript-sdk#step-1-make-sure-the-growsurf-universal-code-is-installed). Remember to replace `https://replaceme.com` at line 7 with your redirect URL. ```markup ``` {% endtab %} {% endtabs %} {% hint style="warning" %} Please note that if the redirect is not working, it is most likely because the form submission is failing. If this is the case, please check your browser console for errors. {% endhint %} ## Example 5: Add a personalized message to your Share URL for a warm welcome When a new visitor lands on your site using their friend's unique link, you can personalize a message for them with [`growsurf.getReferrerId()`](https://docs.growsurf.com/developer-tools/javascript-sdk/api-reference#get-referrer-id) and [`growsurf.getParticipantById()`](https://docs.growsurf.com/developer-tools/javascript-sdk/api-reference#get-participant-by-id). In this example, we have a simple page with a `h1#header` that will display as *"Emily S. invited you to pet puppies on-demand"* if a referrer exists, otherwise it will display as *"Pet puppies on-demand"*. ### [Step 1: Make sure the GrowSurf Universal Code is installed](/developer-tools/javascript-sdk#step-1-make-sure-the-growsurf-universal-code-is-installed) ### Step 2: Add code {% tabs %} {% tab title="index.html" %} ```html ``` {% endtab %} {% endtabs %} ## Example 6: Only add a participant if they were referred In this example, we will only add a participant if they were referred by another participant within your program. We will use [`growsurf.addReferredParticipant()`](https://docs.growsurf.com/developer-tools/javascript-sdk/api-reference#add-referred-participant), which validates the referrer and creates a participant only when the referrer is valid. The example code also assumes that you have set up a submit listener on your form which will listen for submission events and invoke the callback function described below. If you are not sure how to add a form submission listener [here is an example](https://developer.mozilla.org/en-US/docs/Web/API/HTMLFormElement/submit_event). ### [Step 1: Make sure the GrowSurf Universal Code is installed](/developer-tools/javascript-sdk#step-1-make-sure-the-growsurf-universal-code-is-installed) ### Step 2: Add code {% hint style="warning" %} This code is for demonstration purposes only. You may need to modify it to work on your website. {% endhint %} {% tabs %} {% tab title="index.html" %} ```html ``` {% endtab %} {% endtabs %} A few things to notice here are the `window.addEventListener` and the `form.addEventListener` snippets of code. The `window.addEventListener` listens for the GrowSurf script `grsfReady` event which is emitted when the [GrowSurf script is ready](https://docs.growsurf.com/developer-tools/javascript-sdk#grsfready-event-listener). Once the GrowSurf script is ready we are adding a `submit` event listener to our form `form.addEventListener` to listen for submission events. **You will need to get the form element using `document.getElementById` using the id of your form for this to work - this is just an example.**\ \ The next piece of code we will look at is the `onFormSubmit` function that is called when our form is submitted. The [addReferredParticipant()](https://docs.growsurf.com/developer-tools/javascript-sdk/api-reference#add-referred-participant) function validates the current referrer and only creates a participant when the referrer is valid. **You will need to get the value of the`userEmail` input using the id or name of the input element of your form - this is just an example.**\ \ Please note that this example will attempt referral-only participant creation on all form submissions regardless if the form is valid or not. If you wish to perform some validation before adding the participant that will require some extra coding to do so but is out of scope for this example. ## Example 7: Hide the GrowSurf Embedded Form until a GrowSurf participant is detected Let's say you are using the [Embedded Form](https://docs.growsurf.com/developer-tools/embeddable-elements#embedded-form) and passing an email address as a data attribute so that a participant gets created. Because GrowSurf needs to wait for a network request to finish, the signup form may be shown for a few seconds or less. To change this behavior to hide the signup form, you can use the following HTML, CSS, and JS (jQuery) code as an example below. ### [Step 1: Make sure the GrowSurf Universal Code is installed](/developer-tools/javascript-sdk#step-1-make-sure-the-growsurf-universal-code-is-installed) ### Step 2: Add code {% tabs %} {% tab title="HTML" %} ```html

``` {% endtab %} {% tab title="CSS" %} ```css .show-after-grsf-auth { display: initial } .hide-until-grsf-auth { display: none } ``` {% endtab %} {% tab title="JS (jQuery)" %} ```javascript // Check if a participant is logged-in, and display auth views based on if there is a participant function showGrsf() { var participantAuth = growsurf.getParticipantId(); if (participantAuth) { $('.hide-until-grsf-auth').addClass('show-after-grsf-auth'); } else { // Subscribe to a 'GrowSurf signup' event listener growsurf.subscribe('signup', function(participant) { $('.hide-until-grsf-auth').addClass('show-after-grsf-auth'); }); } } // See if GrowSurf is available if(!window.growsurf) { // Listen and wait for the Growsurf Universal Code to initialize window.addEventListener('grsfReady', function() { showGrsf(); }); } else { showGrsf(); } ``` {% endtab %} {% endtabs %} ## Example 8: Add internationalization support for the GrowSurf Embedded Form and embedded invite In this example, we'll walk through how to use GrowSurf embeddable elements to support multiple languages on your website. We will use the [Embedded Form](https://docs.growsurf.com/developer-tools/embeddable-elements#embedded-form) and [Embedded Invite](https://docs.growsurf.com/developer-tools/embeddable-elements#embedded-invite) elements, customizing data attributes to display text in both English and Spanish. ### [Step 1: Make sure the GrowSurf Universal Code is installed](/developer-tools/javascript-sdk#step-1-make-sure-the-growsurf-universal-code-is-installed) ### Step 2: Add code {% tabs %} {% tab title="Embedded Form" %} These examples only use `facebook` and `twitter` as the enabled social share buttons. If you have other social share options enabled, make sure to account for them.\ \ These examples also assume that you have a custom signup field called "Phone Number" ([see image](https://gblobscdn.gitbook.com/assets%2F-LeklWo0yn03AhWro2Ux%2F-MZLXwjfm2woyi5XcNvF%2F-MZLYxUjnDT8b5lUVQlO%2Fmain_full.png?alt=media\&token=d328abcb-ca39-46b0-8878-cbbe447198c7)). Custom fields are supported via [kebab-case](https://en.wikipedia.org/wiki/Letter_case#Special_case_styles) (see example usage of `phone-number` at lines 6 and 7 in the code snippets below). **In English:** ```html

``` **In Spanish:** ```html

``` {% endtab %} {% tab title="Embedded Invite" %} These examples used `Google` as the enabled address book. If you have other address books enabled, make sure to account for them. **In English:** ```html

``` **In Spanish:** ```html

``` {% endtab %} {% endtabs %} ## Example 9: Update pre-populated share and email invite messages to capitalize on a customer "aha moment" If your product has an "[aha moment](https://userguiding.com/blog/what-is-aha-moment-how-to-find-it/)", this is a great time to ask for referrals. On your webpage or web app, display the [Embedded Form](https://docs.growsurf.com/developer-tools/embeddable-elements#embedded-form) and [Embedded Invite](https://docs.growsurf.com/developer-tools/embeddable-elements#embedded-invite) elements to provoke the participant to share. In this example, we will use two methods [`growsurf.updateSocialShareMessage()`](https://docs.growsurf.com/developer-tools/javascript-sdk/api-reference#update-social-share-message) and [`growsurf.updateEmailInviteMessage()`](https://docs.growsurf.com/developer-tools/javascript-sdk/api-reference#update-email-invite-message) to update pre-populated social share messages so that the default text is more relevant to your user. ### [Step 1: Make sure the GrowSurf Universal Code is installed](/developer-tools/javascript-sdk#step-1-make-sure-the-growsurf-universal-code-is-installed) ### Step 2: Add code To better illustrate this use-case, consider the following scenarios: {% tabs %} {% tab title="Social media SaaS" %} Let's say you're a SaaS company that helps social media users gain more followers. You could ask for referrals once a user gains 100 followers. Add the following HTML code (e.g, in a popup on your webpage): ```html

💯 Alert!

Amazing, you just hit 100 followers this past week.

``` Add the following JavaScript code: ```javascript // Sign up (or log in) your user as a GrowSurf participant const userEmail = 'bob@boblaw.com'; // Replace with the user's email address growsurf.addParticipant({email: userEmail}); // Set the initial message and subject line const message = "I've just gained 100 followers by using this tool! {{shareUrl}}"; const subjectLine = "Check this out!"; // Update the social share messages growsurf.updateSocialShareMessage('email', message, subjectLine); growsurf.updateSocialShareMessage('facebook', message); growsurf.updateSocialShareMessage('twitter', message); growsurf.updateSocialShareMessage('pinterest', message); growsurf.updateSocialShareMessage('sms', message); growsurf.updateSocialShareMessage('whatsapp', message); // Update the pre-populated email invite message and subject line growsurf.updateEmailInviteMessage(message, subjectLine); ``` If you need to call this on immediate page load, wrap the JavaScript code in a [`grsfReady` Event Listener](https://docs.growsurf.com/developer-tools/javascript-sdk#grsfready-event-listener). {% endtab %} {% tab title="Enterprise messaging app" %} Let's say you're a messaging SaaS (e.g, Slack). You could ask for referrals once a team sends 2,000 messages in a workspace. Add the following HTML code (e.g, in a popup on your webpage): ```html

Woohoo, you've just sent 2,000 messages!

That's 6 days worth of time saved in productivity.

``` Add the following JavaScript code: ```javascript // Sign up (or log in) your user as a GrowSurf participant const userEmail = 'bob@boblaw.com'; // Replace with the user's email address growsurf.addParticipant(userEmail); // Set the initial message and subject line const message = "We've just sent 2,000 messages using this service and have saved 6 days of productivity. Love this service! {{shareUrl}}"; const subjectLine = "Check this out!"; // Update the social share messages growsurf.updateSocialShareMessage('email', message, subjectLine); growsurf.updateSocialShareMessage('facebook', message); growsurf.updateSocialShareMessage('twitter', message); growsurf.updateSocialShareMessage('pinterest', message); growsurf.updateSocialShareMessage('sms', message); growsurf.updateSocialShareMessage('whatsapp', message); // Update the pre-populated email invite message and subject line growsurf.updateEmailInviteMessage(message, subjectLine); ``` If you need to call this on immediate page load, wrap the JavaScript code in a [`grsfReady` Event Listener](https://docs.growsurf.com/developer-tools/javascript-sdk#grsfready-event-listener). {% endtab %} {% tab title="Food delivery service" %} Let's say you're a food delivery service company (e.g, Doordash). You could ask for referrals once the user leaves a positive review after a delivery. Add the following HTML code (e.g, in a popup on your webpage): ```html

Loving Doordash?

``` Add the following JavaScript code: ```javascript // Sign up (or log in) your user as a GrowSurf participant const userEmail = 'bob@boblaw.com'; // Replace with the user's email address growsurf.addParticipant(userEmail); // Set the initial message and subject line const message = "I just ordered delicious Wing's spicy noodle soup with DoorDash. 5/5 experience! Get $20 off your first order: {{shareUrl}}"; const subjectLine = "Check this out!"; // Update the social share messages growsurf.updateSocialShareMessage('email', message, subjectLine); growsurf.updateSocialShareMessage('facebook', message); growsurf.updateSocialShareMessage('twitter', message); growsurf.updateSocialShareMessage('pinterest', message); growsurf.updateSocialShareMessage('sms', message); growsurf.updateSocialShareMessage('whatsapp', message); // Update the pre-populated email invite message and subject line growsurf.updateEmailInviteMessage(message, subjectLine); ``` If you need to call this on immediate page load, wrap the JavaScript code in a [`grsfReady` Event Listener](https://docs.growsurf.com/developer-tools/javascript-sdk#grsfready-event-listener). {% endtab %} {% endtabs %} ## Example 10: Load multiple GrowSurf programs on a single webpage If you have multiple GrowSurf programs and want to use the same landing page and/or signup pages, here's how you can load the right program depending on where the traffic is coming from. ### Step 1: Update each Share URL for each of your programs For each of your programs, navigate to *Program Editor > 5. Installation* and update the Share URL to include a `?growsurf_campaign` parameter. * Grab the program ID in the address bar of your browser. * See an example in the image below:

Update your Share URL with a ?growsurf_campaign parameter

### Step 2: Paste this code into the \ of your website instead of the GrowSurf Universal Code Instead of pasting the GrowSurf Universal Code into the `` of your webpage(s), add the following code below. Make sure to update the `DEFAULT_GROWSURF_PROGRAM_ID` value at line 3 to your own default program ID. ```html ``` {% hint style="info" %} **Here's what this code does:** * Referral links will now look something like this: `https://mysite.com?growsurf_campaign=abc123&grsf=xyz789` . The program ID is `abc123` and will be saved as a cookie for 365 days. So when a referred friend lands on a referral link, the appropriate program ID will first be loaded. (The referrer ID `xyz789` is also automatically saved as a cookie). * If that referred friend revisits or returns to your site (e.g, `mysite.com`) even without using a referral link, the appropriate program will still be loaded b/c the program ID was saved as a cookie. * Once the referred friend signs up, the program that they originally came through a referral link from will be the one they get added to. * If a website visitor did not use a referral link to land on your website and sign ups, the fallback program `abc123` will be the one used. {% endhint %} ## Example 11: Display a Referral Link on Your Login Page In this tutorial, you'll learn how to display referral links to users on your login page. The typical use-case for this is to remind returning users of your referral/affiliate program and conveniently provide their referral link that they can share.

Display a referral link to returning users on your login page

This tutorial uses React, Firebase Authentication, and the GrowSurf JavaScript SDK. {% hint style="success" %} **Demo:** To view a working demo and to access the full code, [click here](https://codesandbox.io/p/sandbox/54r4g5). {% endhint %} ### Step 1: Install GrowSurf in Your React App The first step is to install the [GrowSurf Universal Code](https://docs.growsurf.com/getting-started#get-the-growsurf-universal-code) by dynamically injecting it into your React app. Inside your `App.js`, add the following function and use it in a `useEffect`: ```jsx const GROWSURF_PROGRAM_ID = "x8yi1l" // Replace with your own program ID const addGrsfScript = () => { if (document.querySelector('script[src*="growsurf.js"]')) return; const script = document.createElement("script"); script.src = "https://app.growsurf.com/growsurf.js?v=2.0.0"; script.setAttribute("grsf-campaign", GROWSURF_PROGRAM_ID); script.async = true; document.head.appendChild(script); }; useEffect(() => { onAuthStateChanged(auth, (user) => { setCurrentUser(user); }); if (document.readyState === "complete") { addGrsfScript(); } else { window.addEventListener("load", addGrsfScript); return () => window.removeEventListener("load", addGrsfScript); } }, []); ``` {% hint style="danger" %} **Important**: Make sure to replace `x8yi1l` at line 1 with your own program ID. {% endhint %} This ensures GrowSurf loads once when the app starts. ### Step 2: Register Users and Add Them to GrowSurf For the purpose of this demo, this is the logic that we'll have when a new user registers: 1. Create the user in Firebase 2. Add the user to GrowSurf using [`growsurf.addParticipant()`](/developer-tools/javascript-sdk/api-reference#add-participant) 3. Redirect them to the Profile page This is what the `register()` function in the `Register.js` file looks like: ```jsx const register = (e) => { e.preventDefault(); createUserWithEmailAndPassword(auth, email, password) .then((userCredential) => { const user = userCredential.user; // Add user to GrowSurf if (window.growsurf?.addParticipant) { window.growsurf.addParticipant(user.email); } navigate("/"); // Redirect to profile }) .catch((err) => setError(err.message)); }; ``` ### Step 3: Display Profile Page After Login/Registration In the `Profile.js` file, we'll show the user’s email and display a Logout button: ```jsx

Welcome, {currentUser.email}

``` When the user logs out, they’re redirected back to the Login page. ### **Step 4:** Login and Validate the GrowSurf Participant When a user logs in, we'll have the following logic be executed: 1. After a successful Firebase login, check if the user exists in your GrowSurf program using [`growsurf.getParticipantByEmail(email)`](https://docs.growsurf.com/developer-tools/javascript-sdk/api-reference#get-participant-by-email). 2. If the user exists in the program, call [`growsurf.addParticipant(email)`](/developer-tools/javascript-sdk/api-reference#add-participant) to log them in as a GrowSurf participant. Here's what we have in the `Login.js` file: ```jsx const login = (e) => { e.preventDefault(); setError(""); signInWithEmailAndPassword(auth, email, password) .then(() => { if (window.growsurf?.getParticipantByEmail) { window.growsurf.getParticipantByEmail(email, (participant) => { if (participant) { // Initialize GrowSurf participant session window.growsurf.addParticipant(email, () => { localStorage.setItem("hasLoggedIn", "true"); setShowReferral(true); navigate("/"); }); } }); } else { setError("GrowSurf is not ready. Please try again shortly."); } }) .catch((err) => setError(err.message)); }; ``` ### Step 5: Show the Referral Widget (Only After Logout) After tracking the user login state, we can now conditionally display the [GrowSurf Embedded Form](https://docs.growsurf.com/developer-tools/embeddable-elements#embedded-form) (aka the referral link) on the Login page — but only after logout. ```jsx {showReferral && (

)} ``` {% hint style="info" %} **Important note on authentication:**\ This tutorial focuses on integrating GrowSurf referral tracking in a React app using Firebase for authentication. However, the same concepts apply no matter what auth system you’re using (Supabase, Auth0, a custom backend, etc). For simplicity, the tutorial assumes that returning users already exist in both your authentication system and your GrowSurf program. This tutorial doesn’t cover all security details, and you'll want to adapt the logic to fit your own authentication flow and app structure. {% endhint %} ## Example 12: Display "You came through a referral link!" on Your Signup Page In this tutorial, you'll learn how to display a message like “You came through a referral link!” on your signup page using the GrowSurf JavaScript SDK using the following two methods: * [`growsurf.getReferrerId()`](https://docs.growsurf.com/developer-tools/javascript-sdk/api-reference#get-referrer-id) to fetch the referrer ID (aka the referral code) * [`growsurf.getCampaign()`](/developer-tools/javascript-sdk/api-reference#get-campaign) to fetch custom reward metadata (for displaying the `50` in "$50 discount will automatically be applied to your account.") * [`growsurf.addReferredParticipant()`](https://docs.growsurf.com/developer-tools/javascript-sdk/api-reference#add-referred-participant) to add new referred signups The use-case for this scenario is for verifying to referred visitors that they came through a referral link.

Display "You came through a referral link!" on your signup page

This tutorial uses React, Firebase Authentication, and the GrowSurf JavaScript SDK. {% hint style="success" %} **Demo:** * To view a working demo, [click here](https://dgxz4y.csb.app/?grsf=ay7rx1) and navigate to the signup page. * To access the full code, [click here](https://codesandbox.io/p/sandbox/dgxz4y). {% endhint %} From this tutorial, the following can be assumed: * The GrowSurf Universal Code will be dynamically injected in `App.js` * User authentication is via Firebase Auth and Firebase Realtime Database * `growsurf.addReferredParticipant(email)` will be called after user signup to track referrals * The login state is managed using a custom `AuthContext.js` ### Step 1: Install GrowSurf in Your React App The first step is to install the [GrowSurf Universal Code](https://docs.growsurf.com/getting-started#get-the-growsurf-universal-code) by dynamically injecting it into your React app. Inside your `App.js`, add the following function and use it in a `useEffect`: ```jsx const GROWSURF_PROGRAM_ID = "x8yi1l" // Replace with your own program ID const addGrsfScript = () => { if (document.querySelector('script[src*="growsurf.js"]')) return; const script = document.createElement("script"); script.src = "https://app.growsurf.com/growsurf.js?v=2.0.0"; script.setAttribute("grsf-campaign", GROWSURF_PROGRAM_ID); script.async = true; document.head.appendChild(script); }; useEffect(() => { onAuthStateChanged(auth, (user) => { setCurrentUser(user); }); if (document.readyState === "complete") { addGrsfScript(); } else { window.addEventListener("load", addGrsfScript); return () => window.removeEventListener("load", addGrsfScript); } }, []); ``` {% hint style="danger" %} **Important**: Make sure to replace `x8yi1l` at line 1 with your own program ID. {% endhint %} This ensures GrowSurf loads once when the app starts. ### Step 2: Get the `referralId` and show the referral message on the registration page Now switch to `Register.js`. Inside a `useEffect`, check if a referral ID is stored by calling [`growsurf.getReferrerId()`](https://docs.growsurf.com/developer-tools/javascript-sdk/api-reference#get-referrer-id). If there is a referrer ID, then show a banner that says "You came through a referral link! $50 discount will automatically be applied to your account." Get the `50` by fetching the reward amount from your GrowSurf program's reward metadata by calling [`growsurf.getCampaign()`](https://docs.growsurf.com/developer-tools/javascript-sdk/api-reference#get-campaign): ```jsx useEffect(() => { if (window.growsurf?.getReferrerId) { const referrerId = window.growsurf.getReferrerId(); if (referrerId) { setShowReferralBanner(true); if (window.growsurf?.getCampaign) { window.growsurf.getCampaign((campaign) => { const reward = campaign?.rewards?.[0]; const rewardValue = reward?.metadata?.rewardForReferred; if (rewardValue !== undefined) { setRewardAmount(rewardValue); } }); } } } }, []); ``` This code does two things: 1. Shows a referral banner only if a referrer ID is stored. The `growsurf.getReferrerId()` method checks if there is a referral cookie stored (which would be present if the visitor initially came from a referral link). 2. Uses `growsurf.getCampaign()` to fetch the metadata of your program's first reward. Note, you'll need to have [set the reward metadata](https://docs.growsurf.com/developer-tools/metadata#reward-metadata-1). Then render the message inside your JSX: ```jsx {showReferralBanner && rewardAmount !== null && rewardAmount !== undefined && (

You came through a referral link! ${rewardAmount} discount will automatically be applied to your account.

)} ``` ### **Step 4:** Register Users and Add Them to GrowSurf When a new user signs up, you’re already registering them with Firebase Auth. After that, use [`growsurf.addParticipant()`](https://docs.growsurf.com/developer-tools/javascript-sdk/api-reference#add-participant) to add them to your GrowSurf program: ```jsx if (response?.user?.email) { window.growsurf.addParticipant(response.user.email, () => { // Mark that this user is part of GrowSurf localStorage.setItem("isGrowSurfParticipant", "true"); }); } ``` {% hint style="warning" %} **Important note on applying the $50 discount upfront:** This tutorial does not cover how to apply the $50 discount the new user who just signed up. To view how to apply the actual discount, [view this article](https://support.growsurf.com/article/280-how-can-i-have-a-coupon-code-instantly-available-for-a-referred-person-before-they-sign-up). {% endhint %} # Single Page Applications View sample code and troubleshooting tips for integrating GrowSurf into common JavaScript frameworks such as React and Vue. {% hint style="info" %} To test in a sandbox/development environment, we recommend creating two different programs for development and production environments. [Learn more here](https://support.growsurf.com/article/262-how-can-i-test-in-a-sandbox-or-development-environment). Due to the asynchronous behavior of SPAs, if the GrowSurf Universal Code has already been added you may need to re-initialize GrowSurf at times. For example, if embeddable elements are not being displayed, call [growsurf.init()](https://docs.growsurf.com/developer-tools/javascript-sdk/api-reference#initialize-reinitialize-growsurf). {% endhint %} ## GitHub [Check out the `growsurf-samples` GitHub repo for sample code](https://github.com/growsurf/growsurf-samples). ## React Check out the GitHub sample code for React [here](https://github.com/growsurf/growsurf-samples/tree/master/samples/growsurf-react-example) and our [GrowSurf React project](https://github.com/growsurf/growsurf-react-firebase). ### React Component To initialize GrowSurf asynchronously within your SPA, simply include the following code within your [React components `componentDidMount()`](https://reactjs.org/docs/react-component.html#componentdidmount)lifecycle event. {% hint style="info" %} IMPORTANT: `componentDidMount()`is a lifecycle method for class components and cannot be used in functional components. If you want to initialize GrowSurf using a functional component you will need to use the [Effect Hook](https://reactjs.org/docs/hooks-effect.html). {% endhint %} ### Example using Classes This snippet of code will only add the GrowSurf Universal Code when a visitor is brought to a page within your site that includes the component with this code. Once the script has been added successfully and [initialized](/developer-tools/javascript-sdk#grsfready-event-listener), you will then have the ability to add any [GrowSurf embeddable element](/developer-tools/embeddable-elements)(s) you would like within your components JSX. {% code title="App.js" %} ```jsx class App extends React.Component { componentDidMount() { const script = document.createElement('script'); script.src = 'https://app.growsurf.com/growsurf.js?v=2.0.0'; script.setAttribute('grsf-campaign', 'jaoh4t'); script.async = true; document.head.appendChild(script); } render() { return (

REACT + GROWSURF

) } } ``` {% endcode %} ### Example using Effect Hook {% code title="App.js" %} ```jsx import {useEffect} from 'react' function App() { // GrowSurf Universal Code const addGrsfScript = () => { const script = document.createElement('script'); script.src = 'https://app.growsurf.com/growsurf.js?v=2.0.0'; script.setAttribute('grsf-campaign', 'jaoh4t'); script.async = true; document.head.appendChild(script); }; useEffect(() => { addGrsfScript(); }, []) } ``` {% endcode %} {% hint style="info" %} In React, third-party JavaScript SDKs like GrowSurf's are not automatically accessible within the Virtual DOM. To interact with them, you must reference them via the `window` object.\ \ **Example** ```javascript window.growsurf.getParticipantId(); ``` {% endhint %} ## Vue [Check out the GitHub sample code for Vue here](https://github.com/growsurf/growsurf-samples/tree/master/samples/growsurf-vue-example). ## Troubleshooting If you experience issues with embeddable elements rendering on the page (depending on how URL routes are handled in your SPA, this behavior will typically be seen when you refresh the webpage with the absolute route) you will need to call [`growsurf.init()`](https://docs.growsurf.com/developer-tools/javascript-sdk/api-reference#initialize-reinitialize-growsurf)to re-initialize GrowSurf to make the embeddable elements render. # API Reference This reference documents the GrowSurf JavaScript SDK, including all available public methods and examples of each. {% hint style="info" %} If you're using an AI tool such as Cursor, Codex, Claude Code, or Antigravity to help you implement GrowSurf, we recommend utilizing our [MCP server](https://docs.growsurf.com/build-with-ai). {% endhint %} Use this page to look up individual GrowSurf JavaScript SDK methods. All asynchronous methods support both callback and Promise styles unless otherwise noted. ## SDK LIFECYCLE ↓ ### Initialize / Reinitialize GrowSurf Initializes or reinitializes the `window.growsurf` Object. {% hint style="info" %} The method is useful for the following use-cases: * If you have participant authentication enabled for your program and you would like to [automatically authenticate](/getting-started/participant-auto-authentication) your participants after they log in within your own user portal. * Load multiple programs on a single webpage depending on where the traffic is coming from. [View a tutorial here](https://docs.growsurf.com/developer-tools/javascript-sdk/tutorials#example-10-load-multiple-growsurf-campaigns-on-a-single-webpage). {% endhint %} ```javascript growsurf.init(settings); ``` **Example use** {% tabs %} {% tab title="Using Callbacks" %} ```javascript // Using a Callback growsurf.init({ email: "participant@email.com", hash: "HASH_VALUE" }, () => { // GrowSurf is Ready }); ``` {% endtab %} {% tab title="Using Promises" %} ```javascript // Using a promise growsurf.init({ email: "participant@email.com", hash: "HASH_VALUE" }).then(() => { // GrowSurf is Ready }); ``` {% endtab %} {% endtabs %} | Parameter | Data Type | Description | | -------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **`settings`** | Object |

(Optional) The settings GrowSurf should use when initializing or reinitializing.

campaignId- Provide this to initialize another program
email- The email of the participant you wish to auto authenticate (only applies if authentication is enabled for your program).
hash- The hash token generated by your server. Used to auto authenticate a participant (only applies if authentication is enabled for your program).

| *** ### Get participant ID Returns the ID of the authenticated participant or **`null`** if there is no participant authentication cookie present. {% hint style="info" %} **Example:** Someone signed up as a participant in your referral/affiliate program from your website. Calling this method will return `aj7auu1` (which is the participant ID). {% endhint %} ```javascript growsurf.getParticipantId(); ``` #### **Example use** ```javascript growsurf.getParticipantId(); ``` **Example response** ```javascript "aj7auu1" ``` *** ### Log out Logs the participant out of the browser (clears the participant's GrowSurf browser cookie and local storage). ```javascript growsurf.logout(); ``` #### **Example use** ```javascript growsurf.logout(); ``` *** ## CAMPAIGNS ↓ ### Get campaign Retrieves limited details of a campaign. ```javascript growsurf.getCampaign(callback); ``` | Parameter | Data Type | Description | | -------------- | --------- | --------------------------------------------------------------------------- | | **`callback`** | Function | (Optional) A callback function that will be invoked with the campaign data. | Returns a [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Using_promises)that resolves with an [Object](https://developer.mozilla.org/en-US/docs/Learn/JavaScript/Objects/Basics)containing limited campaign data of `id` and `rewards`. #### **Example use** {% tabs %} {% tab title="Using Callbacks" %} ```javascript // Using a Callback growsurf.getCampaign((campaign) => { // Handle Campaign console.log(campaign); }); ``` {% endtab %} {% tab title="Using Promises" %} ```javascript // Using a Promise growsurf.getCampaign().then(campaign => { // Handle Campaign console.log(campaign); }); ``` {% endtab %} {% endtabs %} #### Example response ```json { "id": "bpsxg4", "type": "REFERRAL", "rewards": [ { "id": "crew_xyz789", "type": "DOUBLE_SIDED", "description": "Refer a friend and get $20", "referralDescription": "Sign up and get $10 off your first invoice", "referredRewardUpfront": false, "isUnlimited": false, "limit": 1, "conversionsRequired": 1, "numberOfWinners": 3, "imageUrl": "https://example.com/reward-image.png", "metadata": { "rewardValueForReferrer": 20, "rewardValueForReferred": 10 }, // Only for affiliate programs: "commissionStructure": { "amount": null, "event": "SALE", "type": "PERCENT", "minPaidReferrals": 3, "holdDuration": 30, "duration": "FOREVER", "durationInMonths": 12, "approvalRequired": false, "percent": 50, "hasMaxAmount": false, "maxAmount": null, "maxAmountISO": "USD", "hasIntro": false, "introType": null, "introPercent": null, "introAmount": null, "introAmountISO": "USD", "introDuration": "REPEATING", "introDurationInMonths": 2 } } ] } ``` *** ## GROWSURF WINDOW ↓ ### Open GrowSurf window Opens the GrowSurf window. ```javascript growsurf.open(callback); ``` | **Parameter** | Data Type | Description | | -------------- | --------- | ----------------------------------------------------------------- | | **`callback`** | Function | (Optional) A callback function that will be invoked once complete | Returns a [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Using_promises)that resolves once complete. #### **Example use** {% tabs %} {% tab title="Using Callbacks" %} ```javascript // Using a Callback growsurf.open(function() { // Do something here }); ``` {% endtab %} {% tab title="Using Promises" %} ```javascript // Using a Promise growsurf.open().then(() => { // Do something here }); ``` {% endtab %} {% endtabs %} {% hint style="success" %} #### **CSS Alternative:** Instead of using the JavaScript method `growsurf.open()`, you can simply add a CSS class `growsurf-open-window` to a button. A benefit of this option is that if the participant has any unread rewards, the unread badge will automatically show up as well.\ \ **Here is an example:** ```html Refer and Earn ``` **Note:** You'll need to make sure you have the [GrowSurf Universal Code](https://docs.growsurf.com/getting-started#get-the-growsurf-universal-code) installed. {% endhint %} *** ### Close GrowSurf window Closes the GrowSurf window. ```javascript growsurf.close(callback); ``` | **Parameter** | Data Type | Description | | -------------- | --------- | ----------------------------------------------------------------- | | **`callback`** | Function | (Optional) A callback function that will be invoked once complete | Returns a [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Using_promises)that resolves once complete. #### **Example use** {% tabs %} {% tab title="Using Callbacks" %} ```javascript // Using a Callback growsurf.close(() => { // Do something here }); ``` {% endtab %} {% tab title="Using Promises" %} ```javascript // Using a Promise growsurf.close().then(() => { // Do something here }); ``` {% endtab %} {% endtabs %} *** ## ATTRIBUTION ↓ ### Get referrer ID Returns the ID of the participant that referred the visitor or **`null`** if the visitor was not referred. This method will first check to see if a `grsf` URL parameter exists, then will check for the presence of a referrer ID as a browser cookie (which was set from the initial visit). {% hint style="info" %} **Example:** If someone refers their friend, and the friend visits `https://yoursite.com?grsf=1h97da`, calling this method will return `1h97da` (which is the referrer ID). {% endhint %} ```javascript growsurf.getReferrerId(); ``` #### **Example use** ```javascript growsurf.getReferrerId(); ``` #### Example response ```javascript "1h97da" ``` {% hint style="info" %} **Note:** You can verify that the referrer ID is valid by calling [`growsurf.validateReferrer()`](https://docs.growsurf.com/developer-tools/javascript-sdk/api-reference#validate-referrer). {% endhint %} *** ### Validate referrer Checks whether a referrer (participant) exists in the campaign. Returns `true` if the referrer exists, `false` otherwise. Unlike [`getParticipantById()`](https://docs.growsurf.com/developer-tools/javascript-sdk/api-reference#get-participant-by-id), this method does **not** require participant authentication and does **not** return any participant data. {% hint style="info" %} **When to use this:** Use `validateReferrer()` when you need to confirm that a referral link is valid or to check if a participant exists. If you want to add a referred signup only when the referrer is valid, use [`addReferredParticipant()`](#add-referred-participant). {% endhint %} ```javascript growsurf.validateReferrer(referrerId, callback); ``` | Parameter | Data Type | Description | | ---------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | **`referrerId`** | String | (Optional) The GrowSurf referrer ID to validate. If omitted, the referrer ID is automatically resolved from the `grsf` URL parameter or browser cookie. | | **`callback`** | Function | (Optional) A callback function that will be invoked with `true` if the referrer exists or `false` if the referrer does not exist. | Returns a [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Using_promises) that resolves with a [Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean). Returns `true` if the referrer exists as a participant in the campaign, `false` otherwise. #### **Example use** {% tabs %} {% tab title="Using Callbacks" %} ```javascript // Using a Callback // Without specifying a referrer ID (auto-detects referrer) growsurf.validateReferrer(isValid => { if (isValid) { // Referrer exists } }); // With a specific referrer ID growsurf.validateReferrer('kafewp', (isValid) => { if (isValid) { // Referrer exists } }); ``` {% endtab %} {% tab title="Using Promises" %} ```javascript // Using a Promise // Without specifying a participant ID (auto-detects referrer) growsurf.validateReferrer().then(isValid => { if (isValid) { // Referrer exists } }); // With a specific participant ID growsurf.validateReferrer('kafewp').then(isValid => { if (isValid) { // Referrer exists } }); ``` {% endtab %} {% endtabs %} #### **Example response**

true

*** ## PARTICIPANTS ↓ ### Add referred participant Adds a participant only when the current visitor has a valid referrer. Use this method when you want to track referred signups. The method validates an explicit `referredBy` value first. If one is not provided, it automatically uses the referrer ID from the `grsf` URL parameter or browser cookie. If no valid referrer is present, it returns a normal not-added result. {% hint style="info" %} **Tips:** Though they are optional, we recommend passing in the fields `firstName` and `lastName` . These fields are used for anti-fraud purposes and they show up in referred friend motivator elements, if enabled. {% endhint %} ```javascript growsurf.addReferredParticipant(data, callback); ``` | Parameter | Data Type | Description | | -------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **`data`** | String or Object |

(Required) A String containing the participant email or an Object containing the participant email and any other data to include for the participant.

If providing an Object, referredBy is optional and will override the automatically detected referrer. Any Object keys other than email, firstName, lastName, referredBy, referredAt, and gdprAgreements will be treated as metadata by GrowSurf.

| | **`callback`** | Function | (Optional) A callback function that will be invoked with the result. | Returns a [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Using_promises) that resolves with a result object. #### **Example use** {% tabs %} {% tab title="Using Callbacks" %} ```javascript growsurf.addReferredParticipant({ email: 'gavin@hooli.com', firstName: 'Gavin', lastName: 'Belson' }, (result) => { if (result.added) { // handle result.participant } }); ``` {% endtab %} {% tab title="Using Promises" %} ```javascript const result = await growsurf.addReferredParticipant({ email: 'gavin@hooli.com', firstName: 'Gavin', lastName: 'Belson' }); if (result.added) { // handle result.participant } ``` {% endtab %} {% endtabs %} #### Example response ```json { "added": true, "validReferral": true, "referredBy": "kafewp", "participant": { "id": "gavin", "firstName": "Gavin", "lastName": "Belson", "referralCount": 0, "monthlyReferralCount": 0, "shareUrl": "https://piedpiper.com?grsf=gavin-kafewp", "rewards": [], "vanityKeys": [ "gavin-kafewp" ] } } ``` If no participant is added, `notAddedReason` will be one of `no_referrer`, `invalid_referrer`, or `participant_already_exists`. *** ### Add participant Adds a participant to the referral/affiliate program. Use this method for the following use-cases: * Add every signup to your GrowSurf program. If a referral link was used, GrowSurf automatically submits the referrer ID behind the scenes. * Generate referral links for your signed-in users on the fly (or return existing data if they are an existing participant) For referral-only signup tracking, use [`growsurf.addReferredParticipant()`](#add-referred-participant) instead. {% hint style="info" %} **Tips:** Though they are optional, we recommend passing in the fields `firstName` and `lastName` . These fields are used for anti-fraud purposes and they show up in referred friend motivator elements, if enabled. {% endhint %} {% hint style="warning" %} **Note:** A `401` error will be returned if the following conditions are met: (1) the program has participant authentication enabled, (2) there is no authentication cookie present on the participant's browser, (3) the given email is the same as an existing participant. {% endhint %} ```javascript growsurf.addParticipant(data, callback); ``` | Parameter | Data Type | Description | | -------------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **`data`** | String or Object |

(Required) A String containing the participant email or an Object containing the participant email and any other data to include for the participant.

If providing an Object, any Object keys other than email, firstName, lastName , and gdprAgreements will be treated as metadata by GrowSurf.

For more information about metadata please see our API Guidelines.

| | **`callback`** | Function | (Optional) A callback function that will be invoked with the added participant data if successful. | Returns a [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Using_promises)that resolves with an [Object](https://developer.mozilla.org/en-US/docs/Learn/JavaScript/Objects/Basics)containing limited participant data. #### **Example use** {% tabs %} {% tab title="Using Callbacks" %} ```javascript // Email only using a Callback growsurf.addParticipant('gavin@hooli.com', (participant) => { // handle participant }); // Object using a Callback growsurf.addParticipant({ email: 'gavin@hooli.com', firstName: 'Gavin', // optional, but recommended for anti-fraud purposes lastName: 'Belson', // optional, but recommended for anti-fraud purposes company: 'Hooli, Inc', // Fields that are not email, firstName, or lastName will be saved as custom metadata companySize: 10000 // Fields that are not email, firstName, or lastName will be saved as custom metadata }, (participant) => { // handle participant }); ``` {% endtab %} {% tab title="Using Promises" %} ```javascript // Email only using a Promise growsurf.addParticipant('gavin@hooli.com').then(participant => { // handle participant }); // Object using a Promise growsurf.addParticipant({ email: 'gavin@hooli.com', firstName: 'Gavin', // optional, but recommended for anti-fraud purposes lastName: 'Belson', // optional, but recommended for anti-fraud purposes company: 'Hooli, Inc', // Fields that are not email, firstName, or lastName will be saved as custom metadata companySize: 10000 // Fields that are not email, firstName, or lastName will be saved as custom metadata }).then(participant => { // handle participant }); ``` {% endtab %} {% endtabs %} #### Example response ```json { "id": "kafewp", "firstName": "Gavin", "lastName": "Belson", "referralCount": 0, "monthlyReferralCount": 0, "shareUrl": "https://piedpiper.com?grsf=gavin-kafewp", "rewards": [], "vanityKeys": [ "gavin-kafewp" ] } ``` *** ### Get participant by email Retrieves limited details of an existing participant. You will need to supply the unique email of the participant. {% hint style="warning" %} **Note:** A `403` error will be returned if the following conditions are met: (1) the program has participant authentication enabled, (2) there is no authentication cookie present on the participant's browser. {% endhint %} ```javascript growsurf.getParticipantByEmail(participantEmail, callback); ``` | Parameter | Data Type | Description | | ---------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | **`participantEmail`** | String | (Required) The email of the participant to retrieve. | | **`callback`** | Function | (Optional) A callback function that will be invoked with the participant data if successful or `undefined` if the participant does not exist. | Returns a [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Using_promises)that resolves with an [Object](https://developer.mozilla.org/en-US/docs/Learn/JavaScript/Objects/Basics)containing the participant data. If the participant does not exist in the campaign, then `undefined` is returned. #### **Example use** {% tabs %} {% tab title="Using Callbacks" %} ```javascript // Using a callback growsurf.getParticipantByEmail('gavin@hooli.com', (participant) => { // Handle participant data }); ``` {% endtab %} {% tab title="Using Promises" %} ```javascript // Using a promise growsurf.getParticipantByEmail('gavin@hooli.com').then(participant => { // Handle participant data }); ``` {% endtab %} {% endtabs %} #### Example response ```json { "id": "kafewp", "firstName": "Gavin", "lastName": "Belson", "referralCount": 0, "monthlyReferralCount": 0, "shareUrl": "https://piedpiper.com?grsf=gavin-kafewp", "rewards": [], "vanityKeys" [ "gavin-kafewp" ] } ``` *** ### Get participant by ID Retrieves limited details of an existing participant. You will need to supply the GrowSurf unique identifier that was returned upon participant creation. {% hint style="warning" %} **Note:** A `403` error will be returned if the following conditions are met: (1) the program has participant authentication enabled, (2) there is no authentication cookie present on the participant's browser. {% endhint %} ```javascript growsurf.getParticipantById(participantId, callback); ``` | Parameter | Data Type | Description | | ------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | **`participantId`** | String | (Required) The GrowSurf identifier of the participant to retrieve. | | **`callback`** | Function | (Optional) A callback function that will be invoked with the participant data if successful or `undefined` if the participant does not exist. | Returns a [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Using_promises)that resolves with an [Object](https://developer.mozilla.org/en-US/docs/Learn/JavaScript/Objects/Basics)containing the participant data. If the participant does not exist in the campaign, then `undefined` is returned. #### **Example use** {% tabs %} {% tab title="Using Callbacks" %} ```javascript // Using a Callback growsurf.getParticipantById('kafewp', (participant) => { // Handle participant data }); ``` {% endtab %} {% tab title="Using Promises" %} ```javascript // Using a promise growsurf.getParticipantById('kafewp').then(participant => { // Handle participant data }); ``` {% endtab %} {% endtabs %} #### Example response ```json { "id": "kafewp", "firstName": "Gavin", "lastName": "Belson", "referralCount": 0, "monthlyReferralCount": 0, "shareUrl": "https://piedpiper.com?grsf=gavin-kafewp", "rewards": [], "vanityKeys" [ "gavin-kafewp" ] } ``` *** ## REFERRALS AND INVITES ↓ ### Update social share message Updates the pre-populated social share message for the given share type (e.g, email, Facebook, Twitter). This method will update all social share buttons in GrowSurf embedded elements and the GrowSurf window. {% hint style="info" %} **Example:** This method is useful for optimizing referral asks when your participants complete an "[aha moment](https://userguiding.com/blog/what-is-aha-moment-how-to-find-it/)". You would present your participant with the [GrowSurf Embedded Form](https://docs.growsurf.com/developer-tools/embeddable-elements#embedded-form) element and then call this method to update social share message(s) to be specific to the "aha moment". See [this tutorial](https://docs.growsurf.com/developer-tools/javascript-sdk/tutorials#example-9-update-pre-populated-share-and-email-invite-messages-to-capitalize-on-a-customer-aha-momen) for an example. {% endhint %} ```javascript growsurf.updateSocialShareMessage(type, message, subjectLine); ``` | Parameter | Data Type | Description | | ----------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **`type`** | String |

(Required) The social share type to update.

These are the options:

email
facebook
twitter
threads
bluesky
pinterest
sms
whatsapp
reddit
tumblr

| | **`message`** | String |

(Required) The new pre-populated social share message.

Use {{shareUrl}} to reference the participant's referral link.

| | **`subjectLine`** | String |

(Optional) The new pre-populated subject line (only applies when type is email).

Use {{shareUrl}} to reference the participant's referral link.

| #### **Example use** ```javascript const message = "I have saved 1,540 hours using this service. Highly recommend! {{shareUrl}}"; const subjectLine = "Check this out!"; // Update the pre-populated email social share message growsurf.updateSocialShareMessage('email', message, subjectLine); // Update the pre-populated Facebook social share message growsurf.updateSocialShareMessage('facebook', message); // Update the pre-populated Twitter social share message growsurf.updateSocialShareMessage('twitter', message); // Update the pre-populated Threads social share message growsurf.updateSocialShareMessage('threads', message); // Update the pre-populated Bluesky social share message growsurf.updateSocialShareMessage('bluesky', message); // Update the pre-populated Pinterest social share message growsurf.updateSocialShareMessage('pinterest', message); // Update the pre-populated SMS social share message growsurf.updateSocialShareMessage('sms', message); // Update the pre-populated WhatsApp social share message growsurf.updateSocialShareMessage('whatsapp', message); // Update the pre-populated Reddit social share message growsurf.updateSocialShareMessage('reddit', message); // Update the pre-populated Tumblr social share message growsurf.updateSocialShareMessage('tumblr', message); ``` *** ### Update email invite message Updates the pre-populated email invite message. This method will only apply updates to [GrowSurf Embedded Invite](https://docs.growsurf.com/developer-tools/embeddable-elements#embedded-invite) elements (the email invite section within the GrowSurf window will not be updated). {% hint style="info" %} **Example:** This method is useful for optimizing referral asks when your participants complete an "[aha moment](https://userguiding.com/blog/what-is-aha-moment-how-to-find-it/)". You would present your participant with the [GrowSurf Embedded Invite](https://docs.growsurf.com/developer-tools/embeddable-elements#embedded-invite) element and then call this method to update the email invite message to be specific to the "aha moment". See [this tutorial](https://docs.growsurf.com/developer-tools/javascript-sdk/tutorials#example-9-update-pre-populated-share-and-email-invite-messages-to-capitalize-on-a-customer-aha-momen) for an example. {% endhint %} ```javascript growsurf.updateEmailInviteMessage(message, subjectLine); ``` | Parameter | Data Type | Description | | ----------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | | **`message`** | String |

(Required) The new pre-populated email invite message.

Use {{shareUrl}} to reference the participant's referral link.

| | **`subjectLine`** | String |

(Optional) The new pre-populated subject line.

Use {{shareUrl}} to reference the participant's referral link.

| #### **Example use** ```javascript const message = "I have saved 1,540 hours using this service. Highly recommend! {{shareUrl}}"; const subjectLine = "Check this out!"; // Update the pre-populated email invite message and subject line growsurf.updateEmailInviteMessage(message, subjectLine); ``` *** ## REFERRAL PROGRAMS ↓ ### Trigger referral Referral programs only Triggers a referral, awarding referral credit to the referrer of an existing or new participant. If the program participant does not exist, they will be newly added. {% hint style="warning" %} **Note:** A `401` error will be returned but the referral will still be triggered if the following conditions are met: (1) the program has participant authentication enabled, (2) there is no authentication cookie present on the participant's browser, (3) the given email is the same as an existing participant. {% endhint %} ```javascript growsurf.triggerReferral(data, callback); ``` | Parameter | Data Type | Description | | -------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **`data`** | String or Object |

(Optional) A String containing the participant email or an Object containing the participant email and any other data to include for the participant.

If providing an Object, any Object keys other than email, firstName, and lastName will be treated as metadata by GrowSurf.

\*This parameter is only optional if the participant has already signed up for the campaign and GrowSurf is able to determine they are a participant (does not include participants imported or manually added using the dashboard). For more information about metadata please see our API Guidelines.

| | **`callback`** | Function | (Optional) A callback function that will be invoked with the added or updated participant data if successful. | Returns a [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Using_promises)that resolves with an [Object](https://developer.mozilla.org/en-US/docs/Learn/JavaScript/Objects/Basics)containing limited participant data. #### **Example use** {% tabs %} {% tab title="Using Callbacks" %} ```javascript // Email only using a Callback growsurf.triggerReferral('gavin@hooli.com', (participant) => { // handle participant }); // Object using a Callback growsurf.triggerReferral({ email: 'gavin@hooli.com', firstName: 'Gavin', // optional, but recommended for anti-fraud purposes lastName: 'Belson', // optional, but recommended for anti-fraud purposes company: 'Hooli, Inc', // Fields that are not email, firstName, or lastName will be saved as custom metadata companySize: 10000 // Fields that are not email, firstName, or lastName will be saved as custom metadata }, (participant) => { // handle participant }); ``` {% endtab %} {% tab title="Using Promises" %} ```javascript // Email only using a Promise growsurf.triggerReferral('gavin@hooli.com').then(participant => { // handle participant }); // Object using a Promise growsurf.triggerReferral({ email: 'gavin@hooli.com', firstName: 'Gavin', lastName: 'Belson', company: 'Hooli, Inc', companySize: 10000 }).then(participant => { // handle participant }); ``` {% endtab %} {% endtabs %} #### Example response ```json { "id": "kafewp", "firstName": "Gavin", "lastName": "Belson", "referralCount": 0, "shareUrl": "https://piedpiper.com?grsf=gavin-kafewp", "rewards": [], "vanityKeys" [ "gavin-kafewp" ] } ``` *** ### Get upfront discount Referral programs only Use this method when you want to apply an upfront discount to a referred friend (e.g., "Get 20% off your first invoice"). Returns the upfront discount promotion code and coupon ID for the current referred visitor. Returns `null` if the visitor was not referred, if no upfront discount is enabled, or if the program has ended. {% hint style="warning" %} **Note:** The upfront discount must be enabled on a Double-Sided reward (via the "Give the referred friend their reward upfront instead of after they complete the qualifying action" toggle) and a coupon integration ([Stripe](https://docs.growsurf.com/integrations/stripe#upfront-discounts), [Chargebee](https://docs.growsurf.com/integrations/chargebee#upfront-discounts), or [Recurly](https://docs.growsurf.com/integrations/recurly#upfront-discounts)) must be connected with referred friend coupon settings. The visitor must have been referred (i.e., arrived via a referral link) for a discount to be returned. {% endhint %} | Parameter | Data Type | Description | | ----------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | | `integrationType` | String | (Optional) One of `'stripe'`, `'chargebee'`, or `'recurly'`. If omitted, returns the first available upfront discount across all integrations. | Returns an [Object](https://developer.mozilla.org/en-US/docs/Learn/JavaScript/Objects/Basics) or `null`. #### Example use ```js // Get the first available upfront discount const discount = window.growsurf.getUpfrontDiscount(); // Get Stripe-specific upfront discount const stripeDiscount = window.growsurf.getUpfrontDiscount('stripe'); // Get Chargebee-specific upfront discount const chargebeeDiscount = window.growsurf.getUpfrontDiscount('chargebee'); if (discount) { // Apply the promotion code to your checkout flow applyDiscount(discount.promotionCode); } ``` #### Example response ```js { integration: 'stripe', // Which integration the discount is from promotionCode: 'GRSF-A1B2C3D4', // Customer-facing code couponId: 'coupon_abc123' // Provider coupon ID } ``` *** ### Get referral summary Referral programs only Returns referral summary statistics for the currently logged-in participant. {% hint style="warning" %} **Note:** A `401` error will be returned if the following conditions are met: (1) the program has participant authentication enabled, (2) there is no authentication cookie present on the participant's browser {% endhint %} ```javascript growsurf.getReferralSummary(); ``` Returns a [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Using_promises) that resolves with an [Object](https://developer.mozilla.org/en-US/docs/Learn/JavaScript/Objects/Basics) containing the participant's referral summary stats. #### Example use {% tabs %} {% tab title="Using Callbacks" %} ```javascript // Using a Callback growsurf.getReferralSummary({}, (summary) => { console.log('Referral Summary:', summary); }); ``` {% endtab %} {% tab title="Using Promises" %} ```javascript // Using a Promise const summary = await growsurf.getReferralSummary(); console.log(summary); ``` {% endtab %} {% endtabs %} #### Example response ```json { "referrals": 23, // Number of successful referrals "leads": 45, // Number of pending referrals (leads) "expiredReferrals": 3, // Number of referrals that expired before being credited "clicks": 23000, // Number of unique visitors from the participant's referral link "rewardsEarned": 4, // Number of rewards the participant has earned (approved) "pendingRewards": 1, // Number of rewards still waiting to be approved (not yet earned) "invitesSent": 12, // Number of email invites the participant has sent through GrowSurf "currencyISO": "USD" // The ISO 4217 currency code of the campaign } ``` *** ## AFFILIATE PROGRAMS ↓ ### Get commissions Affiliate programs only Returns a paginated list of commissions for the logged-in participant. {% hint style="warning" %} **Note:** A `401` error will be returned if the following conditions are met: (1) the program has participant authentication enabled, (2) there is no authentication cookie present on the participant's browser {% endhint %} ```javascript growsurf.getCommissions(options, callback); ``` | Parameter | Data Type | Description | | -------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **`options`** | Object | (Optional) An object containing pagination options. | | **`options.limit`** | Number | (Optional) The number of commissions to return per page. Defaults to 20. | | **`options.nextId`** | String | (Optional) The ID of the commission 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 commissions otherwise the `nextId` value will be `null`. | Returns a [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Using_promises)that resolves with an [Object](https://developer.mozilla.org/en-US/docs/Learn/JavaScript/Objects/Basics)containing limited commissions data. #### **Example use** {% tabs %} {% tab title="Using Callbacks" %} ```javascript // Using a Callback - First page growsurf.getCommissions({ limit: 10 }, (result) => { console.log(result.commissions); // Array of commission objects console.log(result.summary); // Summary of commissions by status console.log(result.hasMore); // Boolean indicating if more results are available console.log(result.nextId); // Cursor ID for next page (undefined if no more results) }); // Fetching the next page growsurf.getCommissions({ limit: 10, nextId: 'comm_abc123' }, (result) => { console.log(result.commissions); // Next page of results }); ``` {% endtab %} {% tab title="Using Promises" %} ```javascript // Using a Promise - First page const result = await growsurf.getCommissions({ limit: 10 }); console.log(result.commissions); // Array of commission objects console.log(result.summary); // Summary of commissions by status // Fetching additional pages if (result.hasMore) { const nextPage = await growsurf.getCommissions({ limit: 10, nextId: result.nextId }); console.log(nextPage.commissions); // Next page of results } ``` {% endtab %} {% endtabs %} #### Example response ```json { "commissions": [ { "id": "comm_t1so1w", "amount": 7228, "currencyISO": "USD", "status": "PENDING", "holdDuration": 0, "createdAt": 1764768074294, "amountInCampaignCurrency": 7228, "saleAmountInCampaignCurrency": 38900, "campaignCurrencyISO": "USD" } ], "summary": { "pending": { "count": 1, "totalAmount": 7228 }, "approved": { "count": 0, "totalAmount": 0 }, "paid": { "count": 0, "totalAmount": 0 }, "reversed": { "count": 0, "totalAmount": 0 } }, "totalCount": 1, "totalAmount": 7228, "nextId": "comm_def456", "hasMore": true } ``` *** ### Get payouts Affiliate programs only Returns a paginated list of payouts for the logged-in participant. {% hint style="warning" %} **Note:** A `401` error will be returned if the following conditions are met: (1) the program has participant authentication enabled, (2) there is no authentication cookie present on the participant's browser {% endhint %} ```javascript growsurf.getPayouts(options, callback); ``` | Parameter | Data Type | Description | | -------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **`options`** | Object | (Optional) An object containing pagination options. | | **`options.limit`** | Number | (Optional) The number of payouts to return per page. Defaults to 20. | | **`options.nextId`** | String | (Optional) The ID of the payout 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 payouts otherwise the `nextId` value will be `null`. | Returns a [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Using_promises)that resolves with an [Object](https://developer.mozilla.org/en-US/docs/Learn/JavaScript/Objects/Basics)containing limited payouts data. #### **Example use** {% tabs %} {% tab title="Using Callbacks" %} ```javascript // Using a Callback - First page growsurf.getPayouts({ limit: 10 }, (result) => { console.log(result.payouts); // Array of payout objects console.log(result.summary); // Summary of payouts by status console.log(result.hasMore); // Boolean indicating if more results are available console.log(result.nextId); // Cursor ID for next page (undefined if no more results) }); // Fetching the next page growsurf.getPayouts({ limit: 10, nextId: 'payout_xyz' }, (result) => { console.log(result.payouts); // Next page of results }); ``` {% endtab %} {% tab title="Using Promises" %} ```javascript // Using a Promise - First page const result = await growsurf.getPayouts({ limit: 10 }); console.log(result.payouts); // Array of payout objects console.log(result.summary); // Summary of commissions by status // Fetching additional pages if (result.hasMore) { const nextPage = await growsurf.getPayouts({ limit: 10, nextId: result.nextId }); console.log(nextPage.payouts); // Next page of results } ``` {% endtab %} {% endtabs %} #### Example response ```json { "payouts": [ { "id": "po_kj19ss", "amount": 91212, "currencyISO": "USD", "status": "UPCOMING", "createdAt": 1763974665314, "amountInCampaignCurrency": 91212, "campaignCurrencyISO": "USD" }, { "id": "po_asaj1s", "amount": 89120, "currencyISO": "USD", "status": "ISSUED", "createdAt": 1763974665314, "amountInCampaignCurrency": 89120, "campaignCurrencyISO": "USD" } ], "summary": { "upcoming": { "count": 1, "totalAmount": 91212 }, "queued": { "count": 0, "totalAmount": 0 }, "issued": { "count": 1, "totalAmount": 89120 } }, "totalCount": 2, "totalAmount": 180332, "nextId": "po_x99s1o", "hasMore": true } ``` *** ### Get affiliate summary Affiliate programs only Returns affiliate summary statistics for the currently logged-in participant. {% hint style="warning" %} **Note:** A `401` error will be returned if the following conditions are met: (1) the program has participant authentication enabled, (2) there is no authentication cookie present on the participant's browser {% endhint %} ```javascript growsurf.getAffiliateSummary(); ``` Returns a [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Using_promises)that resolves with an [Object](https://developer.mozilla.org/en-US/docs/Learn/JavaScript/Objects/Basics)containing limited commissions data. #### Example use {% tabs %} {% tab title="Using Callbacks" %} ```javascript // Using a Callback growsurf.getAffiliateSummary({}, (summary) => { console.log('Affiliate Summary:', summary); }); ``` {% endtab %} {% tab title="Using Promises" %} ```javascript // Using a Promise const summary = await growsurf.getAffiliateSummary(); console.log(summary); ``` {% endtab %} {% endtabs %} #### Example response ```json { "referralRevenue": 2500000, // Total revenue generated from referrals (in minor currency units, e.g., cents) "totalPaidOut": 1500000, // Total commissions paid out to the affiliate (in minor currency units) "upcomingPayout": 500000, // Pending commissions to be paid out (in minor currency units) "referrals": 23, // Number of successful referrals "leads": 45, // Number of pending referrals (leads) "clicks": 23000, // Number of unique visitors from the affiliate's referral link (aka unique impressions) "currencyISO": "USD" // The ISO 4217 currency code of the campaign (e.g., "USD") } ``` *** ## NOTIFICATIONS ↓ ### Initialize unread notifications badge This method will inject an unread notifications badge onto a target element.

The unread badge will be injected into your target element

This method is useful for highlighting an unread notifications badge to your users from within your own user portal. We recommend that the target element be a button that opens the GrowSurf window (via [`growsurf.open()`](https://docs.growsurf.com/developer-tools/javascript-sdk/api-reference#open-growsurf-window)), because the unread notifications badge will be cleared when the participant views the respective section in the GrowSurf window (rewards section for referral programs; commissions or payouts sections for affiliate programs). {% hint style="info" %} Alternatively, you can use [`growsurf.markNotificationsAsRead()`](https://docs.growsurf.com/developer-tools/javascript-sdk/api-reference#mark-notifications-as-read) to clear the unread notifications badge. {% endhint %} If a participant cookie doesn't exist, the badge will not be displayed on the target element. ```javascript growsurf.initUnreadNotificationsBadge(targetElement, type); ```

Parameter Data Type Description

Parameter	Data Type	Description
`targetElement`	String	(Required) The target element Example: `.my-button`
`type`	String	(Optional) Available options: `rewards` `commissions` `payouts` If no `type` is provided, then all unread notification badges will be initialized.

targetElement

String

(Required) The target element

Example: .my-button

type String (Optional) Available options:

rewards
commissions
payouts

If no type is provided, then all unread notification badges will be initialized.

#### **Example use** ```html Refer and Earn ``` {% hint style="success" %} #### **CSS Alternative:** Instead of using the JavaScript method `growsurf.initUnreadNotificationsBadge()`, you can simply add a CSS class `growsurf-unread-notifications-badge` to your target element. This will also inject the unread badge without requiring JavaScript.\ \ **Here is an example:** ```html Refer and Earn ``` **Note:** You'll need to make sure you have the [GrowSurf Universal Code](https://docs.growsurf.com/getting-started#get-the-growsurf-universal-code) installed. {% endhint %} {% hint style="danger" %} **Important Note**: Notification counts will not appear if you have certain sections disabled within the *Program Editor > 2. Design > Rewards* section. For example: * For referral programs, if you have the rewards section hidden (see image below), the notification counts will not appear.

* For affiliate programs, if you have the commissions or payouts sections hidden (see image below), the notification counts will only reflect the sections that are enabled.

{% endhint %} *** ### Get unread notifications count Returns the number of unread notifications (rewards for referral programs; commissions and payouts for affiliate programs) of the authenticated participant or **`null`** if there is no participant authentication cookie present. This method is useful for highlighting an unread notifications badge to your users from within your own user portal. {% hint style="info" %} Alternatively, you can use the [`growsurf.initUnreadNotificationsBadge()`](https://docs.growsurf.com/developer-tools/javascript-sdk/api-reference#initialize-unread-notifications-badge) method for displaying the unread notifications count as a badge on a target element. {% endhint %}

Parameter	Data Type	Description
`type`	String	(Optional) Available options: `rewards` `commissions` `payouts` If no `type` is provided, then all unread notification counts will be returned.

```javascript growsurf.getUnreadNotificationsCount(type); ``` #### **Example use** ```javascript growsurf.getUnreadNotificationsCount('rewards'); ``` **Example response** ```javascript 2 ``` {% hint style="danger" %} **Important Note**: Notification counts will not appear if you have certain sections disabled within the *Program Editor > 2. Design > Rewards* section. For example: * For referral programs, if you have the rewards section hidden (see image below), the notification counts will not appear.

* For affiliate programs, if you have the commissions or payouts sections hidden (see image below), the notification counts will only reflect the sections that are enabled.

{% endhint %} *** ### Mark notifications as read Mark unread notifications of the authenticated participant. This method is useful if you are using [`growsurf.initUnreadNotificationsBadge()`](https://docs.growsurf.com/developer-tools/javascript-sdk/api-reference#initialize-unread-notifications-badge) instead of the GrowSurf window to show your users their unread notifications count and want to clear out the unread badge. ```javascript growsurf.markNotificationsAsRead(type); ```

Parameter	Data Type	Description
`type`	String	(Optional) Available options: `rewards` `commissions` `payouts` If no `type` is provided, then all unread notifications will be marked as read.

Returns a [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Using_promises)that resolves with an [Object](https://developer.mozilla.org/en-US/docs/Learn/JavaScript/Objects/Basics)with a success response. #### **Example use** {% tabs %} {% tab title="Using Callbacks" %} ```javascript // Using a Callback growsurf.markNotificationsAsRead(response => { // handle success response }); ``` {% endtab %} {% tab title="Using Promises" %} ```javascript // Using a Promise growsurf.markNotificationsAsRead().then(response => { // handle success response }); ``` {% endtab %} {% endtabs %} #### Example response ```json { "success": true } ``` *** ## EVENTS ↓ ### Subscribe to event Adds an event subscription of the given event type. When an event of the given type occurs, the given callback will be invoked. Below are detailed descriptions of each event type. ```javascript growsurf.subscribe(eventType, callback); ``` | Parameter | Data Type | Description | | --------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **`eventType`** | String |

(Required) The event type to subscribe to.

These are the options:

referral
referralTrigger
signup
share
invite

| | **`callback`** | Function | The callback function that will be invoked when the event occurs. | #### **Example use** ```javascript /** * REFERRED FRIEND EVENTS */ // Subscribe to a `referral` event type growsurf.subscribe('referral', (participant) => { // A new participant was referred }); // Subscribe to a `referralTrigger` event type growsurf.subscribe('referralTrigger', (participant) => { // A referred participant triggered a referral (AKA they completed the qualifying action) }); /** * REFERRER EVENTS */ // Subscribe to a `signup` event type growsurf.subscribe('signup', (participant) => { // A new participant was added (only non-referred signups) }); // Subscribe to a `share` event type growsurf.subscribe('share', (data) => { // A participant shared their unique referral URL by clicking a social share button }); // Subscribe to an `invite` event type growsurf.subscribe('invite', (participant) => { // A participant sent out an invite }); ``` #### **Example response** Dispatched anytime an event happens. The provided callback will be invoked with an Object containing data relevant to the event. {% tabs %} {% tab title="" %} The `'referral'` event returns limited data of the new referred participant. The `referredBy` key represents the referring participant's unique ID. ```json { "id": "kafewp", "email": "gavin@hooli.com", "firstName": "Gavin", "lastName": "Belson", "referredBy": "xyz789", "referralCount": 0, "shareUrl": "https://piedpiper.com?grsf=kafewp", "rewards": [], "campaign": { "id": "abc123" } } ``` {% endtab %} {% tab title="" %} The `'referralTrigger'` Event returns limited data of the referred participant that triggered a referral (which means they completed a qualifying action). **Note:** This event happens when calling [`growsurf.triggerReferral()`](https://docs.growsurf.com/developer-tools/javascript-sdk/api-reference#trigger-referral). If you are looking for the referred signup event, use the 'referral' Event that contains a `referredBy` property. ```json { "id": "kafewp", "email": "gavin@hooli.com", "firstName": "Gavin", "lastName": "Belson", "referralCount": 0, "shareUrl": "https://piedpiper.com?grsf=kafewp", "rewards": [], "campaign": { "id": "abc123" } } ``` {% endtab %} {% tab title="" %} The `'signup'` Event returns limited data of the new non-referred participant. ```json { "id": "kafewp", "email": "gavin@hooli.com", "firstName": "Gavin", "lastName": "Belson", "referralCount": 0, "shareUrl": "https://piedpiper.com?grsf=kafewp", "rewards": [], "campaign": { "id": "abc123" } } ``` {% endtab %} {% tab title="" %} The `'share'` Event returns limited data of the participant and the share type. The `shareType` value will either be a social network (e.g., `linkedin`, `reddit`) or `copyLink` if the participant copied their link to share (e.g., they clicked "Copy Link"). ```json { "participant": { "id": "kafewp", "email": "gavin@hooli.com", "firstName": "Gavin", "lastName": "Belson", "referralCount": 0, "shareUrl": "https://piedpiper.com?grsf=kafewp", "rewards": [] }, "shareType": "facebook", "campaign": { "id": "abc123" } } ``` {% endtab %} {% tab title="" %} The `'invite'` Event returns limited data of the participant and the number of invites sent.
If your campaign is set up for email invites to be sent by participants, `invitesAttempted` will always match `invitesSent`. If email invites are sent by your company, `invitesSent` will only count successfully delivered emails confirmed by our server. [Learn more here](https://support.growsurf.com/article/353-how-email-invites-work). ```json { "participant": { "id": "kafewp", "email": "gavin@hooli.com", "firstName": "Gavin", "lastName": "Belson", "referralCount": 0, "shareUrl": "https://piedpiper.com?grsf=kafewp", "rewards": [] }, "invitesAttempted": 3, "invitesSent": 3, "campaign": { "id": "abc123" } } ``` {% endtab %} {% endtabs %} # Client Response Codes Refer to the below response code glossary to help you troubleshoot any errors when using the JavaScript SDK or Embeddable Elements. ## Glossary | **Response Code** | **Messages** | **Explanation** | | -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `200 OK` | The request was successful! | N/A | | `400 Bad Request` | Participant cannot join this program. | The participant was prevented from being added to the program (please check that your program's anti-fraud settings are not set to *Strict*, or that you do not have the email or IP address blacklisted) | | `401 Unauthorized` | Participant authentication is required. | If an existing participant is trying to access their account, they need to first authenticate (by logging in via one-time access token link in email) | | `401 Failed to add participant` | Participant was not able to join this program. | The person may be a high-risk fraudster, and has been blocked from entering the program. [Learn more about how GrowSurf's anti-fraud system works](https://support.growsurf.com/article/195-what-does-the-growsurf-anti-fraud-system-entail). | | `402` | Usage limit exceeded | N/A | | `403 Forbidden` |

You are not allowed to perform that action.
No valid participant access token provided.
Request was blocked (includes CORS issues)

This may be due to the URL not matching what is configured for your program. Make sure to check your whitelisted URLs as well. Any URLs that makes excessive unauthorized requests to your GrowSurf program may be blocked. Please reach out to for assistance.
If an existing participant is trying to access their account, they need to first authenticate (by logging in via one-time access token link in email)
Your program may be blocked due to excessive requests made to our system from the same IP address. Please see this article.

If a request is made but has not finished and that exact same request is made.

More details on the specific request will be provided within the returned error.

| | `429 Too Many Requests` | You have reached your \ limit | You have reached the rate limit. | | `5XX Internal Server Error` | The GrowSurf server is inaccessible or offline -- that's our fault! Check for updates on our [status page](https://growsurf.com/status). | N/A | # iOS SDK (Beta) Install and use the GrowSurf iOS SDK to capture referral attribution, create referred participants, and show a native referral window in your app. {% hint style="info" %} If you're using an AI tool such as Cursor, Codex, Claude Code, or Antigravity to help you implement GrowSurf, we recommend utilizing our [MCP server](https://docs.growsurf.com/build-with-ai). {% endhint %} ## Install The core library is lightweight, adding roughly \~2.6 MB (uncompressed device binary) to your iOS app (attribution adapters add only tens of KB each). Choose one install path. {% tabs %} {% tab title="CocoaPods" %} Add the SDK from the public `v0.3.3` podspec: ```ruby growsurf_podspec = 'https://raw.githubusercontent.com/growsurf/growsurf-ios-sdk-distribution/v0.3.3/GrowSurfSDK.podspec' pod 'GrowSurfSDK', :podspec => growsurf_podspec ``` Optional attribution adapter subspecs: ```ruby pod 'GrowSurfSDK/BranchAttribution', :podspec => growsurf_podspec pod 'GrowSurfSDK/AdjustAttribution', :podspec => growsurf_podspec pod 'GrowSurfSDK/AppsFlyerAttribution', :podspec => growsurf_podspec pod 'GrowSurfSDK/SingularAttribution', :podspec => growsurf_podspec ``` {% endtab %} {% tab title="Swift Package Manager" %} In Xcode, add the public binary package repository: ``` https://github.com/growsurf/growsurf-ios-sdk-distribution.git ``` Choose version `0.3.3` or later, then add the `GrowSurfSDK` product to your app target. For a `Package.swift` target: ```swift dependencies: [ .package(url: "https://github.com/growsurf/growsurf-ios-sdk-distribution.git", from: "0.3.3"), ], targets: [ .target( name: "YourApp", dependencies: [ .product(name: "GrowSurfSDK", package: "growsurf-ios-sdk-distribution"), ] ), ] ``` Optional attribution adapter products are available from the same package: * `GrowSurfBranchAttribution` * `GrowSurfAdjustAttribution` * `GrowSurfAppsFlyerAttribution` * `GrowSurfSingularAttribution` The optional `GrowSurfGoogleContacts` product additionally pulls in Google Sign-In, so add it only if you want the native in-app Google contacts sign-in sheet. {% endtab %} {% tab title="Manual XCFramework" %} 1. Download `GrowSurfSDK.xcframework.zip` from the public [`v0.3.3` release](https://github.com/growsurf/growsurf-ios-sdk-distribution/releases/tag/v0.3.3). 2. Unzip it and drag `GrowSurfSDK.xcframework` into your Xcode project. 3. In your app target, set `GrowSurfSDK.xcframework` to **Embed & Sign**. 4. Add optional adapter XCFrameworks the same way when you use Branch, Adjust, AppsFlyer, or Singular helpers. {% endtab %} {% endtabs %} {% hint style="info" %} If you use Branch, Adjust, AppsFlyer, or Singular, add the matching GrowSurf adapter and keep your provider's SDK setup in your app. {% endhint %} ### Initialize Enable Mobile SDK access in your GrowSurf program on the instructions page, then configure the SDK once when your app starts or before your first GrowSurf call. * Find `campaignId` in your GrowSurf program dashboard. It is the 6-character program ID, such as `p9josq`. * Find `publicKey` in *Program Editor > 5. Installation > Instructions page > Step 1. iOS > Configure SDK*. ```swift import GrowSurfSDK let growsurf = GrowSurf.configure( campaignId: "p9josq", publicKey: "pk_mobile" ) ``` {% hint style="info" %} Native apps use a public Mobile SDK key, which can safely be exposed. This is different than your REST API key on your backend, which you should always keep secret. {% endhint %} *** ## Track referrals Tracking referrals entails capturing attribution and creating new referred participants. ### Capture attribution Capture referral attribution before you create the referred friend's participant record. {% stepper %} {% step %} **For direct app links that open your installed app:** ```swift if let url { try await growsurf.handleDeepLink(url) } ``` {% hint style="info" %} **Already support deep links?** If you use an attribution provider (Branch, AppsFlyer, Adjust, Singular) or otherwise open your app from links, this is already set up — just forward the opened URL to `handleDeepLink(url)`. **Starting from scratch?** Register a custom URL scheme (`CFBundleURLSchemes` in `Info.plist`) — the quickest path, no domain needed — and/or configure Universal Links (Associated Domains entitlement) for nicer `https` links, which require a domain you control. Then call `handleDeepLink(url)` from your app's URL-open handler (SwiftUI `.onOpenURL` or `application(_:open:options:)`). {% endhint %} {% endstep %} {% step %} **For deferred deep links from an attribution provider:** Unlike Android (which reads the Play Install Referrer for native deferred attribution), iOS has no native deferred deep link mechanism, so deferred attribution is delegated to your attribution provider (e.g., Branch, AppsFlyer). View [Adapter docs](https://docs.growsurf.com/developer-tools/ios-sdk/attribution-providers#adapters) for your specific provider setup instructions. {% endstep %} {% endstepper %} ### Create a referred participant Use [`addReferredParticipant()`](https://docs.growsurf.com/developer-tools/ios-sdk/api-reference#add-referred-participant) for referred signups. This is typically where new users sign up in your app. The SDK validates saved or explicit attribution and only creates the participant when the referral code is valid. ```swift // Only creates a referred participant if the referral code is valid let created = try await growsurf.addReferredParticipant( .init( email: "person@example.com", firstName: "Ada", lastName: "Lovelace", metadata: ["plan": "pro"] // Optional, saved as participant metadata // The referral code and mobile instance ID (for anti-fraud) are passed automatically ) ) let participant = created.participant ``` *** ## Generate referral links for your users Generating referral links to users in your app entails generating a participant token by using the GrowSurf API, then opening the GrowSurf window. ### Generate a participant token To allow authenticated access to your logged-in users, you must call the GrowSurf backend to generate a participant token. {% stepper %} {% step %} **Call backend endpoint** [**create a mobile participant token**](/developer-tools/rest-api/api-reference#post-campaign-id-mobile-participant-token)**.** Here is an example `cURL` command: ```bash curl -X POST "https://api.growsurf.com/v2/campaign/YOUR_PROGRAM_ID/mobile-participant-token" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "email": "person@example.com", "firstName": "Ada", "lastName": "Lovelace", "mobileInstanceId": "5f7d0f4c-3e7c-4aa9-8c41-d81d998f0bb1", "ipAddress": "203.0.113.10", "metadata": { "plan": "pro" } }' ``` Only `email` is required. `firstName`, `lastName`, `mobileInstanceId`, and `ipAddress` are optional but recommended for anti-fraud. `metadata` is optional and is not used by GrowSurf. {% hint style="info" %} Using TypeScript, Python, PHP, Ruby, or Java for your backend? Use an official [GrowSurf API Library](https://docs.growsurf.com/developer-tools/rest-api/api-libraries). {% endhint %} **Optional:** To get `mobileInstanceId`, which is used for anti-fraud purposes, use the SDK method [`mobileInstanceId()`](https://docs.growsurf.com/developer-tools/ios-sdk/api-reference#get-mobile-instance-id). This will create a new participant or return an existing one, along with a participant token that allows authenticated calls. {% endstep %} {% step %} **Pass it to the app, then store in the SDK via** [**`setParticipantToken()`**](https://docs.growsurf.com/developer-tools/ios-sdk/api-reference#set-participant-token)**.** Here is example SDK code: ```swift let mobileInstanceId = try await growsurf.mobileInstanceId() // Used for anti-fraud (optional) let backendResponse = try await api.createMobileParticipantToken( email: user.email, mobileInstanceId: mobileInstanceId ) let participantToken = backendResponse.participantToken try await growsurf.setParticipantToken(participantToken) ``` {% endstep %} {% endstepper %} ### Show the GrowSurf window

The GrowSurf window allows your participants to view/share their referral link and track the status of their referrals and rewards. Call [`presentGrowSurfWindow()`](https://docs.growsurf.com/developer-tools/ios-sdk/api-reference#present-growsurf-window) from your own button, menu item, or referral screen. Set the `identity` parameter to [`.existingParticipantToken()`](https://docs.growsurf.com/developer-tools/ios-sdk/models-and-errors#growsurfwindowidentity), which will use the participant token you generated above. ```swift growsurf.presentGrowSurfWindow( from: viewController, identity: .existingParticipantToken(participantToken), theme: GrowSurfWindowTheme( primaryColorHex: "#13795B", presentationStyle: .automatic ), callbacks: GrowSurfWindowCallbacks( onShareTracked: { type in print("Share tracked: \(type)") }, onError: { error in print(error.localizedDescription) } ) ) ``` *** ## \[Optional] Google Contacts invites

Only needed when Google Contacts invites are enabled for your program. When enabled, the native GrowSurf window can read the participant's Google contacts (read-only) so they can pick people to invite. This works **out of the box** — the core `GrowSurfSDK` uses a dependency-free external-browser sign-in flow, so there is **no extra dependency to install** for the default experience. To use the **native in-app Google Sign-In sheet** instead (a smoother flow that doesn't leave your app), add the optional `GrowSurfGoogleContacts` product. It bundles Google Sign-In, so it is kept out of the core SDK — apps that don't use it never link GoogleSignIn. {% hint style="info" %} The native in-app Google Sign-In sheet is available via **Swift Package Manager only**. CocoaPods apps use the built-in browser-based Google contacts flow described above — no extra package needed. {% endhint %} Add the `GrowSurfGoogleContacts` product from the `growsurf-ios-sdk-distribution` package to your app target (alongside `GrowSurfSDK`). First complete the [Google Cloud setup](https://support.growsurf.com/article/343-how-to-set-up-google-contacts-address-book) to create your OAuth client and add your iOS Client ID and reversed-client-ID URL scheme to your GrowSurf campaign. The steps below are the additional in-app setup the in-app Google Sign-In sheet needs — without them the in-app sign-in will fail even when your campaign is configured correctly. {% stepper %} {% step %} **Enable the in-app GoogleSignIn flow** at app startup, before opening a GrowSurf window that offers Google contacts import: ```swift import GrowSurfGoogleContacts GrowSurfGoogleContacts.enable() ``` {% endstep %} {% step %} **Register your Google reversed-client-ID URL scheme** in `Info.plist`. Add a `CFBundleURLTypes` entry whose `CFBundleURLSchemes` value is your reversed client ID (the `REVERSED_CLIENT_ID` from your `GoogleService-Info.plist` / OAuth client, in the form `com.googleusercontent.apps.XXXXXXXX`). {% endstep %} {% step %} **Forward incoming URLs to GrowSurf** from your app's URL-open handler so the Google Sign-In callback is handled: ```swift // SwiftUI .onOpenURL { url in GrowSurf.handleGoogleSignInURL(url) } // UIKit func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey: Any] = [:]) -> Bool { GrowSurf.handleGoogleSignInURL(url) } ``` {% endstep %} {% endstepper %} Either way, the SDK requests only the `contacts.readonly` scope and imports the participant's primary Google connections. *** ## Log out If your user logs out of your app, call [`shutdown()`](https://docs.growsurf.com/developer-tools/ios-sdk/api-reference#shutdown) to remove all participant data from the device: ```swift try await growsurf.shutdown() ``` *** ## Next steps {% content-ref url="/pages/YE7Ni8qQb5eckfGra6D3" %} [Attribution Providers](/developer-tools/ios-sdk/attribution-providers) {% endcontent-ref %} {% content-ref url="/pages/NfDPGxhzyFbz5HJzp01b" %} [API Reference](/developer-tools/ios-sdk/api-reference) {% endcontent-ref %} {% content-ref url="/pages/slZUcKYhVJInEALri596" %} [Models and Errors](/developer-tools/ios-sdk/models-and-errors) {% endcontent-ref %} {% content-ref url="/pages/exdoU1ymhoG3SfIjmIsO" %} [Getting Started for Native Mobile](/getting-started-for-native-mobile) {% endcontent-ref %} # Attribution Providers Configure direct deep links and attribution adapters for the GrowSurf iOS SDK. On iOS, GrowSurf relies on your app or attribution provider to return the referral payload after install. Pass that payload into the SDK before calling `addReferredParticipant()`. Unlike Android (which reads the Play Install Referrer for native deferred attribution via `handleDeferredDeepLink()`), iOS has no native deferred deep link equivalent, so deferred attribution is delegated to your attribution provider (e.g., Branch, AppsFlyer). ### Why iOS deferred is provider-specific For a referral program, the deferred / cold-install path is the **primary** one — a referral targets people who don't yet have your app. When a friend taps a referral link, installs your app, then opens it for the first time (a **deferred** / cold install), iOS has no reliable native way to carry the referral across the install. iOS 14 (App Tracking Transparency removed the IDFA) and iOS 15 (Private Relay masks the Safari IP) broke the probabilistic device matching attribution providers previously relied on. Each provider now solves this differently, so **deferred setup is not interchangeable between providers** — follow the integration guide for yours. | Provider | iOS deferred mechanism | On by default? | What you must turn on | | ------------------------------------------------------------------------------- | ----------------------------------------------- | ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [**Branch**](/integrations/branch#ios-deferred-deep-linking-new-installs) | NativeLink (encrypted clipboard token) | Yes, once NativeLink is enabled | Branch dashboard **Enable NativeLink** + a non-web-only link; call `checkPasteboardOnInstall()` before `initSession()` (iOS 16+: consider `BranchPasteControl`). | | [**Adjust**](/integrations/adjust#ios-deferred-deep-linking-new-installs) | LinkMe (clipboard token) | No (optional) | `ADJConfig.enableLinkMe()` (v5) / `setLinkMeEnabled(true)` (v4) + link tag `adj_linkme=1` or `linkme=1`; otherwise deferred is server-side/probabilistic. | | [**Singular**](/integrations/singular#ios-deferred-deep-linking-new-installs) | Clipboard-Based DDL (clipboard token) | No (optional, enterprise) | `SingularConfig.clipboardAttribution = true` + Singular WebSDK on the landing page (ask your Singular CSM to enable); otherwise server-side/probabilistic. | | [**AppsFlyer**](/integrations/appsflyer#ios-deferred-deep-linking-new-installs) | Server-side Unified Deep Linking (no clipboard) | Yes | Implement the `deepLinkDelegate` / `didResolveDeepLink(_:)` callback; new installs receive `deep_link_value` + `deep_link_sub1`–`deep_link_sub10` within a \~15-min click-to-install window. | In every case the GrowSurf SDK simply reads `grsf` out of whatever deep link your provider hands back. So GrowSurf deferred attribution survives a cold install only when (1) your provider's deferred path is enabled (above) **and** (2) the link your participants share carries `grsf`. The integration guides cover keeping `grsf` on the link; this table covers turning on the provider's deferred path. {% hint style="info" %} Any **clipboard-based** path (Branch NativeLink, Adjust LinkMe, Singular Clipboard-Based DDL) triggers Apple's one-time "Pasted from …" prompt on first launch on iOS 16+. AppsFlyer's server-side UDL does not use the clipboard and shows no prompt. Provider SDK APIs are version-specific — confirm exact method names against your installed provider SDK. iOS deferred is **best-effort even when configured** — the user can decline the paste prompt, overwrite the clipboard before first launch, or tap from an in-app/non-Safari browser (AppsFlyer also has a \~15-minute click-to-install window) — so always pair it with a fallback such as manual referral-code entry. Android's Play Install Referrer is deterministic and not subject to these. {% endhint %} *** ## Direct deep links Use `handleDeepLink(_:)` when the installed app opens from a link that already contains `grsf`, which contains the referral code. ```swift if let url { let attribution = try await growsurf.handleDeepLink(url) } ``` {% hint style="info" %} **Example accepted links:** * `your-app://open?grsf=referrer_id` * `https://example.com/app?grsf=referrer_id` {% endhint %} {% hint style="info" %} **Already support deep links?** If you use an attribution provider (Branch, AppsFlyer, Adjust, Singular) or otherwise open your app from links, this is already set up — just forward the opened URL to `handleDeepLink(url)`. **Starting from scratch?** Register a custom URL scheme (`CFBundleURLSchemes` in `Info.plist`) — the quickest path, no domain needed — and/or configure Universal Links (Associated Domains entitlement) for nicer `https` links, which require a domain you control. Then call `handleDeepLink(url)` from your app's URL-open handler (SwiftUI `.onOpenURL` or `application(_:open:options:)`). {% endhint %} *** ## Adapters GrowSurf provides adapters for popular attribution providers. Choose your provider below, or use **Other** to pass a dictionary of attribution values from any other provider. {% tabs %} {% tab title="Adjust" %} ## Adjust adapter Add the Adjust adapter: {% tabs %} {% tab title="CocoaPods" %} ```ruby pod 'GrowSurfSDK/AdjustAttribution', :podspec => 'https://raw.githubusercontent.com/growsurf/growsurf-ios-sdk-distribution/v0.3.3/GrowSurfSDK.podspec' ``` {% endtab %} {% tab title="Swift Package Manager" %} Add the `GrowSurfAdjustAttribution` product alongside `GrowSurfSDK` from the public binary package repository: ``` https://github.com/growsurf/growsurf-ios-sdk-distribution.git ``` For a `Package.swift` target: ```swift dependencies: [ .package(url: "https://github.com/growsurf/growsurf-ios-sdk-distribution.git", from: "0.3.3"), ], targets: [ .target( name: "YourApp", dependencies: [ .product(name: "GrowSurfSDK", package: "growsurf-ios-sdk-distribution"), .product(name: "GrowSurfAdjustAttribution", package: "growsurf-ios-sdk-distribution"), ] ), ] ``` {% endtab %} {% tab title="Manual" %} Download `GrowSurfAdjustAttribution.xcframework.zip` from the public release: ``` https://github.com/growsurf/growsurf-ios-sdk-distribution/releases/tag/v0.3.3 ``` Unzip it, drag `GrowSurfAdjustAttribution.xcframework` into your Xcode project alongside `GrowSurfSDK.xcframework`, and set it to **Embed & Sign** in your app target. {% endtab %} {% endtabs %} Then pass the Adjust deferred deep link into GrowSurf: ```swift import GrowSurfAdjustAttribution try await GrowSurfAdjustAttribution.handle(adjustDeferredDeepLinkURL, sdk: growsurf) ``` The adapter accepts `URL` and `String` deep link values. {% hint style="warning" %} For **deferred** (no-app-installed) referrals on iOS, Adjust's clipboard path (**LinkMe**) is optional and off by default — enable it with `ADJConfig.enableLinkMe()` (v5) / `setLinkMeEnabled(true)` (v4) and tag your link `adj_linkme=1`/`linkme=1`; without it, deferred falls back to Adjust's server-side matching. See [Adjust - iOS Deferred Deep Linking](/integrations/adjust#ios-deferred-deep-linking-new-installs) for detailed instructions. {% endhint %} {% endtab %} {% tab title="AppsFlyer" %} ## AppsFlyer adapter Add the AppsFlyer adapter: {% tabs %} {% tab title="CocoaPods" %} ```ruby pod 'GrowSurfSDK/AppsFlyerAttribution', :podspec => 'https://raw.githubusercontent.com/growsurf/growsurf-ios-sdk-distribution/v0.3.3/GrowSurfSDK.podspec' ``` {% endtab %} {% tab title="Swift Package Manager" %} Add the `GrowSurfAppsFlyerAttribution` product alongside `GrowSurfSDK` from the public binary package repository: ``` https://github.com/growsurf/growsurf-ios-sdk-distribution.git ``` For a `Package.swift` target: ```swift dependencies: [ .package(url: "https://github.com/growsurf/growsurf-ios-sdk-distribution.git", from: "0.3.3"), ], targets: [ .target( name: "YourApp", dependencies: [ .product(name: "GrowSurfSDK", package: "growsurf-ios-sdk-distribution"), .product(name: "GrowSurfAppsFlyerAttribution", package: "growsurf-ios-sdk-distribution"), ] ), ] ``` {% endtab %} {% tab title="Manual" %} Download `GrowSurfAppsFlyerAttribution.xcframework.zip` from the public release: ``` https://github.com/growsurf/growsurf-ios-sdk-distribution/releases/tag/v0.3.3 ``` Unzip it, drag `GrowSurfAppsFlyerAttribution.xcframework` into your Xcode project alongside `GrowSurfSDK.xcframework`, and set it to **Embed & Sign** in your app target. {% endtab %} {% endtabs %} Then pass AppsFlyer conversion data into GrowSurf: ```swift import GrowSurfAppsFlyerAttribution try await GrowSurfAppsFlyerAttribution.handle(appsFlyerParams, sdk: growsurf) ``` The adapter accepts `[String: String]`, `[String: Any]`, and `[AnyHashable: Any]` payloads. {% hint style="warning" %} For **deferred** (no-app-installed) referrals on iOS, AppsFlyer has **no clipboard path** — the referral arrives via server-side **Unified Deep Linking** (`deepLinkDelegate` / `didResolveDeepLink(_:)`) within a \~15-minute lookback, carrying `deep_link_value` and `deep_link_sub1`–`deep_link_sub10`. See [AppsFlyer - iOS Deferred Deep Linking](/integrations/appsflyer#ios-deferred-deep-linking-new-installs) for detailed instructions. {% endhint %} {% endtab %} {% tab title="Branch" %} ## Branch adapter Add the Branch adapter: {% tabs %} {% tab title="CocoaPods" %} ```ruby pod 'GrowSurfSDK/BranchAttribution', :podspec => 'https://raw.githubusercontent.com/growsurf/growsurf-ios-sdk-distribution/v0.3.3/GrowSurfSDK.podspec' ``` {% endtab %} {% tab title="Swift Package Manager" %} Add the `GrowSurfBranchAttribution` product alongside `GrowSurfSDK` from the public binary package repository: ``` https://github.com/growsurf/growsurf-ios-sdk-distribution.git ``` For a `Package.swift` target: ```swift dependencies: [ .package(url: "https://github.com/growsurf/growsurf-ios-sdk-distribution.git", from: "0.3.3"), ], targets: [ .target( name: "YourApp", dependencies: [ .product(name: "GrowSurfSDK", package: "growsurf-ios-sdk-distribution"), .product(name: "GrowSurfBranchAttribution", package: "growsurf-ios-sdk-distribution"), ] ), ] ``` {% endtab %} {% tab title="Manual" %} Download `GrowSurfBranchAttribution.xcframework.zip` from the public release: ``` https://github.com/growsurf/growsurf-ios-sdk-distribution/releases/tag/v0.3.3 ``` Unzip it, drag `GrowSurfBranchAttribution.xcframework` into your Xcode project alongside `GrowSurfSDK.xcframework`, and set it to **Embed & Sign** in your app target. {% endtab %} {% endtabs %} Then pass Branch callback data into GrowSurf: ```swift import GrowSurfBranchAttribution try await GrowSurfBranchAttribution.handle(branchParams, sdk: growsurf) ``` The adapter accepts `[String: String]`, `[String: Any]`, and `[AnyHashable: Any]` payloads. {% hint style="warning" %} For **deferred** (no-app-installed) referrals on iOS, Branch requires **NativeLink**: enable it in the Branch dashboard (Configuration → Enable NativeLink) with a non-web-only link, and call `Branch.getInstance().checkPasteboardOnInstall()` **before** `initSession()` so the SDK reads the NativeLink clipboard token on first launch (iOS 14+ removed the fingerprint matching used previously; on iOS 16+ Branch also offers `BranchPasteControl` as a user-tappable alternative to the silent read). See [Branch - iOS Deferred Deep Linking](/integrations/branch#ios-deferred-deep-linking-new-installs) for detailed instructions. {% endhint %} {% endtab %} {% tab title="Singular" %} ## Singular adapter Add the Singular adapter: {% tabs %} {% tab title="CocoaPods" %} ```ruby pod 'GrowSurfSDK/SingularAttribution', :podspec => 'https://raw.githubusercontent.com/growsurf/growsurf-ios-sdk-distribution/v0.3.3/GrowSurfSDK.podspec' ``` {% endtab %} {% tab title="Swift Package Manager" %} Add the `GrowSurfSingularAttribution` product alongside `GrowSurfSDK` from the public binary package repository: ``` https://github.com/growsurf/growsurf-ios-sdk-distribution.git ``` For a `Package.swift` target: ```swift dependencies: [ .package(url: "https://github.com/growsurf/growsurf-ios-sdk-distribution.git", from: "0.3.3"), ], targets: [ .target( name: "YourApp", dependencies: [ .product(name: "GrowSurfSDK", package: "growsurf-ios-sdk-distribution"), .product(name: "GrowSurfSingularAttribution", package: "growsurf-ios-sdk-distribution"), ] ), ] ``` {% endtab %} {% tab title="Manual" %} Download `GrowSurfSingularAttribution.xcframework.zip` from the public release: ``` https://github.com/growsurf/growsurf-ios-sdk-distribution/releases/tag/v0.3.3 ``` Unzip it, drag `GrowSurfSingularAttribution.xcframework` into your Xcode project alongside `GrowSurfSDK.xcframework`, and set it to **Embed & Sign** in your app target. {% endtab %} {% endtabs %} Then pass Singular callback data into GrowSurf: ```swift import GrowSurfSingularAttribution try await GrowSurfSingularAttribution.handle(singularParams, sdk: growsurf) ``` The adapter accepts `[String: String]`, `[String: Any]`, `[AnyHashable: Any]`, `URL`, and `String` payloads. It parses GrowSurf referral keys from Singular deep link, deferred deep link, and passthrough fields such as `_dl`, `_ddl`, and `_p`. {% hint style="warning" %} For **deferred** (no-app-installed) referrals on iOS, Singular **Clipboard-Based DDL** is an optional, enterprise feature requiring `SingularConfig.clipboardAttribution = true` and the Singular WebSDK on your landing page (enabled via your Singular CSM); otherwise deferred is server-side/probabilistic. See [Singular - iOS Deferred Deep Linking](/integrations/singular#ios-deferred-deep-linking-new-installs) for detailed instructions. {% endhint %} {% endtab %} {% tab title="Other" %} ## Manual attribution parameters Use `handleAttributionParameters(_:provider:)` for any other provider that can return a dictionary of attribution values. No extra adapter install is required. ```swift try await growsurf.handleAttributionParameters( [ "grsf": "referrer_id", "click_id": "click_123", ], provider: "your-provider-name" ) ``` {% endtab %} {% endtabs %} *** ## Accepted attribution keys | Key | Description | | ------------ | ------------------------------------------------------------------------------------------------ | | `grsf` | Preferred GrowSurf referrer ID. | | `ref` | Alternate referrer ID. | | `referredBy` | Alternate referrer ID. | | `provider` | Attribution provider name. Ignored when the SDK method receives an explicit `provider` argument. | | `clickId` | Provider click ID metadata. | | `click_id` | Provider click ID metadata. | | `unique` | Optional boolean string: `true` or `false`. | The SDK also parses values nested inside URL-like payload fields. For example, a provider value of `https://example.com/?grsf=referrer_id&click_id=click_123` can still produce GrowSurf attribution. If a provider returns a GrowSurf-hosted share URL such as `https://grow.surf/share/:campaignId/:referrerId`, the SDK uses the participant value from the path. # API Reference Public methods, attribution adapters, and models exposed by the GrowSurf iOS SDK. {% hint style="info" %} If you're using an AI tool such as Cursor, Codex, Claude Code, or Antigravity to help you implement GrowSurf, we recommend utilizing our [MCP server](https://docs.growsurf.com/build-with-ai). {% endhint %} Use this page to look up individual GrowSurf iOS SDK methods. All SDK methods use Swift concurrency unless otherwise noted. {% hint style="warning" %} Use the Mobile SDK public key in your app. Do not embed your secret REST API key in an iOS app. {% endhint %} ## SDK LIFECYCLE ↓ ### Configure Call this once before using GrowSurf. It connects the SDK to your GrowSurf campaign and Mobile SDK public key. ```swift let growsurf = GrowSurf.configure( campaignId: "abc123", publicKey: "pk_mobile" ) ``` | Parameter | Data Type | Description | | ---------------- | --------- | -------------------------------------------------------------------------------------------- | | **`campaignId`** | `String` | (Required) Your GrowSurf program ID. | | **`publicKey`** | `String` | (Required) Your Mobile SDK public key. | | **`baseURL`** | `URL` | (Optional) Custom Mobile SDK API base URL. Defaults to `https://api.growsurf.com/mobile/v2`. | Returns a configured `GrowSurf` instance. #### **Example use** ```swift import GrowSurfSDK let growsurf = GrowSurf.configure( campaignId: "p9josq", publicKey: "pk_mobile" ) ``` Optionally, for advanced apps, initialize directly with explicit stores or a custom transport. Pass the production stores shown below, or your own conformances to the public store protocols: ```swift let growsurf = GrowSurf( configuration: GrowSurfConfiguration( campaignId: "abc123", publicKey: "pk_mobile" ), tokenStore: GrowSurfKeychainTokenStore(), attributionStore: GrowSurfUserDefaultsAttributionStore(), mobileInstanceIdStore: GrowSurfUserDefaultsMobileInstanceIdStore() ) ``` *** ### Set participant token Use this after your backend creates a mobile participant token for a signed-in user. It lets participant-scoped SDK calls load or update that participant's data. ```swift try await growsurf.setParticipantToken(participantToken) ``` | Parameter | Data Type | Description | | ----------- | --------- | --------------------------------------------------------------------------------------------------- | | **`token`** | `String` | (Required) A mobile participant token returned by your backend or by a participant creation method. | Returns `Void`. #### **Example use** ```swift try await growsurf.setParticipantToken(participantToken) ``` {% hint style="info" %} Use this method with tokens created by the REST API mobile participant token endpoint after a user is already signed in. {% endhint %} *** ### Get participant token Returns the participant token currently held by the SDK, or `nil` if none is stored. Useful right after the GrowSurf window's `ParticipantFields` signup flow so your app can persist the freshly minted token for the user's next session. ```swift try await growsurf.participantToken() ``` Returns `String?`. #### **Example use** ```swift if let token = try await growsurf.participantToken() { // Persist the token to your backend so the user stays signed in to GrowSurf. } ``` *** ### Get current participant ID Returns the current participant's ID decoded from the stored participant token, or `nil` if no participant token is set. ```swift let participantId = try await growsurf.currentParticipantId() ``` Returns `String?`. #### **Example use** ```swift if let participantId = try await growsurf.currentParticipantId() { print("Current participant:", participantId) } ``` *** ### Get mobile instance ID Returns the app-install ID the SDK sends with participant creation for mobile anti-fraud. You usually only need this if your backend creates mobile participant tokens and needs to pass the same ID to GrowSurf. ```swift try await growsurf.mobileInstanceId() ``` Returns a lowercase UUID `String`. #### **Example use** ```swift let mobileInstanceId = try await growsurf.mobileInstanceId() ``` {% hint style="info" %} Participant creation methods send `mobileInstanceId` automatically. Read it manually only when your backend creates a mobile participant token and needs to pass `mobileInstanceId` to the REST API. {% endhint %} *** ### Shutdown Call this when a user signs out or you need to reset GrowSurf state on the device. It clears the stored session token, participant token, and pending attribution. ```swift try await growsurf.shutdown() ``` Returns `Void`. #### **Example use** ```swift try await growsurf.shutdown() ``` *** ## CAMPAIGNS ↓ ### Get campaign Use this to read campaign details and rewards for the configured GrowSurf program. The SDK creates or uses a session token before calling GrowSurf. ```swift try await growsurf.getCampaign() ``` Returns `GrowSurfCampaign`. #### **Example use** ```swift let campaign = try await growsurf.getCampaign() print(campaign.id) print(campaign.rewards) ``` *** ### Get leaderboard Use this to show leaderboard rows in a custom referral screen. You can page through results with page or cursor parameters. ```swift try await growsurf.getLeaderboard( limit: 20, page: 1, offsetKey: nil, leaderboardType: nil ) ``` | Parameter | Data Type | Description | | --------------------- | --------- | -------------------------------------------------- | | **`limit`** | `Int?` | (Optional) Number of rows to return. | | **`page`** | `Int?` | (Optional) Page number. | | **`offsetKey`** | `String?` | (Optional) Cursor key for offset-based pagination. | | **`leaderboardType`** | `String?` | (Optional) Leaderboard type filter. | Returns `GrowSurfLeaderboardResponse`. #### **Example use** ```swift let leaderboard = try await growsurf.getLeaderboard(limit: 10) for row in leaderboard.participants { print(row.rank as Any, row.email as Any) } ``` *** ## GROWSURF WINDOW ↓ ### Present GrowSurf window Call this from your own button, menu item, or referral screen to open GrowSurf's native SwiftUI referral window. {% hint style="info" %} The native GrowSurf window uses the GrowSurf window settings from your dashboard. This method is available on iOS. {% endhint %} ```swift growsurf.presentGrowSurfWindow( from: viewController, identity: .existingParticipantToken(participantToken), theme: GrowSurfWindowTheme(), callbacks: GrowSurfWindowCallbacks() ) ``` | Parameter | Data Type | Description | | --------------- | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **`from`** | `UIViewController` | (Required) The view controller that presents the native window. | | **`identity`** | `GrowSurfWindowIdentity` | (Optional) How the window should identify the current user. Defaults to `.anonymous`. | | **`theme`** | `GrowSurfWindowTheme` | (Optional) Native presentation and theme overrides. | | **`callbacks`** | `GrowSurfWindowCallbacks` | (Optional) Event callbacks for window open, close, participant creation (from the signup form), share tracking, invite sending, payout/settings actions, and errors. | Returns `GrowSurfWindowController` — call `close()` on it to dismiss the window programmatically. #### **Example use** ```swift let windowController = growsurf.presentGrowSurfWindow( from: self, identity: .existingParticipantToken(participantToken), theme: GrowSurfWindowTheme( primaryColorHex: "#13795B", presentationStyle: .automatic ), callbacks: GrowSurfWindowCallbacks( onShareTracked: { type in print("Share tracked:", type) }, onParticipantCreated: { participant, participantToken in print("Participant:", participant.id) }, onError: { error in print("GrowSurf window error:", error) } ) ) ``` *** ### Get GrowSurf window Use this when you are building your own referral screen instead of showing the native GrowSurf window. It returns the campaign, participant, share, reward, leaderboard, and affiliate data used by the window. ```swift try await growsurf.getGrowSurfWindow(identity: .anonymous) ``` | Parameter | Data Type | Description | | -------------- | ------------------------ | ----------------------------------------------------- | | **`identity`** | `GrowSurfWindowIdentity` | (Optional) Window identity. Defaults to `.anonymous`. | Returns `GrowSurfWindowResponse`. #### **Example use** ```swift let window = try await growsurf.getGrowSurfWindow( identity: .existingParticipantToken(participantToken) ) let shareUrl = window.participant?.shareUrl ?? window.share?.preferredUrl ?? window.share?.fallbackUrl ``` {% hint style="info" %} Use `participant.shareUrl` as the customer-facing referral link when a participant is available. Fall back to `share.preferredUrl` or `share.fallbackUrl` only for rendering. {% endhint %} *** ## ATTRIBUTION ↓ ### Handle deep link Call this when your app opens from a referral deep link. If the URL contains `grsf`, `ref`, or `referredBy`, the SDK saves the attribution so you can apply it when the user signs up. ```swift try await growsurf.handleDeepLink(url) ``` | Parameter | Data Type | Description | | --------- | --------- | ------------------------------------------------ | | **`url`** | `URL` | (Required) The deep link URL opened by your app. | Returns `GrowSurfAttribution?`. Returns `nil` when no GrowSurf referral value is found. #### **Example use** ```swift if let url { let attribution = try await growsurf.handleDeepLink(url) print(attribution?.referredBy as Any) } ``` *** ### Handle attribution parameters Call this from an attribution provider callback, such as Branch, Adjust, AppsFlyer, or Singular. If the parameters include `grsf`, `ref`, or `referredBy` directly or inside URL-like values, the SDK saves the attribution for signup. ```swift try await growsurf.handleAttributionParameters(parameters, provider: "branch") ``` | Parameter | Data Type | Description | | ---------------- | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- | | **`parameters`** | `[String: String]` | (Required) Provider callback parameters. The SDK recognizes direct values and nested URL-like values containing `grsf`, `ref`, or `referredBy`. | | **`provider`** | `String?` | (Optional) Attribution provider name, such as `branch`, `adjust`, `appsflyer`, or `singular`. | Returns `GrowSurfAttribution?`. Returns `nil` when no GrowSurf referral value is found. #### **Example use** ```swift let attribution = try await growsurf.handleAttributionParameters( [ "grsf": "referrer_id", "click_id": "click_123", "unique": "true", ], provider: "branch" ) ``` *** ### Get pending attribution Use this to inspect referral attribution saved on this device before creating or signing in a participant. ```swift try await growsurf.pendingAttribution() ``` Returns `GrowSurfAttribution?`. #### **Example use** ```swift if let attribution = try await growsurf.pendingAttribution() { print("Pending referrer:", attribution.referredBy as Any) } ``` *** ### Clear pending attribution Clear saved referral attribution when it should no longer apply, such as after you handle it or when a different user signs in. ```swift try await growsurf.clearPendingAttribution() ``` Returns `Void`. #### **Example use** ```swift try await growsurf.clearPendingAttribution() ``` *** ### Validate referrer Use this to check whether a saved or supplied referrer is valid before you show a referred state or create a participant. ```swift try await growsurf.validateReferrer(attribution) ``` | Parameter | Data Type | Description | | ----------------- | ---------------------- | ----------------------------------------------------------------------------------------------------- | | **`attribution`** | `GrowSurfAttribution?` | (Optional) Attribution to validate. If omitted, the SDK validates locally stored pending attribution. | Returns `GrowSurfValidateReferrerResponse`. #### **Example use** {% tabs %} {% tab title="Pending attribution" %} ```swift let validation = try await growsurf.validateReferrer() if validation.valid { print("Valid referrer:", validation.referredBy as Any) } ``` {% endtab %} {% tab title="Explicit referrer" %} ```swift let validation = try await growsurf.validateReferrer(referredBy: "referrer_id") if validation.valid { print("Valid referrer") } ``` {% endtab %} {% endtabs %} *** ## PARTICIPANTS ↓ ### Add referred participant Use this for referred signups. The SDK looks for a saved or explicit referrer, validates it, and only creates the participant when the referral is valid. ```swift try await growsurf.addReferredParticipant(input) ``` | Parameter | Data Type | Description | | ----------- | -------------------------- | ----------------------------------------------------------------------------------------------------------- | | **`input`** | `GrowSurfParticipantInput` | (Required) Participant fields, optional explicit `referredBy`, optional attribution, and optional metadata. | Returns `GrowSurfAddReferredParticipantResponse`. #### **Example use** ```swift let result = try await growsurf.addReferredParticipant( GrowSurfParticipantInput( email: "person@example.com", firstName: "Ada", lastName: "Lovelace", metadata: ["plan": "pro"] ) ) if result.added { print("Referred participant:", result.participant?.id as Any) } else { print("Not added:", result.notAddedReason as Any) } ``` {% hint style="info" %} If no participant is added, `notAddedReason` will be `no_referrer`, `invalid_referrer`, or `participant_already_exists`. {% endhint %} *** ### Add participant Use this for public signup flows where the SDK can create a participant even without a referral. It sends pending attribution when available, stores the returned participant token when present, and includes the SDK-generated mobile instance ID for anti-fraud. ```swift try await growsurf.addParticipant(input) ``` | Parameter | Data Type | Description | | ----------- | -------------------------- | --------------------------------------------------------------------------- | | **`input`** | `GrowSurfParticipantInput` | (Required) Participant fields, optional attribution, and optional metadata. | Returns `GrowSurfCreateParticipantResponse`. #### **Example use** ```swift let response = try await growsurf.addParticipant( GrowSurfParticipantInput( email: "person@example.com", firstName: "Ada", lastName: "Lovelace", metadata: ["plan": "pro"] ) ) if let participant = response.participant { print("Created participant:", participant.id) } ``` {% hint style="info" %} Use this method for public signup flows where the SDK should create a new participant. If the email already belongs to an existing participant, GrowSurf returns `requiresParticipantToken: true` and does not return a participant token. For signed-in or existing users, use an SDK-issued participant token you already have, or create a mobile participant token from your backend, then pass it to `setParticipantToken(_:)` or `.existingParticipantToken(...)`. {% endhint %} *** ### Get participant Use this after you have a participant token to load the participant's referral data, including their referral link and counts. ```swift try await growsurf.getParticipant() ``` Returns `GrowSurfParticipant`. #### **Example use** ```swift let participant = try await growsurf.getParticipant() print(participant.shareUrl as Any) ``` *** ### Update participant Use this when your app lets a participant update profile fields, such as first name, last name, or metadata. ```swift try await growsurf.updateParticipant(with: input) ``` | Parameter | Data Type | Description | | ---------- | -------------------------------- | ----------------------------------------------------------------------------- | | **`with`** | `GrowSurfParticipantUpdateInput` | (Required) Fields to update, such as `firstName`, `lastName`, and `metadata`. | Returns `GrowSurfParticipant`. #### **Example use** ```swift let participant = try await growsurf.updateParticipant( with: GrowSurfParticipantUpdateInput( firstName: "Ada", lastName: "Lovelace", metadata: ["plan": "enterprise"] ) ) ``` *** ### Update vanity links Use this when your app lets a participant manage multiple custom referral link keys at once. ```swift try await growsurf.updateVanityLinks(vanityKeys: ["ada", "ada-pro"]) ``` | Parameter | Data Type | Description | | ---------------- | ---------- | --------------------------------------------------------- | | **`vanityKeys`** | `[String]` | (Required) Vanity keys to associate with the participant. | Returns `GrowSurfParticipant`. #### **Example use** ```swift let participant = try await growsurf.updateVanityLinks( vanityKeys: ["ada", "ada-pro"] ) ``` *** ## REFERRALS AND INVITES ↓ ### Get participant referrals Use this to show who a participant has referred and the status of each referral. ```swift try await growsurf.getParticipantReferrals( limit: 20, offset: 0 ) ``` | Parameter | Data Type | Description | | ------------ | --------- | ----------------------------------------- | | **`limit`** | `Int?` | (Optional) Number of referrals to return. | | **`offset`** | `Int?` | (Optional) Offset for pagination. | Returns `GrowSurfReferralsResponse`. #### **Example use** ```swift let response = try await growsurf.getParticipantReferrals( limit: 20 ) for referral in response.referrals { print(referral.email as Any, referral.referralStatus as Any) } ``` *** ### Send invites Use this to send referral invite emails from a participant's referral screen. ```swift try await growsurf.sendInvites( emailAddresses: ["friend@example.com"], messageText: "Join me on GrowSurf", subjectText: "You're invited" ) ``` | Parameter | Data Type | Description | | -------------------- | ---------- | ------------------------------------- | | **`emailAddresses`** | `[String]` | (Required) Email addresses to invite. | | **`messageText`** | `String` | (Required) Invite message body. | | **`subjectText`** | `String?` | (Optional) Invite email subject. | Returns `GrowSurfInviteResponse`. #### **Example use** ```swift let response = try await growsurf.sendInvites( emailAddresses: ["friend@example.com"], messageText: "Try this app with my referral link.", subjectText: "Join me" ) ``` *** ### Track share Call this after a participant shares their referral link from your UI. GrowSurf records the share type, such as `copy`, `email`, `sms`, or a social channel. ```swift try await growsurf.trackShare(type: "copy") ``` | Parameter | Data Type | Description | | ---------- | --------- | ------------------------------------------------------------------------------------------------------------------------- | | **`type`** | `String` | (Required) Share type, such as `copy`, `email`, `sms`, or a social channel type returned by the GrowSurf window response. | Returns `GrowSurfSuccessResponse`. #### **Example use** ```swift try await growsurf.trackShare(type: "copy") ``` *** ## REFERRAL PROGRAMS ↓ ### Trigger referral Referral programs only Use this when a referred participant completes the in-app action that should count as a referral conversion. For purchases or other high-trust events, trigger referral credit from your backend instead. ```swift try await growsurf.triggerReferral() ``` Returns `GrowSurfSuccessResponse`. #### **Example use** ```swift let response = try await growsurf.triggerReferral() ``` {% hint style="warning" %} For server-verified purchases, subscriptions, or other high-trust reward events, trigger referral credit from your backend using the REST API or a GrowSurf integration instead of from the app. {% endhint %} *** ### Get participant rewards Referral programs only Use this to show the rewards a participant has earned or can track inside your app. ```swift try await growsurf.getParticipantRewards( limit: 20, nextId: nil ) ``` | Parameter | Data Type | Description | | ------------ | --------- | --------------------------------------- | | **`limit`** | `Int?` | (Optional) Number of rewards to return. | | **`nextId`** | `String?` | (Optional) Cursor ID for the next page. | Returns `GrowSurfRewardsResponse`. #### **Example use** ```swift let rewards = try await growsurf.getParticipantRewards( limit: 20 ) ``` *** ### Mark participant rewards read Referral programs only Call this after showing reward notifications so GrowSurf can clear the participant's unread reward state. ```swift try await growsurf.markParticipantRewardsRead() ``` Returns `GrowSurfSuccessResponse`. #### **Example use** ```swift try await growsurf.markParticipantRewardsRead() ``` *** ### Get participant referral summary Referral programs only Use this for referral programs to show a participant's high-level referral stats (referrals, leads, expired referrals, clicks, rewards earned, pending rewards, invites sent). ```swift try await growsurf.getParticipantReferralSummary() ``` Returns `GrowSurfReferralSummary`. #### **Example use** ```swift let summary = try await growsurf.getParticipantReferralSummary() print(summary.referrals as Any) ``` *** ## AFFILIATE PROGRAMS ↓ ### Get participant commissions Affiliate programs only Use this for affiliate programs to show a participant's commission history. ```swift try await growsurf.getParticipantCommissions( limit: 20, nextId: nil ) ``` | Parameter | Data Type | Description | | ------------ | --------- | ------------------------------------------- | | **`limit`** | `Int?` | (Optional) Number of commissions to return. | | **`nextId`** | `String?` | (Optional) Cursor ID for the next page. | Returns `GrowSurfCommissionsResponse`. #### **Example use** ```swift let commissions = try await growsurf.getParticipantCommissions( limit: 20 ) ``` *** ### Mark participant commissions read Affiliate programs only Call this after showing commission notifications so GrowSurf can clear the participant's unread commission state. ```swift try await growsurf.markParticipantCommissionsRead() ``` Returns `GrowSurfSuccessResponse`. #### **Example use** ```swift try await growsurf.markParticipantCommissionsRead() ``` *** ### Get participant payouts Affiliate programs only Use this for affiliate programs to show a participant's payout history. ```swift try await growsurf.getParticipantPayouts( limit: 20, nextId: nil ) ``` | Parameter | Data Type | Description | | ------------ | --------- | --------------------------------------- | | **`limit`** | `Int?` | (Optional) Number of payouts to return. | | **`nextId`** | `String?` | (Optional) Cursor ID for the next page. | Returns `GrowSurfPayoutsResponse`. #### **Example use** ```swift let payouts = try await growsurf.getParticipantPayouts( limit: 20 ) ``` *** ### Mark participant payouts read Affiliate programs only Call this after showing payout notifications so GrowSurf can clear the participant's unread payout state. ```swift try await growsurf.markParticipantPayoutsRead() ``` Returns `GrowSurfSuccessResponse`. #### **Example use** ```swift try await growsurf.markParticipantPayoutsRead() ``` *** ### Get participant affiliate summary Affiliate programs only Use this for affiliate programs to show a participant's high-level affiliate stats, such as referral revenue, total paid out, and upcoming payout. ```swift try await growsurf.getParticipantAffiliateSummary() ``` Returns `GrowSurfAffiliateSummary`. #### **Example use** ```swift let summary = try await growsurf.getParticipantAffiliateSummary() print(summary.upcomingPayout as Any) ``` *** ### Request PayPal confirm email Affiliate programs only Use this when your affiliate program needs the participant to confirm their PayPal email before payouts can continue. ```swift try await growsurf.requestPaypalConfirmEmail() ``` Returns `GrowSurfSuccessResponse`. #### **Example use** ```swift let response = try await growsurf.requestPaypalConfirmEmail() ``` *** ### Request tax info session Use this when the campaign requires tax documentation and the participant needs to complete or resubmit their W-9 / W-8 form before rewards or payouts can continue. It starts a secure hosted tax-form session and returns the hosted URL to open in an in-app browser, plus the participant's new tax status. The native GrowSurf window calls this automatically from its Tax Forms settings row; call it yourself only if you build a custom settings UI. ```swift try await growsurf.requestTaxInfoSession() ``` Returns `GrowSurfTaxSessionResponse`. #### **Example use** ```swift let session = try await growsurf.requestTaxInfoSession() if let urlString = session.hostedUrl, let url = URL(string: urlString) { await UIApplication.shared.open(url) } ``` {% hint style="info" %} GrowSurf never stores participant tax IDs. The W-9 / W-8 is completed on a hosted page served by GrowSurf's IRS-authorized e-file partner. {% endhint %} *** ## ATTRIBUTION ADAPTERS ↓ ### Branch attribution adapter Use this helper when Branch returns attribution data. It normalizes Branch payloads and can store the resulting GrowSurf attribution on the SDK. ```swift GrowSurfBranchAttribution.normalize(parameters) try await GrowSurfBranchAttribution.handle(parameters, sdk: growsurf) ``` | Method | Description | | ---------------------------------------------------- | --------------------------------------------------------------------------------- | | **`normalize(_ parameters: [String: String])`** | Parses a string dictionary and returns `GrowSurfAttribution?` without storing it. | | **`normalize(_ parameters: [String: Any])`** | Converts a mixed dictionary, then parses attribution without storing it. | | **`normalize(_ parameters: [AnyHashable: Any])`** | Converts a hashable-key dictionary, then parses attribution without storing it. | | **`handle(_ parameters: [String: String], sdk:)`** | Parses and stores attribution on the provided SDK instance. | | **`handle(_ parameters: [String: Any], sdk:)`** | Converts, parses, and stores attribution on the provided SDK instance. | | **`handle(_ parameters: [AnyHashable: Any], sdk:)`** | Converts, parses, and stores attribution on the provided SDK instance. | #### **Example use** ```swift import GrowSurfBranchAttribution try await GrowSurfBranchAttribution.handle( branchParams, sdk: growsurf ) ``` *** ### Adjust attribution adapter Use this helper when Adjust returns a deep link. It normalizes the URL and can store the resulting GrowSurf attribution on the SDK. ```swift GrowSurfAdjustAttribution.normalize(url) try await GrowSurfAdjustAttribution.handle(url, sdk: growsurf) ``` | Method | Description | | --------------------------------------- | ------------------------------------------------------------------- | | **`normalize(_ url: URL)`** | Parses a URL and returns `GrowSurfAttribution?` without storing it. | | **`normalize(_ urlString: String)`** | Parses a URL string or encoded URL string without storing it. | | **`handle(_ url: URL, sdk:)`** | Parses and stores attribution on the provided SDK instance. | | **`handle(_ urlString: String, sdk:)`** | Parses and stores attribution on the provided SDK instance. | #### **Example use** ```swift import GrowSurfAdjustAttribution try await GrowSurfAdjustAttribution.handle( adjustDeeplinkURL, sdk: growsurf ) ``` *** ### AppsFlyer attribution adapter Use this helper when AppsFlyer returns conversion or deep link data. It normalizes the payload and can store the resulting GrowSurf attribution on the SDK. ```swift GrowSurfAppsFlyerAttribution.normalize(parameters) try await GrowSurfAppsFlyerAttribution.handle(parameters, sdk: growsurf) ``` | Method | Description | | ---------------------------------------------------- | --------------------------------------------------------------------------------- | | **`normalize(_ parameters: [String: String])`** | Parses a string dictionary and returns `GrowSurfAttribution?` without storing it. | | **`normalize(_ parameters: [String: Any])`** | Converts a mixed dictionary, then parses attribution without storing it. | | **`normalize(_ parameters: [AnyHashable: Any])`** | Converts a hashable-key dictionary, then parses attribution without storing it. | | **`handle(_ parameters: [String: String], sdk:)`** | Parses and stores attribution on the provided SDK instance. | | **`handle(_ parameters: [String: Any], sdk:)`** | Converts, parses, and stores attribution on the provided SDK instance. | | **`handle(_ parameters: [AnyHashable: Any], sdk:)`** | Converts, parses, and stores attribution on the provided SDK instance. | #### **Example use** ```swift import GrowSurfAppsFlyerAttribution try await GrowSurfAppsFlyerAttribution.handle( conversionData, sdk: growsurf ) ``` *** ### Singular attribution adapter Use this helper when Singular returns callback parameters or deep link values. It normalizes the payload and can store the resulting GrowSurf attribution on the SDK. ```swift GrowSurfSingularAttribution.normalize(parameters) try await GrowSurfSingularAttribution.handle(parameters, sdk: growsurf) ``` | Method | Description | | ---------------------------------------------------- | --------------------------------------------------------------------------------- | | **`normalize(_ parameters: [String: String])`** | Parses a string dictionary and returns `GrowSurfAttribution?` without storing it. | | **`normalize(_ parameters: [String: Any])`** | Converts a mixed dictionary, then parses attribution without storing it. | | **`normalize(_ parameters: [AnyHashable: Any])`** | Converts a hashable-key dictionary, then parses attribution without storing it. | | **`normalize(_ url: URL)`** | Parses a URL without storing it. | | **`normalize(_ urlString: String)`** | Parses a URL string or encoded URL string without storing it. | | **`handle(_ parameters: [String: String], sdk:)`** | Parses and stores attribution on the provided SDK instance. | | **`handle(_ parameters: [String: Any], sdk:)`** | Converts, parses, and stores attribution on the provided SDK instance. | | **`handle(_ parameters: [AnyHashable: Any], sdk:)`** | Converts, parses, and stores attribution on the provided SDK instance. | | **`handle(_ url: URL, sdk:)`** | Parses and stores attribution on the provided SDK instance. | | **`handle(_ urlString: String, sdk:)`** | Parses and stores attribution on the provided SDK instance. | #### **Example use** ```swift import GrowSurfSingularAttribution try await GrowSurfSingularAttribution.handle( singularPayload, sdk: growsurf ) ``` *** ## UTILITIES ↓ ### Normalize attribution parameters Use this when you need to read GrowSurf attribution from raw provider parameters without storing it. It looks for `grsf`, `ref`, or `referredBy` directly and inside URL-like values. ```swift GrowSurfAttributionNormalizer.normalize( parameters: parameters, provider: "branch" ) ``` | Parameter | Data Type | Description | | ---------------- | ------------------ | ------------------------------------------------------------------------------------------ | | **`parameters`** | `[String: String]` | (Required) Raw parameters. The normalizer checks direct fields and URL-like nested values. | | **`provider`** | `String?` | (Optional) Provider name to attach to the attribution result. | Returns `GrowSurfAttribution?`. #### **Example use** ```swift let attribution = GrowSurfAttributionNormalizer.normalize( parameters: [ "deep_link_value": "https://example.com/signup?grsf=referrer_id", "click_id": "click_123", ], provider: "appsflyer" ) ``` *** ### Normalize attribution URL Use this when you need to parse a URL for `grsf`, `ref`, or `referredBy` without storing attribution on the SDK. ```swift GrowSurfAttributionNormalizer.normalize(url: url, provider: "adjust") ``` | Parameter | Data Type | Description | | -------------- | --------- | ------------------------------------------------------------- | | **`url`** | `URL` | (Required) URL to parse. | | **`provider`** | `String?` | (Optional) Provider name to attach to the attribution result. | Returns `GrowSurfAttribution?`. #### **Example use** ```swift let attribution = GrowSurfAttributionNormalizer.normalize( url: URL(string: "https://example.com/signup?grsf=referrer_id")!, provider: "adjust" ) ``` *** ### Convert attribution parameters to strings Use this before passing mixed provider callback payloads to the normalizer or SDK attribution methods. It converts nested values into a `[String: String]` dictionary without storing attribution. ```swift GrowSurfAttributionNormalizer.stringParameters(from: parameters) ``` | Parameter | Data Type | Description | | ---------------- | --------------- | ------------------------------------------------------------------------------------------------------ | | **`parameters`** | `[String: Any]` | (Required) Provider callback payload. Nested dictionaries and arrays are flattened into string values. | Returns `[String: String]`. #### **Example use** ```swift let stringParameters = GrowSurfAttributionNormalizer.stringParameters( from: providerPayload ) try await growsurf.handleAttributionParameters( stringParameters, provider: "branch" ) ``` # Models and Errors Models, callbacks, stores, and errors exposed by the GrowSurf iOS SDK. This reference documents the models, callbacks, advanced protocols, stores, and errors exposed by the GrowSurf iOS SDK. ## Core models ### GrowSurfConfiguration | Field | Type | Description | | ------------ | -------- | ------------------------ | | `campaignId` | `String` | GrowSurf program ID. | | `publicKey` | `String` | Mobile SDK public key. | | `baseURL` | `URL` | Mobile SDK API base URL. | ### GrowSurfAttribution | Field | Type | Description | | ------------ | --------- | ------------------------------------------------------------ | | `referredBy` | `String?` | Referrer participant ID or vanity key. | | `ref` | `String?` | Referrer value mirrored for provider compatibility. | | `unique` | `Bool?` | Whether the attribution provider marked the click as unique. | | `provider` | `String?` | Attribution provider name. | | `clickId` | `String?` | Provider click ID. | ### GrowSurfParticipantInput | Field | Type | Description | | ------------- | ---------------------- | -------------------------------------------- | | `email` | `String` | Participant email address. | | `firstName` | `String?` | Participant first name. | | `lastName` | `String?` | Participant last name. | | `referredBy` | `String?` | Explicit referrer value. | | `attribution` | `GrowSurfAttribution?` | Explicit attribution payload. | | `metadata` | `[String: String]?` | Custom metadata to store on the participant. | {% hint style="info" %} `mobileInstanceId` is generated and sent by the SDK automatically. It is not part of `GrowSurfParticipantInput`. {% endhint %} ### GrowSurfParticipantUpdateInput | Field | Type | Description | | ----------- | ------------------- | ------------------- | | `firstName` | `String?` | Updated first name. | | `lastName` | `String?` | Updated last name. | | `metadata` | `[String: String]?` | Updated metadata. | ### GrowSurfCampaign | Field | Type | | ------------------ | -------------------------- | | `id` | `String` | | `name` | `String?` | | `type` | `String?` | | `referralCount` | `Int?` | | `participantCount` | `Int?` | | `impressionCount` | `Int?` | | `inviteCount` | `Int?` | | `winnerCount` | `Int?` | | `currencyISO` | `String?` | | `status` | `String?` | | `rewards` | `[GrowSurfCampaignReward]` | ### GrowSurfCampaignReward | Field | Type | | ----------------------- | --------- | | `id` | `String?` | | `type` | `String?` | | `title` | `String?` | | `description` | `String?` | | `referralDescription` | `String?` | | `isUnlimited` | `Bool?` | | `limit` | `Int?` | | `conversionsRequired` | `Int?` | | `numberOfWinners` | `Int?` | | `imageUrl` | `String?` | | `order` | `Int?` | | `limitDuration` | `String?` | | `nextMilestonePrefix` | `String?` | | `nextMilestoneSuffix` | `String?` | | `couponCode` | `String?` | | `referredRewardUpfront` | `Bool?` | ### GrowSurfParticipant | Field | Type | | -------------------------- | ----------- | | `id` | `String` | | `email` | `String?` | | `firstName` | `String?` | | `lastName` | `String?` | | `shareUrl` | `String?` | | `paypalEmailAddress` | `String?` | | `referralCount` | `Int?` | | `inviteCount` | `Int?` | | `monthlyReferralCount` | `Int?` | | `prevMonthlyReferralCount` | `Int?` | | `rank` | `Int?` | | `monthlyRank` | `Int?` | | `prevMonthlyRank` | `Int?` | | `vanityKeys` | `[String]?` | | `unreadCommissionsCount` | `Int?` | | `unreadPayoutsCount` | `Int?` | ### GrowSurfCreateParticipantResponse | Field | Type | | -------------------------- | ------------------------- | | `participantToken` | `String?` | | `expiresIn` | `Int?` | | `participant` | `GrowSurfParticipant?` | | `isNew` | `Bool?` | | `requiresParticipantToken` | `Bool?` | | `window` | `GrowSurfWindowResponse?` | ### GrowSurfAddReferredParticipantResponse | Field | Type | | -------------------------- | ----------------------------------------------- | | `added` | `Bool` | | `validReferral` | `Bool` | | `referredBy` | `String?` | | `notAddedReason` | `GrowSurfAddReferredParticipantNotAddedReason?` | | `participantToken` | `String?` | | `expiresIn` | `Int?` | | `participant` | `GrowSurfParticipant?` | | `isNew` | `Bool?` | | `requiresParticipantToken` | `Bool?` | ### GrowSurfAddReferredParticipantNotAddedReason | Case | Raw value | | --------------------------- | ---------------------------- | | `.noReferrer` | `no_referrer` | | `.invalidReferrer` | `invalid_referrer` | | `.participantAlreadyExists` | `participant_already_exists` | ### Referral and reward models | Model | Fields | | ---------------------------------- | ----------------------------------------------------------------------------------------------------------- | | `GrowSurfReferralsResponse` | `referrals`, `limit`, `nextOffset`, `more` | | `GrowSurfReferral` | `id`, `email`, `referralStatus`, `createdAt`, `updatedAt`, `referralTriggeredAt`, `referralCreditExpiredAt` | | `GrowSurfRewardsResponse` | `rewards`, `limit`, `nextId` | | `GrowSurfReward` | `id`, `status`, `unread`, `approved`, `rewardId`, `isReferrer`, `title`, `description` | | `GrowSurfSuccessResponse` | `success`, `message` | | `GrowSurfAttributionResponse` | `success`, `valid`, `referredBy` | | `GrowSurfValidateReferrerResponse` | `success`, `valid`, `referredBy` | | `GrowSurfInviteResponse` | `success`, `message`, `messageType` | ## GrowSurf window models ### GrowSurfWindowIdentity | Case | Description | | ---------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `.anonymous` | Loads the window without participant identity. | | `.participantFields(GrowSurfParticipantInput)` | Creates a new participant from fields before loading the window. Existing participants need a participant token; use `.existingParticipantToken(String)` with a token created by your backend or returned by the SDK. | | `.existingParticipantToken(String)` | Uses a participant token created by your backend or by the SDK. | ### GrowSurfWindowTheme | Field | Type | Description | | ------------------- | --------------------------------------- | --------------------------------------------------- | | `primaryColorHex` | `String?` | Optional primary color override, such as `#13795B`. | | `colorScheme` | `GrowSurfWindowTheme.ColorScheme` | `.system`, `.light`, or `.dark`. | | `cornerRadius` | `Double?` | Optional corner radius override. | | `presentationStyle` | `GrowSurfWindowTheme.PresentationStyle` | `.automatic`, `.fullScreen`, or `.sheet`. | ### GrowSurfWindowCallbacks | Callback | Type | | -------------------------- | ---------------------------------------- | | `onOpen` | `() -> Void` | | `onClose` | `() -> Void` | | `onParticipantCreated` | `(GrowSurfParticipant, String?) -> Void` | | `onShareTracked` | `(String) -> Void` | | `onInviteSent` | `() -> Void` | | `onPayoutOrSettingsAction` | `(String) -> Void` | | `onError` | `(Error) -> Void` | ### GrowSurfWindowController | Method | Description | | --------- | ------------------------------------- | | `close()` | Closes the presented GrowSurf window. | ### GrowSurfWindowResponse | Field | Type | | ------------------ | ------------------------------ | | `version` | `String?` | | `campaign` | `GrowSurfWindowCampaign?` | | `signup` | `GrowSurfWindowSignup?` | | `visibleSections` | `[String: Bool]` | | `share` | `GrowSurfWindowShareConfig?` | | `participant` | `GrowSurfParticipant?` | | `unreadCounts` | `GrowSurfWindowUnreadCounts?` | | `payoutSettings` | `GrowSurfPayoutSettings?` | | `content` | `[String: GrowSurfJSONValue]?` | | `referrals` | `GrowSurfReferralsResponse?` | | `rewards` | `GrowSurfRewardsResponse?` | | `leaderboard` | `GrowSurfLeaderboardResponse?` | | `referralSummary` | `GrowSurfReferralSummary?` | | `affiliateSummary` | `GrowSurfAffiliateSummary?` | | `commissions` | `GrowSurfCommissionsResponse?` | | `payouts` | `GrowSurfPayoutsResponse?` | ### Additional window models | Model | Fields | | -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `GrowSurfWindowCampaign` | `id`, `type`, `status`, `companyName`, `companyLogoImageUrl`, `goal`, `currencyISO`, `shouldDisplayPoweredBy`, `rewardTypes`, `rewards`, `design` | | `GrowSurfWindowSignup` | `state`, `canCreateParticipant` | | `GrowSurfWindowShareConfig` | `preferredUrl`, `fallbackUrl`, `nativeShare`, `channels`, `invite` | | `GrowSurfWindowShareChannel` | `type`, `label`, `order`, `subject`, `message`, `nativePreferred` | | `GrowSurfWindowUnreadCounts` | `commissions`, `payouts` | | `GrowSurfPayoutSettings` | `provider`, `paypalEmailAddress`, `canRequestPaypalConfirmEmail`, `hostedActions`, `requiredActions`, `payoutInstructionsMode`, `taxInfo` | | `GrowSurfTaxInfo` | `status`, `formType`, `residencyCountryCode`, `vatNumber`, `vatCountryCode`, `statusReason`, `payoutSettings` | | `GrowSurfTaxInfoRefreshPayoutSettings` | `hostedActions`, `requiredActions` | | `GrowSurfTaxSessionResponse` | `hostedUrl`, `status` | | `GrowSurfTaxInfoSaveResponse` | `success`, `taxInfo` | | `GrowSurfLeaderboardResponse` | `participants`, `offsetKey`, `nextKey`, `page`, `hasMore` | | `GrowSurfLeaderboardParticipant` | `id`, `rank`, `monthlyRank`, `prevMonthlyRank`, `email`, `isWinner`, `referralCount`, `monthlyReferralCount`, `prevMonthlyReferralCount`, `pendingReferralCount`, `revenueAmount`, `commissionAmount` | | `GrowSurfReferralSummary` | `referrals`, `leads`, `expiredReferrals`, `clicks`, `rewardsEarned`, `pendingRewards`, `invitesSent`, `currencyISO` | | `GrowSurfAffiliateSummary` | `referralRevenue`, `totalPaidOut`, `upcomingPayout`, `referrals`, `leads`, `clicks`, `currencyISO` | | `GrowSurfCommissionsResponse` | `commissions`, `totalCount`, `totalAmount`, `summary`, `nextId` | | `GrowSurfCommission` | `id`, `amount`, `currencyISO`, `status`, `holdDuration`, `createdAt`, `amountInCampaignCurrency`, `saleAmountInCampaignCurrency`, `campaignCurrencyISO`, `unread` | | `GrowSurfPayoutsResponse` | `payouts`, `totalCount`, `totalAmount`, `summary`, `nextId` | | `GrowSurfPayout` | `id`, `amount`, `currencyISO`, `status`, `queuedAt`, `createdAt`, `amountInCampaignCurrency`, `campaignCurrencyISO`, `unread` | | `GrowSurfJSONValue` | `.string`, `.number`, `.bool`, `.object`, `.array`, `.null` | ## Advanced protocols and stores Use these APIs for tests or custom storage/transport integrations. | Type | Public methods | | ------------------------------------------- | ----------------------------------------------------------------------------------------------------- | | `GrowSurfHTTPClient` | `data(for:)` | | `GrowSurfTokenStore` | `sessionToken()`, `participantToken()`, `saveSessionToken(_:)`, `saveParticipantToken(_:)`, `clear()` | | `GrowSurfAttributionStore` | `attribution()`, `saveAttribution(_:)`, `clearAttribution()` | | `GrowSurfMobileInstanceIdStore` | `mobileInstanceId()` | | `GrowSurfWindowCacheStore` | `windowData(cacheKey:now:)`, `saveWindowData(_:cacheKey:expiresAt:)`, `clear()` | | `GrowSurfUserDefaultsAttributionStore` | UserDefaults-backed attribution store. | | `GrowSurfUserDefaultsMobileInstanceIdStore` | UserDefaults-backed mobile instance ID store. | | `GrowSurfUserDefaultsWindowCacheStore` | UserDefaults-backed window cache store. | | `GrowSurfFileWindowCacheStore` | File-backed window cache store used by default. | | `GrowSurfKeychainTokenStore` | Keychain-backed token store used by default. | ## Errors `GrowSurfError` can be: * `invalidURL` * `missingSessionToken` * `missingParticipantToken` * `invalidResponse` * `httpStatus(Int, String?)` # Android SDK (Beta) Install and use the GrowSurf Android SDK to capture referral attribution, create referred participants, and show a native referral window in your app. {% hint style="info" %} If you're using an AI tool such as Cursor, Codex, Claude Code, or Antigravity to help you implement GrowSurf, we recommend utilizing our [MCP server](https://docs.growsurf.com/build-with-ai). {% endhint %} ## Install The core library is lightweight, adding roughly \~1 MB to your Android app (attribution adapters add only tens of KB each). Add the core SDK from Maven Central. Choose one install path. {% tabs %} {% tab title="Kotlin DSL" %} ```kotlin repositories { mavenCentral() } dependencies { implementation("com.growsurf:growsurf-android-sdk:0.3.3") } ``` {% endtab %} {% tab title="Groovy" %} ```groovy repositories { mavenCentral() } dependencies { implementation 'com.growsurf:growsurf-android-sdk:0.3.3' } ``` {% endtab %} {% endtabs %} If you use Branch, Adjust, AppsFlyer, or Singular, add the matching GrowSurf adapter. {% tabs %} {% tab title="Kotlin DSL" %} ```kotlin dependencies { implementation("com.growsurf:growsurf-android-sdk-attribution-branch:0.3.3") implementation("com.growsurf:growsurf-android-sdk-attribution-adjust:0.3.3") implementation("com.growsurf:growsurf-android-sdk-attribution-appsflyer:0.3.3") implementation("com.growsurf:growsurf-android-sdk-attribution-singular:0.3.3") } ``` {% endtab %} {% tab title="Groovy" %} ```groovy dependencies { implementation 'com.growsurf:growsurf-android-sdk-attribution-branch:0.3.3' implementation 'com.growsurf:growsurf-android-sdk-attribution-adjust:0.3.3' implementation 'com.growsurf:growsurf-android-sdk-attribution-appsflyer:0.3.3' implementation 'com.growsurf:growsurf-android-sdk-attribution-singular:0.3.3' } ``` {% endtab %} {% endtabs %} {% hint style="info" %} Keep your provider's SDK setup in your app. The GrowSurf adapter passes provider callback data into GrowSurf. {% endhint %} ### Initialize Enable Mobile SDK access in your GrowSurf program on the instructions page, then configure the SDK once when your app starts or before your first GrowSurf call. * Find `campaignId` in your GrowSurf program dashboard. It is the 6-character program ID, such as `p9josq`. * Find `publicKey` in *Program Editor > 5. Installation > Instructions page > Step 1. Android > Configure SDK*. ```kotlin import com.growsurf.sdk.GrowSurfSdk val growsurf = GrowSurfSdk.configure( context = context, campaignId = "p9josq", publicKey = "pk_mobile", ) ``` {% hint style="info" %} Native apps use a public Mobile SDK key, which can safely be exposed. This is different than your REST API key on your backend, which you should always keep secret. {% endhint %} *** ## Track referrals Tracking referrals entails capturing attribution and creating new referred participants. ### Capture attribution Capture referral attribution before you create the referred friend's participant record. {% stepper %} {% step %} **For direct app links that open your installed app:** ```kotlin intent.data?.let { uri -> growsurf.handleDeepLink(uri) } ``` {% hint style="info" %} **Already support deep links?** If you use an attribution provider (Branch, AppsFlyer, Adjust, Singular) or otherwise open your app from links, this is already set up — just forward the opened `Intent`'s URI to `handleDeepLink(uri)`. **Starting from scratch?** Add a custom-scheme `` (`android:scheme`) to your launch Activity in `AndroidManifest.xml` — the quickest path, no domain needed — and/or set up Android App Links (`android:autoVerify="true"` plus an `assetlinks.json` hosted on a domain you control) for verified `https` links. Then read `intent.data` in `onCreate`/`onNewIntent` and call `handleDeepLink(uri)` inside a coroutine scope. {% endhint %} {% endstep %} {% step %} **For deferred deep links from an attribution provider:** View [Adapter docs](https://docs.growsurf.com/developer-tools/android-sdk/attribution-providers#adapters) for your specific provider setup instructions. {% hint style="info" %} For Google Play installs, [`addReferredParticipant()`](https://docs.growsurf.com/developer-tools/android-sdk/api-reference#add-referred-participant) checks Play Install Referrer once when no explicit or pending attribution exists. You can still call [`handleDeferredDeepLink()`](https://docs.growsurf.com/developer-tools/android-sdk/api-reference#handle-deferred-deep-link) yourself if you want to inspect attribution earlier: ```kotlin lifecycleScope.launch { growsurf.handleDeferredDeepLink() } ``` {% endhint %} {% endstep %} {% endstepper %} ### Create a referred participant Use [`addReferredParticipant()`](https://docs.growsurf.com/developer-tools/android-sdk/api-reference#add-referred-participant) for referred signups. This is typically where new users sign up in your app. The SDK validates saved, explicit, or Play Install Referrer attribution and only creates the participant when the referral code is valid. ```kotlin // Only creates a referred participant if the referral code is valid val created = growsurf.addReferredParticipant( GrowSurfParticipantInput( email = "person@example.com", firstName = "Ada", lastName = "Lovelace", metadata = mapOf("plan" to "pro"), // Optional, saved as participant metadata // The referral code and mobile instance ID (for anti-fraud) are passed automatically ) ) val participant = created.participant ``` *** ## Generate referral links for your users Generating referral links to users in your app entails generating a participant token by using the GrowSurf API, then opening the GrowSurf window. ### Generate a participant token To allow authenticated access to your logged-in users, you must call the GrowSurf backend to generate a participant token. {% stepper %} {% step %} **Call backend endpoint** [**create a mobile participant token.**](/developer-tools/rest-api/api-reference#post-campaign-id-mobile-participant-token) Here is an example `cURL` command: ```bash curl -X POST "https://api.growsurf.com/v2/campaign/YOUR_PROGRAM_ID/mobile-participant-token" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "email": "person@example.com", "firstName": "Ada", "lastName": "Lovelace", "mobileInstanceId": "5f7d0f4c-3e7c-4aa9-8c41-d81d998f0bb1", "ipAddress": "203.0.113.10", "metadata": { "plan": "pro" } }' ``` Only `email` is required. `firstName`, `lastName`, `mobileInstanceId`, and `ipAddress` are optional but recommended for anti-fraud. `metadata` is optional and is not used by GrowSurf. {% hint style="info" %} Using TypeScript, Python, PHP, Ruby, or Java for your backend? Use an official [GrowSurf API Library](https://docs.growsurf.com/developer-tools/rest-api/api-libraries). {% endhint %} **Optional:** To get `mobileInstanceId`, which is used for anti-fraud purposes, use the SDK method [`getMobileInstanceId()`](https://docs.growsurf.com/developer-tools/android-sdk/api-reference#get-mobile-instance-id). This will create a new participant or return an existing one, along with a participant token that allows authenticated calls. {% endstep %} {% step %} **Pass it to the app, then store in the SDK via** [**`setParticipantToken()`**](https://docs.growsurf.com/developer-tools/android-sdk/api-reference#set-participant-token)**.** Here is example SDK code: ```kotlin // getMobileInstanceId() is a suspend function, so call it from a coroutine. lifecycleScope.launch { val mobileInstanceId = growsurf.getMobileInstanceId() // Used for anti-fraud (optional) val backendResponse = api.createMobileParticipantToken( email = user.email, mobileInstanceId = mobileInstanceId, ) val participantToken = backendResponse.participantToken growsurf.setParticipantToken(participantToken) } ``` {% endstep %} {% endstepper %} ### Show the GrowSurf window

The GrowSurf window allows your participants to view/share their referral link and track the status of their referrals and rewards. Call [`presentGrowSurfWindow()`](https://docs.growsurf.com/developer-tools/android-sdk/api-reference#present-growsurf-window) from your own button, menu item, or referral screen. Set the `identity` parameter to [`GrowSurfWindowIdentity.ExistingParticipantToken()`](https://docs.growsurf.com/developer-tools/android-sdk/models-and-errors#growsurfwindowidentity), which will use the participant token you generated above. ```kotlin growsurf.presentGrowSurfWindow( activity = this, identity = GrowSurfWindowIdentity.ExistingParticipantToken(participantToken), theme = GrowSurfWindowTheme( primaryColor = 0xFF13795B, presentationStyle = GrowSurfWindowPresentationStyle.AUTOMATIC, ), callbacks = GrowSurfWindowCallbacks( onShareTracked = { type -> Log.d("GrowSurf", "Share tracked: $type") }, onError = { error -> Log.e("GrowSurf", "GrowSurf window error", error) }, ), ) ``` *** ## \[Optional] Google Contacts invites

Only needed when Google Contacts invites are enabled for your program. When a participant taps the Google Contacts button, the GrowSurf window takes them through Google's sign-in to grant access to their contacts (read-only) — the same experience as on iOS. Unlike iOS, there is **no in-app code to add** on Android: the required Google Sign-In library is bundled with the SDK, and there is no URL scheme or URL forwarding to configure. The only requirement is a correctly configured Google Cloud OAuth client for your app. {% stepper %} {% step %} **Create an Android OAuth client** as part of the [Google Cloud setup](https://support.growsurf.com/article/343-how-to-set-up-google-contacts-address-book). Set the application type to **Android** and register it with your app's **package name** and its **SHA-1 signing-certificate fingerprint**. Without this, the consent screen fails with a `DEVELOPER_ERROR`. {% endstep %} {% step %} **Get your SHA-1 fingerprint.** The quickest way is the Gradle signing report, which prints the SHA-1 for every build variant: ```bash ./gradlew signingReport ``` Or read it directly from a keystore with `keytool`: ```bash # Debug keystore (default location) keytool -list -v \ -keystore ~/.android/debug.keystore \ -alias androiddebugkey -storepass android -keypass android # Release keystore keytool -list -v \ -keystore /path/to/your/release.keystore \ -alias your-key-alias ``` Register **both** your debug and release SHA-1 fingerprints so Google Contacts works in development and production. {% endstep %} {% step %} **Using Google Play App Signing?** Register the SHA-1 of the **app signing key** shown in **Play Console → Test and release → App integrity → App signing key certificate** — not just your upload key. Otherwise the consent screen will fail in production even after the steps above. {% endstep %} {% endstepper %} *** ## Log out If your user logs out of your app, call [`shutdown()`](https://docs.growsurf.com/developer-tools/android-sdk/api-reference#shutdown) to remove all participant data from the device: ```kotlin growsurf.shutdown() ``` *** ## Next steps {% content-ref url="/pages/GhQfB3WsJlg97Hqpy7n9" %} [Attribution Providers](/developer-tools/android-sdk/attribution-providers) {% endcontent-ref %} {% content-ref url="/pages/XLxytePFauV0nWRkLmv8" %} [API Reference](/developer-tools/android-sdk/api-reference) {% endcontent-ref %} {% content-ref url="/pages/3NzBu6Jtu7Cvd7wWg7L1" %} [Models and Errors](/developer-tools/android-sdk/models-and-errors) {% endcontent-ref %} {% content-ref url="/pages/exdoU1ymhoG3SfIjmIsO" %} [Getting Started for Native Mobile](/getting-started-for-native-mobile) {% endcontent-ref %} # Attribution Providers Configure direct deep links, Google Play Install Referrer, and attribution adapters for the GrowSurf Android SDK. On Android, GrowSurf can capture referral attribution from direct deep links, Google Play Install Referrer, or provider callback payloads. Capture attribution before calling `addReferredParticipant()`. *** ## Direct deep links Use `handleDeepLink(uri)` when the installed app opens from a link that already contains `grsf`, which contains the referral code. ```kotlin intent.data?.let { uri -> val attribution = growsurf.handleDeepLink(uri) } ``` {% hint style="info" %} **Example accepted links:** * `your-app://open?grsf=referrer_id` * `https://example.com/app?grsf=referrer_id` {% endhint %} {% hint style="info" %} **Already support deep links?** If you use an attribution provider (Branch, AppsFlyer, Adjust, Singular) or otherwise open your app from links, this is already set up — just forward the opened `Intent`'s URI to `handleDeepLink(uri)`. **Starting from scratch?** Add a custom-scheme `` (`android:scheme`) to your launch Activity in `AndroidManifest.xml` — the quickest path, no domain needed — and/or set up Android App Links (`android:autoVerify="true"` plus an `assetlinks.json` hosted on a domain you control) for verified `https` links. Then read `intent.data` in `onCreate`/`onNewIntent` and call `handleDeepLink(uri)` inside a coroutine scope. GrowSurf-hosted share links live on `grow.surf` (not your domain), so they can't open your app via App Links — use a custom scheme, your own domain with `grsf` appended, or an attribution provider. {% endhint %} *** ## Google Play Install Referrer When Android referral clicks route to Google Play with a Play Install Referrer payload, `addReferredParticipant(...)` checks the install referrer once when no explicit or pending attribution exists. You can also call `handleDeferredDeepLink()` yourself before signup when you want to inspect the attribution result. ```kotlin lifecycleScope.launch { growsurf.handleDeferredDeepLink() val created = growsurf.addReferredParticipant( GrowSurfParticipantInput(email = "person@example.com") ) } ``` By default, the SDK checks the install referrer only once. Pass `forceRefresh = true` while testing if you need to query it again: ```kotlin growsurf.handleDeferredDeepLink(forceRefresh = true) ``` *** ## Adapters GrowSurf provides adapters for popular attribution providers. Choose your provider below, or use **Other** to pass a dictionary of attribution values from any other provider. {% tabs %} {% tab title="Adjust" %} ## Adjust adapter Add the adapter artifact: {% tabs %} {% tab title="Kotlin DSL" %} ```kotlin dependencies { implementation("com.growsurf:growsurf-android-sdk-attribution-adjust:0.3.3") } ``` {% endtab %} {% tab title="Groovy" %} ```groovy dependencies { implementation 'com.growsurf:growsurf-android-sdk-attribution-adjust:0.3.3' } ``` {% endtab %} {% endtabs %} Then pass the Adjust deferred deep link into GrowSurf: ```kotlin import com.growsurf.sdk.attribution.adjust.GrowSurfAdjustAttribution GrowSurfAdjustAttribution.handle(adjustDeferredDeepLinkUri, growsurf) ``` The adapter accepts `Uri` and `String` deep link values. {% endtab %} {% tab title="AppsFlyer" %} ## AppsFlyer adapter Add the adapter artifact: {% tabs %} {% tab title="Kotlin DSL" %} ```kotlin dependencies { implementation("com.growsurf:growsurf-android-sdk-attribution-appsflyer:0.3.3") } ``` {% endtab %} {% tab title="Groovy" %} ```groovy dependencies { implementation 'com.growsurf:growsurf-android-sdk-attribution-appsflyer:0.3.3' } ``` {% endtab %} {% endtabs %} Then pass AppsFlyer conversion data into GrowSurf: ```kotlin import com.growsurf.sdk.attribution.appsflyer.GrowSurfAppsFlyerAttribution GrowSurfAppsFlyerAttribution.handle(appsFlyerConversionData, growsurf) ``` The adapter accepts `Map` and `JSONObject` payloads. {% endtab %} {% tab title="Branch" %} ## Branch adapter Add the adapter artifact: {% tabs %} {% tab title="Kotlin DSL" %} ```kotlin dependencies { implementation("com.growsurf:growsurf-android-sdk-attribution-branch:0.3.3") } ``` {% endtab %} {% tab title="Groovy" %} ```groovy dependencies { implementation 'com.growsurf:growsurf-android-sdk-attribution-branch:0.3.3' } ``` {% endtab %} {% endtabs %} Then pass Branch callback data into GrowSurf: ```kotlin import com.growsurf.sdk.attribution.branch.GrowSurfBranchAttribution GrowSurfBranchAttribution.handle(branchParams, growsurf) ``` The adapter accepts `Map` and `JSONObject` payloads. {% endtab %} {% tab title="Singular" %} ## Singular adapter Add the adapter artifact: {% tabs %} {% tab title="Kotlin DSL" %} ```kotlin dependencies { implementation("com.growsurf:growsurf-android-sdk-attribution-singular:0.3.3") } ``` {% endtab %} {% tab title="Groovy" %} ```groovy dependencies { implementation 'com.growsurf:growsurf-android-sdk-attribution-singular:0.3.3' } ``` {% endtab %} {% endtabs %} Then pass Singular callback data into GrowSurf: ```kotlin import com.growsurf.sdk.attribution.singular.GrowSurfSingularAttribution GrowSurfSingularAttribution.handle(singularParams, growsurf) ``` The adapter accepts `Map`, `JSONObject`, `Uri`, and `String` payloads. It parses GrowSurf referral keys from Singular deep link, deferred deep link, and passthrough fields such as `_dl`, `_ddl`, and `_p`. {% endtab %} {% tab title="Other" %} ## Manual attribution parameters Use `handleAttributionParameters(parameters, provider)` for any other provider that can return a dictionary of attribution values. No extra adapter install is required. ```kotlin growsurf.handleAttributionParameters( mapOf( "grsf" to "referrer_id", "click_id" to "click_123", ), provider = "your-provider-name", ) ``` {% endtab %} {% endtabs %} *** ## Accepted attribution keys | Key | Description | | ------------ | ------------------------------------------------------------------------------------------------ | | `grsf` | Preferred GrowSurf referrer ID. | | `ref` | Alternate referrer ID. | | `referredBy` | Alternate referrer ID. | | `provider` | Attribution provider name. Ignored when the SDK method receives an explicit `provider` argument. | | `clickId` | Provider click ID metadata. | | `click_id` | Provider click ID metadata. | | `unique` | Optional boolean string: `true` or `false`. | The SDK also parses values nested inside URL-like payload fields. For example, a provider value of `https://example.com/?grsf=referrer_id&click_id=click_123` can still produce GrowSurf attribution. If a provider returns a GrowSurf-hosted share URL such as `https://grow.surf/share/:campaignId/:referrerId`, the SDK uses the participant value from the path. # API Reference Public methods, Java callback overloads, attribution adapters, and models exposed by the GrowSurf Android SDK. {% hint style="info" %} If you're using an AI tool such as Cursor, Codex, Claude Code, or Antigravity to help you implement GrowSurf, we recommend utilizing our [MCP server](https://docs.growsurf.com/build-with-ai). {% endhint %} Use this page to look up individual GrowSurf Android SDK methods. Most SDK methods are Kotlin coroutine methods. Java examples are included where the SDK exposes callback overloads or synchronous/static methods. {% hint style="warning" %} Use the Mobile SDK public key in your app. Do not embed your secret REST API key in an Android app. {% endhint %} ## SDK LIFECYCLE ↓ ### Configure Call this once before using GrowSurf. It connects the SDK to your GrowSurf campaign, Mobile SDK public key, and Android context. {% tabs %} {% tab title="Kotlin" %} ```kotlin val growsurf = GrowSurfSdk.configure( context = context, campaignId = "abc123", publicKey = "pk_mobile", ) ``` {% endtab %} {% tab title="Java" %} ```java GrowSurfSdk growsurf = GrowSurfSdk.configure( context, "abc123", "pk_mobile", "https://api.growsurf.com/mobile/v2" ); ``` {% endtab %} {% endtabs %} | Parameter | Data Type | Description | | ---------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | | **`context`** | `Context` | (Required) Android context used for encrypted token storage, attribution storage, mobile instance ID storage, and Play Install Referrer access. | | **`campaignId`** | `String` | (Required) Your GrowSurf program ID. | | **`publicKey`** | `String` | (Required) Your Mobile SDK public key. | | **`baseUrl`** | `String` | (Optional in Kotlin) Custom Mobile SDK API base URL. Defaults to `https://api.growsurf.com/mobile/v2`. | Returns a configured `GrowSurfSdk` instance. Optionally, for advanced apps, initialize directly with explicit stores, transport, dispatcher, or install referrer client. Pass the production stores shown below (or your own conformances to the public store interfaces): ```kotlin val growsurf = GrowSurfSdk( configuration = GrowSurfConfiguration( campaignId = "abc123", publicKey = "pk_mobile", ), tokenStore = EncryptedPreferencesGrowSurfTokenStore(context), attributionStore = PreferencesGrowSurfAttributionStore(context), ) ``` *** ### Set participant token Use this after your backend creates a mobile participant token for a signed-in user. It lets participant-scoped SDK calls load or update that participant's data. ```kotlin growsurf.setParticipantToken(participantToken) ``` | Parameter | Data Type | Description | | ----------- | --------- | --------------------------------------------------------------------------------------------------- | | **`token`** | `String` | (Required) A mobile participant token returned by your backend or by a participant creation method. | Returns `Unit`. #### **Example use** ```kotlin growsurf.setParticipantToken(participantToken) ``` {% hint style="info" %} Use this method with tokens created by the REST API mobile participant token endpoint after a user is already signed in. {% endhint %} *** ### Get participant token Returns the participant token currently held by the SDK, or `null` if none is stored. Useful right after the GrowSurf window's `ParticipantFields` signup flow so your app can persist the freshly minted token for the user's next session. ```kotlin growsurf.getParticipantToken() ``` Returns `String?`. #### **Example use** ```kotlin growsurf.getParticipantToken()?.let { token -> // Persist the token to your backend so the user stays signed in to GrowSurf. } ``` {% hint style="info" %} The default `EncryptedPreferencesGrowSurfTokenStore` can propagate KeyStore or EncryptedSharedPreferences errors. Wrap this call in `try`/`catch` and rethrow `CancellationException` to preserve structured concurrency. {% endhint %} *** ### Get current participant ID Returns the current participant's ID from the stored participant token, or `null` if none. {% tabs %} {% tab title="Kotlin coroutine" %} ```kotlin val participantId = growsurf.getCurrentParticipantId() ``` {% endtab %} {% tab title="Java callback" %} ```java growsurf.getCurrentParticipantId(new GrowSurfCallback() { @Override public void onSuccess(String result) { Log.d("GrowSurf", "Current participant: " + result); } @Override public void onError(Throwable error) { Log.e("GrowSurf", "Current participant error", error); } }); ``` {% endtab %} {% endtabs %} Returns `String?`. #### **Example use** ```kotlin growsurf.getCurrentParticipantId()?.let { participantId -> Log.d("GrowSurf", "Current participant: $participantId") } ``` *** ### Get mobile instance ID Returns the app-install ID the SDK sends with participant creation for mobile anti-fraud. You usually only need this if your backend creates mobile participant tokens and needs to pass the same ID to GrowSurf. `getMobileInstanceId()` is a `suspend` function, so call it from a coroutine. ```kotlin growsurf.getMobileInstanceId() ``` Returns a UUID `String`. #### **Example use** ```kotlin lifecycleScope.launch { val mobileInstanceId = growsurf.getMobileInstanceId() } ``` {% hint style="info" %} Participant creation methods send `mobileInstanceId` automatically. Read it manually only when your backend creates a mobile participant token and needs to pass `mobileInstanceId` to the REST API. {% endhint %} *** ### Shutdown Call this when a user signs out or you need to reset GrowSurf state on the device. It clears the stored session token, participant token, and pending attribution. ```kotlin growsurf.shutdown() ``` Returns `Unit`. #### **Example use** ```kotlin growsurf.shutdown() ``` *** ## CAMPAIGNS ↓ ### Get campaign Use this to read campaign details and rewards for the configured GrowSurf program. The SDK creates or uses a session token before calling GrowSurf. ```kotlin growsurf.getCampaign() ``` Returns `GrowSurfCampaign`. #### **Example use** ```kotlin val campaign = growsurf.getCampaign() Log.d("GrowSurf", campaign.id) ``` *** ### Get leaderboard Use this to show leaderboard rows in a custom referral screen. You can page through results with page or cursor parameters. ```kotlin growsurf.getLeaderboard( limit = 20, page = 1, offsetKey = null, leaderboardType = null, ) ``` | Parameter | Data Type | Description | | --------------------- | --------- | -------------------------------------------------- | | **`limit`** | `Int?` | (Optional) Number of rows to return. | | **`page`** | `Int?` | (Optional) Page number. | | **`offsetKey`** | `String?` | (Optional) Cursor key for offset-based pagination. | | **`leaderboardType`** | `String?` | (Optional) Leaderboard type filter. | Returns `GrowSurfLeaderboardResponse`. #### **Example use** ```kotlin val leaderboard = growsurf.getLeaderboard(limit = 10) leaderboard.participants.forEach { row -> Log.d("GrowSurf", "Rank ${row.rank}: ${row.email}") } ``` *** ## GROWSURF WINDOW ↓ ### Present GrowSurf window Call this from your own button, menu item, or referral screen to open GrowSurf's native Compose referral window. {% hint style="info" %} The native GrowSurf window uses the GrowSurf window settings from your dashboard. This method is not a coroutine method. {% endhint %} ```kotlin growsurf.presentGrowSurfWindow( activity = activity, identity = GrowSurfWindowIdentity.ExistingParticipantToken(participantToken), theme = GrowSurfWindowTheme(), callbacks = GrowSurfWindowCallbacks(), ) ``` | Parameter | Data Type | Description | | --------------- | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **`activity`** | `Activity` | (Required) Activity that hosts the native window. | | **`identity`** | `GrowSurfWindowIdentity` | (Optional) How the window should identify the current user. Defaults to `Anonymous`. | | **`theme`** | `GrowSurfWindowTheme` | (Optional) Native presentation and theme overrides. | | **`callbacks`** | `GrowSurfWindowCallbacks` | (Optional) Event callbacks for window open, close, participant creation (from the signup form), share tracking, invite sending, payout/settings actions, and errors. | Returns `GrowSurfWindowController` — call `close()` on it to dismiss the window programmatically. #### **Example use** ```kotlin val controller = growsurf.presentGrowSurfWindow( activity = this, identity = GrowSurfWindowIdentity.ExistingParticipantToken(participantToken), theme = GrowSurfWindowTheme( primaryColor = 0xFF13795B, presentationStyle = GrowSurfWindowPresentationStyle.AUTOMATIC, ), callbacks = GrowSurfWindowCallbacks( onShareTracked = { type -> Log.d("GrowSurf", "Share tracked: $type") }, onParticipantCreated = { participant, participantToken -> Log.d("GrowSurf", "Participant: ${participant.id}") }, onError = { error -> Log.e("GrowSurf", "GrowSurf window error", error) }, ), ) ``` *** ### Get GrowSurf window Use this when you are building your own referral screen instead of showing the native GrowSurf window. It returns the campaign, participant, share, reward, leaderboard, and affiliate data used by the window. ```kotlin growsurf.getGrowSurfWindow(identity = GrowSurfWindowIdentity.Anonymous) ``` | Parameter | Data Type | Description | | -------------- | ------------------------ | ---------------------------------------------------- | | **`identity`** | `GrowSurfWindowIdentity` | (Optional) Window identity. Defaults to `Anonymous`. | Returns `GrowSurfWindowResponse`. #### **Example use** ```kotlin val window = growsurf.getGrowSurfWindow( identity = GrowSurfWindowIdentity.ExistingParticipantToken(participantToken), ) val shareUrl = window.participant?.shareUrl ?: window.share?.preferredUrl ?: window.share?.fallbackUrl ``` {% hint style="info" %} Use `participant.shareUrl` as the customer-facing referral link when a participant is available. Fall back to `share.preferredUrl` or `share.fallbackUrl` only for rendering. {% endhint %} *** ## ATTRIBUTION ↓ ### Handle deep link Call this when your app opens from a referral deep link. If the URI contains `grsf`, `ref`, or `referredBy`, the SDK saves the attribution so you can apply it when the user signs up. ```kotlin growsurf.handleDeepLink(uri) ``` | Parameter | Data Type | Description | | --------- | --------- | ------------------------------------------------ | | **`uri`** | `Uri` | (Required) The deep link URI opened by your app. | Returns `GrowSurfAttribution?`. Returns `null` when no GrowSurf referral value is found. #### **Example use** ```kotlin intent.data?.let { uri -> val attribution = growsurf.handleDeepLink(uri) Log.d("GrowSurf", "Referrer: ${attribution?.referredBy}") } ``` *** ### Handle deferred deep link Call this if you want to read Google Play Install Referrer before signup. `addReferredParticipant(...)` checks it automatically when no explicit or pending attribution exists. ```kotlin growsurf.handleDeferredDeepLink(forceRefresh = false) ``` | Parameter | Data Type | Description | | ------------------ | --------- | -------------------------------------------------------------------------------------------------------------------- | | **`forceRefresh`** | `Boolean` | (Optional) When `true`, queries Play Install Referrer again even if the SDK already checked it. Defaults to `false`. | Returns `GrowSurfAttribution?`. Returns `null` when no GrowSurf referral value is found. #### **Example use** ```kotlin val attribution = growsurf.handleDeferredDeepLink() ``` {% hint style="info" %} `addReferredParticipant(...)` checks Play Install Referrer automatically when no explicit or pending attribution exists. Call this manually only when you want to inspect attribution earlier. {% endhint %} *** ### Handle attribution parameters Call this from an attribution provider callback, such as Branch, Adjust, AppsFlyer, or Singular. If the parameters include `grsf`, `ref`, or `referredBy` directly or inside URL-like values, the SDK saves the attribution for signup. ```kotlin growsurf.handleAttributionParameters(parameters, provider = "branch") ``` | Parameter | Data Type | Description | | ---------------- | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | | **`parameters`** | `Map` | (Required) Provider callback parameters. The SDK recognizes direct values and nested URL-like values containing `grsf`, `ref`, or `referredBy`. | | **`provider`** | `String?` | (Optional) Attribution provider name, such as `branch`, `adjust`, `appsflyer`, or `singular`. | Returns `GrowSurfAttribution?`. Returns `null` when no GrowSurf referral value is found. #### **Example use** ```kotlin val attribution = growsurf.handleAttributionParameters( mapOf( "grsf" to "referrer_id", "click_id" to "click_123", "unique" to "true", ), provider = "branch", ) ``` *** ### Get pending attribution Use this to inspect referral attribution saved on this device before creating or signing in a participant. ```kotlin growsurf.getPendingAttribution() ``` Returns `GrowSurfAttribution?`. #### **Example use** ```kotlin val attribution = growsurf.getPendingAttribution() ``` *** ### Clear pending attribution Clear saved referral attribution when it should no longer apply, such as after you handle it or when a different user signs in. ```kotlin growsurf.clearPendingAttribution() ``` Returns `Unit`. #### **Example use** ```kotlin growsurf.clearPendingAttribution() ``` *** ### Validate referrer Use this to check whether a saved or supplied referrer is valid before you show a referred state or create a participant. ```kotlin growsurf.validateReferrer(attribution) ``` | Parameter | Data Type | Description | | ----------------- | ---------------------- | ----------------------------------------------------------------------------------------------------- | | **`attribution`** | `GrowSurfAttribution?` | (Optional) Attribution to validate. If omitted, the SDK validates locally stored pending attribution. | Returns `GrowSurfValidateReferrerResponse`. #### **Example use** {% tabs %} {% tab title="Pending attribution" %} ```kotlin val validation = growsurf.validateReferrer() if (validation.valid) { Log.d("GrowSurf", "Valid referrer: ${validation.referredBy}") } ``` {% endtab %} {% tab title="Explicit referrer" %} ```kotlin val validation = growsurf.validateReferrer("referrer_id") if (validation.valid) { Log.d("GrowSurf", "Valid referrer") } ``` {% endtab %} {% endtabs %} *** ## PARTICIPANTS ↓ ### Add referred participant Use this for referred signups. The SDK looks for saved attribution, an explicit referrer, or Play Install Referrer attribution, validates it, and only creates the participant when the referral is valid. {% tabs %} {% tab title="Kotlin coroutine" %} ```kotlin val result = growsurf.addReferredParticipant( GrowSurfParticipantInput( email = "person@example.com", firstName = "Ada", lastName = "Lovelace", metadata = mapOf("plan" to "pro"), ), ) if (result.added) { Log.d("GrowSurf", "Referred participant: ${result.participant?.id}") } ``` {% endtab %} {% tab title="Java callback" %} ```java Map metadata = new HashMap<>(); metadata.put("plan", "pro"); GrowSurfParticipantInput input = new GrowSurfParticipantInput( "person@example.com", "Ada", "Lovelace", null, null, metadata ); growsurf.addReferredParticipant( input, new GrowSurfCallback() { @Override public void onSuccess(GrowSurfAddReferredParticipantResponse result) { if (result.getAdded()) { GrowSurfParticipant participant = result.getParticipant(); } } @Override public void onError(Throwable error) { Log.e("GrowSurf", "Add referred participant error", error); } } ); ``` {% endtab %} {% endtabs %} | Parameter | Data Type | Description | | -------------- | ---------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | | **`input`** | `GrowSurfParticipantInput` | (Required) Participant fields, optional explicit `referredBy`, optional attribution, and optional metadata. | | **`callback`** | `GrowSurfCallback` | (Optional) Java-friendly callback overload. | Returns `GrowSurfAddReferredParticipantResponse`. {% hint style="info" %} If no participant is added, `notAddedReason` will be `NO_REFERRER`, `INVALID_REFERRER`, or `PARTICIPANT_ALREADY_EXISTS`. {% endhint %} *** ### Add participant Use this for public signup flows where the SDK can create a participant even without a referral. It sends pending attribution when available, stores the returned participant token when present, and includes the SDK-generated mobile instance ID for anti-fraud. {% tabs %} {% tab title="Kotlin coroutine" %} ```kotlin val response = growsurf.addParticipant( GrowSurfParticipantInput( email = "person@example.com", firstName = "Ada", lastName = "Lovelace", metadata = mapOf("plan" to "pro"), ), ) response.participant?.let { participant -> Log.d("GrowSurf", "Created participant: ${participant.id}") } ``` {% endtab %} {% tab title="Java callback" %} ```java Map metadata = new HashMap<>(); metadata.put("plan", "pro"); GrowSurfParticipantInput input = new GrowSurfParticipantInput( "person@example.com", "Ada", "Lovelace", null, null, metadata ); growsurf.addParticipant( input, new GrowSurfCallback() { @Override public void onSuccess(GrowSurfCreateParticipantResponse result) { GrowSurfParticipant participant = result.getParticipant(); if (participant != null) { Log.d("GrowSurf", "Created participant: " + participant.getId()); } } @Override public void onError(Throwable error) { Log.e("GrowSurf", "Create participant error", error); } } ); ``` {% endtab %} {% endtabs %} | Parameter | Data Type | Description | | -------------- | ----------------------------------------------------- | --------------------------------------------------------------------------- | | **`input`** | `GrowSurfParticipantInput` | (Required) Participant fields, optional attribution, and optional metadata. | | **`callback`** | `GrowSurfCallback` | (Optional) Java-friendly callback overload. | Returns `GrowSurfCreateParticipantResponse`. {% hint style="info" %} Use this method for public signup flows where the SDK should create a new participant. If the email already belongs to an existing participant, GrowSurf returns `requiresParticipantToken: true` and does not return a participant token. For signed-in or existing users, use an SDK-issued participant token you already have, or create a mobile participant token from your backend, then pass it to `setParticipantToken(...)` or `GrowSurfWindowIdentity.ExistingParticipantToken(...)`. {% endhint %} *** ### Get participant Use this after you have a participant token to load the participant's referral data, including their referral link and counts. ```kotlin growsurf.getParticipant() ``` Returns `GrowSurfParticipant`. #### **Example use** ```kotlin val participant = growsurf.getParticipant() Log.d("GrowSurf", participant.shareUrl.orEmpty()) ``` *** ### Update participant Use this when your app lets a participant update profile fields, such as first name, last name, or metadata. ```kotlin growsurf.updateParticipant(input) ``` | Parameter | Data Type | Description | | ----------- | -------------------------------- | ----------------------------------------------------------------------------- | | **`input`** | `GrowSurfParticipantUpdateInput` | (Required) Fields to update, such as `firstName`, `lastName`, and `metadata`. | Returns `GrowSurfParticipant`. #### **Example use** ```kotlin val participant = growsurf.updateParticipant( GrowSurfParticipantUpdateInput( firstName = "Ada", lastName = "Lovelace", metadata = mapOf("plan" to "enterprise"), ), ) ``` *** ### Update vanity links Use this when your app lets a participant manage multiple custom referral link keys at once. ```kotlin growsurf.updateVanityLinks(vanityKeys) ``` | Parameter | Data Type | Description | | ---------------- | -------------- | --------------------------------------------------------- | | **`vanityKeys`** | `List` | (Required) Vanity keys to associate with the participant. | Returns `GrowSurfParticipant`. #### **Example use** ```kotlin val participant = growsurf.updateVanityLinks( vanityKeys = listOf("ada", "ada-pro"), ) ``` *** ## REFERRALS AND INVITES ↓ ### Get participant referrals Use this to show who a participant has referred and the status of each referral. ```kotlin growsurf.getParticipantReferrals( limit = 20, offset = 0, ) ``` | Parameter | Data Type | Description | | ------------ | --------- | ----------------------------------------- | | **`limit`** | `Int?` | (Optional) Number of referrals to return. | | **`offset`** | `Int?` | (Optional) Offset for pagination. | Returns `GrowSurfReferralsResponse`. #### **Example use** ```kotlin val response = growsurf.getParticipantReferrals( limit = 20, ) response.referrals.forEach { referral -> Log.d("GrowSurf", "${referral.email}: ${referral.referralStatus}") } ``` *** ### Send invites Use this to send referral invite emails from a participant's referral screen. ```kotlin growsurf.sendInvites( emailAddresses = listOf("friend@example.com"), messageText = "Join me on GrowSurf", subjectText = "You're invited", ) ``` | Parameter | Data Type | Description | | -------------------- | -------------- | ------------------------------------- | | **`emailAddresses`** | `List` | (Required) Email addresses to invite. | | **`messageText`** | `String` | (Required) Invite message body. | | **`subjectText`** | `String?` | (Optional) Invite email subject. | Returns `GrowSurfInviteResponse`. #### **Example use** ```kotlin val response = growsurf.sendInvites( emailAddresses = listOf("friend@example.com"), messageText = "Try this app with my referral link.", subjectText = "Join me", ) ``` *** ### Track share Call this after a participant shares their referral link from your UI. GrowSurf records the share type, such as `copy`, `email`, `sms`, or a social channel. ```kotlin growsurf.trackShare(type) ``` | Parameter | Data Type | Description | | ---------- | --------- | ------------------------------------------------------------------------------------------------------------------------- | | **`type`** | `String` | (Required) Share type, such as `copy`, `email`, `sms`, or a social channel type returned by the GrowSurf window response. | Returns `GrowSurfSuccessResponse`. #### **Example use** ```kotlin growsurf.trackShare( type = "copy", ) ``` *** ## REFERRAL PROGRAMS ↓ ### Trigger referral Referral programs only Use this when a referred participant completes the in-app action that should count as a referral conversion. For purchases or other high-trust events, trigger referral credit from your backend instead. ```kotlin growsurf.triggerReferral() ``` Returns `GrowSurfSuccessResponse`. #### **Example use** ```kotlin val response = growsurf.triggerReferral() ``` {% hint style="warning" %} For server-verified purchases, subscriptions, or other high-trust reward events, trigger referral credit from your backend using the REST API or a GrowSurf integration instead of from the app. {% endhint %} *** ### Get participant rewards Referral programs only Use this to show the rewards a participant has earned or can track inside your app. ```kotlin growsurf.getParticipantRewards( limit = 20, nextId = null, ) ``` | Parameter | Data Type | Description | | ------------ | --------- | --------------------------------------- | | **`limit`** | `Int?` | (Optional) Number of rewards to return. | | **`nextId`** | `String?` | (Optional) Cursor ID for the next page. | Returns `GrowSurfRewardsResponse`. #### **Example use** ```kotlin val rewards = growsurf.getParticipantRewards( limit = 20, ) ``` *** ### Mark participant rewards read Referral programs only Call this after showing reward notifications so GrowSurf can clear the participant's unread reward state. ```kotlin growsurf.markParticipantRewardsRead() ``` Returns `GrowSurfSuccessResponse`. #### **Example use** ```kotlin growsurf.markParticipantRewardsRead() ``` *** ### Get participant referral summary Referral programs only Use this for referral programs to show a participant's high-level referral stats (referrals, leads, expired referrals, clicks, rewards earned, pending rewards, invites sent). ```kotlin growsurf.getParticipantReferralSummary() ``` Returns `GrowSurfReferralSummary`. #### **Example use** ```kotlin val summary = growsurf.getParticipantReferralSummary() Log.d("GrowSurf", "Referrals: ${summary.referrals}") ``` *** ## AFFILIATE PROGRAMS ↓ ### Get participant commissions Affiliate programs only Use this for affiliate programs to show a participant's commission history. ```kotlin growsurf.getParticipantCommissions( limit = 20, nextId = null, ) ``` | Parameter | Data Type | Description | | ------------ | --------- | ------------------------------------------- | | **`limit`** | `Int?` | (Optional) Number of commissions to return. | | **`nextId`** | `String?` | (Optional) Cursor ID for the next page. | Returns `GrowSurfCommissionsResponse`. #### **Example use** ```kotlin val commissions = growsurf.getParticipantCommissions( limit = 20, ) ``` *** ### Mark participant commissions read Affiliate programs only Call this after showing commission notifications so GrowSurf can clear the participant's unread commission state. ```kotlin growsurf.markParticipantCommissionsRead() ``` Returns `GrowSurfSuccessResponse`. #### **Example use** ```kotlin growsurf.markParticipantCommissionsRead() ``` *** ### Get participant payouts Affiliate programs only Use this for affiliate programs to show a participant's payout history. ```kotlin growsurf.getParticipantPayouts( limit = 20, nextId = null, ) ``` | Parameter | Data Type | Description | | ------------ | --------- | --------------------------------------- | | **`limit`** | `Int?` | (Optional) Number of payouts to return. | | **`nextId`** | `String?` | (Optional) Cursor ID for the next page. | Returns `GrowSurfPayoutsResponse`. #### **Example use** ```kotlin val payouts = growsurf.getParticipantPayouts( limit = 20, ) ``` *** ### Mark participant payouts read Affiliate programs only Call this after showing payout notifications so GrowSurf can clear the participant's unread payout state. ```kotlin growsurf.markParticipantPayoutsRead() ``` Returns `GrowSurfSuccessResponse`. #### **Example use** ```kotlin growsurf.markParticipantPayoutsRead() ``` *** ### Get participant affiliate summary Affiliate programs only Use this for affiliate programs to show a participant's high-level affiliate stats, such as referral revenue, total paid out, and upcoming payout. ```kotlin growsurf.getParticipantAffiliateSummary() ``` Returns `GrowSurfAffiliateSummary`. #### **Example use** ```kotlin val summary = growsurf.getParticipantAffiliateSummary() Log.d("GrowSurf", "Upcoming payout: ${summary.upcomingPayout}") ``` *** ### Request PayPal confirm email Affiliate programs only Use this when your affiliate program needs the participant to confirm their PayPal email before payouts can continue. ```kotlin growsurf.requestPaypalConfirmEmail() ``` Returns `GrowSurfSuccessResponse`. #### **Example use** ```kotlin val response = growsurf.requestPaypalConfirmEmail() ``` *** ### Request tax info session Use this when the campaign requires tax documentation and the participant needs to complete or resubmit their W-9 / W-8 form before rewards or payouts can continue. It starts a secure hosted tax-form session and returns the hosted URL to open (in a browser or Chrome Custom Tab) plus the participant's new tax status. The native GrowSurf window calls this automatically from its Tax Forms settings row; call it yourself only if you build a custom settings UI. ```kotlin growsurf.requestTaxInfoSession() ``` Returns `GrowSurfTaxSessionResponse`. #### **Example use** ```kotlin val session = growsurf.requestTaxInfoSession() session.hostedUrl?.let { url -> startActivity(Intent(Intent.ACTION_VIEW, Uri.parse(url))) } ``` {% hint style="info" %} GrowSurf never stores participant tax IDs. The W-9 / W-8 is completed on a hosted page served by GrowSurf's IRS-authorized e-file partner. {% endhint %} *** ## ATTRIBUTION ADAPTERS ↓ ### Branch attribution adapter Use this helper when Branch returns attribution data. It normalizes Branch payloads and can store the resulting GrowSurf attribution on the SDK. ```kotlin GrowSurfBranchAttribution.normalize(parameters) GrowSurfBranchAttribution.handle(parameters, growsurf) ``` | Method | Description | | ---------------------------------------------------------- | ---------------------------------------------------------------------- | | **`normalize(parameters: Map)`** | Converts a mixed map, then parses attribution without storing it. | | **`normalize(json: JSONObject)`** | Parses JSON attribution without storing it. | | **`handle(parameters: Map, sdk: GrowSurfSdk)`** | Converts, parses, and stores attribution on the provided SDK instance. | | **`handle(json: JSONObject, sdk: GrowSurfSdk)`** | Parses and stores attribution on the provided SDK instance. | #### **Example use** {% tabs %} {% tab title="Kotlin" %} ```kotlin import com.growsurf.sdk.attribution.branch.GrowSurfBranchAttribution val attribution = GrowSurfBranchAttribution.handle(branchParams, growsurf) ``` {% endtab %} {% tab title="Java normalize" %} ```java GrowSurfAttribution attribution = GrowSurfBranchAttribution.normalize(branchJson); ``` {% endtab %} {% endtabs %} *** ### Adjust attribution adapter Use this helper when Adjust returns a deep link. It normalizes the URI or URL and can store the resulting GrowSurf attribution on the SDK. ```kotlin GrowSurfAdjustAttribution.normalize(uri) GrowSurfAdjustAttribution.handle(uri, growsurf) ``` | Method | Description | | ------------------------------------------- | ------------------------------------------------------------------- | | **`normalize(uri: Uri)`** | Parses a URI and returns `GrowSurfAttribution?` without storing it. | | **`normalize(url: String)`** | Parses a URL string or encoded URL string without storing it. | | **`handle(uri: Uri, sdk: GrowSurfSdk)`** | Parses and stores attribution on the provided SDK instance. | | **`handle(url: String, sdk: GrowSurfSdk)`** | Parses and stores attribution on the provided SDK instance. | #### **Example use** {% tabs %} {% tab title="Kotlin" %} ```kotlin import com.growsurf.sdk.attribution.adjust.GrowSurfAdjustAttribution val attribution = GrowSurfAdjustAttribution.handle(adjustDeepLink, growsurf) ``` {% endtab %} {% tab title="Java normalize" %} ```java GrowSurfAttribution attribution = GrowSurfAdjustAttribution.normalize(adjustUri); ``` {% endtab %} {% endtabs %} *** ### AppsFlyer attribution adapter Use this helper when AppsFlyer returns conversion or deep link data. It normalizes the payload and can store the resulting GrowSurf attribution on the SDK. ```kotlin GrowSurfAppsFlyerAttribution.normalize(parameters) GrowSurfAppsFlyerAttribution.handle(parameters, growsurf) ``` | Method | Description | | ---------------------------------------------------------- | ---------------------------------------------------------------------- | | **`normalize(parameters: Map)`** | Converts a mixed map, then parses attribution without storing it. | | **`normalize(json: JSONObject)`** | Parses JSON attribution without storing it. | | **`handle(parameters: Map, sdk: GrowSurfSdk)`** | Converts, parses, and stores attribution on the provided SDK instance. | | **`handle(json: JSONObject, sdk: GrowSurfSdk)`** | Parses and stores attribution on the provided SDK instance. | #### **Example use** {% tabs %} {% tab title="Kotlin" %} ```kotlin import com.growsurf.sdk.attribution.appsflyer.GrowSurfAppsFlyerAttribution val attribution = GrowSurfAppsFlyerAttribution.handle(conversionData, growsurf) ``` {% endtab %} {% tab title="Java normalize" %} ```java GrowSurfAttribution attribution = GrowSurfAppsFlyerAttribution.normalize(conversionJson); ``` {% endtab %} {% endtabs %} *** ### Singular attribution adapter Use this helper when Singular returns callback parameters or deep link values. It normalizes the payload and can store the resulting GrowSurf attribution on the SDK. ```kotlin GrowSurfSingularAttribution.normalize(parameters) GrowSurfSingularAttribution.handle(parameters, growsurf) ``` | Method | Description | | ---------------------------------------------------------- | ---------------------------------------------------------------------- | | **`normalize(parameters: Map)`** | Converts a mixed map, then parses attribution without storing it. | | **`normalize(json: JSONObject)`** | Parses JSON attribution without storing it. | | **`normalize(uri: Uri)`** | Parses a URI without storing it. | | **`normalize(url: String)`** | Parses a URL string or encoded URL string without storing it. | | **`handle(parameters: Map, sdk: GrowSurfSdk)`** | Converts, parses, and stores attribution on the provided SDK instance. | | **`handle(json: JSONObject, sdk: GrowSurfSdk)`** | Parses and stores attribution on the provided SDK instance. | | **`handle(uri: Uri, sdk: GrowSurfSdk)`** | Parses and stores attribution on the provided SDK instance. | | **`handle(url: String, sdk: GrowSurfSdk)`** | Parses and stores attribution on the provided SDK instance. | #### **Example use** {% tabs %} {% tab title="Kotlin" %} ```kotlin import com.growsurf.sdk.attribution.singular.GrowSurfSingularAttribution val attribution = GrowSurfSingularAttribution.handle(singularPayload, growsurf) ``` {% endtab %} {% tab title="Java normalize" %} ```java GrowSurfAttribution attribution = GrowSurfSingularAttribution.normalize(singularJson); ``` {% endtab %} {% endtabs %} *** ## UTILITIES ↓ ### Normalize attribution parameters Use this when you need to read GrowSurf attribution from raw provider parameters without storing it. It looks for `grsf`, `ref`, or `referredBy` directly and inside URL-like values. {% tabs %} {% tab title="Kotlin" %} ```kotlin val attribution = GrowSurfAttributionNormalizer.normalize( parameters = mapOf( "deep_link_value" to "https://example.com/signup?grsf=referrer_id", "click_id" to "click_123", ), provider = "appsflyer", ) ``` {% endtab %} {% tab title="Java" %} ```java Map parameters = new HashMap<>(); parameters.put("deep_link_value", "https://example.com/signup?grsf=referrer_id"); parameters.put("click_id", "click_123"); GrowSurfAttribution attribution = GrowSurfAttributionNormalizer.normalize( parameters, "appsflyer" ); ``` {% endtab %} {% endtabs %} | Parameter | Data Type | Description | | ---------------- | --------------------- | ------------------------------------------------------------------------------------------ | | **`parameters`** | `Map` | (Required) Raw parameters. The normalizer checks direct fields and URL-like nested values. | | **`provider`** | `String?` | (Optional) Provider name to attach to the attribution result. | Returns `GrowSurfAttribution?`. *** ### Normalize attribution URI Use this when you need to parse a URI for `grsf`, `ref`, or `referredBy` without storing attribution on the SDK. ```kotlin GrowSurfAttributionNormalizer.normalize(uri, provider = "adjust") ``` | Parameter | Data Type | Description | | -------------- | --------- | ------------------------------------------------------------- | | **`uri`** | `Uri` | (Required) URI to parse. | | **`provider`** | `String?` | (Optional) Provider name to attach to the attribution result. | Returns `GrowSurfAttribution?`. #### **Example use** ```kotlin val attribution = GrowSurfAttributionNormalizer.normalize( Uri.parse("https://example.com/signup?grsf=referrer_id"), provider = "adjust", ) ``` *** ### Normalize attribution JSON Use this when a provider gives you a JSON payload and you need to find `grsf`, `ref`, or `referredBy` without storing attribution on the SDK. ```kotlin GrowSurfAttributionNormalizer.normalize(json, provider = "branch") ``` | Parameter | Data Type | Description | | -------------- | ------------ | ------------------------------------------------------------- | | **`json`** | `JSONObject` | (Required) JSON provider payload. | | **`provider`** | `String?` | (Optional) Provider name to attach to the attribution result. | Returns `GrowSurfAttribution?`. #### **Example use** ```kotlin val attribution = GrowSurfAttributionNormalizer.normalize( JSONObject().put("~referring_link", "https://example.com?grsf=referrer_id"), provider = "branch", ) ``` *** ### Convert attribution parameters to strings Use this before passing mixed provider callback payloads to the normalizer or SDK attribution methods. It converts nested values into a `Map` without storing attribution. ```kotlin GrowSurfAttributionNormalizer.stringParameters(parameters) ``` | Parameter | Data Type | Description | | ---------------- | -------------------------------- | ------------------------------------------------------------------------------------- | | **`parameters`** | `Map` or `JSONObject` | (Required) Provider callback payload. Nested values are flattened into string values. | Returns `Map`. #### **Example use** ```kotlin val stringParameters = GrowSurfAttributionNormalizer.stringParameters(providerPayload) growsurf.handleAttributionParameters( stringParameters, provider = "branch", ) ``` # Models and Errors Models, callbacks, stores, interfaces, and errors exposed by the GrowSurf Android SDK. This reference documents the models, callbacks, advanced interfaces, stores, and errors exposed by the GrowSurf Android SDK. ## Core models ### GrowSurfConfiguration | Field | Type | Description | | ------------ | -------- | ------------------------ | | `campaignId` | `String` | GrowSurf program ID. | | `publicKey` | `String` | Mobile SDK public key. | | `baseUrl` | `String` | Mobile SDK API base URL. | ### GrowSurfAttribution | Field | Type | Description | | ------------ | ---------- | ------------------------------------------------------------ | | `referredBy` | `String?` | Referrer participant ID or vanity key. | | `ref` | `String?` | Referrer value mirrored for provider compatibility. | | `unique` | `Boolean?` | Whether the attribution provider marked the click as unique. | | `provider` | `String?` | Attribution provider name. | | `clickId` | `String?` | Provider click ID. | ### GrowSurfParticipantInput | Field | Type | Description | | ------------- | ---------------------- | -------------------------------------------- | | `email` | `String` | Participant email address. | | `firstName` | `String?` | Participant first name. | | `lastName` | `String?` | Participant last name. | | `referredBy` | `String?` | Explicit referrer value. | | `attribution` | `GrowSurfAttribution?` | Explicit attribution payload. | | `metadata` | `Map?` | Custom metadata to store on the participant. | {% hint style="info" %} `mobileInstanceId` is generated and sent by the SDK automatically. It is not part of `GrowSurfParticipantInput`. {% endhint %} ### GrowSurfParticipantUpdateInput | Field | Type | Description | | ----------- | ---------------------- | ------------------- | | `firstName` | `String?` | Updated first name. | | `lastName` | `String?` | Updated last name. | | `metadata` | `Map?` | Updated metadata. | ### GrowSurfCampaign | Field | Type | | ------------------ | ------------------------------ | | `id` | `String` | | `name` | `String?` | | `type` | `String?` | | `referralCount` | `Int?` | | `participantCount` | `Int?` | | `impressionCount` | `Int?` | | `inviteCount` | `Int?` | | `winnerCount` | `Int?` | | `currencyISO` | `String?` | | `status` | `String?` | | `rewards` | `List` | ### GrowSurfCampaignReward | Field | Type | | ----------------------- | ---------- | | `id` | `String?` | | `type` | `String?` | | `title` | `String?` | | `description` | `String?` | | `referralDescription` | `String?` | | `isUnlimited` | `Boolean?` | | `limit` | `Int?` | | `conversionsRequired` | `Int?` | | `numberOfWinners` | `Int?` | | `imageUrl` | `String?` | | `order` | `Int?` | | `limitDuration` | `String?` | | `nextMilestonePrefix` | `String?` | | `nextMilestoneSuffix` | `String?` | | `couponCode` | `String?` | | `referredRewardUpfront` | `Boolean?` | ### GrowSurfParticipant | Field | Type | | -------------------------- | -------------- | | `id` | `String` | | `email` | `String?` | | `firstName` | `String?` | | `lastName` | `String?` | | `shareUrl` | `String?` | | `paypalEmailAddress` | `String?` | | `referralCount` | `Int?` | | `inviteCount` | `Int?` | | `monthlyReferralCount` | `Int?` | | `prevMonthlyReferralCount` | `Int?` | | `rank` | `Int?` | | `monthlyRank` | `Int?` | | `prevMonthlyRank` | `Int?` | | `vanityKeys` | `List` | | `unreadCommissionsCount` | `Int?` | | `unreadPayoutsCount` | `Int?` | ### GrowSurfCreateParticipantResponse | Field | Type | | -------------------------- | ------------------------- | | `participantToken` | `String?` | | `expiresIn` | `Int?` | | `participant` | `GrowSurfParticipant?` | | `isNew` | `Boolean?` | | `requiresParticipantToken` | `Boolean?` | | `window` | `GrowSurfWindowResponse?` | ### GrowSurfAddReferredParticipantResponse | Field | Type | | -------------------------- | ----------------------------------------------- | | `added` | `Boolean` | | `validReferral` | `Boolean` | | `referredBy` | `String?` | | `notAddedReason` | `GrowSurfAddReferredParticipantNotAddedReason?` | | `participantToken` | `String?` | | `expiresIn` | `Int?` | | `participant` | `GrowSurfParticipant?` | | `isNew` | `Boolean?` | | `requiresParticipantToken` | `Boolean?` | ### GrowSurfAddReferredParticipantNotAddedReason | Case | Value | | ---------------------------- | ---------------------------- | | `NO_REFERRER` | `no_referrer` | | `INVALID_REFERRER` | `invalid_referrer` | | `PARTICIPANT_ALREADY_EXISTS` | `participant_already_exists` | ### Referral and reward models | Model | Fields | | ---------------------------------- | ----------------------------------------------------------------------------------------------------------- | | `GrowSurfReferralsResponse` | `referrals`, `limit`, `nextOffset`, `more` | | `GrowSurfReferral` | `id`, `email`, `referralStatus`, `createdAt`, `updatedAt`, `referralTriggeredAt`, `referralCreditExpiredAt` | | `GrowSurfRewardsResponse` | `rewards`, `limit`, `nextId` | | `GrowSurfReward` | `id`, `status`, `unread`, `approved`, `rewardId`, `title`, `description`, `isReferrer` | | `GrowSurfSuccessResponse` | `success`, `message` | | `GrowSurfAttributionResponse` | `success`, `valid`, `referredBy` | | `GrowSurfValidateReferrerResponse` | `success`, `valid`, `referredBy` | | `GrowSurfInviteResponse` | `success`, `message`, `messageType` | ## GrowSurf window models ### GrowSurfWindowIdentity | Case | Description | | --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Anonymous` | Loads the window without participant identity. | | `ParticipantFields(GrowSurfParticipantInput)` | Creates a new participant from fields before loading the window. Existing participants need a participant token; use `ExistingParticipantToken(String)` with a token created by your backend or returned by the SDK. | | `ExistingParticipantToken(String)` | Uses a participant token created by your backend or by the SDK. | ### GrowSurfWindowTheme | Field | Type | Description | | ------------------- | --------------------------------- | ----------------------------------------------------------- | | `primaryColor` | `Long?` | Optional ARGB primary color override, such as `0xFF13795B`. | | `colorScheme` | `GrowSurfWindowColorScheme` | `SYSTEM`, `LIGHT`, or `DARK`. | | `cornerRadiusDp` | `Float?` | Optional corner radius override in dp. | | `presentationStyle` | `GrowSurfWindowPresentationStyle` | `AUTOMATIC`, `FULL_SCREEN`, or `SHEET`. | ### GrowSurfWindowCallbacks | Callback | Type | | -------------------------- | ---------------------------------------- | | `onOpen` | `() -> Unit` | | `onClose` | `() -> Unit` | | `onParticipantCreated` | `(GrowSurfParticipant, String?) -> Unit` | | `onShareTracked` | `(String) -> Unit` | | `onInviteSent` | `() -> Unit` | | `onPayoutOrSettingsAction` | `(String) -> Unit` | | `onError` | `(Throwable) -> Unit` | ### GrowSurfWindowController | Method | Description | | --------- | ------------------------------------- | | `close()` | Closes the presented GrowSurf window. | ### GrowSurfWindowResponse | Field | Type | | ------------------ | ------------------------------ | | `version` | `String?` | | `campaign` | `GrowSurfWindowCampaign?` | | `signup` | `GrowSurfWindowSignup?` | | `visibleSections` | `Map` | | `share` | `GrowSurfWindowShareConfig?` | | `participant` | `GrowSurfParticipant?` | | `unreadCounts` | `GrowSurfWindowUnreadCounts?` | | `payoutSettings` | `GrowSurfPayoutSettings?` | | `content` | `Map` | | `referrals` | `GrowSurfReferralsResponse?` | | `rewards` | `GrowSurfRewardsResponse?` | | `leaderboard` | `GrowSurfLeaderboardResponse?` | | `referralSummary` | `GrowSurfReferralSummary?` | | `affiliateSummary` | `GrowSurfAffiliateSummary?` | | `commissions` | `GrowSurfCommissionsResponse?` | | `payouts` | `GrowSurfPayoutsResponse?` | ### Additional window models | Model | Fields | | -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `GrowSurfWindowCampaign` | `id`, `type`, `status`, `companyName`, `companyLogoImageUrl`, `goal`, `currencyISO`, `shouldDisplayPoweredBy`, `rewardTypes`, `rewards`, `design` | | `GrowSurfWindowSignup` | `state`, `canCreateParticipant` | | `GrowSurfWindowShareConfig` | `preferredUrl`, `fallbackUrl`, `nativeShare`, `channels`, `invite` | | `GrowSurfWindowShareChannel` | `type`, `label`, `order`, `subject`, `message`, `nativePreferred` | | `GrowSurfWindowUnreadCounts` | `commissions`, `payouts` | | `GrowSurfPayoutSettings` | `provider`, `paypalEmailAddress`, `canRequestPaypalConfirmEmail`, `hostedActions`, `requiredActions`, `payoutInstructionsMode`, `taxInfo` | | `GrowSurfTaxInfo` | `status`, `formType`, `residencyCountryCode`, `vatNumber`, `vatCountryCode`, `statusReason`, `payoutSettings` | | `GrowSurfTaxSessionResponse` | `hostedUrl`, `status` | | `GrowSurfTaxInfoSaveResponse` | `success`, `taxInfo` | | `GrowSurfLeaderboardResponse` | `participants`, `offsetKey`, `nextKey`, `page`, `hasMore` | | `GrowSurfLeaderboardParticipant` | `id`, `rank`, `monthlyRank`, `prevMonthlyRank`, `email`, `isWinner`, `referralCount`, `monthlyReferralCount`, `prevMonthlyReferralCount`, `pendingReferralCount`, `revenueAmount`, `commissionAmount` | | `GrowSurfReferralSummary` | `referrals`, `leads`, `expiredReferrals`, `clicks`, `rewardsEarned`, `pendingRewards`, `invitesSent`, `currencyISO` | | `GrowSurfAffiliateSummary` | `referralRevenue`, `totalPaidOut`, `upcomingPayout`, `referrals`, `leads`, `clicks`, `currencyISO` | | `GrowSurfCommissionsResponse` | `commissions`, `totalCount`, `totalAmount`, `summary`, `nextId` | | `GrowSurfCommission` | `id`, `amount`, `currencyISO`, `status`, `holdDuration`, `createdAt`, `amountInCampaignCurrency`, `saleAmountInCampaignCurrency`, `campaignCurrencyISO`, `unread` | | `GrowSurfPayoutsResponse` | `payouts`, `totalCount`, `totalAmount`, `summary`, `nextId` | | `GrowSurfPayout` | `id`, `amount`, `currencyISO`, `status`, `queuedAt`, `createdAt`, `amountInCampaignCurrency`, `campaignCurrencyISO`, `unread` | ## Advanced interfaces and stores Use these APIs for tests or custom storage/transport integrations. | Type | Public methods | | ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | `GrowSurfCallback` | `onSuccess(result)`, `onError(error)` | | `GrowSurfTokenStore` | `getSessionToken()`, `getParticipantToken()`, `saveSessionToken(token)`, `saveParticipantToken(token)`, `clear()` | | `GrowSurfAttributionStore` | `getAttribution()`, `saveAttribution(attribution)`, `clearAttribution()`, `hasCheckedDeferredDeepLink()`, `markDeferredDeepLinkChecked()` | | `GrowSurfMobileInstanceIdStore` | `getMobileInstanceId()` | | `GrowSurfWindowCacheStore` | `getWindow(cacheKey, nowMillis)`, `saveWindow(cacheKey, windowJson, expiresAtMillis)`, `clear()` | | `GrowSurfInstallReferrerClient` | `getInstallReferrer()` | | `GrowSurfHttpTransport` | `execute(request)` | | `GrowSurfHttpRequest` | `method`, `url`, `headers`, `body`, `timeoutMillis` | | `GrowSurfHttpResponse` | `statusCode`, `body` | | `EncryptedPreferencesGrowSurfTokenStore` | EncryptedSharedPreferences-backed token store used by default. | | `PreferencesGrowSurfAttributionStore` | SharedPreferences-backed attribution store used by default. | | `PreferencesGrowSurfMobileInstanceIdStore` | SharedPreferences-backed mobile instance ID store used by default. | | `PreferencesGrowSurfWindowCacheStore` | SharedPreferences-backed window cache store. | | `EncryptedPreferencesGrowSurfWindowCacheStore` | EncryptedSharedPreferences-backed window cache store used by default. | | `UrlConnectionGrowSurfHttpTransport` | Default HTTP transport. | | `PlayStoreGrowSurfInstallReferrerClient` | Default Google Play Install Referrer client. | ## Errors The SDK throws: * `GrowSurfException` for SDK state errors such as missing participant tokens. * `GrowSurfHttpException` for non-2xx HTTP responses. Exposes a `statusCode: Int` property and the response body as the exception message. # REST API Use the REST API to create and manage your GrowSurf programs, participants, referrals, rewards, webhooks, and team settings from a secure server-side environment. {% hint style="info" %} * **Using AI?** If you're using an AI tool such as Cursor, Claude Code, Antigravity, or Codex to help you implement GrowSurf, we recommend utilizing our [MCP server](https://docs.growsurf.com/build-with-ai). * **Using TypeScript, Python, PHP, Ruby, or Java?** Use an official GrowSurf API library. [Learn more](https://docs.growsurf.com/developer-tools/rest-api/api-libraries). * **Building a native iOS or Android app?** Use the [iOS SDK](/developer-tools/ios-sdk) or [Android SDK](/developer-tools/android-sdk) for mobile attribution, participant creation, sharing, and referral portal data. Use the REST API from your backend for secure server-side actions. {% endhint %} ## Getting started {% hint style="info" %} **Note:** The GrowSurf REST API is available to the following types of programs (campaigns): * **Referral programs:** Users on a GrowSurf paid subscription plan * **Affiliate programs:** Users who have a valid payment method on file {% endhint %} ### Step 1: Get your API key 1. Go to [API Keys in GrowSurf Settings](https://app.growsurf.com/settings#api-keys). 2. Create an API key. 3. Copy the new key when GrowSurf shows it. For security, the full key is shown only once. {% hint style="warning" %} **Important Tips:** * Your API key holds many privileges, so keep it secure. Do not share your API key in publicly accessible areas such as GitHub, Bitbucket, web browsers, or frontend client code. * Do not use the RESTful API in browser applications. Exposing your secret API key within front end code exposes it to security risks. Anybody with a bit of programming knowledge could potentially hijack your API key and begin making requests on your behalf. * Do not embed your REST API key in native mobile apps. Native iOS and Android apps should use the Mobile SDKs with a public Mobile SDK key. Keep REST API calls on your backend, especially for purchase, subscription, or other server-verified referral qualification events. {% endhint %} *** ### Step 2: Set up authentication The GrowSurf REST API uses your API key to authenticate requests: 1. Set a plain text header named `Authorization` with the contents `Bearer `, where `` is your API key. #### Example Authenticated Request {% tabs %} {% tab title="cURL" %} ```bash curl -X "GET" "https://api.growsurf.com/v2/campaign/4pdlhb" -H "Authorization: Bearer " ``` {% endtab %} {% tab title="Java" %} ```java OkHttpClient client = new OkHttpClient(); Request request = new Request.Builder() .url("https://api.growsurf.com/v2/campaign/4pdlhb") .get() .addHeader("Authorization", "Bearer ") .build(); Response response = client.newCall(request).execute(); ``` {% endtab %} {% tab title="Node.js" %} ```javascript const request = require("request"); const options = { method: 'GET', url: 'https://api.growsurf.com/v2/campaign/4pdlhb', headers: { Authorization: 'Bearer ' } }; request(options, function (error, response, body) { if (error) throw new Error(error); console.log(body); }); ``` {% endtab %} {% tab title="Python" %} ```python import requests url = "https://api.growsurf.com/v2/campaign/4pdlhb" headers = { 'Authorization': "Bearer " } response = requests.request("GET", url, headers=headers) print(response.text) ``` {% endtab %} {% tab title="PHP" %} ```php setUrl('https://api.growsurf.com/v2/campaign/4pdlhb'); $request->setMethod(HTTP_METH_GET); $request->setHeaders(array( 'Authorization' => 'Bearer ' )); try { $response = $request->send(); echo $response->getBody(); } catch (HttpException $ex) { echo $ex; } ``` {% endtab %} {% tab title="Go" %} ```go package main import ( "fmt" "net/http" "io/ioutil" ) func main() { url := "https://api.growsurf.com/v2/campaign/4pdlhb" req, _ := http.NewRequest("GET", url, nil) req.Header.Add("Authorization", "Bearer ") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := ioutil.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` {% endtab %} {% endtabs %} #### Scoped Access If a scoped key does not include the required scope or program access for a request, the API returns `403`. You can change API key scopes from your [Settings](https://app.growsurf.com/settings#api-keys) page. Choose only the access that your API key needs: | Scope | Access | | -------------------- | ------------------------------------------------------------------------------------------------------ | | `team:read` | Read the selected team's name and GrowSurf verification state. | | `team:write` | Update the team name, request team verification, or resend the team owner verification email. | | `api_key:rotate` | Rotate the API key making the direct REST/SDK request. This scope and action are not available in MCP. | | `program:read` | Read programs, reward configuration, emails, installation, options, design, and webhooks. | | `program:write` | Create, clone, and update programs; create, update, or delete reward configuration and webhooks. | | `participant:read` | Read participants, referrals, leaderboards, and participant activity. | | `participant:write` | Create and update participants, trigger or cancel referrals, and send participant emails or invites. | | `participant:delete` | Delete participants in one request or in bulk. | | `reward:read` | Read issued rewards, commissions, and payouts. | | `reward:write` | Record or refund sales and approve commissions or rewards without fulfilling them. | | `reward:delete` | Delete issued rewards or commissions. | | `reward:fulfill` | Fulfill an issued reward. This is separate because fulfillment may deliver something of value. | | `analytics:read` | Read aggregate program and participant analytics. | Approving a reward requires `reward:write`. Approving and fulfilling it in the same request requires both `reward:write` and `reward:fulfill`. *** ## Base URL All endpoints for the GrowSurf REST API start with the same base URL: ``` https://api.growsurf.com/v2 ``` *** ## **Next steps** * [View Tutorials](/developer-tools/rest-api/tutorials) * [View Objects](/developer-tools/rest-api/api-objects) * [View API Reference](/developer-tools/rest-api/api-reference) # Tutorials How to implement the GrowSurf REST API in common use-case scenarios. {% hint style="success" %} #### Customer Example: How Bolt.new Powered Their Viral Referral Program with GrowSurf’s API See our in-depth technical [blog post](https://growsurf.com/blog/how-boltnew-powered-their-viral-referral-program-with-growsurfs-api) on how a GrowSurf customer implemented the API, webhooks, and reward metadata to scale their referral program to millions of users. {% endhint %} ## Table of contents The following examples use **Node.js**. | Scenario | | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [Example 1: Trigger a referral on qualifying action (e.g, on conversion, purchase or upgrade)](#example-1-trigger-a-referral-on-qualifying-action-e.g-on-conversion-purchase-or-upgrade) | | [Example 2: Trigger a referral on signup event](#example-2-trigger-a-referral-on-signup-event) | | [Example 3: Get a participant's details](#example-3-get-a-participants-details) | | [Example 4: Delete a list of participants](#example-4-delete-a-list-of-participants) | ## Example 1: Trigger a referral on qualifying action (e.g, on conversion, purchase or upgrade) {% hint style="info" %} **Airbnb as an example** > ***"**Send a friend $40 in Airbnb credit. You’ll get $20 when they travel and $75 when they host."* Follow this tutorial if your program's [referral trigger](https://support.growsurf.com/article/188-what-triggers-a-referral) is *Qualifying Action,* where a referrer only receives credit when the person they referred signs up AND performs a certain qualifying action. {% endhint %} This requires two API calls to GrowSurf. ### [Step 1: Make sure you have authentication set up](/developer-tools/rest-api#getting-started) ### Step 2: Add the participant {% hint style="warning" %} **Important Note:** If your program is configured to add participants automatically through a form on your website ([see image](https://blobscdn.gitbook.com/v0/b/gitbook-28427.appspot.com/o/assets%2F-LeklWo0yn03AhWro2Ux%2F-LgbRcVrYaKYUhQVctKK%2F-LgbS62PrNqHiJm-qwdI%2FScreen%20Shot%202019-06-05%20at%207.42.50%20PM.png?alt=media\&token=85e064ce-4bac-4617-9481-f80215478d51)), skip this step**.** {% endhint %} First, in the code where you capture the new user's email, add them to your GrowSurf program as a participant with the [**`POST`** `Add participant`](/developer-tools/rest-api/api-reference#post-campaign-id-participant) method. Alternatively, you can use the JavaScript method [`growsurf.addParticipant()`](https://docs.growsurf.com/developer-tools/javascript-sdk/api-reference#add-participant) instead to add participants. The example below is what that code could look like when using the REST API. **Code Example** {% code title="signup.js" %} ```javascript const request = require("request"); let options = { method: 'POST', url: 'https://api.growsurf.com/v2/campaign/4pdlhb/participant', headers: { Authorization: 'Bearer ' }, json: true }; const signUp = user => { // Set the body of the GrowSurf API request options.body = user; // Send the API request to add the user as a new participant in your GrowSurf program request(options, (error, response, body) => { if (error) { throw new Error(error); } const growsurfId = body.id; // Save the new user to your database (optional) saveUser(user, growsurfId); }); }; ``` {% endcode %} **At line 21,** we set the GrowSurf participant ID as a variable called `growsurfId`. **At line 23**, `saveUser(user, growsurfId)` is an example function you would use to save the GrowSurf participant ID to the new user in your database. We will use this `growsurfId` value later for triggering a referral. {% hint style="info" %} **Don't want to save the `growsurfId` to your database?** The participant's`email` can be used instead of the `growsurfId` to trigger a referral later. If you have access to the participant's email then there is no need to persist the `growsurfId` into your database. {% endhint %} **At line 11**, the `user` argument passed into `signUp(user)` is an Object that looks like this: ```javascript { email: 'sally_mayweathers9448@gmail.com', firstName: 'Sally', // Optional, but recommended for anti-fraud purposes lastName: 'Mayweathers', // Optional, but recommended for anti-fraud purposes ipAddress: 1.2.1.827, // Optional, but recommended for anti-fraud purposes fingerprint: 'dwah12iu3hi1u2h', // Optional, but recommended for anti-fraud purposes referredBy: '1cca8d', // The referrer's unique GrowSurf ID. Can also be the referrer's unique email address metadata: { phoneNumber: '+1 415-123-4567', country: 'USA', zipCode: '94303' } } ``` * **At lines 2 and 3,** we pass in `firstName` and `lastName`. These will be used for anti-fraud purposes, as well as in referred friend motivator elements, if enabled. * **At line 4**, we pass in the user's IP address, which will be used for anti-fraud purposes. * **At line 5**, we pass in the user's browser fingerprint, which will be used for anti-fraud purposes. You can use a library like [fingerprintjs](https://github.com/fingerprintjs/fingerprintjs) to get this value. * **At line 6**, we use `referredBy` to associate this new user with a referrer. This value can be the referrer's email address or unique GrowSurf ID (you may want to use [`growsurf.getReferrerId()`](https://docs.growsurf.com/developer-tools/javascript-sdk/api-reference#get-referrer-id) to retrieve the referrer ID). * **At line 7**, we save a shallow `metadata` Object to the GrowSurf Participant. This is optional, but is useful for viewing specific participant information in your GrowSurf dashboard ([see image](https://blobscdn.gitbook.com/v0/b/gitbook-28427.appspot.com/o/assets%2F-LeklWo0yn03AhWro2Ux%2F-LfiWyhm5z0L0AN3V1o_%2F-Lficu90C8YEPgrdhKyA%2FScreen%20Shot%20on%202019-05-25%20at%2018%3A56%3A33.png?alt=media\&token=1d3a352f-652e-4d13-83bd-aab4aa7ae369)). ### **Step 3: Trigger the referral** {% hint style="warning" %} **Important Note:** Make sure your program's referral trigger is set to *Sign Up + Qualifying Action* ([see image](https://blobscdn.gitbook.com/v0/b/gitbook-28427.appspot.com/o/assets%2F-LeklWo0yn03AhWro2Ux%2F-LnvqQyyEju4bLT4R5PC%2F-LnvsusHI0xFY2PJcJzB%2FScreen%20Shot%202019-09-04%20at%206.42.06%20PM.png?alt=media\&token=21db3d41-f20b-4887-833c-8109205cbc89)). If the referral trigger is set to *Sign Up*, triggering referrals will not work since referral credit has already been provided. {% endhint %} Now at any future date [within the referral credit window](https://blobscdn.gitbook.com/v0/b/gitbook-28427.appspot.com/o/assets%2F-LeklWo0yn03AhWro2Ux%2F-LfTU5fPPuEimujYPBlL%2F-LfTUYdelF4Itf1vXW9T%2FScreen%20Shot%20on%202019-05-22%20at%2015%3A42%3A38.png?alt=media\&token=b1bd5196-2825-4229-b280-0c1240b0b30e), if this new participant performs the goal event, then referral credit will be awarded to their referrer. To trigger the referral, use the [**`POST`** `Trigger referral by participant ID`](/developer-tools/rest-api/api-reference#post-campaign-id-participant-participantidoremail-ref) method. The example below is what that code could look like. **Code Example** {% code title="purchase.js" %} ```javascript const request = require("request"); let options = { method: 'POST', headers: { Authorization: 'Bearer ' }, json: true }; const purchase = growsurfId => { // ...code that makes the purchase... // Set the GrowSurf API request URL with the participant's ID options.url = `https://api.growsurf.com/v2/campaign/4pdlhb/participant/${growsurfId}/ref`; // Send the API request to trigger the referral request(options, (error, response, body) => { if (error) { throw new Error(error); } // Check to see if the referral was triggered successfully const { success, message } = body.success; if(success) { console.log('Referral trigger success!'); } else { console.log('Referral trigger failed :( ', message); } }); }; ``` {% endcode %} **At line 11**, we passed a `growsurfId` argument, which is the GrowSurf participant's unique ID and is required in the API call. If you do not have access to the `growsurfId` of the participant, the participant `email` can be used instead. {% hint style="info" %} ### **Want to honor a refund or cancellation window?** You can hold the referral credit for a set number of days before it is awarded by including an optional `delayInDays` value (an integer between `1` and `90`) in the request body of the [`POST` `Trigger referral`](/developer-tools/rest-api/api-reference#post-campaign-id-participant-participantidoremail-ref) call. If the purchase is refunded during that window, cancel the pending trigger with the [`DELETE` `Cancel delayed referral trigger`](/developer-tools/rest-api/api-reference#delete-campaign-id-participant-participantidoremail-ref) method before the credit is awarded. {% endhint %} {% hint style="info" %} **Remember to set up reward fulfillment automation** Make sure you have [Webhooks](/developer-tools/webhooks) or [Zapier](/integrations/zapier) set up so that rewards automatically get fulfilled to the participant once they reach a reward goal. {% endhint %} ## Example 2: Trigger a referral on signup event {% hint style="info" %} **Dropbox as an example** > ***"**For every friend you refer, you’ll both receive an extra 250MB in cloud storage."* Follow this tutorial if your program's [referral trigger](https://support.growsurf.com/article/188-what-triggers-a-referral) is *Signup Event*, where a referrer receives credit when the person they referred signs up with their email address. {% endhint %} This requires just one API call to GrowSurf. ### [Step 1: Make sure you have authentication set up](/developer-tools/rest-api#getting-started) ### Step 2: Add the participant (and trigger the referral at the same time) {% hint style="warning" %} **Important Notes:** * If your program is configured to add participants automatically through a form on your website ([see image](https://blobscdn.gitbook.com/v0/b/gitbook-28427.appspot.com/o/assets%2F-LeklWo0yn03AhWro2Ux%2F-LgbRcVrYaKYUhQVctKK%2F-LgbS62PrNqHiJm-qwdI%2FScreen%20Shot%202019-06-05%20at%207.42.50%20PM.png?alt=media\&token=85e064ce-4bac-4617-9481-f80215478d51)), skip this step**.** * Make sure your program's referral trigger is set to *Signup Event* ([see image](https://blobscdn.gitbook.com/v0/b/gitbook-28427.appspot.com/o/assets%2F-LeklWo0yn03AhWro2Ux%2F-Lnvt7uOcb1oD4xpY-jJ%2F-Lnvtjtp4i_3zpP2Yag7%2FScreen%20Shot%202019-09-04%20at%206.40.09%20PM.png?alt=media\&token=58dea9be-eb47-42c0-b1af-cb392c246e6b)). {% endhint %} In the code where you capture the new user's email, add them to your GrowSurf program as a participant with the [**`POST`** `Add participant`](/developer-tools/rest-api/api-reference#post-campaign-id-participant) method. The example below is what that code could look like. **Code Example** {% code title="signup.js" %} ```javascript const request = require("request"); let options = { method: 'POST', url: 'https://api.growsurf.com/v2/campaign/4pdlhb/participant', headers: { Authorization: 'Bearer ' }, json: true }; const signUp = user => { // Set the body of the GrowSurf API request options.body = user; // Send the API request to add the user as a new participant in your GrowSurf program request(options, (error, response, body) => { if (error) { throw new Error(error); } // Save the new user to your database (Optional) saveUser(); }); }; ``` {% endcode %} **At line 12**, the `user` argument passed into `signUp(user)` is an Object that looks like this: ```javascript { email: 'sally_mayweathers9448@gmail.com', firstName: 'Sally', // Optional, but recommended for anti-fraud purposes lastName: 'Mayweathers', // Optional, but recommended for anti-fraud purposes ipAddress: 1.2.1.827, // Optional, but recommended for anti-fraud purposes fingerprint: 'dwah12iu3hi1u2h', // Optional, but recommended for anti-fraud purposes referredBy: '1cca8d', // The referrer's unique GrowSurf ID. Can also be the referrer's unique email address referralStatus: 'CREDIT_AWARDED', metadata: { phoneNumber: '+1 415-123-4567', country: 'USA', zipCode: '94303' } } ``` * **At lines 2 and 3,** we pass in `firstName` and `lastName`. These will be used for anti-fraud purposes, as well as in referred friend motivator elements, if enabled. * **At line 4**, we pass in the user's IP address, which will be used for anti-fraud purposes. * **At line 5**, we pass in the user's browser fingerprint, which will be used for anti-fraud purposes. You can use a library like [fingerprintjs](https://github.com/fingerprintjs/fingerprintjs) to get this value. * **At line 6**, we use `referredBy` to associate this new user with a referrer. This value can be the referrer's email address or unique GrowSurf ID (you may want to use [`growsurf.getReferrerId()`](https://docs.growsurf.com/developer-tools/javascript-sdk/api-reference#get-referrer-id) to retrieve the referrer ID) * **At line 7**, we set `referralStatus` to be `CREDIT_AWARDED`. This triggers the referral credit at the same time that this new participant is added (and it overrides the program referral trigger ([what's a referral trigger?](https://support.growsurf.com/article/188-what-triggers-a-referral)) that was set from the *Installation* step of the *Program Editor* ([see image](https://blobscdn.gitbook.com/v0/b/gitbook-28427.appspot.com/o/assets%2F-LeklWo0yn03AhWro2Ux%2F-LfU6JzlO17UzeyVOQcZ%2F-LfU6SW-uc8zI2uuzeah%2FScreen%20Shot%20on%202019-05-22%20at%2018%3A36%3A23.png?alt=media\&token=6204ba21-12b5-4630-90e3-f6117230d7f9)). * **Note:** `referralStatus` must be used with `referredBy`, or else it will be ignored. * **At line 8**, we save a shallow `metadata` Object to the GrowSurf Participant. This is optional, but is useful for viewing specific participant information in your GrowSurf dashboard ([see image](https://blobscdn.gitbook.com/v0/b/gitbook-28427.appspot.com/o/assets%2F-LeklWo0yn03AhWro2Ux%2F-LfiWyhm5z0L0AN3V1o_%2F-Lficu90C8YEPgrdhKyA%2FScreen%20Shot%20on%202019-05-25%20at%2018%3A56%3A33.png?alt=media\&token=1d3a352f-652e-4d13-83bd-aab4aa7ae369)). {% hint style="info" %} **Remember to set up reward fulfillment automation** Make sure you have [Webhooks](/developer-tools/webhooks) or [Zapier](/integrations/zapier) set up so that rewards automatically get fulfilled to the participant once they reach a reward goal. {% endhint %} ## Example 3: Get a participant's details Let's say you want to display a participant's referral progress/stats/rewards in your website or mobile app. With the REST API, you can fetch [`Participant`](/developer-tools/rest-api/api-objects#participant)s and [`ParticipantReward`](/developer-tools/rest-api/api-objects#reward)s by using either of the following API methods: * [**`GET`** `Get participant by email`](/developer-tools/rest-api/api-reference#get-campaign-id-participant-participantidoremail) * [**`GET`** `Get participant by ID`](/developer-tools/rest-api/api-reference#get-campaign-id-participant-participantidoremail) ### [Step 1: Make sure you have authentication set up](/developer-tools/rest-api#getting-started) ### Step 2: Retrieve a participant by email Let's say your server calls your database to retrieve user details and in that same call you want to send their participant information by using their unique email. The example below is what that code could look like. **Code Example** ```javascript const request = require("request"); let options = { method: 'GET', headers: { Authorization: 'Bearer ' } }; const getUserDetails = userEmail => { // ...Call your database to get user details... // ...code here... // Get the GrowSurf participant's details request(options, (error, response, body) => { options.url = `https://api.growsurf.com/v2/campaign/4pdlhb/participant/${userEmail}`; if (error) { throw new Error(error); } console.log(body); }); }; ``` **At line 10**, we passed `userEmail` so we could set it in the GrowSurf API URL at line 16. **At line 20**, `console.log` would print something like this: ```javascript { "id": "f8g9nl", "firstName": "Gavin", "lastName": "Belson", "referralCount": 2, "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, "referrals": [ "i9g2bh", "xua4sq" ], "referralSource": "PARTICIPANT", "referralStatus": "CREDIT_AWARDED", "referrer": { "id": "h8kp6l", "firstName": "Richard", "lastName": "Hendricks", "referralCount": 5, "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, "referrals": [ "0dveu7", "f8g9nl", "j0hbym", "m5xm9l", "w01fil" ] } } ``` ## Example 4: Delete a list of participants To remove many participants at once, send them to the [**`POST`** `Bulk delete participants`](https://docs.growsurf.com/developer-tools/rest-api/api-reference#post-campaign-id-participants-bulk-delete) endpoint. One request deletes up to `200` participants, and each entry can be a participant ID or an email address. The response returns a per-row `status` for every entry, so you can see exactly which ones were removed. {% hint style="warning" %} Deleting a participant is permanent. It also removes that participant's referrals, rewards, commissions, and payout records. {% endhint %} **Code Example (Node.js)** This example reads emails from a CSV, splits them into batches of `200`, and deletes each batch. Follow the steps below: 1. Replace `API_KEY` and `CAMPAIGN_ID` at lines 1 and 2 in the `script.js` file. 2. Replace the email addresses in the `emails.csv` file with your own list of participants to delete (keep the column header labeled `Email`). 3. Run `npm install csv-parser` to install the one dependency. The script uses the built-in `fetch`, so you need Node.js 18 or newer. 4. Run `node script.js` to run the script. {% tabs %} {% tab title="script.js" %} {% code title="script.js" lineNumbers="true" %} ```javascript const API_KEY = "ABC123FS9GM2FBJFZ68T7JNAMRCZ" // Replace with your own API key const CAMPAIGN_ID = "2x3b5c"; // Replace with your campaign ID const csv = require("csv-parser"); const fs = require("fs"); const BATCH_SIZE = 200; // Max entries the bulk-delete endpoint accepts per request // Reads emails.csv and returns the list of email addresses. async function readEmails() { const emails = []; const reader = fs.createReadStream("emails.csv").pipe(csv()); for await (const row of reader) { if (row["Email"]) { emails.push(row["Email"].trim()); } } return emails; } // Deletes one batch of up to 200 participants and returns the API's report. async function deleteBatch(participants) { const url = `https://api.growsurf.com/v2/campaign/${CAMPAIGN_ID}/participants/bulk-delete`; const response = await fetch(url, { method: "POST", headers: { "Authorization": `Bearer ${API_KEY}`, "Content-Type": "application/json" }, body: JSON.stringify({ participants }) }); const body = await response.json(); if (!response.ok) { throw new Error(`Request failed (${response.status}): ${body.message || "unknown error"}`); } return body; } async function main() { const emails = await readEmails(); console.log(`Deleting ${emails.length} participant(s) in batches of ${BATCH_SIZE}...`); for (let i = 0; i < emails.length; i += BATCH_SIZE) { const batch = emails.slice(i, i + BATCH_SIZE); const { summary, results } = await deleteBatch(batch); for (const row of results) { if (row.status === "DELETED") { console.log(`✅ ${row.identifier} deleted`); } else { console.log(`⚠️ ${row.identifier} (${row.status}): ${row.message}`); } } console.log( `Batch done: ${summary.deletedCount} deleted, ${summary.notFoundCount} not found, ` + `${summary.duplicateCount} duplicate, ${summary.errorCount} error` ); } } main(); ``` {% endcode %} {% endtab %} {% tab title="emails.csv" %} {% code title="emails.csv" lineNumbers="true" %} ```csv Email person1@company.com person2@company.com person3@company.com ``` {% endcode %} {% endtab %} {% endtabs %} **Some other notes:** * Each request replaces up to `200` individual delete calls, so you are far less likely to hit the [rate limit](https://docs.growsurf.com/developer-tools/rest-api/api-guidelines#rate-limits). For very large lists, add a short pause between batches. * A `200` response does not mean every row was deleted. Check each row's `status`: `DELETED`, `NOT_FOUND` (no participant matched the ID or email), `DUPLICATE` (the entry resolves to the same participant as an earlier one in the batch), or `ERROR` (the lookup or deletion failed). The `summary` object totals each outcome. * A single request can mix participant IDs and email addresses. # Objects ## Team ```json {"openapi":"3.1.0","info":{"title":"GrowSurf REST API","version":"2.0.0"},"components":{"schemas":{"Team":{"type":"object","description":"The team bound to the API key or OAuth connection.","required":["name","verificationStatus","verificationRequestedAt"],"properties":{"name":{"description":"The team's display name.","type":"string"},"verificationStatus":{"type":"string","enum":["NOT_REQUESTED","REQUESTED","VERIFIED"],"readOnly":true,"description":"GrowSurf team verification state. `VERIFIED` is required before a program can send participant emails."},"verificationRequestedAt":{"type":"integer","format":"int64","nullable":true,"readOnly":true,"description":"When team verification was last requested, as a Unix timestamp in milliseconds."}}}}}} ``` *** ## Campaign ```json {"openapi":"3.1.0","info":{"title":"GrowSurf REST API","version":"2.0.0"},"components":{"schemas":{"Campaign":{"type":"object","description":"Detailed information about a GrowSurf program.","required":["id","name","type","referralCount","participantCount","impressionCount","inviteCount","winnerCount","status","rewards"],"properties":{"id":{"type":"string","readOnly":true,"description":"The unique identifier of the program."},"name":{"type":"string","description":"The program name (internal only, never exposed to participants)."},"type":{"$ref":"#/components/schemas/CampaignType","description":"The program type."},"referralCount":{"type":"integer","readOnly":true,"description":"The total referral count."},"participantCount":{"type":"integer","readOnly":true,"description":"The total participant count."},"impressionCount":{"type":"integer","readOnly":true,"description":"The total number of impressions — the collective number of times participants' unique referral links have been viewed."},"inviteCount":{"type":"integer","readOnly":true,"description":"The total number of invites sent by participants."},"winnerCount":{"type":"integer","readOnly":true,"description":"The total number of winners — all participants with at least one approved reward (includes referrers and referred friends)."},"currencyISO":{"type":["string","null"],"minLength":3,"maxLength":3,"description":"The program currency as an [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) code (e.g., `USD`, `GBP`)."},"status":{"$ref":"#/components/schemas/CampaignStatus","description":"The program status."},"rewards":{"type":"array","items":{"$ref":"#/components/schemas/Reward"},"description":"The list of rewards associated with the program."}}},"CampaignType":{"type":"string","enum":["REFERRAL","AFFILIATE"]},"CampaignStatus":{"type":"string","enum":["DRAFT","IN_PROGRESS","COMPLETE","DELETED"]},"Reward":{"type":"object","description":"A single campaign reward (also known as a `CampaignReward`). This is different from a `ParticipantReward`, which is a reward earned by a participant.","required":["id","type","isUnlimited","metadata"],"properties":{"id":{"type":"string","readOnly":true,"description":"The unique identifier of the campaign reward. You can find this ID from *Program Editor > 1. Rewards* and clicking the reward."},"type":{"$ref":"#/components/schemas/RewardType","description":"The reward type."},"title":{"type":["string","null"],"description":"The reward title (internal only, never exposed to participants)."},"isVisible":{"type":"boolean","description":"Whether the reward is enabled. When `false`, the reward is disabled: it is no longer awarded, and it is hidden from participants, including those who already earned it. Set `true` for the reward to be visible and awardable."},"description":{"type":["string","null"],"description":"The reward description shown to the referrer."},"referralDescription":{"type":["string","null"],"description":"The reward description shown to the referred friend (only applicable for double-sided reward types)."},"referredRewardUpfront":{"type":"boolean","description":"Only applies to double-sided rewards. When `true`, the referred friend's reward is delivered upfront as a discount and no `ParticipantReward` is created for them when the referral triggers."},"isUnlimited":{"type":"boolean","description":"`true` if this reward can be earned by a single participant an unlimited number of times."},"limit":{"type":["integer","null"],"description":"The number of times a participant can earn this reward (overridden when `isUnlimited` is `true`). `-1` represents an unlimited reward in REST responses."},"conversionsRequired":{"type":["integer","null"],"description":"The number of referrals a participant must make to earn this reward."},"numberOfWinners":{"type":["integer","null"],"description":"The maximum number of winners. Only applies to `LEADERBOARD` rewards. When `limitDuration` is `PER_MONTH`, this many top referrers win each month; otherwise this many win in total."},"limitDuration":{"type":["string","null"],"enum":["IN_TOTAL","PER_MONTH","PER_YEAR",null],"description":"Whether the reward can be earned in total, on a monthly basis, or on a yearly basis."},"imageUrl":{"type":["string","null"],"description":"The reward image URL."},"couponCode":{"type":["string","null"],"description":"A static coupon code shown to the referrer in the reward-won email and webhook. Display text only; GrowSurf does not create or validate it in any billing system. If the program has a connected billing integration (Stripe, Chargebee, or Recurly) that issues a coupon for the referral, that issued code is shown instead."},"order":{"type":["integer","null"],"description":"If there are multiple rewards, the order in which the reward should be displayed. `null` by default until set within the Design step of the program editor."},"nextMilestonePrefix":{"type":["string","null"],"description":"Text displayed in front of a participant's referral count for UI purposes (e.g., \"You are only\"). Applicable for milestone rewards (when `type` is `MILESTONE`)."},"nextMilestoneSuffix":{"type":["string","null"],"description":"Text displayed after a participant's referral count for UI purposes (e.g., \"referrals away from receiving a nice reward!\"). Applicable for milestone rewards (when `type` is `MILESTONE`)."},"metadata":{"$ref":"#/components/schemas/Metadata","description":"The reward metadata."},"commissionStructure":{"oneOf":[{"$ref":"#/components/schemas/CommissionStructure"},{"type":"null"}],"description":"The reward commission structure. Present only for affiliate programs."},"referralCouponCode":{"type":["string","null"],"description":"A static coupon code shown to the referred friend in the reward-won email and webhook (double-sided rewards). Same caveats as `couponCode`: display text only, not created or validated in any billing system, and superseded by a connected billing integration's issued coupon when one exists."},"value":{"oneOf":[{"$ref":"#/components/schemas/RewardTaxValuation"},{"type":"null"}],"description":"Tax valuation for the reward (the referrer's side of a double-sided reward). `null` when no valuation is set."},"referredValue":{"oneOf":[{"$ref":"#/components/schemas/RewardTaxValuation"},{"type":"null"}],"description":"Tax valuation for the referred friend's side of a double-sided reward. `null` when no valuation is set."}}},"RewardType":{"type":"string","enum":["SINGLE_SIDED","DOUBLE_SIDED","MILESTONE","LEADERBOARD","AFFILIATE"]},"Metadata":{"type":"object","description":"Shallow custom metadata object.","additionalProperties":true},"CommissionStructure":{"type":"object","description":"The commission configuration for an affiliate reward. Present only for affiliate programs.","properties":{"amount":{"type":["integer","null"],"description":"Fixed commission amount in the currency's smallest denomination, used when `type` is `FIXED`. `null` for percentage-based commissions."},"amountISO":{"type":["string","null"],"description":"ISO 4217 currency code for the fixed `amount`. Defaults to the program's currency when omitted. Must match the campaign `currencyISO` when provided. `null` for percentage-based commissions."},"event":{"type":["string","null"],"description":"The event that generates a commission (e.g., `SALE`)."},"type":{"type":["string","null"],"enum":["PERCENT","FIXED",null],"description":"How the commission is calculated: `PERCENT` (a percentage of the sale) or `FIXED` (a fixed `amount`)."},"minPaidReferrals":{"type":["integer","null"],"description":"The minimum number of paid referrals required before commissions are earned."},"holdDuration":{"type":["integer","null"],"description":"Number of days a commission is held before it can be paid out."},"duration":{"type":["string","null"],"description":"How long commissions continue to be earned for a referred customer."},"durationInMonths":{"type":["integer","null"],"description":"When `duration` is repeating, the number of months over which commissions are earned."},"approvalRequired":{"type":["boolean","null"],"description":"`true` if commissions require manual approval before they can be paid out."},"percent":{"type":["number","null"],"description":"The commission percentage, used when `type` is `PERCENT`."},"hasMaxAmount":{"type":["boolean","null"],"description":"`true` if a maximum commission amount cap is configured."},"maxAmount":{"type":["integer","null"],"description":"The maximum commission amount cap in the currency's smallest denomination. `null` if no cap is set."},"maxAmountISO":{"type":["string","null"],"description":"The [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code for `maxAmount`. Must match the campaign `currencyISO` when provided."},"hasIntro":{"type":["boolean","null"],"description":"`true` if an introductory commission rate is configured."},"introType":{"type":["string","null"],"description":"How the introductory commission is calculated: `PERCENT` or `FIXED`."},"introPercent":{"type":["number","null"],"description":"The introductory commission percentage, used when `introType` is `PERCENT`."},"introAmount":{"type":["integer","null"],"description":"The introductory commission amount in the currency's smallest denomination, used when `introType` is `FIXED`."},"introAmountISO":{"type":["string","null"],"description":"The [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code for `introAmount`. Must match the campaign `currencyISO` when provided."},"introDuration":{"type":["string","null"],"description":"How long the introductory rate applies."},"introDurationInMonths":{"type":["integer","null"],"description":"When `introDuration` is repeating, the number of months the introductory rate applies."}},"additionalProperties":false},"RewardTaxValuation":{"type":"object","description":"Tax valuation settings for a reward. Only relevant when the program collects tax documentation.","properties":{"fairMarketValueUSD":{"type":["number","null"],"minimum":0,"description":"Manual fair-market value in USD (major units) used as the fallback when the reward value cannot be resolved automatically. `null` = no manual value."},"isTaxReportable":{"type":["boolean","null"],"description":"Whether the reward's value counts toward 1099 thresholds/totals. `null` = use the smart default for the reward's source."}}}}}} ``` *** ## Reward ```json {"openapi":"3.1.0","info":{"title":"GrowSurf REST API","version":"2.0.0"},"components":{"schemas":{"Reward":{"type":"object","description":"A single campaign reward (also known as a `CampaignReward`). This is different from a `ParticipantReward`, which is a reward earned by a participant.","required":["id","type","isUnlimited","metadata"],"properties":{"id":{"type":"string","readOnly":true,"description":"The unique identifier of the campaign reward. You can find this ID from *Program Editor > 1. Rewards* and clicking the reward."},"type":{"$ref":"#/components/schemas/RewardType","description":"The reward type."},"title":{"type":["string","null"],"description":"The reward title (internal only, never exposed to participants)."},"isVisible":{"type":"boolean","description":"Whether the reward is enabled. When `false`, the reward is disabled: it is no longer awarded, and it is hidden from participants, including those who already earned it. Set `true` for the reward to be visible and awardable."},"description":{"type":["string","null"],"description":"The reward description shown to the referrer."},"referralDescription":{"type":["string","null"],"description":"The reward description shown to the referred friend (only applicable for double-sided reward types)."},"referredRewardUpfront":{"type":"boolean","description":"Only applies to double-sided rewards. When `true`, the referred friend's reward is delivered upfront as a discount and no `ParticipantReward` is created for them when the referral triggers."},"isUnlimited":{"type":"boolean","description":"`true` if this reward can be earned by a single participant an unlimited number of times."},"limit":{"type":["integer","null"],"description":"The number of times a participant can earn this reward (overridden when `isUnlimited` is `true`). `-1` represents an unlimited reward in REST responses."},"conversionsRequired":{"type":["integer","null"],"description":"The number of referrals a participant must make to earn this reward."},"numberOfWinners":{"type":["integer","null"],"description":"The maximum number of winners. Only applies to `LEADERBOARD` rewards. When `limitDuration` is `PER_MONTH`, this many top referrers win each month; otherwise this many win in total."},"limitDuration":{"type":["string","null"],"enum":["IN_TOTAL","PER_MONTH","PER_YEAR",null],"description":"Whether the reward can be earned in total, on a monthly basis, or on a yearly basis."},"imageUrl":{"type":["string","null"],"description":"The reward image URL."},"couponCode":{"type":["string","null"],"description":"A static coupon code shown to the referrer in the reward-won email and webhook. Display text only; GrowSurf does not create or validate it in any billing system. If the program has a connected billing integration (Stripe, Chargebee, or Recurly) that issues a coupon for the referral, that issued code is shown instead."},"order":{"type":["integer","null"],"description":"If there are multiple rewards, the order in which the reward should be displayed. `null` by default until set within the Design step of the program editor."},"nextMilestonePrefix":{"type":["string","null"],"description":"Text displayed in front of a participant's referral count for UI purposes (e.g., \"You are only\"). Applicable for milestone rewards (when `type` is `MILESTONE`)."},"nextMilestoneSuffix":{"type":["string","null"],"description":"Text displayed after a participant's referral count for UI purposes (e.g., \"referrals away from receiving a nice reward!\"). Applicable for milestone rewards (when `type` is `MILESTONE`)."},"metadata":{"$ref":"#/components/schemas/Metadata","description":"The reward metadata."},"commissionStructure":{"oneOf":[{"$ref":"#/components/schemas/CommissionStructure"},{"type":"null"}],"description":"The reward commission structure. Present only for affiliate programs."},"referralCouponCode":{"type":["string","null"],"description":"A static coupon code shown to the referred friend in the reward-won email and webhook (double-sided rewards). Same caveats as `couponCode`: display text only, not created or validated in any billing system, and superseded by a connected billing integration's issued coupon when one exists."},"value":{"oneOf":[{"$ref":"#/components/schemas/RewardTaxValuation"},{"type":"null"}],"description":"Tax valuation for the reward (the referrer's side of a double-sided reward). `null` when no valuation is set."},"referredValue":{"oneOf":[{"$ref":"#/components/schemas/RewardTaxValuation"},{"type":"null"}],"description":"Tax valuation for the referred friend's side of a double-sided reward. `null` when no valuation is set."}}},"RewardType":{"type":"string","enum":["SINGLE_SIDED","DOUBLE_SIDED","MILESTONE","LEADERBOARD","AFFILIATE"]},"Metadata":{"type":"object","description":"Shallow custom metadata object.","additionalProperties":true},"CommissionStructure":{"type":"object","description":"The commission configuration for an affiliate reward. Present only for affiliate programs.","properties":{"amount":{"type":["integer","null"],"description":"Fixed commission amount in the currency's smallest denomination, used when `type` is `FIXED`. `null` for percentage-based commissions."},"amountISO":{"type":["string","null"],"description":"ISO 4217 currency code for the fixed `amount`. Defaults to the program's currency when omitted. Must match the campaign `currencyISO` when provided. `null` for percentage-based commissions."},"event":{"type":["string","null"],"description":"The event that generates a commission (e.g., `SALE`)."},"type":{"type":["string","null"],"enum":["PERCENT","FIXED",null],"description":"How the commission is calculated: `PERCENT` (a percentage of the sale) or `FIXED` (a fixed `amount`)."},"minPaidReferrals":{"type":["integer","null"],"description":"The minimum number of paid referrals required before commissions are earned."},"holdDuration":{"type":["integer","null"],"description":"Number of days a commission is held before it can be paid out."},"duration":{"type":["string","null"],"description":"How long commissions continue to be earned for a referred customer."},"durationInMonths":{"type":["integer","null"],"description":"When `duration` is repeating, the number of months over which commissions are earned."},"approvalRequired":{"type":["boolean","null"],"description":"`true` if commissions require manual approval before they can be paid out."},"percent":{"type":["number","null"],"description":"The commission percentage, used when `type` is `PERCENT`."},"hasMaxAmount":{"type":["boolean","null"],"description":"`true` if a maximum commission amount cap is configured."},"maxAmount":{"type":["integer","null"],"description":"The maximum commission amount cap in the currency's smallest denomination. `null` if no cap is set."},"maxAmountISO":{"type":["string","null"],"description":"The [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code for `maxAmount`. Must match the campaign `currencyISO` when provided."},"hasIntro":{"type":["boolean","null"],"description":"`true` if an introductory commission rate is configured."},"introType":{"type":["string","null"],"description":"How the introductory commission is calculated: `PERCENT` or `FIXED`."},"introPercent":{"type":["number","null"],"description":"The introductory commission percentage, used when `introType` is `PERCENT`."},"introAmount":{"type":["integer","null"],"description":"The introductory commission amount in the currency's smallest denomination, used when `introType` is `FIXED`."},"introAmountISO":{"type":["string","null"],"description":"The [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code for `introAmount`. Must match the campaign `currencyISO` when provided."},"introDuration":{"type":["string","null"],"description":"How long the introductory rate applies."},"introDurationInMonths":{"type":["integer","null"],"description":"When `introDuration` is repeating, the number of months the introductory rate applies."}},"additionalProperties":false},"RewardTaxValuation":{"type":"object","description":"Tax valuation settings for a reward. Only relevant when the program collects tax documentation.","properties":{"fairMarketValueUSD":{"type":["number","null"],"minimum":0,"description":"Manual fair-market value in USD (major units) used as the fallback when the reward value cannot be resolved automatically. `null` = no manual value."},"isTaxReportable":{"type":["boolean","null"],"description":"Whether the reward's value counts toward 1099 thresholds/totals. `null` = use the smart default for the reward's source."}}}}}} ``` *** ## Webhook ```json {"openapi":"3.1.0","info":{"title":"GrowSurf REST API","version":"2.0.0"},"components":{"schemas":{"Webhook":{"type":"object","description":"A program webhook's configuration (payload URL, subscribed events, enabled state) plus read-only delivery-health fields.","required":["id","events","isEnabled","autoDisabledDueToFailures","failureCount"],"properties":{"id":{"type":"string","readOnly":true,"description":"The webhook id (`primary` for the program's primary webhook)."},"payloadUrl":{"type":"string","nullable":true,"description":"The URL that receives webhook deliveries."},"events":{"description":"Webhook events this endpoint is subscribed to.","type":"array","items":{"$ref":"#/components/schemas/WebhookEvent"}},"isEnabled":{"description":"Whether deliveries to this webhook are enabled.","type":"boolean"},"autoDisabledDueToFailures":{"type":"boolean","readOnly":true,"description":"Read-only. Whether GrowSurf auto-disabled this webhook after repeated delivery failures."},"failureCount":{"type":"integer","readOnly":true,"description":"Read-only. Consecutive delivery failures."},"lastFailureAt":{"type":"integer","format":"int64","nullable":true,"readOnly":true,"description":"Read-only. When the last delivery failure occurred, as a Unix timestamp in milliseconds."}}},"WebhookEvent":{"type":"string","description":"A webhook event name (the events GrowSurf delivers to subscribed webhooks).","enum":["PARTICIPANT_REACHED_A_GOAL","NEW_PARTICIPANT_ADDED","CAMPAIGN_ENDED","PARTICIPANT_FRAUD_STATUS_UPDATED","NEW_COMMISSION_ADDED","COMMISSION_ADJUSTED","NEW_PAYOUT_ISSUED"]}}}} ``` *** ## Participant ```json {"openapi":"3.1.0","info":{"title":"GrowSurf REST API","version":"2.0.0"},"components":{"schemas":{"Participant":{"type":"object","description":"Detailed information about a program participant.","required":["id","referralCount","monthlyReferralCount","rank","monthlyRank","shareUrl","rewards","email"],"properties":{"id":{"type":"string","readOnly":true,"description":"The unique identifier of the participant."},"firstName":{"type":["string","null"],"description":"The first name of the participant."},"lastName":{"type":["string","null"],"description":"The last name of the participant."},"email":{"type":"string","description":"The email of the participant."},"paypalEmailAddress":{"type":"string","format":"email","description":"The PayPal email address on file for the participant, used for affiliate or PayPal reward payouts."},"referralCount":{"type":"integer","readOnly":true,"description":"The total number of referrals made by the participant."},"monthlyReferralCount":{"type":"integer","readOnly":true,"description":"The total number of referrals made this month by the participant (resets at the end of the month)."},"prevMonthlyReferralCount":{"type":"integer","readOnly":true,"description":"The total number of referrals made the previous month by the participant."},"rank":{"type":"integer","readOnly":true,"description":"The rank of the participant."},"monthlyRank":{"type":"integer","readOnly":true,"description":"The monthly rank of the participant. This rank resets to 0 at the end of each month."},"prevMonthlyRank":{"type":"integer","readOnly":true,"description":"The previous monthly rank of the participant. Not returned if the participant did not exist in your program during the previous month."},"shareUrl":{"type":"string","readOnly":true,"description":"The unique share URL of the participant."},"createdAt":{"type":"integer","format":"int64","readOnly":true,"description":"The date the participant was added to the program (UTC milliseconds)."},"referralSource":{"$ref":"#/components/schemas/ReferralSource","readOnly":true,"description":"The source of how the participant joined the program."},"referralStatus":{"$ref":"#/components/schemas/ReferralStatus","description":"If the participant was referred, the referrer's status in receiving the referral credit. Only applicable if the participant was referred into the program."},"referredBy":{"type":"string","description":"The ID of the referrer. Only applicable if the participant was referred into the program."},"fraudRiskLevel":{"$ref":"#/components/schemas/FraudRiskLevel","readOnly":true,"description":"A value that represents the integrity of the participant."},"fraudReasonCode":{"type":"string","readOnly":true,"description":"The reason for the participant's `fraudRiskLevel`:\n\n- `UNIQUE_IDENTITY` — They have a unique identity (no other participant has the same identity).\n- `DUPLICATE_EMAIL` — Their email is not unique and is identical to another participant's email (e.g., gavin@hooli.com = gavin+1@hooli.com).\n- `DUPLICATE_IDENTITY` — Their identity (fingerprint or mobile instance ID) is not unique and matches another participant's.\n- `DUPLICATE_IDENTITY_EXCESSIVE` — Within a small window of time, they had an excessive number of referred participants who also shared the same IP address.\n- `EMAIL_FRAUD` — Their email was found to match another participant's when updated in a connected billing or payment integration.\n- `SIMILAR_EMAIL` — Their browser fingerprint matches another participant's and their email looks suspiciously similar.\n- `SIMILAR_FIRST_NAME` — Their browser fingerprint matches another participant's and their first name looks suspiciously similar.\n- `SIMILAR_LAST_NAME` — Their browser fingerprint matches another participant's and their last name looks suspiciously similar.\n- `REFERRAL_EMAIL_PATTERN` — (Status for a referred person) Their email matched a similar pattern to their referrer's email.\n- `REFERRAL_CHAIN_FRAUD` — (Status for a referrer or referred person) Their characteristics matched a pattern with other referrals the referrer made, indicating a fraud ring.\n- `REFERRAL_VELOCITY_FRAUD` — (Status for a referrer or referred person) The referrer made an excessive number of referrals in a short period of time.\n- `DOMAIN_CLUSTERING_FRAUD` — (Status for a referrer or referred person) The referrer made an excessive number of referrals sharing the same suspicious domain in a short period of time.\n- `MANUAL_UPDATE` — They were manually marked as a fraudster from the GrowSurf dashboard.\n- `WHITELISTED` — They were allowed to join the program because one of their properties matched an allowed value.\n- `BLACKLIST_MATCH` — They were not allowed to join the program because one of their properties matched a blocked value.\n- `BLOCKED_IP` — They were not allowed to join the program because their IP address was recently blocked by antifraud IP throttling.\n- `REFERRER_HIGH_RISK` — They were not allowed to join the program because their referrer was a high-risk fraudster."},"isWinner":{"type":"boolean","readOnly":true,"description":"`true` if the participant has earned one or more rewards."},"shareCount":{"type":"object","readOnly":true,"additionalProperties":{"type":"integer"},"description":"An object containing counts of how many times the participant has shared their referral link, keyed by channel. Standard web channels include `email`, `facebook`, and `twitter`; SDK/native-share channels include `iosNativeShare` and `androidNativeShare`."},"impressionCount":{"type":"integer","readOnly":true,"description":"The total number of impressions the participant has made."},"uniqueImpressionCount":{"type":"integer","readOnly":true,"description":"The total number of unique impressions the participant has made."},"inviteCount":{"type":"integer","readOnly":true,"description":"The total number of invites the participant has sent."},"referrals":{"type":"array","readOnly":true,"items":{"type":"string"},"description":"A list of `Participant` IDs who were successfully referred by the participant. Limited to the 100 most recently referred friends."},"monthlyReferrals":{"type":"array","readOnly":true,"items":{"type":"string"},"description":"A list of `Participant` IDs successfully referred by the participant this month (resets at the end of the month). Limited to the 100 most recent."},"referrer":{"readOnly":true,"oneOf":[{"$ref":"#/components/schemas/ParticipantReferrer"},{"type":"null"}],"description":"An object containing the participant's referrer information. Only applicable if the participant was referred into the program."},"ipAddress":{"type":["string","null"],"description":"The IP address associated with the participant, used for anti-fraud matching."},"fingerprint":{"type":["string","null"],"description":"The browser fingerprint associated with the participant, used for anti-fraud matching."},"mobileInstanceId":{"type":["string","null"],"description":"App-install scoped mobile identifier used for anti-fraud matching when provided by native mobile apps. The official mobile SDKs generate this as a lowercase UUID. Not stored when strict GDPR/CCPA mode is enabled."},"metadata":{"$ref":"#/components/schemas/Metadata","description":"An object containing any custom key-value data, useful for saving additional data for the participant (e.g., `company`, `companySize`). Metadata is never used by GrowSurf and usage is optional. Metadata is returned only in REST API calls, and never in JavaScript Web API calls. See [API Guidelines](https://docs.growsurf.com/developer-tools/rest-api/api-guidelines)."},"notes":{"type":["string","null"],"description":"Internal notes about the participant, added via the [GrowSurf Dashboard](https://growsurf.com/dashboard)."},"unsubscribed":{"type":"boolean","description":"`true` if the participant has unsubscribed from program emails."},"rewards":{"type":"array","readOnly":true,"items":{"$ref":"#/components/schemas/ParticipantReward"},"description":"A list of the rewards the participant has earned."},"vanityKeys":{"type":"array","items":{"type":"string"},"description":"The list of vanity keys that the participant has."},"unreadCommissionsCount":{"type":"integer","readOnly":true,"description":"Affiliate programs only. The number of commissions the participant has not yet viewed."},"unreadPayoutsCount":{"type":"integer","readOnly":true,"description":"Affiliate programs only. The number of payouts the participant has not yet viewed."},"isNew":{"type":"boolean","readOnly":true,"description":"Whether this participant was newly created by the request. Returned by participant creation calls; `false` when the participant already existed."},"allMatchingFraudsters":{"type":"array","readOnly":true,"items":{"type":"object","additionalProperties":true},"description":"A list of other participants flagged as matching this participant during anti-fraud checks."},"payoutSettings":{"type":"object","readOnly":true,"description":"Payout-related actions the participant must complete before a payout can be released (e.g. confirming a PayPal email or submitting a W-9/W-8 tax form). Always present; the requiredActions array is empty when no action is required.","properties":{"requiredActions":{"description":"Actions the participant must complete before payouts can be sent.","type":"array","readOnly":true,"items":{"type":"string","enum":["PAYPAL_EMAIL","TAX_INFO"]}}}}}},"ReferralSource":{"type":"string","enum":["DIRECT","PARTICIPANT"]},"ReferralStatus":{"type":"string","enum":["CREDIT_PENDING","CREDIT_AWARDED","CREDIT_EXPIRED","INVITE_SENT"]},"FraudRiskLevel":{"type":"string","enum":["LOW","MEDIUM","HIGH"]},"ParticipantReferrer":{"type":"object","description":"Summary information about a participant's referrer, returned within the `referrer` field of a `Participant`.","properties":{"id":{"type":"string","description":"The unique identifier of the referrer."},"firstName":{"type":["string","null"],"description":"The first name of the referrer."},"lastName":{"type":["string","null"],"description":"The last name of the referrer."},"email":{"type":"string","description":"The email of the referrer."},"referralCount":{"type":"integer","description":"The total number of referrals made by the referrer."},"monthlyReferralCount":{"type":"integer","description":"The total number of referrals made this month by the referrer (resets at the end of the month)."},"prevMonthlyReferralCount":{"type":"integer","description":"The total number of referrals made the previous month by the referrer."},"rank":{"type":"integer","description":"The rank of the referrer."},"monthlyRank":{"type":"integer","description":"The monthly rank of the referrer. This rank resets to 0 at the end of each month."},"prevMonthlyRank":{"type":"integer","description":"The previous monthly rank of the referrer."},"shareUrl":{"type":"string","description":"The unique share URL of the referrer."},"createdAt":{"type":"integer","format":"int64","description":"The date the referrer was added to the program (UTC milliseconds)."},"referralSource":{"$ref":"#/components/schemas/ReferralSource","description":"The source of how the referrer joined the program."},"referralStatus":{"$ref":"#/components/schemas/ReferralStatus","description":"If the referrer was themselves referred, their referrer's status in receiving the referral credit."},"fraudRiskLevel":{"$ref":"#/components/schemas/FraudRiskLevel","description":"A value that represents the integrity of the referrer."},"fraudReasonCode":{"type":"string","description":"The reason for the referrer's `fraudRiskLevel`. See `Participant.fraudReasonCode` for the list of possible values."},"isWinner":{"type":"boolean","description":"`true` if the referrer has earned one or more rewards."},"shareCount":{"type":"object","additionalProperties":{"type":"integer"},"description":"An object containing counts of how many times the referrer has shared their referral link, keyed by channel."},"impressionCount":{"type":"integer","description":"The total number of impressions the referrer has made."},"uniqueImpressionCount":{"type":"integer","description":"The total number of unique impressions the referrer has made."},"inviteCount":{"type":"integer","description":"The total number of invites the referrer has sent."},"referrals":{"type":"array","items":{"type":"string"},"description":"A list of `Participant` IDs who were successfully referred by the referrer. Limited to the 100 most recent."},"monthlyReferrals":{"type":"array","items":{"type":"string"},"description":"A list of `Participant` IDs successfully referred by the referrer this month (resets at the end of the month). Limited to the 100 most recent."},"ipAddress":{"type":["string","null"],"description":"The IP address associated with the referrer, used for anti-fraud matching."},"fingerprint":{"type":["string","null"],"description":"The browser fingerprint associated with the referrer, used for anti-fraud matching."},"metadata":{"$ref":"#/components/schemas/Metadata","description":"An object containing any custom key-value data for the referrer."},"unsubscribed":{"type":"boolean","description":"`true` if the referrer has unsubscribed from program emails."}}},"Metadata":{"type":"object","description":"Shallow custom metadata object.","additionalProperties":true},"ParticipantReward":{"type":"object","description":"A reward that a participant has earned. This is different from a program `Reward` Object and contains information pertinent only to the participant that earned the reward.","required":["id","rewardId","status"],"properties":{"id":{"type":"string","readOnly":true,"description":"The unique identifier of the participant's reward. This is different for every new reward the participant earns."},"rewardId":{"type":"string","readOnly":true,"description":"The ID of the program `Reward` (`CampaignReward`) that this participant has earned."},"status":{"$ref":"#/components/schemas/RewardStatus","readOnly":true,"description":"The status of the participant's reward."},"unread":{"type":"boolean","readOnly":true,"description":"`true` if the participant has not yet seen the reward in a GrowSurf window."},"approved":{"type":"boolean","readOnly":true,"description":"`true` if the participant's reward has been approved."},"approvedAt":{"type":["integer","null"],"format":"int64","readOnly":true,"description":"The date and time the reward was approved for this participant (UTC milliseconds). `null` for unapproved rewards."},"fulfilledAt":{"type":["integer","null"],"format":"int64","readOnly":true,"description":"The date and time the reward was fulfilled for this participant (UTC milliseconds). `null` for unapproved or unfulfilled rewards."},"isReferrer":{"type":"boolean","readOnly":true,"description":"`true` if the participant earned the reward as the referrer; `false` if they earned it as the referred friend (only applicable for double-sided reward types)."},"isAvailable":{"type":"boolean","readOnly":true,"description":"`true` if the reward is available for the participant to claim or redeem."},"isFulfilled":{"type":"boolean","readOnly":true,"description":"`true` if the participant's reward has been fulfilled."},"referredId":{"type":"string","readOnly":true,"description":"The ID of the friend that was referred."},"referrerId":{"type":"string","readOnly":true,"description":"The ID of the participant that made the referral."},"commissionStructure":{"readOnly":true,"oneOf":[{"$ref":"#/components/schemas/CommissionStructure"},{"type":"null"}],"description":"The commission structure associated with this reward. Present only for affiliate programs."}}},"RewardStatus":{"type":"string","enum":["PENDING","FULFILLED"]},"CommissionStructure":{"type":"object","description":"The commission configuration for an affiliate reward. Present only for affiliate programs.","properties":{"amount":{"type":["integer","null"],"description":"Fixed commission amount in the currency's smallest denomination, used when `type` is `FIXED`. `null` for percentage-based commissions."},"amountISO":{"type":["string","null"],"description":"ISO 4217 currency code for the fixed `amount`. Defaults to the program's currency when omitted. Must match the campaign `currencyISO` when provided. `null` for percentage-based commissions."},"event":{"type":["string","null"],"description":"The event that generates a commission (e.g., `SALE`)."},"type":{"type":["string","null"],"enum":["PERCENT","FIXED",null],"description":"How the commission is calculated: `PERCENT` (a percentage of the sale) or `FIXED` (a fixed `amount`)."},"minPaidReferrals":{"type":["integer","null"],"description":"The minimum number of paid referrals required before commissions are earned."},"holdDuration":{"type":["integer","null"],"description":"Number of days a commission is held before it can be paid out."},"duration":{"type":["string","null"],"description":"How long commissions continue to be earned for a referred customer."},"durationInMonths":{"type":["integer","null"],"description":"When `duration` is repeating, the number of months over which commissions are earned."},"approvalRequired":{"type":["boolean","null"],"description":"`true` if commissions require manual approval before they can be paid out."},"percent":{"type":["number","null"],"description":"The commission percentage, used when `type` is `PERCENT`."},"hasMaxAmount":{"type":["boolean","null"],"description":"`true` if a maximum commission amount cap is configured."},"maxAmount":{"type":["integer","null"],"description":"The maximum commission amount cap in the currency's smallest denomination. `null` if no cap is set."},"maxAmountISO":{"type":["string","null"],"description":"The [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code for `maxAmount`. Must match the campaign `currencyISO` when provided."},"hasIntro":{"type":["boolean","null"],"description":"`true` if an introductory commission rate is configured."},"introType":{"type":["string","null"],"description":"How the introductory commission is calculated: `PERCENT` or `FIXED`."},"introPercent":{"type":["number","null"],"description":"The introductory commission percentage, used when `introType` is `PERCENT`."},"introAmount":{"type":["integer","null"],"description":"The introductory commission amount in the currency's smallest denomination, used when `introType` is `FIXED`."},"introAmountISO":{"type":["string","null"],"description":"The [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code for `introAmount`. Must match the campaign `currencyISO` when provided."},"introDuration":{"type":["string","null"],"description":"How long the introductory rate applies."},"introDurationInMonths":{"type":["integer","null"],"description":"When `introDuration` is repeating, the number of months the introductory rate applies."}},"additionalProperties":false}}}} ``` *** ## ParticipantCommission ```json {"openapi":"3.1.0","info":{"title":"GrowSurf REST API","version":"2.0.0"},"components":{"schemas":{"ParticipantCommission":{"type":"object","description":"**Affiliate programs only.** A commission generated for a (referrer) participant in an affiliate program.","required":["id","referrerId","referredId","amount","saleAmount","currencyISO","status","createdAt"],"properties":{"id":{"type":"string","readOnly":true,"description":"The unique identifier of the participant commission."},"referrerId":{"type":"string","readOnly":true,"description":"The participant ID of the referrer who earned the commission."},"referredId":{"type":"string","readOnly":true,"description":"The participant ID of the referred friend (the conversion that triggered the commission)."},"amount":{"type":["integer","null"],"readOnly":true,"description":"Commission amount (what the affiliate earned) in the currency's smallest denomination (e.g., `100` cents equals $1.00 USD, and `100` equals ¥100 for a zero-decimal currency). Always non-negative when present; `null` if it could not be computed."},"saleAmount":{"type":["integer","null"],"readOnly":true,"description":"The sale amount from the transaction the referral paid, in the currency's smallest denomination. Always non-negative when present; `null` for commissions whose provider does not report a sale amount."},"currencyISO":{"type":"string","readOnly":true,"description":"The [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code of the commission (e.g., `USD`, `GBP`)."},"status":{"$ref":"#/components/schemas/CommissionStatus","readOnly":true,"description":"Current lifecycle state of the commission."},"approvedAt":{"type":["integer","null"],"format":"int64","readOnly":true,"description":"UTC timestamp (in milliseconds) when the commission was approved. `null` until the commission transitions to `APPROVED`."},"paidAt":{"type":["integer","null"],"format":"int64","readOnly":true,"description":"UTC timestamp (in milliseconds) when the commission was sent in a payout. `null` until the commission transitions to `PAID`."},"reversedAt":{"type":["integer","null"],"format":"int64","readOnly":true,"description":"UTC timestamp (in milliseconds) when the commission was reversed (for example, due to a refund or chargeback). `null` unless the commission transitions to `REVERSED`."},"holdDuration":{"type":["integer","null"],"readOnly":true,"description":"Number of days the commission must age before it can be processed for payout. Defaults to `0` (no hold)."},"payoutQueuedAt":{"type":["integer","null"],"format":"int64","readOnly":true,"description":"UTC timestamp (in milliseconds) when the commission was queued for payout. `null` if it has not been scheduled."},"provider":{"type":["string","null"],"readOnly":true,"description":"Origin of the commission event. For example, `stripe` or `api`."},"createdAt":{"type":"integer","format":"int64","readOnly":true,"description":"UTC timestamp (in milliseconds) when the commission record was created."},"amountInCampaignCurrency":{"type":["integer","null"],"readOnly":true,"description":"Commission amount converted to the program's currency, in the currency's smallest denomination. Always non-negative. `null` if the commission is still pending FX conversion."},"saleAmountInCampaignCurrency":{"type":["integer","null"],"readOnly":true,"description":"The sale amount converted to the program's currency, in the currency's smallest denomination. Always non-negative. `null` if the commission is still pending FX conversion."},"exchangeRate":{"type":["number","null"],"readOnly":true,"description":"The currency exchange rate used for conversion. `null` if the commission is still pending FX conversion."},"campaignCurrencyISO":{"type":["string","null"],"readOnly":true,"description":"The [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code of the program used in currency conversion (e.g., `USD`, `GBP`). `null` if the commission is still pending FX conversion."},"exchangeRateAt":{"type":["integer","null"],"format":"int64","readOnly":true,"description":"UTC timestamp (in milliseconds) when the currency exchange rate was received. `null` if the commission is still pending FX conversion."},"fxError":{"type":["string","null"],"readOnly":true,"description":"If there was an error with FX conversion, the specific details. `null` if conversion was successful."}}},"CommissionStatus":{"type":"string","enum":["PENDING","APPROVED","PAID","REVERSED","DELETED"]}}}} ``` {% hint style="success" %} **Currency Exchange Note:** If the referral makes a payment in a currency different from your program's currency (`Campaign.currencyISO`), the following foreign currency exchange-related fields can be used to normalize commission data for accounting/reporting purposes: `amountInCampaignCurrency`, `saleAmountInCampaignCurrency`, `exchangeRate`, `campaignCurrencyISO`, and `exchangeRateAt`.\ \ For example, if your campaign's currency is set to `USD` but a referral makes a payment in `CAD`, the generated commission will have `amountInCampaignCurrency` as the `USD` equivalent of the `CAD` payment. {% endhint %} *** ## ParticipantPayout ```json {"openapi":"3.1.0","info":{"title":"GrowSurf REST API","version":"2.0.0"},"components":{"schemas":{"ParticipantPayout":{"type":"object","description":"**Affiliate programs only.** A payout generated for a participant in an affiliate program. All payouts start with a status of `UPCOMING`, which represents an aggregation of the participant's `ParticipantCommission` amounts, and is adjusted in real time as commissions change.","required":["id","participantId","commissionIds","amount","currencyISO","status","createdAt"],"properties":{"id":{"type":"string","readOnly":true,"description":"The unique identifier of the participant payout."},"participantId":{"type":"string","readOnly":true,"description":"The participant ID of the referrer who earned the payout."},"commissionIds":{"type":"array","readOnly":true,"items":{"type":"string"},"description":"The IDs of the associated `ParticipantCommission`s."},"amount":{"type":"integer","readOnly":true,"description":"Payout amount in the currency's smallest denomination (e.g., `100` cents equals $1.00 USD, and `100` equals ¥100 for a zero-decimal currency). Always non-negative."},"currencyISO":{"type":"string","readOnly":true,"description":"The [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code of the payout (e.g., `USD`, `GBP`)."},"status":{"$ref":"#/components/schemas/PayoutStatus","readOnly":true,"description":"Current lifecycle state of the payout."},"createdAt":{"type":"integer","format":"int64","readOnly":true,"description":"UTC timestamp (in milliseconds) when the payout record was created."},"queuedAt":{"type":["integer","null"],"format":"int64","readOnly":true,"description":"UTC timestamp (in milliseconds) when the payout was queued for processing (status `QUEUED`). `null` until the payout is queued."},"issuedAt":{"type":["integer","null"],"format":"int64","readOnly":true,"description":"UTC timestamp (in milliseconds) when the payout was issued. `null` if the payout was not successfully issued."},"failedAt":{"type":["integer","null"],"format":"int64","readOnly":true,"description":"UTC timestamp (in milliseconds) when the payout failed to be issued. `null` if the payout did not fail to be issued."},"provider":{"type":["string","null"],"readOnly":true,"description":"The payment provider used to issue the payout (e.g., `paypal`). `null` for payouts with a status of `UPCOMING`."},"amountInCampaignCurrency":{"type":["integer","null"],"readOnly":true,"description":"Payout amount converted to the program's currency, in the currency's smallest denomination. Always non-negative. `null` if the payout status is `UPCOMING` or if it is still pending FX conversion."},"campaignCurrencyISO":{"type":["string","null"],"readOnly":true,"description":"The [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code of the program used in currency conversion (e.g., `USD`, `GBP`). `null` if the payout status is `UPCOMING` or if it is still pending FX conversion."},"exchangeRateAt":{"type":["integer","null"],"format":"int64","readOnly":true,"description":"UTC timestamp (in milliseconds) when the currency exchange rate was received. `null` if the payout status is `UPCOMING` or if it is still pending FX conversion."},"exchangeRate":{"type":["number","null"],"readOnly":true,"description":"The currency exchange rate used for conversion. `null` if the payout status is `UPCOMING` or if it is still pending FX conversion."},"fxError":{"type":["string","null"],"readOnly":true,"description":"If there was an error with FX conversion, the specific details. `null` if the payout status is `UPCOMING` or if the FX conversion was successful."}}},"PayoutStatus":{"type":"string","enum":["UPCOMING","QUEUED","ISSUED","FAILED"]}}}} ``` # API Reference This reference documents the GrowSurf REST API, including all available public methods and examples of each. {% hint style="info" %} * **Using AI?** If you're using an AI tool such as Cursor, Codex, Claude Code, or Antigravity to help you implement GrowSurf, we recommend utilizing our [MCP server](https://docs.growsurf.com/build-with-ai). * **Using TypeScript, Python, PHP, Ruby, or Java?** Use an official GrowSurf API library. [Learn more](https://docs.growsurf.com/developer-tools/rest-api/api-libraries). * **Building a native iOS or Android app?** Use the [iOS SDK](/developer-tools/ios-sdk) or [Android SDK](/developer-tools/android-sdk) for mobile attribution, participant creation, sharing, and referral portal data. Use this REST API from your backend for secure server-side actions. {% endhint %} {% hint style="warning" %} Do not embed your REST API key in native mobile apps. The iOS and Android SDKs use a separate Mobile SDK API and public Mobile SDK key. This REST API remains the right place for backend-only operations, including server-verified purchase or subscription referral qualification. {% endhint %} ## INDEX ↓ | Section | Endpoints | | --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [Accounts](https://docs.growsurf.com/developer-tools/rest-api/api-reference#accounts) | [Create account](https://docs.growsurf.com/developer-tools/rest-api/api-reference#post-accounts) | | [Teams](https://docs.growsurf.com/developer-tools/rest-api/api-reference#teams) | [Retrieve team](https://docs.growsurf.com/developer-tools/rest-api/api-reference#get-team) · [Update team](https://docs.growsurf.com/developer-tools/rest-api/api-reference#patch-team) · [Request team verification](https://docs.growsurf.com/developer-tools/rest-api/api-reference#post-team-verification-request) · [Resend team owner verification email](https://docs.growsurf.com/developer-tools/rest-api/api-reference#post-team-owner-verification-email) · [Rotate API key](https://docs.growsurf.com/developer-tools/rest-api/api-reference#post-api-key-rotate) | | [Campaigns](https://docs.growsurf.com/developer-tools/rest-api/api-reference#campaigns) | [List campaigns](https://docs.growsurf.com/developer-tools/rest-api/api-reference#get-campaigns) · [Retrieve a campaign](https://docs.growsurf.com/developer-tools/rest-api/api-reference#get-campaign-id) · [Create a campaign](https://docs.growsurf.com/developer-tools/rest-api/api-reference#post-campaigns) · [Update a campaign](https://docs.growsurf.com/developer-tools/rest-api/api-reference#patch-campaign-id) · [Clone a campaign](https://docs.growsurf.com/developer-tools/rest-api/api-reference#post-campaign-id-clone) | | [Campaign Rewards](https://docs.growsurf.com/developer-tools/rest-api/api-reference#campaign-rewards) | [List campaign rewards](https://docs.growsurf.com/developer-tools/rest-api/api-reference#get-campaign-id-reward-configs) · [Create a campaign reward](https://docs.growsurf.com/developer-tools/rest-api/api-reference#post-campaign-id-reward-configs) · [Update a campaign reward](https://docs.growsurf.com/developer-tools/rest-api/api-reference#patch-campaign-id-reward-configs-campaignrewardid) · [Delete a campaign reward](https://docs.growsurf.com/developer-tools/rest-api/api-reference#delete-campaign-id-reward-configs-campaignrewardid) | | [Campaign Design](https://docs.growsurf.com/developer-tools/rest-api/api-reference#campaign-design) | [Retrieve campaign design](https://docs.growsurf.com/developer-tools/rest-api/api-reference#get-campaign-id-design) · [Update campaign design](https://docs.growsurf.com/developer-tools/rest-api/api-reference#patch-campaign-id-design) | | [Campaign Emails](https://docs.growsurf.com/developer-tools/rest-api/api-reference#campaign-emails) | [Retrieve campaign emails](https://docs.growsurf.com/developer-tools/rest-api/api-reference#get-campaign-id-emails) · [Update campaign emails](https://docs.growsurf.com/developer-tools/rest-api/api-reference#patch-campaign-id-emails) | | [Campaign Options](https://docs.growsurf.com/developer-tools/rest-api/api-reference#campaign-options) | [Retrieve campaign options](https://docs.growsurf.com/developer-tools/rest-api/api-reference#get-campaign-id-options) · [Update campaign options](https://docs.growsurf.com/developer-tools/rest-api/api-reference#patch-campaign-id-options) | | [Campaign Installation](https://docs.growsurf.com/developer-tools/rest-api/api-reference#campaign-installation) | [Retrieve campaign installation](https://docs.growsurf.com/developer-tools/rest-api/api-reference#get-campaign-id-installation) · [Update campaign installation](https://docs.growsurf.com/developer-tools/rest-api/api-reference#patch-campaign-id-installation) | | [Campaign Webhooks](https://docs.growsurf.com/developer-tools/rest-api/api-reference#campaign-webhooks) | [List webhooks](https://docs.growsurf.com/developer-tools/rest-api/api-reference#get-campaign-id-webhooks) · [Create webhook](https://docs.growsurf.com/developer-tools/rest-api/api-reference#post-campaign-id-webhooks) · [Update webhook](https://docs.growsurf.com/developer-tools/rest-api/api-reference#patch-campaign-id-webhooks-webhookid) · [Delete webhook](https://docs.growsurf.com/developer-tools/rest-api/api-reference#delete-campaign-id-webhooks-webhookid) · [Test webhook](https://docs.growsurf.com/developer-tools/rest-api/api-reference#post-campaign-id-webhooks-webhookid-test) | | [Participants](https://docs.growsurf.com/developer-tools/rest-api/api-reference#participants) | [List participants](https://docs.growsurf.com/developer-tools/rest-api/api-reference#get-campaign-id-participants) · [List leaderboard participants](https://docs.growsurf.com/developer-tools/rest-api/api-reference#get-campaign-id-leaderboard) · [Add participant](https://docs.growsurf.com/developer-tools/rest-api/api-reference#post-campaign-id-participant) · [Retrieve participant](https://docs.growsurf.com/developer-tools/rest-api/api-reference#get-campaign-id-participant-participantidoremail) · [Update participant](https://docs.growsurf.com/developer-tools/rest-api/api-reference#post-campaign-id-participant-participantidoremail) · [Delete participant](https://docs.growsurf.com/developer-tools/rest-api/api-reference#delete-campaign-id-participant-participantidoremail) · [Bulk delete participants](https://docs.growsurf.com/developer-tools/rest-api/api-reference#post-campaign-id-participants-bulk-delete) · [Trigger referral](https://docs.growsurf.com/developer-tools/rest-api/api-reference#post-campaign-id-participant-participantidoremail-ref) · [Cancel delayed referral trigger](https://docs.growsurf.com/developer-tools/rest-api/api-reference#delete-campaign-id-participant-participantidoremail-ref) · [Create mobile participant token](https://docs.growsurf.com/developer-tools/rest-api/api-reference#post-campaign-id-mobile-participant-token) · [Email participant](https://docs.growsurf.com/developer-tools/rest-api/api-reference#post-campaign-id-participant-participantidoremail-email) · [Retrieve participant analytics](https://docs.growsurf.com/developer-tools/rest-api/api-reference#get-campaign-id-participant-participantidoremail-analytics) · [List participant activity logs](https://docs.growsurf.com/developer-tools/rest-api/api-reference#get-campaign-id-participant-participantidoremail-activity-logs) | | [Participant Rewards](https://docs.growsurf.com/developer-tools/rest-api/api-reference#participant-rewards) | [List participant rewards](https://docs.growsurf.com/developer-tools/rest-api/api-reference#get-campaign-id-participant-participantidoremail-rewards) · [Approve participant reward](https://docs.growsurf.com/developer-tools/rest-api/api-reference#post-campaign-id-reward-rewardid-approve) · [Fulfill participant reward](https://docs.growsurf.com/developer-tools/rest-api/api-reference#post-campaign-id-reward-rewardid-fulfill) · [Delete participant reward](https://docs.growsurf.com/developer-tools/rest-api/api-reference#delete-campaign-id-reward-rewardid) | | [Referrals and Invites](https://docs.growsurf.com/developer-tools/rest-api/api-reference#referrals-and-invites) | [List referrals and invites](https://docs.growsurf.com/developer-tools/rest-api/api-reference#get-campaign-id-referrals) · [List participant referrals and invites](https://docs.growsurf.com/developer-tools/rest-api/api-reference#get-campaign-id-participant-participantidoremail-referrals) · [Send participant invites](https://docs.growsurf.com/developer-tools/rest-api/api-reference#post-campaign-id-participant-participantidoremail-invites) | | [Analytics](https://docs.growsurf.com/developer-tools/rest-api/api-reference#analytics) | [Retrieve campaign analytics](https://docs.growsurf.com/developer-tools/rest-api/api-reference#get-campaign-id-analytics) | | [Affiliate Programs](https://docs.growsurf.com/developer-tools/rest-api/api-reference#affiliate-programs) | [Record affiliate transaction](https://docs.growsurf.com/developer-tools/rest-api/api-reference#post-campaign-id-participant-participantidoremail-transaction) · [Refund or amend affiliate transaction](https://docs.growsurf.com/developer-tools/rest-api/api-reference#post-campaign-id-participant-participantidoremail-transaction-refund) · [List participant commissions](https://docs.growsurf.com/developer-tools/rest-api/api-reference#get-campaign-id-commissions) · [List commissions for a participant](https://docs.growsurf.com/developer-tools/rest-api/api-reference#get-campaign-id-participant-participantidoremail-commissions) · [Approve participant commission](https://docs.growsurf.com/developer-tools/rest-api/api-reference#post-campaign-id-commission-commissionid-approve) · [Delete participant commission](https://docs.growsurf.com/developer-tools/rest-api/api-reference#delete-campaign-id-commission-commissionid) · [List participant payouts](https://docs.growsurf.com/developer-tools/rest-api/api-reference#get-campaign-id-payouts) · [List payouts for a participant](https://docs.growsurf.com/developer-tools/rest-api/api-reference#get-campaign-id-participant-participantidoremail-payouts) | *** ## ACCOUNTS ↓ {% hint style="info" %} Create a GrowSurf account and receive its first API key. {% endhint %} ## Create account > Creates a new GrowSurf account. This is the only endpoint that does not require an API key. The response includes an API key for the new account, shown once in the response. The key is locked until the team owner's email address is verified: authenticated program and resource endpoints return a \`403\` with error code \`EMAIL\_NOT\_VERIFIED\_ERROR\` until then (resend the email via \`POST /team/owner/verification-email\`, then retry). A welcome email is sent to the address with the verification link and a set-password link for dashboard access. Accounts whose email is never verified are deleted automatically after 7 days. For security, the API key is rotated the first time the account owner signs in to the GrowSurf dashboard. Some actions (such as emailing participants) additionally require GrowSurf to verify the team first. By creating an account you agree, on behalf of the account holder, to GrowSurf's \[Terms of Service]\() and \[Privacy Policy]\(). ```json {"openapi":"3.1.0","info":{"title":"GrowSurf REST API","version":"2.0.0"},"tags":[{"name":"Accounts","description":"Create a GrowSurf account and its initial API key."}],"servers":[{"url":"https://api.growsurf.com/v2","description":"Production"}],"security":[],"paths":{"/accounts":{"post":{"tags":["Accounts"],"operationId":"createAccount","summary":"Create account","description":"Creates a new GrowSurf account. This is the only endpoint that does not require an API key. The response includes an API key for the new account, shown once in the response. The key is locked until the team owner's email address is verified: authenticated program and resource endpoints return a `403` with error code `EMAIL_NOT_VERIFIED_ERROR` until then (resend the email via `POST /team/owner/verification-email`, then retry). A welcome email is sent to the address with the verification link and a set-password link for dashboard access. Accounts whose email is never verified are deleted automatically after 7 days. For security, the API key is rotated the first time the account owner signs in to the GrowSurf dashboard. Some actions (such as emailing participants) additionally require GrowSurf to verify the team first. By creating an account you agree, on behalf of the account holder, to GrowSurf's [Terms of Service](https://growsurf.com/terms) and [Privacy Policy](https://growsurf.com/privacy).","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateAccountRequest"}}}},"responses":{"200":{"description":"Account created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateAccountResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"}}}}},"components":{"schemas":{"CreateAccountRequest":{"type":"object","required":["email"],"additionalProperties":false,"properties":{"email":{"type":"string","format":"email","description":"The email address for the new GrowSurf account. Personal emails and disposable email addresses are not accepted."},"firstName":{"description":"First name for the new account owner.","type":"string","maxLength":255},"lastName":{"description":"Last name for the new account owner.","type":"string","maxLength":255},"company":{"description":"Company name for the new account.","type":"string","maxLength":255}}},"CreateAccountResponse":{"type":"object","required":["email","apiKey","verificationStatus"],"properties":{"email":{"description":"Email address for the new account.","type":"string","format":"email"},"apiKey":{"type":"string","description":"An API key for the new account. Use it as the `Bearer` token on subsequent requests. It is shown once, locked (`403` `EMAIL_NOT_VERIFIED_ERROR`) until the account's email is verified, and rotated when the account owner first signs in to the GrowSurf dashboard."},"verificationStatus":{"type":"string","enum":["NOT_REQUESTED","REQUESTED","VERIFIED"],"description":"GrowSurf team verification state. `VERIFIED` is required before a program can send participant emails."}}},"Error":{"type":"object","properties":{"name":{"description":"Error name returned for the failed request.","type":"string"},"code":{"description":"Stable machine-readable error code.","type":"string"},"message":{"description":"Human-readable error message.","type":"string"},"errors":{"description":"Optional validation details for specific request fields.","type":"array","items":{"type":"object","additionalProperties":true}},"status":{"description":"HTTP status code for the error.","type":"integer"},"supportUrl":{"description":"Support URL related to the error, when available.","type":"string","format":"uri"},"policyName":{"description":"Rate-limit policy name for `429` errors, when available.","type":"string"},"level":{"description":"Error severity level, when available.","type":"string"},"timestamp":{"description":"When the error response was created.","type":"string","format":"date-time"}}}},"responses":{"BadRequest":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Conflict":{"description":"Conflicting duplicate request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Too many requests.","headers":{"GrowSurf-RateLimit-Second-Limit":{"description":"Number of API requests allowed per second policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Second-Remaining":{"description":"Number of API requests remaining in the second policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Second-Milliseconds":{"description":"Milliseconds until the second policy window resets.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Minute-Limit":{"description":"Number of API requests allowed per minute policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Minute-Remaining":{"description":"Number of API requests remaining in the minute policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Minute-Milliseconds":{"description":"Milliseconds until the minute policy window resets.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Hour-Limit":{"description":"Number of API requests allowed per hour policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Hour-Remaining":{"description":"Number of API requests remaining in the hour policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Hour-Milliseconds":{"description":"Milliseconds until the hour policy window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}} ``` *** ## TEAMS ↓ {% hint style="info" %} Read or update the team bound to your API key or OAuth connection, request GrowSurf verification, resend the team owner's verification email, or rotate the API key making a direct API request. New API keys and OAuth connections act on one team. API key rotation is not available through MCP. {% endhint %} ## Retrieve team > Retrieves the team bound to the API key or OAuth connection. \`verificationStatus\` is \`VERIFIED\` once GrowSurf has verified the team, which is required before a program can send participant emails. ```json {"openapi":"3.1.0","info":{"title":"GrowSurf REST API","version":"2.0.0"},"tags":[{"name":"Teams","description":"The team bound to an API key or OAuth connection."}],"servers":[{"url":"https://api.growsurf.com/v2","description":"Production"}],"security":[{"apiKeyAuth":[]}],"components":{"securitySchemes":{"apiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"API key","description":"GrowSurf REST API key supplied as `Authorization: Bearer `."}},"schemas":{"Team":{"type":"object","description":"The team bound to the API key or OAuth connection.","required":["name","verificationStatus","verificationRequestedAt"],"properties":{"name":{"description":"The team's display name.","type":"string"},"verificationStatus":{"type":"string","enum":["NOT_REQUESTED","REQUESTED","VERIFIED"],"readOnly":true,"description":"GrowSurf team verification state. `VERIFIED` is required before a program can send participant emails."},"verificationRequestedAt":{"type":"integer","format":"int64","nullable":true,"readOnly":true,"description":"When team verification was last requested, as a Unix timestamp in milliseconds."}}},"Error":{"type":"object","properties":{"name":{"description":"Error name returned for the failed request.","type":"string"},"code":{"description":"Stable machine-readable error code.","type":"string"},"message":{"description":"Human-readable error message.","type":"string"},"errors":{"description":"Optional validation details for specific request fields.","type":"array","items":{"type":"object","additionalProperties":true}},"status":{"description":"HTTP status code for the error.","type":"integer"},"supportUrl":{"description":"Support URL related to the error, when available.","type":"string","format":"uri"},"policyName":{"description":"Rate-limit policy name for `429` errors, when available.","type":"string"},"level":{"description":"Error severity level, when available.","type":"string"},"timestamp":{"description":"When the error response was created.","type":"string","format":"date-time"}}}},"responses":{"Forbidden":{"description":"The API key is missing, invalid, revoked, outside its scope, or not allowed to perform this action.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Too many requests.","headers":{"GrowSurf-RateLimit-Second-Limit":{"description":"Number of API requests allowed per second policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Second-Remaining":{"description":"Number of API requests remaining in the second policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Second-Milliseconds":{"description":"Milliseconds until the second policy window resets.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Minute-Limit":{"description":"Number of API requests allowed per minute policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Minute-Remaining":{"description":"Number of API requests remaining in the minute policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Minute-Milliseconds":{"description":"Milliseconds until the minute policy window resets.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Hour-Limit":{"description":"Number of API requests allowed per hour policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Hour-Remaining":{"description":"Number of API requests remaining in the hour policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Hour-Milliseconds":{"description":"Milliseconds until the hour policy window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/team":{"get":{"tags":["Teams"],"operationId":"getTeam","summary":"Retrieve team","description":"Retrieves the team bound to the API key or OAuth connection. `verificationStatus` is `VERIFIED` once GrowSurf has verified the team, which is required before a program can send participant emails.","responses":{"200":{"description":"Team returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Team"}}}},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}}}}} ``` ## Update team > Updates the name of the team bound to the API key or OAuth connection. Any other property is rejected with a \`400\`. Personal profiles, billing, and team ownership are not editable here. ```json {"openapi":"3.1.0","info":{"title":"GrowSurf REST API","version":"2.0.0"},"tags":[{"name":"Teams","description":"The team bound to an API key or OAuth connection."}],"servers":[{"url":"https://api.growsurf.com/v2","description":"Production"}],"security":[{"apiKeyAuth":[]}],"components":{"securitySchemes":{"apiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"API key","description":"GrowSurf REST API key supplied as `Authorization: Bearer `."}},"schemas":{"UpdateTeamRequest":{"type":"object","description":"The Team fields you can update. Any property not listed here is rejected with a `400`.","additionalProperties":false,"required":["name"],"properties":{"name":{"description":"The team's display name.","type":"string","minLength":1,"maxLength":255}}},"Team":{"type":"object","description":"The team bound to the API key or OAuth connection.","required":["name","verificationStatus","verificationRequestedAt"],"properties":{"name":{"description":"The team's display name.","type":"string"},"verificationStatus":{"type":"string","enum":["NOT_REQUESTED","REQUESTED","VERIFIED"],"readOnly":true,"description":"GrowSurf team verification state. `VERIFIED` is required before a program can send participant emails."},"verificationRequestedAt":{"type":"integer","format":"int64","nullable":true,"readOnly":true,"description":"When team verification was last requested, as a Unix timestamp in milliseconds."}}},"Error":{"type":"object","properties":{"name":{"description":"Error name returned for the failed request.","type":"string"},"code":{"description":"Stable machine-readable error code.","type":"string"},"message":{"description":"Human-readable error message.","type":"string"},"errors":{"description":"Optional validation details for specific request fields.","type":"array","items":{"type":"object","additionalProperties":true}},"status":{"description":"HTTP status code for the error.","type":"integer"},"supportUrl":{"description":"Support URL related to the error, when available.","type":"string","format":"uri"},"policyName":{"description":"Rate-limit policy name for `429` errors, when available.","type":"string"},"level":{"description":"Error severity level, when available.","type":"string"},"timestamp":{"description":"When the error response was created.","type":"string","format":"date-time"}}}},"responses":{"BadRequest":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The API key is missing, invalid, revoked, outside its scope, or not allowed to perform this action.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Too many requests.","headers":{"GrowSurf-RateLimit-Second-Limit":{"description":"Number of API requests allowed per second policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Second-Remaining":{"description":"Number of API requests remaining in the second policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Second-Milliseconds":{"description":"Milliseconds until the second policy window resets.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Minute-Limit":{"description":"Number of API requests allowed per minute policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Minute-Remaining":{"description":"Number of API requests remaining in the minute policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Minute-Milliseconds":{"description":"Milliseconds until the minute policy window resets.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Hour-Limit":{"description":"Number of API requests allowed per hour policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Hour-Remaining":{"description":"Number of API requests remaining in the hour policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Hour-Milliseconds":{"description":"Milliseconds until the hour policy window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/team":{"patch":{"tags":["Teams"],"operationId":"updateTeam","summary":"Update team","description":"Updates the name of the team bound to the API key or OAuth connection. Any other property is rejected with a `400`. Personal profiles, billing, and team ownership are not editable here.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateTeamRequest"}}}},"responses":{"200":{"description":"Updated team returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Team"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}}}}} ``` ## Request team verification > Requests GrowSurf to verify the bound team (required before a program can email its participants). Idempotent — calling it again while a request is pending does not create a duplicate. Returns the team with its updated \`verificationStatus\`. ```json {"openapi":"3.1.0","info":{"title":"GrowSurf REST API","version":"2.0.0"},"tags":[{"name":"Teams","description":"The team bound to an API key or OAuth connection."}],"servers":[{"url":"https://api.growsurf.com/v2","description":"Production"}],"security":[{"apiKeyAuth":[]}],"components":{"securitySchemes":{"apiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"API key","description":"GrowSurf REST API key supplied as `Authorization: Bearer `."}},"schemas":{"Team":{"type":"object","description":"The team bound to the API key or OAuth connection.","required":["name","verificationStatus","verificationRequestedAt"],"properties":{"name":{"description":"The team's display name.","type":"string"},"verificationStatus":{"type":"string","enum":["NOT_REQUESTED","REQUESTED","VERIFIED"],"readOnly":true,"description":"GrowSurf team verification state. `VERIFIED` is required before a program can send participant emails."},"verificationRequestedAt":{"type":"integer","format":"int64","nullable":true,"readOnly":true,"description":"When team verification was last requested, as a Unix timestamp in milliseconds."}}},"Error":{"type":"object","properties":{"name":{"description":"Error name returned for the failed request.","type":"string"},"code":{"description":"Stable machine-readable error code.","type":"string"},"message":{"description":"Human-readable error message.","type":"string"},"errors":{"description":"Optional validation details for specific request fields.","type":"array","items":{"type":"object","additionalProperties":true}},"status":{"description":"HTTP status code for the error.","type":"integer"},"supportUrl":{"description":"Support URL related to the error, when available.","type":"string","format":"uri"},"policyName":{"description":"Rate-limit policy name for `429` errors, when available.","type":"string"},"level":{"description":"Error severity level, when available.","type":"string"},"timestamp":{"description":"When the error response was created.","type":"string","format":"date-time"}}}},"responses":{"Forbidden":{"description":"The API key is missing, invalid, revoked, outside its scope, or not allowed to perform this action.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Too many requests.","headers":{"GrowSurf-RateLimit-Second-Limit":{"description":"Number of API requests allowed per second policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Second-Remaining":{"description":"Number of API requests remaining in the second policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Second-Milliseconds":{"description":"Milliseconds until the second policy window resets.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Minute-Limit":{"description":"Number of API requests allowed per minute policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Minute-Remaining":{"description":"Number of API requests remaining in the minute policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Minute-Milliseconds":{"description":"Milliseconds until the minute policy window resets.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Hour-Limit":{"description":"Number of API requests allowed per hour policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Hour-Remaining":{"description":"Number of API requests remaining in the hour policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Hour-Milliseconds":{"description":"Milliseconds until the hour policy window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/team/verification-request":{"post":{"tags":["Teams"],"operationId":"requestTeamVerification","summary":"Request team verification","description":"Requests GrowSurf to verify the bound team (required before a program can email its participants). Idempotent — calling it again while a request is pending does not create a duplicate. Returns the team with its updated `verificationStatus`.","responses":{"200":{"description":"Verification request recorded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Team"}}}},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}}}}} ``` ## Resend team owner verification email > Resends the email-verification message to the bound team's owner. The response never reveals the owner's email address. A \`200\` with \`status: SENT\` is returned only when an email was actually dispatched. Returns \`400\` if the email is already verified, and \`429\` if a verification email was sent too recently — wait a moment, then retry. ```json {"openapi":"3.1.0","info":{"title":"GrowSurf REST API","version":"2.0.0"},"tags":[{"name":"Teams","description":"The team bound to an API key or OAuth connection."}],"servers":[{"url":"https://api.growsurf.com/v2","description":"Production"}],"security":[{"apiKeyAuth":[]}],"components":{"securitySchemes":{"apiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"API key","description":"GrowSurf REST API key supplied as `Authorization: Bearer `."}},"schemas":{"VerificationEmailResponse":{"type":"object","required":["success","status"],"properties":{"success":{"description":"Whether the verification email request was accepted.","type":"boolean"},"status":{"description":"Status of the verification email request.","type":"string","enum":["SENT"]}}},"Error":{"type":"object","properties":{"name":{"description":"Error name returned for the failed request.","type":"string"},"code":{"description":"Stable machine-readable error code.","type":"string"},"message":{"description":"Human-readable error message.","type":"string"},"errors":{"description":"Optional validation details for specific request fields.","type":"array","items":{"type":"object","additionalProperties":true}},"status":{"description":"HTTP status code for the error.","type":"integer"},"supportUrl":{"description":"Support URL related to the error, when available.","type":"string","format":"uri"},"policyName":{"description":"Rate-limit policy name for `429` errors, when available.","type":"string"},"level":{"description":"Error severity level, when available.","type":"string"},"timestamp":{"description":"When the error response was created.","type":"string","format":"date-time"}}}},"responses":{"BadRequest":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The API key is missing, invalid, revoked, outside its scope, or not allowed to perform this action.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Too many requests.","headers":{"GrowSurf-RateLimit-Second-Limit":{"description":"Number of API requests allowed per second policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Second-Remaining":{"description":"Number of API requests remaining in the second policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Second-Milliseconds":{"description":"Milliseconds until the second policy window resets.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Minute-Limit":{"description":"Number of API requests allowed per minute policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Minute-Remaining":{"description":"Number of API requests remaining in the minute policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Minute-Milliseconds":{"description":"Milliseconds until the minute policy window resets.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Hour-Limit":{"description":"Number of API requests allowed per hour policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Hour-Remaining":{"description":"Number of API requests remaining in the hour policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Hour-Milliseconds":{"description":"Milliseconds until the hour policy window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/team/owner/verification-email":{"post":{"tags":["Teams"],"operationId":"resendTeamOwnerVerificationEmail","summary":"Resend team owner verification email","description":"Resends the email-verification message to the bound team's owner. The response never reveals the owner's email address. A `200` with `status: SENT` is returned only when an email was actually dispatched. Returns `400` if the email is already verified, and `429` if a verification email was sent too recently — wait a moment, then retry.","responses":{"200":{"description":"Verification email sent.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerificationEmailResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}}}}} ``` ## Rotate API key > Generates a new API key and makes the key used on this request stop working when rotation succeeds. Send a unique, random \`Idempotency-Key\`. If the response is interrupted, immediately retry with the original API key and the same \`Idempotency-Key\` to receive the same new key. Update every integration that used the old key. The team owner is notified by email whenever the key is rotated. GrowSurf SDKs generate the idempotency key automatically. This endpoint accepts an API key with \`api\_key:rotate\`. If this scope is unavailable, rotate the key in the authenticated dashboard instead. This operation is available only through the REST API or a GrowSurf API SDK, not through MCP. ```json {"openapi":"3.1.0","info":{"title":"GrowSurf REST API","version":"2.0.0"},"tags":[{"name":"Teams","description":"The team bound to an API key or OAuth connection."}],"servers":[{"url":"https://api.growsurf.com/v2","description":"Production"}],"security":[{"apiKeyAuth":[]}],"components":{"securitySchemes":{"apiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"API key","description":"GrowSurf REST API key supplied as `Authorization: Bearer `."}},"schemas":{"RotateApiKeyResponse":{"type":"object","required":["apiKey"],"properties":{"apiKey":{"type":"string","description":"The new API key. Store it now; the key used for rotation stops working immediately."}}},"Error":{"type":"object","properties":{"name":{"description":"Error name returned for the failed request.","type":"string"},"code":{"description":"Stable machine-readable error code.","type":"string"},"message":{"description":"Human-readable error message.","type":"string"},"errors":{"description":"Optional validation details for specific request fields.","type":"array","items":{"type":"object","additionalProperties":true}},"status":{"description":"HTTP status code for the error.","type":"integer"},"supportUrl":{"description":"Support URL related to the error, when available.","type":"string","format":"uri"},"policyName":{"description":"Rate-limit policy name for `429` errors, when available.","type":"string"},"level":{"description":"Error severity level, when available.","type":"string"},"timestamp":{"description":"When the error response was created.","type":"string","format":"date-time"}}}},"responses":{"BadRequest":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The API key is missing, invalid, revoked, outside its scope, or not allowed to perform this action.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Too many requests.","headers":{"GrowSurf-RateLimit-Second-Limit":{"description":"Number of API requests allowed per second policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Second-Remaining":{"description":"Number of API requests remaining in the second policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Second-Milliseconds":{"description":"Milliseconds until the second policy window resets.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Minute-Limit":{"description":"Number of API requests allowed per minute policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Minute-Remaining":{"description":"Number of API requests remaining in the minute policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Minute-Milliseconds":{"description":"Milliseconds until the minute policy window resets.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Hour-Limit":{"description":"Number of API requests allowed per hour policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Hour-Remaining":{"description":"Number of API requests remaining in the hour policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Hour-Milliseconds":{"description":"Milliseconds until the hour policy window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/api-key/rotate":{"post":{"tags":["Teams"],"operationId":"rotateApiKey","summary":"Rotate API key","description":"Generates a new API key and makes the key used on this request stop working when rotation succeeds. Send a unique, random `Idempotency-Key`. If the response is interrupted, immediately retry with the original API key and the same `Idempotency-Key` to receive the same new key. Update every integration that used the old key. The team owner is notified by email whenever the key is rotated. GrowSurf SDKs generate the idempotency key automatically. This endpoint accepts an API key with `api_key:rotate`. If this scope is unavailable, rotate the key in the authenticated dashboard instead. This operation is available only through the REST API or a GrowSurf API SDK, not through MCP.","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"A unique, random value for this rotation request. Reuse this value only when retrying the same request with the original API key.","schema":{"type":"string","minLength":8,"maxLength":255,"pattern":"^[A-Za-z0-9._:-]+$"}}],"responses":{"200":{"description":"The new API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RotateApiKeyResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}}}}} ``` *** ## CAMPAIGNS ↓ {% hint style="info" %} Create and update a program's identity and lifecycle here (`name`, `companyName`, `companyLogoImageUrl`, `status`, and — on create — `type`, `currencyISO`, and inline `rewards`). A program's currency (`currencyISO`) is chosen when the program is created (defaults to `USD`) and can't be changed afterward — sending it to the update endpoint returns a `400`. A program's design, emails, options, and installation are **not** accepted on create or update and will return a `400`. Edit those — and the program's rewards — through the [Campaign Rewards](https://docs.growsurf.com/developer-tools/rest-api/api-reference#campaign-rewards), [Campaign Design](https://docs.growsurf.com/developer-tools/rest-api/api-reference#campaign-design), [Campaign Emails](https://docs.growsurf.com/developer-tools/rest-api/api-reference#campaign-emails), [Campaign Options](https://docs.growsurf.com/developer-tools/rest-api/api-reference#campaign-options), and [Campaign Installation](https://docs.growsurf.com/developer-tools/rest-api/api-reference#campaign-installation) API endpoints. {% endhint %} ## List campaigns > Retrieves a list of your programs. Deleted programs are not returned. ```json {"openapi":"3.1.0","info":{"title":"GrowSurf REST API","version":"2.0.0"},"tags":[{"name":"Campaigns","description":"Program retrieval, listing, creation, updates, cloning, and configuration (design, emails, options, installation, and campaign rewards)."}],"servers":[{"url":"https://api.growsurf.com/v2","description":"Production"}],"security":[{"apiKeyAuth":[]}],"components":{"securitySchemes":{"apiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"API key","description":"GrowSurf REST API key supplied as `Authorization: Bearer `."}},"schemas":{"CampaignListResponse":{"type":"object","required":["campaigns"],"properties":{"campaigns":{"description":"Programs returned for the API key's bound team.","type":"array","items":{"$ref":"#/components/schemas/Campaign"}}}},"Campaign":{"type":"object","description":"Detailed information about a GrowSurf program.","required":["id","name","type","referralCount","participantCount","impressionCount","inviteCount","winnerCount","status","rewards"],"properties":{"id":{"type":"string","readOnly":true,"description":"The unique identifier of the program."},"name":{"type":"string","description":"The program name (internal only, never exposed to participants)."},"type":{"$ref":"#/components/schemas/CampaignType","description":"The program type."},"referralCount":{"type":"integer","readOnly":true,"description":"The total referral count."},"participantCount":{"type":"integer","readOnly":true,"description":"The total participant count."},"impressionCount":{"type":"integer","readOnly":true,"description":"The total number of impressions — the collective number of times participants' unique referral links have been viewed."},"inviteCount":{"type":"integer","readOnly":true,"description":"The total number of invites sent by participants."},"winnerCount":{"type":"integer","readOnly":true,"description":"The total number of winners — all participants with at least one approved reward (includes referrers and referred friends)."},"currencyISO":{"type":["string","null"],"minLength":3,"maxLength":3,"description":"The program currency as an [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) code (e.g., `USD`, `GBP`)."},"status":{"$ref":"#/components/schemas/CampaignStatus","description":"The program status."},"rewards":{"type":"array","items":{"$ref":"#/components/schemas/Reward"},"description":"The list of rewards associated with the program."}}},"CampaignType":{"type":"string","enum":["REFERRAL","AFFILIATE"]},"CampaignStatus":{"type":"string","enum":["DRAFT","IN_PROGRESS","COMPLETE","DELETED"]},"Reward":{"type":"object","description":"A single campaign reward (also known as a `CampaignReward`). This is different from a `ParticipantReward`, which is a reward earned by a participant.","required":["id","type","isUnlimited","metadata"],"properties":{"id":{"type":"string","readOnly":true,"description":"The unique identifier of the campaign reward. You can find this ID from *Program Editor > 1. Rewards* and clicking the reward."},"type":{"$ref":"#/components/schemas/RewardType","description":"The reward type."},"title":{"type":["string","null"],"description":"The reward title (internal only, never exposed to participants)."},"isVisible":{"type":"boolean","description":"Whether the reward is enabled. When `false`, the reward is disabled: it is no longer awarded, and it is hidden from participants, including those who already earned it. Set `true` for the reward to be visible and awardable."},"description":{"type":["string","null"],"description":"The reward description shown to the referrer."},"referralDescription":{"type":["string","null"],"description":"The reward description shown to the referred friend (only applicable for double-sided reward types)."},"referredRewardUpfront":{"type":"boolean","description":"Only applies to double-sided rewards. When `true`, the referred friend's reward is delivered upfront as a discount and no `ParticipantReward` is created for them when the referral triggers."},"isUnlimited":{"type":"boolean","description":"`true` if this reward can be earned by a single participant an unlimited number of times."},"limit":{"type":["integer","null"],"description":"The number of times a participant can earn this reward (overridden when `isUnlimited` is `true`). `-1` represents an unlimited reward in REST responses."},"conversionsRequired":{"type":["integer","null"],"description":"The number of referrals a participant must make to earn this reward."},"numberOfWinners":{"type":["integer","null"],"description":"The maximum number of winners. Only applies to `LEADERBOARD` rewards. When `limitDuration` is `PER_MONTH`, this many top referrers win each month; otherwise this many win in total."},"limitDuration":{"type":["string","null"],"enum":["IN_TOTAL","PER_MONTH","PER_YEAR",null],"description":"Whether the reward can be earned in total, on a monthly basis, or on a yearly basis."},"imageUrl":{"type":["string","null"],"description":"The reward image URL."},"couponCode":{"type":["string","null"],"description":"A static coupon code shown to the referrer in the reward-won email and webhook. Display text only; GrowSurf does not create or validate it in any billing system. If the program has a connected billing integration (Stripe, Chargebee, or Recurly) that issues a coupon for the referral, that issued code is shown instead."},"order":{"type":["integer","null"],"description":"If there are multiple rewards, the order in which the reward should be displayed. `null` by default until set within the Design step of the program editor."},"nextMilestonePrefix":{"type":["string","null"],"description":"Text displayed in front of a participant's referral count for UI purposes (e.g., \"You are only\"). Applicable for milestone rewards (when `type` is `MILESTONE`)."},"nextMilestoneSuffix":{"type":["string","null"],"description":"Text displayed after a participant's referral count for UI purposes (e.g., \"referrals away from receiving a nice reward!\"). Applicable for milestone rewards (when `type` is `MILESTONE`)."},"metadata":{"$ref":"#/components/schemas/Metadata","description":"The reward metadata."},"commissionStructure":{"oneOf":[{"$ref":"#/components/schemas/CommissionStructure"},{"type":"null"}],"description":"The reward commission structure. Present only for affiliate programs."},"referralCouponCode":{"type":["string","null"],"description":"A static coupon code shown to the referred friend in the reward-won email and webhook (double-sided rewards). Same caveats as `couponCode`: display text only, not created or validated in any billing system, and superseded by a connected billing integration's issued coupon when one exists."},"value":{"oneOf":[{"$ref":"#/components/schemas/RewardTaxValuation"},{"type":"null"}],"description":"Tax valuation for the reward (the referrer's side of a double-sided reward). `null` when no valuation is set."},"referredValue":{"oneOf":[{"$ref":"#/components/schemas/RewardTaxValuation"},{"type":"null"}],"description":"Tax valuation for the referred friend's side of a double-sided reward. `null` when no valuation is set."}}},"RewardType":{"type":"string","enum":["SINGLE_SIDED","DOUBLE_SIDED","MILESTONE","LEADERBOARD","AFFILIATE"]},"Metadata":{"type":"object","description":"Shallow custom metadata object.","additionalProperties":true},"CommissionStructure":{"type":"object","description":"The commission configuration for an affiliate reward. Present only for affiliate programs.","properties":{"amount":{"type":["integer","null"],"description":"Fixed commission amount in the currency's smallest denomination, used when `type` is `FIXED`. `null` for percentage-based commissions."},"amountISO":{"type":["string","null"],"description":"ISO 4217 currency code for the fixed `amount`. Defaults to the program's currency when omitted. Must match the campaign `currencyISO` when provided. `null` for percentage-based commissions."},"event":{"type":["string","null"],"description":"The event that generates a commission (e.g., `SALE`)."},"type":{"type":["string","null"],"enum":["PERCENT","FIXED",null],"description":"How the commission is calculated: `PERCENT` (a percentage of the sale) or `FIXED` (a fixed `amount`)."},"minPaidReferrals":{"type":["integer","null"],"description":"The minimum number of paid referrals required before commissions are earned."},"holdDuration":{"type":["integer","null"],"description":"Number of days a commission is held before it can be paid out."},"duration":{"type":["string","null"],"description":"How long commissions continue to be earned for a referred customer."},"durationInMonths":{"type":["integer","null"],"description":"When `duration` is repeating, the number of months over which commissions are earned."},"approvalRequired":{"type":["boolean","null"],"description":"`true` if commissions require manual approval before they can be paid out."},"percent":{"type":["number","null"],"description":"The commission percentage, used when `type` is `PERCENT`."},"hasMaxAmount":{"type":["boolean","null"],"description":"`true` if a maximum commission amount cap is configured."},"maxAmount":{"type":["integer","null"],"description":"The maximum commission amount cap in the currency's smallest denomination. `null` if no cap is set."},"maxAmountISO":{"type":["string","null"],"description":"The [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code for `maxAmount`. Must match the campaign `currencyISO` when provided."},"hasIntro":{"type":["boolean","null"],"description":"`true` if an introductory commission rate is configured."},"introType":{"type":["string","null"],"description":"How the introductory commission is calculated: `PERCENT` or `FIXED`."},"introPercent":{"type":["number","null"],"description":"The introductory commission percentage, used when `introType` is `PERCENT`."},"introAmount":{"type":["integer","null"],"description":"The introductory commission amount in the currency's smallest denomination, used when `introType` is `FIXED`."},"introAmountISO":{"type":["string","null"],"description":"The [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code for `introAmount`. Must match the campaign `currencyISO` when provided."},"introDuration":{"type":["string","null"],"description":"How long the introductory rate applies."},"introDurationInMonths":{"type":["integer","null"],"description":"When `introDuration` is repeating, the number of months the introductory rate applies."}},"additionalProperties":false},"RewardTaxValuation":{"type":"object","description":"Tax valuation settings for a reward. Only relevant when the program collects tax documentation.","properties":{"fairMarketValueUSD":{"type":["number","null"],"minimum":0,"description":"Manual fair-market value in USD (major units) used as the fallback when the reward value cannot be resolved automatically. `null` = no manual value."},"isTaxReportable":{"type":["boolean","null"],"description":"Whether the reward's value counts toward 1099 thresholds/totals. `null` = use the smart default for the reward's source."}}},"Error":{"type":"object","properties":{"name":{"description":"Error name returned for the failed request.","type":"string"},"code":{"description":"Stable machine-readable error code.","type":"string"},"message":{"description":"Human-readable error message.","type":"string"},"errors":{"description":"Optional validation details for specific request fields.","type":"array","items":{"type":"object","additionalProperties":true}},"status":{"description":"HTTP status code for the error.","type":"integer"},"supportUrl":{"description":"Support URL related to the error, when available.","type":"string","format":"uri"},"policyName":{"description":"Rate-limit policy name for `429` errors, when available.","type":"string"},"level":{"description":"Error severity level, when available.","type":"string"},"timestamp":{"description":"When the error response was created.","type":"string","format":"date-time"}}}},"responses":{"Forbidden":{"description":"The API key is missing, invalid, revoked, outside its scope, or not allowed to perform this action.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Too many requests.","headers":{"GrowSurf-RateLimit-Second-Limit":{"description":"Number of API requests allowed per second policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Second-Remaining":{"description":"Number of API requests remaining in the second policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Second-Milliseconds":{"description":"Milliseconds until the second policy window resets.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Minute-Limit":{"description":"Number of API requests allowed per minute policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Minute-Remaining":{"description":"Number of API requests remaining in the minute policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Minute-Milliseconds":{"description":"Milliseconds until the minute policy window resets.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Hour-Limit":{"description":"Number of API requests allowed per hour policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Hour-Remaining":{"description":"Number of API requests remaining in the hour policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Hour-Milliseconds":{"description":"Milliseconds until the hour policy window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/campaigns":{"get":{"tags":["Campaigns"],"operationId":"listCampaigns","summary":"List campaigns","description":"Retrieves a list of your programs. Deleted programs are not returned.","responses":{"200":{"description":"Campaigns returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CampaignListResponse"}}}},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}}}}} ``` ## Retrieve a campaign > Retrieves a program for the given program ID. ```json {"openapi":"3.1.0","info":{"title":"GrowSurf REST API","version":"2.0.0"},"tags":[{"name":"Campaigns","description":"Program retrieval, listing, creation, updates, cloning, and configuration (design, emails, options, installation, and campaign rewards)."}],"servers":[{"url":"https://api.growsurf.com/v2","description":"Production"}],"security":[{"apiKeyAuth":[]}],"components":{"securitySchemes":{"apiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"API key","description":"GrowSurf REST API key supplied as `Authorization: Bearer `."}},"parameters":{"CampaignId":{"name":"id","in":"path","required":true,"description":"GrowSurf program ID.","schema":{"type":"string"}}},"schemas":{"Campaign":{"type":"object","description":"Detailed information about a GrowSurf program.","required":["id","name","type","referralCount","participantCount","impressionCount","inviteCount","winnerCount","status","rewards"],"properties":{"id":{"type":"string","readOnly":true,"description":"The unique identifier of the program."},"name":{"type":"string","description":"The program name (internal only, never exposed to participants)."},"type":{"$ref":"#/components/schemas/CampaignType","description":"The program type."},"referralCount":{"type":"integer","readOnly":true,"description":"The total referral count."},"participantCount":{"type":"integer","readOnly":true,"description":"The total participant count."},"impressionCount":{"type":"integer","readOnly":true,"description":"The total number of impressions — the collective number of times participants' unique referral links have been viewed."},"inviteCount":{"type":"integer","readOnly":true,"description":"The total number of invites sent by participants."},"winnerCount":{"type":"integer","readOnly":true,"description":"The total number of winners — all participants with at least one approved reward (includes referrers and referred friends)."},"currencyISO":{"type":["string","null"],"minLength":3,"maxLength":3,"description":"The program currency as an [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) code (e.g., `USD`, `GBP`)."},"status":{"$ref":"#/components/schemas/CampaignStatus","description":"The program status."},"rewards":{"type":"array","items":{"$ref":"#/components/schemas/Reward"},"description":"The list of rewards associated with the program."}}},"CampaignType":{"type":"string","enum":["REFERRAL","AFFILIATE"]},"CampaignStatus":{"type":"string","enum":["DRAFT","IN_PROGRESS","COMPLETE","DELETED"]},"Reward":{"type":"object","description":"A single campaign reward (also known as a `CampaignReward`). This is different from a `ParticipantReward`, which is a reward earned by a participant.","required":["id","type","isUnlimited","metadata"],"properties":{"id":{"type":"string","readOnly":true,"description":"The unique identifier of the campaign reward. You can find this ID from *Program Editor > 1. Rewards* and clicking the reward."},"type":{"$ref":"#/components/schemas/RewardType","description":"The reward type."},"title":{"type":["string","null"],"description":"The reward title (internal only, never exposed to participants)."},"isVisible":{"type":"boolean","description":"Whether the reward is enabled. When `false`, the reward is disabled: it is no longer awarded, and it is hidden from participants, including those who already earned it. Set `true` for the reward to be visible and awardable."},"description":{"type":["string","null"],"description":"The reward description shown to the referrer."},"referralDescription":{"type":["string","null"],"description":"The reward description shown to the referred friend (only applicable for double-sided reward types)."},"referredRewardUpfront":{"type":"boolean","description":"Only applies to double-sided rewards. When `true`, the referred friend's reward is delivered upfront as a discount and no `ParticipantReward` is created for them when the referral triggers."},"isUnlimited":{"type":"boolean","description":"`true` if this reward can be earned by a single participant an unlimited number of times."},"limit":{"type":["integer","null"],"description":"The number of times a participant can earn this reward (overridden when `isUnlimited` is `true`). `-1` represents an unlimited reward in REST responses."},"conversionsRequired":{"type":["integer","null"],"description":"The number of referrals a participant must make to earn this reward."},"numberOfWinners":{"type":["integer","null"],"description":"The maximum number of winners. Only applies to `LEADERBOARD` rewards. When `limitDuration` is `PER_MONTH`, this many top referrers win each month; otherwise this many win in total."},"limitDuration":{"type":["string","null"],"enum":["IN_TOTAL","PER_MONTH","PER_YEAR",null],"description":"Whether the reward can be earned in total, on a monthly basis, or on a yearly basis."},"imageUrl":{"type":["string","null"],"description":"The reward image URL."},"couponCode":{"type":["string","null"],"description":"A static coupon code shown to the referrer in the reward-won email and webhook. Display text only; GrowSurf does not create or validate it in any billing system. If the program has a connected billing integration (Stripe, Chargebee, or Recurly) that issues a coupon for the referral, that issued code is shown instead."},"order":{"type":["integer","null"],"description":"If there are multiple rewards, the order in which the reward should be displayed. `null` by default until set within the Design step of the program editor."},"nextMilestonePrefix":{"type":["string","null"],"description":"Text displayed in front of a participant's referral count for UI purposes (e.g., \"You are only\"). Applicable for milestone rewards (when `type` is `MILESTONE`)."},"nextMilestoneSuffix":{"type":["string","null"],"description":"Text displayed after a participant's referral count for UI purposes (e.g., \"referrals away from receiving a nice reward!\"). Applicable for milestone rewards (when `type` is `MILESTONE`)."},"metadata":{"$ref":"#/components/schemas/Metadata","description":"The reward metadata."},"commissionStructure":{"oneOf":[{"$ref":"#/components/schemas/CommissionStructure"},{"type":"null"}],"description":"The reward commission structure. Present only for affiliate programs."},"referralCouponCode":{"type":["string","null"],"description":"A static coupon code shown to the referred friend in the reward-won email and webhook (double-sided rewards). Same caveats as `couponCode`: display text only, not created or validated in any billing system, and superseded by a connected billing integration's issued coupon when one exists."},"value":{"oneOf":[{"$ref":"#/components/schemas/RewardTaxValuation"},{"type":"null"}],"description":"Tax valuation for the reward (the referrer's side of a double-sided reward). `null` when no valuation is set."},"referredValue":{"oneOf":[{"$ref":"#/components/schemas/RewardTaxValuation"},{"type":"null"}],"description":"Tax valuation for the referred friend's side of a double-sided reward. `null` when no valuation is set."}}},"RewardType":{"type":"string","enum":["SINGLE_SIDED","DOUBLE_SIDED","MILESTONE","LEADERBOARD","AFFILIATE"]},"Metadata":{"type":"object","description":"Shallow custom metadata object.","additionalProperties":true},"CommissionStructure":{"type":"object","description":"The commission configuration for an affiliate reward. Present only for affiliate programs.","properties":{"amount":{"type":["integer","null"],"description":"Fixed commission amount in the currency's smallest denomination, used when `type` is `FIXED`. `null` for percentage-based commissions."},"amountISO":{"type":["string","null"],"description":"ISO 4217 currency code for the fixed `amount`. Defaults to the program's currency when omitted. Must match the campaign `currencyISO` when provided. `null` for percentage-based commissions."},"event":{"type":["string","null"],"description":"The event that generates a commission (e.g., `SALE`)."},"type":{"type":["string","null"],"enum":["PERCENT","FIXED",null],"description":"How the commission is calculated: `PERCENT` (a percentage of the sale) or `FIXED` (a fixed `amount`)."},"minPaidReferrals":{"type":["integer","null"],"description":"The minimum number of paid referrals required before commissions are earned."},"holdDuration":{"type":["integer","null"],"description":"Number of days a commission is held before it can be paid out."},"duration":{"type":["string","null"],"description":"How long commissions continue to be earned for a referred customer."},"durationInMonths":{"type":["integer","null"],"description":"When `duration` is repeating, the number of months over which commissions are earned."},"approvalRequired":{"type":["boolean","null"],"description":"`true` if commissions require manual approval before they can be paid out."},"percent":{"type":["number","null"],"description":"The commission percentage, used when `type` is `PERCENT`."},"hasMaxAmount":{"type":["boolean","null"],"description":"`true` if a maximum commission amount cap is configured."},"maxAmount":{"type":["integer","null"],"description":"The maximum commission amount cap in the currency's smallest denomination. `null` if no cap is set."},"maxAmountISO":{"type":["string","null"],"description":"The [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code for `maxAmount`. Must match the campaign `currencyISO` when provided."},"hasIntro":{"type":["boolean","null"],"description":"`true` if an introductory commission rate is configured."},"introType":{"type":["string","null"],"description":"How the introductory commission is calculated: `PERCENT` or `FIXED`."},"introPercent":{"type":["number","null"],"description":"The introductory commission percentage, used when `introType` is `PERCENT`."},"introAmount":{"type":["integer","null"],"description":"The introductory commission amount in the currency's smallest denomination, used when `introType` is `FIXED`."},"introAmountISO":{"type":["string","null"],"description":"The [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code for `introAmount`. Must match the campaign `currencyISO` when provided."},"introDuration":{"type":["string","null"],"description":"How long the introductory rate applies."},"introDurationInMonths":{"type":["integer","null"],"description":"When `introDuration` is repeating, the number of months the introductory rate applies."}},"additionalProperties":false},"RewardTaxValuation":{"type":"object","description":"Tax valuation settings for a reward. Only relevant when the program collects tax documentation.","properties":{"fairMarketValueUSD":{"type":["number","null"],"minimum":0,"description":"Manual fair-market value in USD (major units) used as the fallback when the reward value cannot be resolved automatically. `null` = no manual value."},"isTaxReportable":{"type":["boolean","null"],"description":"Whether the reward's value counts toward 1099 thresholds/totals. `null` = use the smart default for the reward's source."}}},"Error":{"type":"object","properties":{"name":{"description":"Error name returned for the failed request.","type":"string"},"code":{"description":"Stable machine-readable error code.","type":"string"},"message":{"description":"Human-readable error message.","type":"string"},"errors":{"description":"Optional validation details for specific request fields.","type":"array","items":{"type":"object","additionalProperties":true}},"status":{"description":"HTTP status code for the error.","type":"integer"},"supportUrl":{"description":"Support URL related to the error, when available.","type":"string","format":"uri"},"policyName":{"description":"Rate-limit policy name for `429` errors, when available.","type":"string"},"level":{"description":"Error severity level, when available.","type":"string"},"timestamp":{"description":"When the error response was created.","type":"string","format":"date-time"}}}},"responses":{"BadRequest":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The API key is missing, invalid, revoked, outside its scope, or not allowed to perform this action.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Too many requests.","headers":{"GrowSurf-RateLimit-Second-Limit":{"description":"Number of API requests allowed per second policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Second-Remaining":{"description":"Number of API requests remaining in the second policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Second-Milliseconds":{"description":"Milliseconds until the second policy window resets.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Minute-Limit":{"description":"Number of API requests allowed per minute policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Minute-Remaining":{"description":"Number of API requests remaining in the minute policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Minute-Milliseconds":{"description":"Milliseconds until the minute policy window resets.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Hour-Limit":{"description":"Number of API requests allowed per hour policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Hour-Remaining":{"description":"Number of API requests remaining in the hour policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Hour-Milliseconds":{"description":"Milliseconds until the hour policy window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/campaign/{id}":{"get":{"tags":["Campaigns"],"operationId":"retrieveCampaign","summary":"Retrieve a campaign","description":"Retrieves a program for the given program ID.","parameters":[{"$ref":"#/components/parameters/CampaignId"}],"responses":{"200":{"description":"Campaign returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Campaign"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}}}} ``` ## Create a campaign > Creates a new program, plus any optional program rewards. The new program is created in \`DRAFT\` status and owned by the API key's bound team. ```json {"openapi":"3.1.0","info":{"title":"GrowSurf REST API","version":"2.0.0"},"tags":[{"name":"Campaigns","description":"Program retrieval, listing, creation, updates, cloning, and configuration (design, emails, options, installation, and campaign rewards)."}],"servers":[{"url":"https://api.growsurf.com/v2","description":"Production"}],"security":[{"apiKeyAuth":[]}],"components":{"securitySchemes":{"apiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"API key","description":"GrowSurf REST API key supplied as `Authorization: Bearer `."}},"schemas":{"CampaignCreateRequest":{"type":"object","description":"Request body for creating a program. Only `type` is required; everything else is server-defaulted. Editor-tab configuration (design, emails, options, installation) is NOT accepted here — configure it via the config sub-resources (e.g. `PATCH /campaign/{id}/options`) after the program is created.","required":["type"],"properties":{"type":{"type":"string","enum":["REFERRAL","AFFILIATE"],"description":"The program type. Immutable after creation."},"name":{"type":"string","description":"The program name (internal only, never exposed to participants). Defaults to a generated name (a friendly label plus the creation date) that you can rename at any time."},"companyName":{"type":"string","description":"The company name shown to participants across the program's emails and referral portal. When omitted, it defaults to the `company` name set when the account was created (see `POST /accounts`), with common legal suffixes removed."},"companyLogoImageUrl":{"type":"string","description":"URL of the company logo shown to participants. When omitted, it is auto-populated from your company's domain (and the program theme is seeded with your brand colors). Pass a value to override the logo; the returned campaign reflects a GrowSurf-hosted URL that may differ from the one you supplied."},"currencyISO":{"type":"string","default":"USD","description":"ISO 4217 currency code. Defaults to `USD`. Chosen when the program is created and immutable afterward — it cannot be changed on update."},"rewards":{"type":"array","items":{"$ref":"#/components/schemas/RewardCreateRequest"},"description":"Optional inline rewards to create with the program."}}},"RewardCreateRequest":{"type":"object","description":"Request body for creating a campaign reward. `type` is required and must be compatible with the program type. AFFILIATE rewards additionally require `commissionStructure` (with `amount` for a `FIXED` commission or `percent` for a `PERCENT` commission).","required":["type"],"allOf":[{"$ref":"#/components/schemas/RewardWritableFields"},{"type":"object","properties":{"type":{"$ref":"#/components/schemas/RewardType","description":"The reward type. Immutable after creation."}}}]},"RewardWritableFields":{"type":"object","description":"The writable fields shared by the create and update campaign reward requests.","properties":{"title":{"type":"string","description":"The reward title (internal only, never exposed to participants)."},"description":{"type":"string","description":"The reward description shown to the referrer."},"referralDescription":{"type":["string","null"],"description":"The reward description shown to the referred friend (double-sided rewards only)."},"imageUrl":{"type":["string","null"],"description":"An image URL for the reward."},"isVisible":{"type":"boolean","default":true,"description":"Whether the reward is enabled. When `false`, the reward is disabled: it is no longer awarded, and it is hidden from participants, including those who already earned it. Set `true` for the reward to be visible and awardable."},"isUnlimited":{"type":"boolean","default":true,"description":"Whether the reward can be earned an unlimited number of times. Defaults to `true`, except `MILESTONE` rewards, which can only be earned once."},"referredRewardUpfront":{"type":"boolean","default":false,"description":"For double-sided rewards, deliver the referred friend's reward upfront as a discount."},"limit":{"type":"integer","minimum":0,"default":1,"description":"The number of times a participant can earn the reward (overridden by `isUnlimited`)."},"conversionsRequired":{"type":"integer","minimum":1,"default":1,"description":"The number of referrals required to earn the reward."},"numberOfWinners":{"type":"integer","minimum":0,"description":"The maximum number of winners. Only applies to `LEADERBOARD` rewards. When `limitDuration` is `PER_MONTH`, this many top referrers win each month; otherwise this many win in total. A `LEADERBOARD` reward that omits it defaults to `3`."},"order":{"type":"integer","description":"The display order of the reward."},"limitDuration":{"type":"string","enum":["IN_TOTAL","PER_MONTH","PER_YEAR"],"default":"IN_TOTAL","description":"The window over which `limit` applies."},"nextMilestonePrefix":{"type":["string","null"],"description":"Text shown before a participant's referral count in milestone progress copy (e.g. `You are only`). Applies to `MILESTONE` rewards."},"nextMilestoneSuffix":{"type":["string","null"],"description":"Text shown after a participant's referral count in milestone progress copy (e.g. `referrals away from your next reward!`). Applies to `MILESTONE` rewards."},"couponCode":{"type":["string","null"],"description":"A static coupon code shown to the referrer in the reward-won email and webhook when this reward is earned. Display text only; GrowSurf does not create or validate it in any billing system. If the program has a connected billing integration (Stripe, Chargebee, or Recurly) that issues a coupon for the referral, that issued code is shown instead."},"referralCouponCode":{"type":["string","null"],"description":"A static coupon code shown to the referred friend in the reward-won email and webhook (double-sided rewards). Same behavior and caveats as `couponCode`: display text only, not created or validated in any billing system, and superseded by a connected billing integration's issued coupon when one exists."},"metadata":{"$ref":"#/components/schemas/Metadata","description":"Custom key/value metadata (single-level; keys are camelCased on save; values are stored as strings). Sending `metadata` REPLACES the stored object. Campaign copy can reference a key via `{{campaignReward['']['']}}` tokens: renaming a key (same value, new key) automatically rewrites those references; removing a key that campaign copy still references returns a `409` listing the referencing fields."},"commissionStructure":{"$ref":"#/components/schemas/CommissionStructure","description":"The affiliate commission structure (AFFILIATE rewards only). REQUIRED when creating an AFFILIATE reward — include `amount` (and optionally `amountISO`) for a `FIXED` commission, or `percent` for a `PERCENT` commission."},"value":{"oneOf":[{"$ref":"#/components/schemas/RewardTaxValuation"},{"type":"null"}],"description":"Tax valuation for the reward (the referrer's side of a double-sided reward). Used by tax documentation / 1099 reporting. `null` when no valuation is set."},"referredValue":{"oneOf":[{"$ref":"#/components/schemas/RewardTaxValuation"},{"type":"null"}],"description":"Tax valuation for the referred friend's side of a double-sided reward. Defaults to not tax-reportable (a purchase rebate). `null` when no valuation is set."}}},"Metadata":{"type":"object","description":"Shallow custom metadata object.","additionalProperties":true},"CommissionStructure":{"type":"object","description":"The commission configuration for an affiliate reward. Present only for affiliate programs.","properties":{"amount":{"type":["integer","null"],"description":"Fixed commission amount in the currency's smallest denomination, used when `type` is `FIXED`. `null` for percentage-based commissions."},"amountISO":{"type":["string","null"],"description":"ISO 4217 currency code for the fixed `amount`. Defaults to the program's currency when omitted. Must match the campaign `currencyISO` when provided. `null` for percentage-based commissions."},"event":{"type":["string","null"],"description":"The event that generates a commission (e.g., `SALE`)."},"type":{"type":["string","null"],"enum":["PERCENT","FIXED",null],"description":"How the commission is calculated: `PERCENT` (a percentage of the sale) or `FIXED` (a fixed `amount`)."},"minPaidReferrals":{"type":["integer","null"],"description":"The minimum number of paid referrals required before commissions are earned."},"holdDuration":{"type":["integer","null"],"description":"Number of days a commission is held before it can be paid out."},"duration":{"type":["string","null"],"description":"How long commissions continue to be earned for a referred customer."},"durationInMonths":{"type":["integer","null"],"description":"When `duration` is repeating, the number of months over which commissions are earned."},"approvalRequired":{"type":["boolean","null"],"description":"`true` if commissions require manual approval before they can be paid out."},"percent":{"type":["number","null"],"description":"The commission percentage, used when `type` is `PERCENT`."},"hasMaxAmount":{"type":["boolean","null"],"description":"`true` if a maximum commission amount cap is configured."},"maxAmount":{"type":["integer","null"],"description":"The maximum commission amount cap in the currency's smallest denomination. `null` if no cap is set."},"maxAmountISO":{"type":["string","null"],"description":"The [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code for `maxAmount`. Must match the campaign `currencyISO` when provided."},"hasIntro":{"type":["boolean","null"],"description":"`true` if an introductory commission rate is configured."},"introType":{"type":["string","null"],"description":"How the introductory commission is calculated: `PERCENT` or `FIXED`."},"introPercent":{"type":["number","null"],"description":"The introductory commission percentage, used when `introType` is `PERCENT`."},"introAmount":{"type":["integer","null"],"description":"The introductory commission amount in the currency's smallest denomination, used when `introType` is `FIXED`."},"introAmountISO":{"type":["string","null"],"description":"The [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code for `introAmount`. Must match the campaign `currencyISO` when provided."},"introDuration":{"type":["string","null"],"description":"How long the introductory rate applies."},"introDurationInMonths":{"type":["integer","null"],"description":"When `introDuration` is repeating, the number of months the introductory rate applies."}},"additionalProperties":false},"RewardTaxValuation":{"type":"object","description":"Tax valuation settings for a reward. Only relevant when the program collects tax documentation.","properties":{"fairMarketValueUSD":{"type":["number","null"],"minimum":0,"description":"Manual fair-market value in USD (major units) used as the fallback when the reward value cannot be resolved automatically. `null` = no manual value."},"isTaxReportable":{"type":["boolean","null"],"description":"Whether the reward's value counts toward 1099 thresholds/totals. `null` = use the smart default for the reward's source."}}},"RewardType":{"type":"string","enum":["SINGLE_SIDED","DOUBLE_SIDED","MILESTONE","LEADERBOARD","AFFILIATE"]},"Campaign":{"type":"object","description":"Detailed information about a GrowSurf program.","required":["id","name","type","referralCount","participantCount","impressionCount","inviteCount","winnerCount","status","rewards"],"properties":{"id":{"type":"string","readOnly":true,"description":"The unique identifier of the program."},"name":{"type":"string","description":"The program name (internal only, never exposed to participants)."},"type":{"$ref":"#/components/schemas/CampaignType","description":"The program type."},"referralCount":{"type":"integer","readOnly":true,"description":"The total referral count."},"participantCount":{"type":"integer","readOnly":true,"description":"The total participant count."},"impressionCount":{"type":"integer","readOnly":true,"description":"The total number of impressions — the collective number of times participants' unique referral links have been viewed."},"inviteCount":{"type":"integer","readOnly":true,"description":"The total number of invites sent by participants."},"winnerCount":{"type":"integer","readOnly":true,"description":"The total number of winners — all participants with at least one approved reward (includes referrers and referred friends)."},"currencyISO":{"type":["string","null"],"minLength":3,"maxLength":3,"description":"The program currency as an [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) code (e.g., `USD`, `GBP`)."},"status":{"$ref":"#/components/schemas/CampaignStatus","description":"The program status."},"rewards":{"type":"array","items":{"$ref":"#/components/schemas/Reward"},"description":"The list of rewards associated with the program."}}},"CampaignType":{"type":"string","enum":["REFERRAL","AFFILIATE"]},"CampaignStatus":{"type":"string","enum":["DRAFT","IN_PROGRESS","COMPLETE","DELETED"]},"Reward":{"type":"object","description":"A single campaign reward (also known as a `CampaignReward`). This is different from a `ParticipantReward`, which is a reward earned by a participant.","required":["id","type","isUnlimited","metadata"],"properties":{"id":{"type":"string","readOnly":true,"description":"The unique identifier of the campaign reward. You can find this ID from *Program Editor > 1. Rewards* and clicking the reward."},"type":{"$ref":"#/components/schemas/RewardType","description":"The reward type."},"title":{"type":["string","null"],"description":"The reward title (internal only, never exposed to participants)."},"isVisible":{"type":"boolean","description":"Whether the reward is enabled. When `false`, the reward is disabled: it is no longer awarded, and it is hidden from participants, including those who already earned it. Set `true` for the reward to be visible and awardable."},"description":{"type":["string","null"],"description":"The reward description shown to the referrer."},"referralDescription":{"type":["string","null"],"description":"The reward description shown to the referred friend (only applicable for double-sided reward types)."},"referredRewardUpfront":{"type":"boolean","description":"Only applies to double-sided rewards. When `true`, the referred friend's reward is delivered upfront as a discount and no `ParticipantReward` is created for them when the referral triggers."},"isUnlimited":{"type":"boolean","description":"`true` if this reward can be earned by a single participant an unlimited number of times."},"limit":{"type":["integer","null"],"description":"The number of times a participant can earn this reward (overridden when `isUnlimited` is `true`). `-1` represents an unlimited reward in REST responses."},"conversionsRequired":{"type":["integer","null"],"description":"The number of referrals a participant must make to earn this reward."},"numberOfWinners":{"type":["integer","null"],"description":"The maximum number of winners. Only applies to `LEADERBOARD` rewards. When `limitDuration` is `PER_MONTH`, this many top referrers win each month; otherwise this many win in total."},"limitDuration":{"type":["string","null"],"enum":["IN_TOTAL","PER_MONTH","PER_YEAR",null],"description":"Whether the reward can be earned in total, on a monthly basis, or on a yearly basis."},"imageUrl":{"type":["string","null"],"description":"The reward image URL."},"couponCode":{"type":["string","null"],"description":"A static coupon code shown to the referrer in the reward-won email and webhook. Display text only; GrowSurf does not create or validate it in any billing system. If the program has a connected billing integration (Stripe, Chargebee, or Recurly) that issues a coupon for the referral, that issued code is shown instead."},"order":{"type":["integer","null"],"description":"If there are multiple rewards, the order in which the reward should be displayed. `null` by default until set within the Design step of the program editor."},"nextMilestonePrefix":{"type":["string","null"],"description":"Text displayed in front of a participant's referral count for UI purposes (e.g., \"You are only\"). Applicable for milestone rewards (when `type` is `MILESTONE`)."},"nextMilestoneSuffix":{"type":["string","null"],"description":"Text displayed after a participant's referral count for UI purposes (e.g., \"referrals away from receiving a nice reward!\"). Applicable for milestone rewards (when `type` is `MILESTONE`)."},"metadata":{"$ref":"#/components/schemas/Metadata","description":"The reward metadata."},"commissionStructure":{"oneOf":[{"$ref":"#/components/schemas/CommissionStructure"},{"type":"null"}],"description":"The reward commission structure. Present only for affiliate programs."},"referralCouponCode":{"type":["string","null"],"description":"A static coupon code shown to the referred friend in the reward-won email and webhook (double-sided rewards). Same caveats as `couponCode`: display text only, not created or validated in any billing system, and superseded by a connected billing integration's issued coupon when one exists."},"value":{"oneOf":[{"$ref":"#/components/schemas/RewardTaxValuation"},{"type":"null"}],"description":"Tax valuation for the reward (the referrer's side of a double-sided reward). `null` when no valuation is set."},"referredValue":{"oneOf":[{"$ref":"#/components/schemas/RewardTaxValuation"},{"type":"null"}],"description":"Tax valuation for the referred friend's side of a double-sided reward. `null` when no valuation is set."}}},"Error":{"type":"object","properties":{"name":{"description":"Error name returned for the failed request.","type":"string"},"code":{"description":"Stable machine-readable error code.","type":"string"},"message":{"description":"Human-readable error message.","type":"string"},"errors":{"description":"Optional validation details for specific request fields.","type":"array","items":{"type":"object","additionalProperties":true}},"status":{"description":"HTTP status code for the error.","type":"integer"},"supportUrl":{"description":"Support URL related to the error, when available.","type":"string","format":"uri"},"policyName":{"description":"Rate-limit policy name for `429` errors, when available.","type":"string"},"level":{"description":"Error severity level, when available.","type":"string"},"timestamp":{"description":"When the error response was created.","type":"string","format":"date-time"}}}},"responses":{"BadRequest":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The API key is missing, invalid, revoked, outside its scope, or not allowed to perform this action.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Too many requests.","headers":{"GrowSurf-RateLimit-Second-Limit":{"description":"Number of API requests allowed per second policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Second-Remaining":{"description":"Number of API requests remaining in the second policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Second-Milliseconds":{"description":"Milliseconds until the second policy window resets.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Minute-Limit":{"description":"Number of API requests allowed per minute policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Minute-Remaining":{"description":"Number of API requests remaining in the minute policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Minute-Milliseconds":{"description":"Milliseconds until the minute policy window resets.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Hour-Limit":{"description":"Number of API requests allowed per hour policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Hour-Remaining":{"description":"Number of API requests remaining in the hour policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Hour-Milliseconds":{"description":"Milliseconds until the hour policy window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/campaigns":{"post":{"tags":["Campaigns"],"operationId":"createCampaign","summary":"Create a campaign","description":"Creates a new program, plus any optional program rewards. The new program is created in `DRAFT` status and owned by the API key's bound team.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CampaignCreateRequest"}}}},"responses":{"200":{"description":"Campaign created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Campaign"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"402":{"description":"This action isn't available for your account yet (it needs an active subscription or a payment method on file), or the program limit was reached."},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}}}}} ``` ## Update a campaign > Updates a program's identity and lifecycle. Only the fields you send are changed. \`type\`, \`urlId\`, and \`currencyISO\` are immutable. Editor-tab configuration (design, emails, options, installation) is edited via the dedicated config sub-resources, not here. The program cannot be deleted via this endpoint. ```json {"openapi":"3.1.0","info":{"title":"GrowSurf REST API","version":"2.0.0"},"tags":[{"name":"Campaigns","description":"Program retrieval, listing, creation, updates, cloning, and configuration (design, emails, options, installation, and campaign rewards)."}],"servers":[{"url":"https://api.growsurf.com/v2","description":"Production"}],"security":[{"apiKeyAuth":[]}],"components":{"securitySchemes":{"apiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"API key","description":"GrowSurf REST API key supplied as `Authorization: Bearer `."}},"parameters":{"CampaignId":{"name":"id","in":"path","required":true,"description":"GrowSurf program ID.","schema":{"type":"string"}}},"schemas":{"CampaignUpdateRequest":{"type":"object","description":"Request body for updating a program's identity and lifecycle. Only the fields you send are changed. `type`, `urlId`, and `currencyISO` are immutable — currency is chosen once when the program is created and cannot be changed here (sending it returns a `400`). Editor-tab configuration (design, emails, options, installation) is edited via the dedicated config sub-resources (e.g. `PATCH /campaign/{id}/emails`), not here.","properties":{"name":{"type":"string","description":"The program name (internal only, never exposed to participants)."},"companyName":{"type":"string","description":"The company name shown to participants across the program's emails and referral portal."},"companyLogoImageUrl":{"type":"string","description":"URL of the company logo shown to participants. The returned campaign reflects a GrowSurf-hosted URL that may differ from the one you supplied."},"status":{"type":"string","enum":["IN_PROGRESS","COMPLETE"],"description":"The requested program status. Only the dashboard's lifecycle moves are accepted: `IN_PROGRESS` publishes a `DRAFT` program or resumes a `COMPLETE`/`CANCELLED` one; `COMPLETE` ends an `IN_PROGRESS` program. Any other target (including `DRAFT`, `PENDING`, `CANCELLED`, and `DELETED`) returns a `400`."}}},"Campaign":{"type":"object","description":"Detailed information about a GrowSurf program.","required":["id","name","type","referralCount","participantCount","impressionCount","inviteCount","winnerCount","status","rewards"],"properties":{"id":{"type":"string","readOnly":true,"description":"The unique identifier of the program."},"name":{"type":"string","description":"The program name (internal only, never exposed to participants)."},"type":{"$ref":"#/components/schemas/CampaignType","description":"The program type."},"referralCount":{"type":"integer","readOnly":true,"description":"The total referral count."},"participantCount":{"type":"integer","readOnly":true,"description":"The total participant count."},"impressionCount":{"type":"integer","readOnly":true,"description":"The total number of impressions — the collective number of times participants' unique referral links have been viewed."},"inviteCount":{"type":"integer","readOnly":true,"description":"The total number of invites sent by participants."},"winnerCount":{"type":"integer","readOnly":true,"description":"The total number of winners — all participants with at least one approved reward (includes referrers and referred friends)."},"currencyISO":{"type":["string","null"],"minLength":3,"maxLength":3,"description":"The program currency as an [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) code (e.g., `USD`, `GBP`)."},"status":{"$ref":"#/components/schemas/CampaignStatus","description":"The program status."},"rewards":{"type":"array","items":{"$ref":"#/components/schemas/Reward"},"description":"The list of rewards associated with the program."}}},"CampaignType":{"type":"string","enum":["REFERRAL","AFFILIATE"]},"CampaignStatus":{"type":"string","enum":["DRAFT","IN_PROGRESS","COMPLETE","DELETED"]},"Reward":{"type":"object","description":"A single campaign reward (also known as a `CampaignReward`). This is different from a `ParticipantReward`, which is a reward earned by a participant.","required":["id","type","isUnlimited","metadata"],"properties":{"id":{"type":"string","readOnly":true,"description":"The unique identifier of the campaign reward. You can find this ID from *Program Editor > 1. Rewards* and clicking the reward."},"type":{"$ref":"#/components/schemas/RewardType","description":"The reward type."},"title":{"type":["string","null"],"description":"The reward title (internal only, never exposed to participants)."},"isVisible":{"type":"boolean","description":"Whether the reward is enabled. When `false`, the reward is disabled: it is no longer awarded, and it is hidden from participants, including those who already earned it. Set `true` for the reward to be visible and awardable."},"description":{"type":["string","null"],"description":"The reward description shown to the referrer."},"referralDescription":{"type":["string","null"],"description":"The reward description shown to the referred friend (only applicable for double-sided reward types)."},"referredRewardUpfront":{"type":"boolean","description":"Only applies to double-sided rewards. When `true`, the referred friend's reward is delivered upfront as a discount and no `ParticipantReward` is created for them when the referral triggers."},"isUnlimited":{"type":"boolean","description":"`true` if this reward can be earned by a single participant an unlimited number of times."},"limit":{"type":["integer","null"],"description":"The number of times a participant can earn this reward (overridden when `isUnlimited` is `true`). `-1` represents an unlimited reward in REST responses."},"conversionsRequired":{"type":["integer","null"],"description":"The number of referrals a participant must make to earn this reward."},"numberOfWinners":{"type":["integer","null"],"description":"The maximum number of winners. Only applies to `LEADERBOARD` rewards. When `limitDuration` is `PER_MONTH`, this many top referrers win each month; otherwise this many win in total."},"limitDuration":{"type":["string","null"],"enum":["IN_TOTAL","PER_MONTH","PER_YEAR",null],"description":"Whether the reward can be earned in total, on a monthly basis, or on a yearly basis."},"imageUrl":{"type":["string","null"],"description":"The reward image URL."},"couponCode":{"type":["string","null"],"description":"A static coupon code shown to the referrer in the reward-won email and webhook. Display text only; GrowSurf does not create or validate it in any billing system. If the program has a connected billing integration (Stripe, Chargebee, or Recurly) that issues a coupon for the referral, that issued code is shown instead."},"order":{"type":["integer","null"],"description":"If there are multiple rewards, the order in which the reward should be displayed. `null` by default until set within the Design step of the program editor."},"nextMilestonePrefix":{"type":["string","null"],"description":"Text displayed in front of a participant's referral count for UI purposes (e.g., \"You are only\"). Applicable for milestone rewards (when `type` is `MILESTONE`)."},"nextMilestoneSuffix":{"type":["string","null"],"description":"Text displayed after a participant's referral count for UI purposes (e.g., \"referrals away from receiving a nice reward!\"). Applicable for milestone rewards (when `type` is `MILESTONE`)."},"metadata":{"$ref":"#/components/schemas/Metadata","description":"The reward metadata."},"commissionStructure":{"oneOf":[{"$ref":"#/components/schemas/CommissionStructure"},{"type":"null"}],"description":"The reward commission structure. Present only for affiliate programs."},"referralCouponCode":{"type":["string","null"],"description":"A static coupon code shown to the referred friend in the reward-won email and webhook (double-sided rewards). Same caveats as `couponCode`: display text only, not created or validated in any billing system, and superseded by a connected billing integration's issued coupon when one exists."},"value":{"oneOf":[{"$ref":"#/components/schemas/RewardTaxValuation"},{"type":"null"}],"description":"Tax valuation for the reward (the referrer's side of a double-sided reward). `null` when no valuation is set."},"referredValue":{"oneOf":[{"$ref":"#/components/schemas/RewardTaxValuation"},{"type":"null"}],"description":"Tax valuation for the referred friend's side of a double-sided reward. `null` when no valuation is set."}}},"RewardType":{"type":"string","enum":["SINGLE_SIDED","DOUBLE_SIDED","MILESTONE","LEADERBOARD","AFFILIATE"]},"Metadata":{"type":"object","description":"Shallow custom metadata object.","additionalProperties":true},"CommissionStructure":{"type":"object","description":"The commission configuration for an affiliate reward. Present only for affiliate programs.","properties":{"amount":{"type":["integer","null"],"description":"Fixed commission amount in the currency's smallest denomination, used when `type` is `FIXED`. `null` for percentage-based commissions."},"amountISO":{"type":["string","null"],"description":"ISO 4217 currency code for the fixed `amount`. Defaults to the program's currency when omitted. Must match the campaign `currencyISO` when provided. `null` for percentage-based commissions."},"event":{"type":["string","null"],"description":"The event that generates a commission (e.g., `SALE`)."},"type":{"type":["string","null"],"enum":["PERCENT","FIXED",null],"description":"How the commission is calculated: `PERCENT` (a percentage of the sale) or `FIXED` (a fixed `amount`)."},"minPaidReferrals":{"type":["integer","null"],"description":"The minimum number of paid referrals required before commissions are earned."},"holdDuration":{"type":["integer","null"],"description":"Number of days a commission is held before it can be paid out."},"duration":{"type":["string","null"],"description":"How long commissions continue to be earned for a referred customer."},"durationInMonths":{"type":["integer","null"],"description":"When `duration` is repeating, the number of months over which commissions are earned."},"approvalRequired":{"type":["boolean","null"],"description":"`true` if commissions require manual approval before they can be paid out."},"percent":{"type":["number","null"],"description":"The commission percentage, used when `type` is `PERCENT`."},"hasMaxAmount":{"type":["boolean","null"],"description":"`true` if a maximum commission amount cap is configured."},"maxAmount":{"type":["integer","null"],"description":"The maximum commission amount cap in the currency's smallest denomination. `null` if no cap is set."},"maxAmountISO":{"type":["string","null"],"description":"The [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code for `maxAmount`. Must match the campaign `currencyISO` when provided."},"hasIntro":{"type":["boolean","null"],"description":"`true` if an introductory commission rate is configured."},"introType":{"type":["string","null"],"description":"How the introductory commission is calculated: `PERCENT` or `FIXED`."},"introPercent":{"type":["number","null"],"description":"The introductory commission percentage, used when `introType` is `PERCENT`."},"introAmount":{"type":["integer","null"],"description":"The introductory commission amount in the currency's smallest denomination, used when `introType` is `FIXED`."},"introAmountISO":{"type":["string","null"],"description":"The [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code for `introAmount`. Must match the campaign `currencyISO` when provided."},"introDuration":{"type":["string","null"],"description":"How long the introductory rate applies."},"introDurationInMonths":{"type":["integer","null"],"description":"When `introDuration` is repeating, the number of months the introductory rate applies."}},"additionalProperties":false},"RewardTaxValuation":{"type":"object","description":"Tax valuation settings for a reward. Only relevant when the program collects tax documentation.","properties":{"fairMarketValueUSD":{"type":["number","null"],"minimum":0,"description":"Manual fair-market value in USD (major units) used as the fallback when the reward value cannot be resolved automatically. `null` = no manual value."},"isTaxReportable":{"type":["boolean","null"],"description":"Whether the reward's value counts toward 1099 thresholds/totals. `null` = use the smart default for the reward's source."}}},"Error":{"type":"object","properties":{"name":{"description":"Error name returned for the failed request.","type":"string"},"code":{"description":"Stable machine-readable error code.","type":"string"},"message":{"description":"Human-readable error message.","type":"string"},"errors":{"description":"Optional validation details for specific request fields.","type":"array","items":{"type":"object","additionalProperties":true}},"status":{"description":"HTTP status code for the error.","type":"integer"},"supportUrl":{"description":"Support URL related to the error, when available.","type":"string","format":"uri"},"policyName":{"description":"Rate-limit policy name for `429` errors, when available.","type":"string"},"level":{"description":"Error severity level, when available.","type":"string"},"timestamp":{"description":"When the error response was created.","type":"string","format":"date-time"}}}},"responses":{"BadRequest":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The API key is missing, invalid, revoked, outside its scope, or not allowed to perform this action.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Too many requests.","headers":{"GrowSurf-RateLimit-Second-Limit":{"description":"Number of API requests allowed per second policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Second-Remaining":{"description":"Number of API requests remaining in the second policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Second-Milliseconds":{"description":"Milliseconds until the second policy window resets.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Minute-Limit":{"description":"Number of API requests allowed per minute policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Minute-Remaining":{"description":"Number of API requests remaining in the minute policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Minute-Milliseconds":{"description":"Milliseconds until the minute policy window resets.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Hour-Limit":{"description":"Number of API requests allowed per hour policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Hour-Remaining":{"description":"Number of API requests remaining in the hour policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Hour-Milliseconds":{"description":"Milliseconds until the hour policy window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/campaign/{id}":{"patch":{"tags":["Campaigns"],"operationId":"updateCampaign","summary":"Update a campaign","description":"Updates a program's identity and lifecycle. Only the fields you send are changed. `type`, `urlId`, and `currencyISO` are immutable. Editor-tab configuration (design, emails, options, installation) is edited via the dedicated config sub-resources, not here. The program cannot be deleted via this endpoint.","parameters":[{"$ref":"#/components/parameters/CampaignId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CampaignUpdateRequest"}}}},"responses":{"200":{"description":"Campaign updated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Campaign"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}}}} ``` ## Clone a campaign > Clones an existing program into a new \`DRAFT\` program. Integrations and credentials are not copied; active rewards are cloned. ```json {"openapi":"3.1.0","info":{"title":"GrowSurf REST API","version":"2.0.0"},"tags":[{"name":"Campaigns","description":"Program retrieval, listing, creation, updates, cloning, and configuration (design, emails, options, installation, and campaign rewards)."}],"servers":[{"url":"https://api.growsurf.com/v2","description":"Production"}],"security":[{"apiKeyAuth":[]}],"components":{"securitySchemes":{"apiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"API key","description":"GrowSurf REST API key supplied as `Authorization: Bearer `."}},"parameters":{"CampaignId":{"name":"id","in":"path","required":true,"description":"GrowSurf program ID.","schema":{"type":"string"}}},"schemas":{"Campaign":{"type":"object","description":"Detailed information about a GrowSurf program.","required":["id","name","type","referralCount","participantCount","impressionCount","inviteCount","winnerCount","status","rewards"],"properties":{"id":{"type":"string","readOnly":true,"description":"The unique identifier of the program."},"name":{"type":"string","description":"The program name (internal only, never exposed to participants)."},"type":{"$ref":"#/components/schemas/CampaignType","description":"The program type."},"referralCount":{"type":"integer","readOnly":true,"description":"The total referral count."},"participantCount":{"type":"integer","readOnly":true,"description":"The total participant count."},"impressionCount":{"type":"integer","readOnly":true,"description":"The total number of impressions — the collective number of times participants' unique referral links have been viewed."},"inviteCount":{"type":"integer","readOnly":true,"description":"The total number of invites sent by participants."},"winnerCount":{"type":"integer","readOnly":true,"description":"The total number of winners — all participants with at least one approved reward (includes referrers and referred friends)."},"currencyISO":{"type":["string","null"],"minLength":3,"maxLength":3,"description":"The program currency as an [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) code (e.g., `USD`, `GBP`)."},"status":{"$ref":"#/components/schemas/CampaignStatus","description":"The program status."},"rewards":{"type":"array","items":{"$ref":"#/components/schemas/Reward"},"description":"The list of rewards associated with the program."}}},"CampaignType":{"type":"string","enum":["REFERRAL","AFFILIATE"]},"CampaignStatus":{"type":"string","enum":["DRAFT","IN_PROGRESS","COMPLETE","DELETED"]},"Reward":{"type":"object","description":"A single campaign reward (also known as a `CampaignReward`). This is different from a `ParticipantReward`, which is a reward earned by a participant.","required":["id","type","isUnlimited","metadata"],"properties":{"id":{"type":"string","readOnly":true,"description":"The unique identifier of the campaign reward. You can find this ID from *Program Editor > 1. Rewards* and clicking the reward."},"type":{"$ref":"#/components/schemas/RewardType","description":"The reward type."},"title":{"type":["string","null"],"description":"The reward title (internal only, never exposed to participants)."},"isVisible":{"type":"boolean","description":"Whether the reward is enabled. When `false`, the reward is disabled: it is no longer awarded, and it is hidden from participants, including those who already earned it. Set `true` for the reward to be visible and awardable."},"description":{"type":["string","null"],"description":"The reward description shown to the referrer."},"referralDescription":{"type":["string","null"],"description":"The reward description shown to the referred friend (only applicable for double-sided reward types)."},"referredRewardUpfront":{"type":"boolean","description":"Only applies to double-sided rewards. When `true`, the referred friend's reward is delivered upfront as a discount and no `ParticipantReward` is created for them when the referral triggers."},"isUnlimited":{"type":"boolean","description":"`true` if this reward can be earned by a single participant an unlimited number of times."},"limit":{"type":["integer","null"],"description":"The number of times a participant can earn this reward (overridden when `isUnlimited` is `true`). `-1` represents an unlimited reward in REST responses."},"conversionsRequired":{"type":["integer","null"],"description":"The number of referrals a participant must make to earn this reward."},"numberOfWinners":{"type":["integer","null"],"description":"The maximum number of winners. Only applies to `LEADERBOARD` rewards. When `limitDuration` is `PER_MONTH`, this many top referrers win each month; otherwise this many win in total."},"limitDuration":{"type":["string","null"],"enum":["IN_TOTAL","PER_MONTH","PER_YEAR",null],"description":"Whether the reward can be earned in total, on a monthly basis, or on a yearly basis."},"imageUrl":{"type":["string","null"],"description":"The reward image URL."},"couponCode":{"type":["string","null"],"description":"A static coupon code shown to the referrer in the reward-won email and webhook. Display text only; GrowSurf does not create or validate it in any billing system. If the program has a connected billing integration (Stripe, Chargebee, or Recurly) that issues a coupon for the referral, that issued code is shown instead."},"order":{"type":["integer","null"],"description":"If there are multiple rewards, the order in which the reward should be displayed. `null` by default until set within the Design step of the program editor."},"nextMilestonePrefix":{"type":["string","null"],"description":"Text displayed in front of a participant's referral count for UI purposes (e.g., \"You are only\"). Applicable for milestone rewards (when `type` is `MILESTONE`)."},"nextMilestoneSuffix":{"type":["string","null"],"description":"Text displayed after a participant's referral count for UI purposes (e.g., \"referrals away from receiving a nice reward!\"). Applicable for milestone rewards (when `type` is `MILESTONE`)."},"metadata":{"$ref":"#/components/schemas/Metadata","description":"The reward metadata."},"commissionStructure":{"oneOf":[{"$ref":"#/components/schemas/CommissionStructure"},{"type":"null"}],"description":"The reward commission structure. Present only for affiliate programs."},"referralCouponCode":{"type":["string","null"],"description":"A static coupon code shown to the referred friend in the reward-won email and webhook (double-sided rewards). Same caveats as `couponCode`: display text only, not created or validated in any billing system, and superseded by a connected billing integration's issued coupon when one exists."},"value":{"oneOf":[{"$ref":"#/components/schemas/RewardTaxValuation"},{"type":"null"}],"description":"Tax valuation for the reward (the referrer's side of a double-sided reward). `null` when no valuation is set."},"referredValue":{"oneOf":[{"$ref":"#/components/schemas/RewardTaxValuation"},{"type":"null"}],"description":"Tax valuation for the referred friend's side of a double-sided reward. `null` when no valuation is set."}}},"RewardType":{"type":"string","enum":["SINGLE_SIDED","DOUBLE_SIDED","MILESTONE","LEADERBOARD","AFFILIATE"]},"Metadata":{"type":"object","description":"Shallow custom metadata object.","additionalProperties":true},"CommissionStructure":{"type":"object","description":"The commission configuration for an affiliate reward. Present only for affiliate programs.","properties":{"amount":{"type":["integer","null"],"description":"Fixed commission amount in the currency's smallest denomination, used when `type` is `FIXED`. `null` for percentage-based commissions."},"amountISO":{"type":["string","null"],"description":"ISO 4217 currency code for the fixed `amount`. Defaults to the program's currency when omitted. Must match the campaign `currencyISO` when provided. `null` for percentage-based commissions."},"event":{"type":["string","null"],"description":"The event that generates a commission (e.g., `SALE`)."},"type":{"type":["string","null"],"enum":["PERCENT","FIXED",null],"description":"How the commission is calculated: `PERCENT` (a percentage of the sale) or `FIXED` (a fixed `amount`)."},"minPaidReferrals":{"type":["integer","null"],"description":"The minimum number of paid referrals required before commissions are earned."},"holdDuration":{"type":["integer","null"],"description":"Number of days a commission is held before it can be paid out."},"duration":{"type":["string","null"],"description":"How long commissions continue to be earned for a referred customer."},"durationInMonths":{"type":["integer","null"],"description":"When `duration` is repeating, the number of months over which commissions are earned."},"approvalRequired":{"type":["boolean","null"],"description":"`true` if commissions require manual approval before they can be paid out."},"percent":{"type":["number","null"],"description":"The commission percentage, used when `type` is `PERCENT`."},"hasMaxAmount":{"type":["boolean","null"],"description":"`true` if a maximum commission amount cap is configured."},"maxAmount":{"type":["integer","null"],"description":"The maximum commission amount cap in the currency's smallest denomination. `null` if no cap is set."},"maxAmountISO":{"type":["string","null"],"description":"The [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code for `maxAmount`. Must match the campaign `currencyISO` when provided."},"hasIntro":{"type":["boolean","null"],"description":"`true` if an introductory commission rate is configured."},"introType":{"type":["string","null"],"description":"How the introductory commission is calculated: `PERCENT` or `FIXED`."},"introPercent":{"type":["number","null"],"description":"The introductory commission percentage, used when `introType` is `PERCENT`."},"introAmount":{"type":["integer","null"],"description":"The introductory commission amount in the currency's smallest denomination, used when `introType` is `FIXED`."},"introAmountISO":{"type":["string","null"],"description":"The [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code for `introAmount`. Must match the campaign `currencyISO` when provided."},"introDuration":{"type":["string","null"],"description":"How long the introductory rate applies."},"introDurationInMonths":{"type":["integer","null"],"description":"When `introDuration` is repeating, the number of months the introductory rate applies."}},"additionalProperties":false},"RewardTaxValuation":{"type":"object","description":"Tax valuation settings for a reward. Only relevant when the program collects tax documentation.","properties":{"fairMarketValueUSD":{"type":["number","null"],"minimum":0,"description":"Manual fair-market value in USD (major units) used as the fallback when the reward value cannot be resolved automatically. `null` = no manual value."},"isTaxReportable":{"type":["boolean","null"],"description":"Whether the reward's value counts toward 1099 thresholds/totals. `null` = use the smart default for the reward's source."}}},"Error":{"type":"object","properties":{"name":{"description":"Error name returned for the failed request.","type":"string"},"code":{"description":"Stable machine-readable error code.","type":"string"},"message":{"description":"Human-readable error message.","type":"string"},"errors":{"description":"Optional validation details for specific request fields.","type":"array","items":{"type":"object","additionalProperties":true}},"status":{"description":"HTTP status code for the error.","type":"integer"},"supportUrl":{"description":"Support URL related to the error, when available.","type":"string","format":"uri"},"policyName":{"description":"Rate-limit policy name for `429` errors, when available.","type":"string"},"level":{"description":"Error severity level, when available.","type":"string"},"timestamp":{"description":"When the error response was created.","type":"string","format":"date-time"}}}},"responses":{"BadRequest":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The API key is missing, invalid, revoked, outside its scope, or not allowed to perform this action.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Too many requests.","headers":{"GrowSurf-RateLimit-Second-Limit":{"description":"Number of API requests allowed per second policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Second-Remaining":{"description":"Number of API requests remaining in the second policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Second-Milliseconds":{"description":"Milliseconds until the second policy window resets.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Minute-Limit":{"description":"Number of API requests allowed per minute policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Minute-Remaining":{"description":"Number of API requests remaining in the minute policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Minute-Milliseconds":{"description":"Milliseconds until the minute policy window resets.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Hour-Limit":{"description":"Number of API requests allowed per hour policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Hour-Remaining":{"description":"Number of API requests remaining in the hour policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Hour-Milliseconds":{"description":"Milliseconds until the hour policy window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/campaign/{id}/clone":{"post":{"tags":["Campaigns"],"operationId":"cloneCampaign","summary":"Clone a campaign","description":"Clones an existing program into a new `DRAFT` program. Integrations and credentials are not copied; active rewards are cloned.","parameters":[{"$ref":"#/components/parameters/CampaignId"}],"responses":{"200":{"description":"Campaign cloned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Campaign"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}}}} ``` *** ## CAMPAIGN REWARDS ↓ {% hint style="info" %} Read or update a program's **Rewards** tab. Available fields depend on the program type (referral or affiliate); `PATCH` is a partial merge (send only what you want to change). {% endhint %} ## List campaign rewards > Retrieves the list of a program's configured rewards (\`CampaignReward\`s) — the same set embedded in the \`rewards\` array of the campaign response. Delete a reward with \`DELETE /campaign/{id}/reward-configs/{campaignRewardId}\`. ```json {"openapi":"3.1.0","info":{"title":"GrowSurf REST API","version":"2.0.0"},"tags":[{"name":"Campaigns","description":"Program retrieval, listing, creation, updates, cloning, and configuration (design, emails, options, installation, and campaign rewards)."}],"servers":[{"url":"https://api.growsurf.com/v2","description":"Production"}],"security":[{"apiKeyAuth":[]}],"components":{"securitySchemes":{"apiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"API key","description":"GrowSurf REST API key supplied as `Authorization: Bearer `."}},"parameters":{"CampaignId":{"name":"id","in":"path","required":true,"description":"GrowSurf program ID.","schema":{"type":"string"}}},"schemas":{"CampaignRewardListResponse":{"type":"object","description":"The list of a program's configured rewards.","required":["rewards"],"properties":{"rewards":{"type":"array","items":{"$ref":"#/components/schemas/Reward"},"description":"The program's active, visible, and enabled reward configs."}}},"Reward":{"type":"object","description":"A single campaign reward (also known as a `CampaignReward`). This is different from a `ParticipantReward`, which is a reward earned by a participant.","required":["id","type","isUnlimited","metadata"],"properties":{"id":{"type":"string","readOnly":true,"description":"The unique identifier of the campaign reward. You can find this ID from *Program Editor > 1. Rewards* and clicking the reward."},"type":{"$ref":"#/components/schemas/RewardType","description":"The reward type."},"title":{"type":["string","null"],"description":"The reward title (internal only, never exposed to participants)."},"isVisible":{"type":"boolean","description":"Whether the reward is enabled. When `false`, the reward is disabled: it is no longer awarded, and it is hidden from participants, including those who already earned it. Set `true` for the reward to be visible and awardable."},"description":{"type":["string","null"],"description":"The reward description shown to the referrer."},"referralDescription":{"type":["string","null"],"description":"The reward description shown to the referred friend (only applicable for double-sided reward types)."},"referredRewardUpfront":{"type":"boolean","description":"Only applies to double-sided rewards. When `true`, the referred friend's reward is delivered upfront as a discount and no `ParticipantReward` is created for them when the referral triggers."},"isUnlimited":{"type":"boolean","description":"`true` if this reward can be earned by a single participant an unlimited number of times."},"limit":{"type":["integer","null"],"description":"The number of times a participant can earn this reward (overridden when `isUnlimited` is `true`). `-1` represents an unlimited reward in REST responses."},"conversionsRequired":{"type":["integer","null"],"description":"The number of referrals a participant must make to earn this reward."},"numberOfWinners":{"type":["integer","null"],"description":"The maximum number of winners. Only applies to `LEADERBOARD` rewards. When `limitDuration` is `PER_MONTH`, this many top referrers win each month; otherwise this many win in total."},"limitDuration":{"type":["string","null"],"enum":["IN_TOTAL","PER_MONTH","PER_YEAR",null],"description":"Whether the reward can be earned in total, on a monthly basis, or on a yearly basis."},"imageUrl":{"type":["string","null"],"description":"The reward image URL."},"couponCode":{"type":["string","null"],"description":"A static coupon code shown to the referrer in the reward-won email and webhook. Display text only; GrowSurf does not create or validate it in any billing system. If the program has a connected billing integration (Stripe, Chargebee, or Recurly) that issues a coupon for the referral, that issued code is shown instead."},"order":{"type":["integer","null"],"description":"If there are multiple rewards, the order in which the reward should be displayed. `null` by default until set within the Design step of the program editor."},"nextMilestonePrefix":{"type":["string","null"],"description":"Text displayed in front of a participant's referral count for UI purposes (e.g., \"You are only\"). Applicable for milestone rewards (when `type` is `MILESTONE`)."},"nextMilestoneSuffix":{"type":["string","null"],"description":"Text displayed after a participant's referral count for UI purposes (e.g., \"referrals away from receiving a nice reward!\"). Applicable for milestone rewards (when `type` is `MILESTONE`)."},"metadata":{"$ref":"#/components/schemas/Metadata","description":"The reward metadata."},"commissionStructure":{"oneOf":[{"$ref":"#/components/schemas/CommissionStructure"},{"type":"null"}],"description":"The reward commission structure. Present only for affiliate programs."},"referralCouponCode":{"type":["string","null"],"description":"A static coupon code shown to the referred friend in the reward-won email and webhook (double-sided rewards). Same caveats as `couponCode`: display text only, not created or validated in any billing system, and superseded by a connected billing integration's issued coupon when one exists."},"value":{"oneOf":[{"$ref":"#/components/schemas/RewardTaxValuation"},{"type":"null"}],"description":"Tax valuation for the reward (the referrer's side of a double-sided reward). `null` when no valuation is set."},"referredValue":{"oneOf":[{"$ref":"#/components/schemas/RewardTaxValuation"},{"type":"null"}],"description":"Tax valuation for the referred friend's side of a double-sided reward. `null` when no valuation is set."}}},"RewardType":{"type":"string","enum":["SINGLE_SIDED","DOUBLE_SIDED","MILESTONE","LEADERBOARD","AFFILIATE"]},"Metadata":{"type":"object","description":"Shallow custom metadata object.","additionalProperties":true},"CommissionStructure":{"type":"object","description":"The commission configuration for an affiliate reward. Present only for affiliate programs.","properties":{"amount":{"type":["integer","null"],"description":"Fixed commission amount in the currency's smallest denomination, used when `type` is `FIXED`. `null` for percentage-based commissions."},"amountISO":{"type":["string","null"],"description":"ISO 4217 currency code for the fixed `amount`. Defaults to the program's currency when omitted. Must match the campaign `currencyISO` when provided. `null` for percentage-based commissions."},"event":{"type":["string","null"],"description":"The event that generates a commission (e.g., `SALE`)."},"type":{"type":["string","null"],"enum":["PERCENT","FIXED",null],"description":"How the commission is calculated: `PERCENT` (a percentage of the sale) or `FIXED` (a fixed `amount`)."},"minPaidReferrals":{"type":["integer","null"],"description":"The minimum number of paid referrals required before commissions are earned."},"holdDuration":{"type":["integer","null"],"description":"Number of days a commission is held before it can be paid out."},"duration":{"type":["string","null"],"description":"How long commissions continue to be earned for a referred customer."},"durationInMonths":{"type":["integer","null"],"description":"When `duration` is repeating, the number of months over which commissions are earned."},"approvalRequired":{"type":["boolean","null"],"description":"`true` if commissions require manual approval before they can be paid out."},"percent":{"type":["number","null"],"description":"The commission percentage, used when `type` is `PERCENT`."},"hasMaxAmount":{"type":["boolean","null"],"description":"`true` if a maximum commission amount cap is configured."},"maxAmount":{"type":["integer","null"],"description":"The maximum commission amount cap in the currency's smallest denomination. `null` if no cap is set."},"maxAmountISO":{"type":["string","null"],"description":"The [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code for `maxAmount`. Must match the campaign `currencyISO` when provided."},"hasIntro":{"type":["boolean","null"],"description":"`true` if an introductory commission rate is configured."},"introType":{"type":["string","null"],"description":"How the introductory commission is calculated: `PERCENT` or `FIXED`."},"introPercent":{"type":["number","null"],"description":"The introductory commission percentage, used when `introType` is `PERCENT`."},"introAmount":{"type":["integer","null"],"description":"The introductory commission amount in the currency's smallest denomination, used when `introType` is `FIXED`."},"introAmountISO":{"type":["string","null"],"description":"The [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code for `introAmount`. Must match the campaign `currencyISO` when provided."},"introDuration":{"type":["string","null"],"description":"How long the introductory rate applies."},"introDurationInMonths":{"type":["integer","null"],"description":"When `introDuration` is repeating, the number of months the introductory rate applies."}},"additionalProperties":false},"RewardTaxValuation":{"type":"object","description":"Tax valuation settings for a reward. Only relevant when the program collects tax documentation.","properties":{"fairMarketValueUSD":{"type":["number","null"],"minimum":0,"description":"Manual fair-market value in USD (major units) used as the fallback when the reward value cannot be resolved automatically. `null` = no manual value."},"isTaxReportable":{"type":["boolean","null"],"description":"Whether the reward's value counts toward 1099 thresholds/totals. `null` = use the smart default for the reward's source."}}},"Error":{"type":"object","properties":{"name":{"description":"Error name returned for the failed request.","type":"string"},"code":{"description":"Stable machine-readable error code.","type":"string"},"message":{"description":"Human-readable error message.","type":"string"},"errors":{"description":"Optional validation details for specific request fields.","type":"array","items":{"type":"object","additionalProperties":true}},"status":{"description":"HTTP status code for the error.","type":"integer"},"supportUrl":{"description":"Support URL related to the error, when available.","type":"string","format":"uri"},"policyName":{"description":"Rate-limit policy name for `429` errors, when available.","type":"string"},"level":{"description":"Error severity level, when available.","type":"string"},"timestamp":{"description":"When the error response was created.","type":"string","format":"date-time"}}}},"responses":{"BadRequest":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The API key is missing, invalid, revoked, outside its scope, or not allowed to perform this action.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Too many requests.","headers":{"GrowSurf-RateLimit-Second-Limit":{"description":"Number of API requests allowed per second policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Second-Remaining":{"description":"Number of API requests remaining in the second policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Second-Milliseconds":{"description":"Milliseconds until the second policy window resets.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Minute-Limit":{"description":"Number of API requests allowed per minute policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Minute-Remaining":{"description":"Number of API requests remaining in the minute policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Minute-Milliseconds":{"description":"Milliseconds until the minute policy window resets.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Hour-Limit":{"description":"Number of API requests allowed per hour policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Hour-Remaining":{"description":"Number of API requests remaining in the hour policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Hour-Milliseconds":{"description":"Milliseconds until the hour policy window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/campaign/{id}/reward-configs":{"get":{"tags":["Campaigns"],"operationId":"listCampaignRewards","summary":"List campaign rewards","description":"Retrieves the list of a program's configured rewards (`CampaignReward`s) — the same set embedded in the `rewards` array of the campaign response. Delete a reward with `DELETE /campaign/{id}/reward-configs/{campaignRewardId}`.","parameters":[{"$ref":"#/components/parameters/CampaignId"}],"responses":{"200":{"description":"Campaign rewards returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CampaignRewardListResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}}}} ``` ## Create a campaign reward > Creates a new campaign reward (\`CampaignReward\`) with a GrowSurf-assigned ID. The reward type must be compatible with the program type (affiliate programs support only \`AFFILIATE\` rewards; referral programs support all other types). Enabling an active reward of a type automatically enables that reward type on the program. ```json {"openapi":"3.1.0","info":{"title":"GrowSurf REST API","version":"2.0.0"},"tags":[{"name":"Campaigns","description":"Program retrieval, listing, creation, updates, cloning, and configuration (design, emails, options, installation, and campaign rewards)."}],"servers":[{"url":"https://api.growsurf.com/v2","description":"Production"}],"security":[{"apiKeyAuth":[]}],"components":{"securitySchemes":{"apiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"API key","description":"GrowSurf REST API key supplied as `Authorization: Bearer `."}},"parameters":{"CampaignId":{"name":"id","in":"path","required":true,"description":"GrowSurf program ID.","schema":{"type":"string"}}},"schemas":{"RewardCreateRequest":{"type":"object","description":"Request body for creating a campaign reward. `type` is required and must be compatible with the program type. AFFILIATE rewards additionally require `commissionStructure` (with `amount` for a `FIXED` commission or `percent` for a `PERCENT` commission).","required":["type"],"allOf":[{"$ref":"#/components/schemas/RewardWritableFields"},{"type":"object","properties":{"type":{"$ref":"#/components/schemas/RewardType","description":"The reward type. Immutable after creation."}}}]},"RewardWritableFields":{"type":"object","description":"The writable fields shared by the create and update campaign reward requests.","properties":{"title":{"type":"string","description":"The reward title (internal only, never exposed to participants)."},"description":{"type":"string","description":"The reward description shown to the referrer."},"referralDescription":{"type":["string","null"],"description":"The reward description shown to the referred friend (double-sided rewards only)."},"imageUrl":{"type":["string","null"],"description":"An image URL for the reward."},"isVisible":{"type":"boolean","default":true,"description":"Whether the reward is enabled. When `false`, the reward is disabled: it is no longer awarded, and it is hidden from participants, including those who already earned it. Set `true` for the reward to be visible and awardable."},"isUnlimited":{"type":"boolean","default":true,"description":"Whether the reward can be earned an unlimited number of times. Defaults to `true`, except `MILESTONE` rewards, which can only be earned once."},"referredRewardUpfront":{"type":"boolean","default":false,"description":"For double-sided rewards, deliver the referred friend's reward upfront as a discount."},"limit":{"type":"integer","minimum":0,"default":1,"description":"The number of times a participant can earn the reward (overridden by `isUnlimited`)."},"conversionsRequired":{"type":"integer","minimum":1,"default":1,"description":"The number of referrals required to earn the reward."},"numberOfWinners":{"type":"integer","minimum":0,"description":"The maximum number of winners. Only applies to `LEADERBOARD` rewards. When `limitDuration` is `PER_MONTH`, this many top referrers win each month; otherwise this many win in total. A `LEADERBOARD` reward that omits it defaults to `3`."},"order":{"type":"integer","description":"The display order of the reward."},"limitDuration":{"type":"string","enum":["IN_TOTAL","PER_MONTH","PER_YEAR"],"default":"IN_TOTAL","description":"The window over which `limit` applies."},"nextMilestonePrefix":{"type":["string","null"],"description":"Text shown before a participant's referral count in milestone progress copy (e.g. `You are only`). Applies to `MILESTONE` rewards."},"nextMilestoneSuffix":{"type":["string","null"],"description":"Text shown after a participant's referral count in milestone progress copy (e.g. `referrals away from your next reward!`). Applies to `MILESTONE` rewards."},"couponCode":{"type":["string","null"],"description":"A static coupon code shown to the referrer in the reward-won email and webhook when this reward is earned. Display text only; GrowSurf does not create or validate it in any billing system. If the program has a connected billing integration (Stripe, Chargebee, or Recurly) that issues a coupon for the referral, that issued code is shown instead."},"referralCouponCode":{"type":["string","null"],"description":"A static coupon code shown to the referred friend in the reward-won email and webhook (double-sided rewards). Same behavior and caveats as `couponCode`: display text only, not created or validated in any billing system, and superseded by a connected billing integration's issued coupon when one exists."},"metadata":{"$ref":"#/components/schemas/Metadata","description":"Custom key/value metadata (single-level; keys are camelCased on save; values are stored as strings). Sending `metadata` REPLACES the stored object. Campaign copy can reference a key via `{{campaignReward['']['']}}` tokens: renaming a key (same value, new key) automatically rewrites those references; removing a key that campaign copy still references returns a `409` listing the referencing fields."},"commissionStructure":{"$ref":"#/components/schemas/CommissionStructure","description":"The affiliate commission structure (AFFILIATE rewards only). REQUIRED when creating an AFFILIATE reward — include `amount` (and optionally `amountISO`) for a `FIXED` commission, or `percent` for a `PERCENT` commission."},"value":{"oneOf":[{"$ref":"#/components/schemas/RewardTaxValuation"},{"type":"null"}],"description":"Tax valuation for the reward (the referrer's side of a double-sided reward). Used by tax documentation / 1099 reporting. `null` when no valuation is set."},"referredValue":{"oneOf":[{"$ref":"#/components/schemas/RewardTaxValuation"},{"type":"null"}],"description":"Tax valuation for the referred friend's side of a double-sided reward. Defaults to not tax-reportable (a purchase rebate). `null` when no valuation is set."}}},"Metadata":{"type":"object","description":"Shallow custom metadata object.","additionalProperties":true},"CommissionStructure":{"type":"object","description":"The commission configuration for an affiliate reward. Present only for affiliate programs.","properties":{"amount":{"type":["integer","null"],"description":"Fixed commission amount in the currency's smallest denomination, used when `type` is `FIXED`. `null` for percentage-based commissions."},"amountISO":{"type":["string","null"],"description":"ISO 4217 currency code for the fixed `amount`. Defaults to the program's currency when omitted. Must match the campaign `currencyISO` when provided. `null` for percentage-based commissions."},"event":{"type":["string","null"],"description":"The event that generates a commission (e.g., `SALE`)."},"type":{"type":["string","null"],"enum":["PERCENT","FIXED",null],"description":"How the commission is calculated: `PERCENT` (a percentage of the sale) or `FIXED` (a fixed `amount`)."},"minPaidReferrals":{"type":["integer","null"],"description":"The minimum number of paid referrals required before commissions are earned."},"holdDuration":{"type":["integer","null"],"description":"Number of days a commission is held before it can be paid out."},"duration":{"type":["string","null"],"description":"How long commissions continue to be earned for a referred customer."},"durationInMonths":{"type":["integer","null"],"description":"When `duration` is repeating, the number of months over which commissions are earned."},"approvalRequired":{"type":["boolean","null"],"description":"`true` if commissions require manual approval before they can be paid out."},"percent":{"type":["number","null"],"description":"The commission percentage, used when `type` is `PERCENT`."},"hasMaxAmount":{"type":["boolean","null"],"description":"`true` if a maximum commission amount cap is configured."},"maxAmount":{"type":["integer","null"],"description":"The maximum commission amount cap in the currency's smallest denomination. `null` if no cap is set."},"maxAmountISO":{"type":["string","null"],"description":"The [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code for `maxAmount`. Must match the campaign `currencyISO` when provided."},"hasIntro":{"type":["boolean","null"],"description":"`true` if an introductory commission rate is configured."},"introType":{"type":["string","null"],"description":"How the introductory commission is calculated: `PERCENT` or `FIXED`."},"introPercent":{"type":["number","null"],"description":"The introductory commission percentage, used when `introType` is `PERCENT`."},"introAmount":{"type":["integer","null"],"description":"The introductory commission amount in the currency's smallest denomination, used when `introType` is `FIXED`."},"introAmountISO":{"type":["string","null"],"description":"The [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code for `introAmount`. Must match the campaign `currencyISO` when provided."},"introDuration":{"type":["string","null"],"description":"How long the introductory rate applies."},"introDurationInMonths":{"type":["integer","null"],"description":"When `introDuration` is repeating, the number of months the introductory rate applies."}},"additionalProperties":false},"RewardTaxValuation":{"type":"object","description":"Tax valuation settings for a reward. Only relevant when the program collects tax documentation.","properties":{"fairMarketValueUSD":{"type":["number","null"],"minimum":0,"description":"Manual fair-market value in USD (major units) used as the fallback when the reward value cannot be resolved automatically. `null` = no manual value."},"isTaxReportable":{"type":["boolean","null"],"description":"Whether the reward's value counts toward 1099 thresholds/totals. `null` = use the smart default for the reward's source."}}},"RewardType":{"type":"string","enum":["SINGLE_SIDED","DOUBLE_SIDED","MILESTONE","LEADERBOARD","AFFILIATE"]},"Reward":{"type":"object","description":"A single campaign reward (also known as a `CampaignReward`). This is different from a `ParticipantReward`, which is a reward earned by a participant.","required":["id","type","isUnlimited","metadata"],"properties":{"id":{"type":"string","readOnly":true,"description":"The unique identifier of the campaign reward. You can find this ID from *Program Editor > 1. Rewards* and clicking the reward."},"type":{"$ref":"#/components/schemas/RewardType","description":"The reward type."},"title":{"type":["string","null"],"description":"The reward title (internal only, never exposed to participants)."},"isVisible":{"type":"boolean","description":"Whether the reward is enabled. When `false`, the reward is disabled: it is no longer awarded, and it is hidden from participants, including those who already earned it. Set `true` for the reward to be visible and awardable."},"description":{"type":["string","null"],"description":"The reward description shown to the referrer."},"referralDescription":{"type":["string","null"],"description":"The reward description shown to the referred friend (only applicable for double-sided reward types)."},"referredRewardUpfront":{"type":"boolean","description":"Only applies to double-sided rewards. When `true`, the referred friend's reward is delivered upfront as a discount and no `ParticipantReward` is created for them when the referral triggers."},"isUnlimited":{"type":"boolean","description":"`true` if this reward can be earned by a single participant an unlimited number of times."},"limit":{"type":["integer","null"],"description":"The number of times a participant can earn this reward (overridden when `isUnlimited` is `true`). `-1` represents an unlimited reward in REST responses."},"conversionsRequired":{"type":["integer","null"],"description":"The number of referrals a participant must make to earn this reward."},"numberOfWinners":{"type":["integer","null"],"description":"The maximum number of winners. Only applies to `LEADERBOARD` rewards. When `limitDuration` is `PER_MONTH`, this many top referrers win each month; otherwise this many win in total."},"limitDuration":{"type":["string","null"],"enum":["IN_TOTAL","PER_MONTH","PER_YEAR",null],"description":"Whether the reward can be earned in total, on a monthly basis, or on a yearly basis."},"imageUrl":{"type":["string","null"],"description":"The reward image URL."},"couponCode":{"type":["string","null"],"description":"A static coupon code shown to the referrer in the reward-won email and webhook. Display text only; GrowSurf does not create or validate it in any billing system. If the program has a connected billing integration (Stripe, Chargebee, or Recurly) that issues a coupon for the referral, that issued code is shown instead."},"order":{"type":["integer","null"],"description":"If there are multiple rewards, the order in which the reward should be displayed. `null` by default until set within the Design step of the program editor."},"nextMilestonePrefix":{"type":["string","null"],"description":"Text displayed in front of a participant's referral count for UI purposes (e.g., \"You are only\"). Applicable for milestone rewards (when `type` is `MILESTONE`)."},"nextMilestoneSuffix":{"type":["string","null"],"description":"Text displayed after a participant's referral count for UI purposes (e.g., \"referrals away from receiving a nice reward!\"). Applicable for milestone rewards (when `type` is `MILESTONE`)."},"metadata":{"$ref":"#/components/schemas/Metadata","description":"The reward metadata."},"commissionStructure":{"oneOf":[{"$ref":"#/components/schemas/CommissionStructure"},{"type":"null"}],"description":"The reward commission structure. Present only for affiliate programs."},"referralCouponCode":{"type":["string","null"],"description":"A static coupon code shown to the referred friend in the reward-won email and webhook (double-sided rewards). Same caveats as `couponCode`: display text only, not created or validated in any billing system, and superseded by a connected billing integration's issued coupon when one exists."},"value":{"oneOf":[{"$ref":"#/components/schemas/RewardTaxValuation"},{"type":"null"}],"description":"Tax valuation for the reward (the referrer's side of a double-sided reward). `null` when no valuation is set."},"referredValue":{"oneOf":[{"$ref":"#/components/schemas/RewardTaxValuation"},{"type":"null"}],"description":"Tax valuation for the referred friend's side of a double-sided reward. `null` when no valuation is set."}}},"Error":{"type":"object","properties":{"name":{"description":"Error name returned for the failed request.","type":"string"},"code":{"description":"Stable machine-readable error code.","type":"string"},"message":{"description":"Human-readable error message.","type":"string"},"errors":{"description":"Optional validation details for specific request fields.","type":"array","items":{"type":"object","additionalProperties":true}},"status":{"description":"HTTP status code for the error.","type":"integer"},"supportUrl":{"description":"Support URL related to the error, when available.","type":"string","format":"uri"},"policyName":{"description":"Rate-limit policy name for `429` errors, when available.","type":"string"},"level":{"description":"Error severity level, when available.","type":"string"},"timestamp":{"description":"When the error response was created.","type":"string","format":"date-time"}}}},"responses":{"BadRequest":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The API key is missing, invalid, revoked, outside its scope, or not allowed to perform this action.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Too many requests.","headers":{"GrowSurf-RateLimit-Second-Limit":{"description":"Number of API requests allowed per second policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Second-Remaining":{"description":"Number of API requests remaining in the second policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Second-Milliseconds":{"description":"Milliseconds until the second policy window resets.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Minute-Limit":{"description":"Number of API requests allowed per minute policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Minute-Remaining":{"description":"Number of API requests remaining in the minute policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Minute-Milliseconds":{"description":"Milliseconds until the minute policy window resets.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Hour-Limit":{"description":"Number of API requests allowed per hour policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Hour-Remaining":{"description":"Number of API requests remaining in the hour policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Hour-Milliseconds":{"description":"Milliseconds until the hour policy window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/campaign/{id}/reward-configs":{"post":{"tags":["Campaigns"],"operationId":"createCampaignReward","summary":"Create a campaign reward","description":"Creates a new campaign reward (`CampaignReward`) with a GrowSurf-assigned ID. The reward type must be compatible with the program type (affiliate programs support only `AFFILIATE` rewards; referral programs support all other types). Enabling an active reward of a type automatically enables that reward type on the program.","parameters":[{"$ref":"#/components/parameters/CampaignId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RewardCreateRequest"}}}},"responses":{"200":{"description":"Campaign reward created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Reward"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}}}} ``` ## Update a campaign reward > Updates an existing campaign reward (\`CampaignReward\`). The reward \`type\` is immutable and cannot be changed. When the update replaces \`metadata\`, renamed keys automatically rewrite any \`{{campaignReward\[…]}}\` references in campaign copy; removing a key that campaign copy still references returns a \`409\` listing the referencing fields. ```json {"openapi":"3.1.0","info":{"title":"GrowSurf REST API","version":"2.0.0"},"tags":[{"name":"Campaigns","description":"Program retrieval, listing, creation, updates, cloning, and configuration (design, emails, options, installation, and campaign rewards)."}],"servers":[{"url":"https://api.growsurf.com/v2","description":"Production"}],"security":[{"apiKeyAuth":[]}],"components":{"securitySchemes":{"apiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"API key","description":"GrowSurf REST API key supplied as `Authorization: Bearer `."}},"parameters":{"CampaignId":{"name":"id","in":"path","required":true,"description":"GrowSurf program ID.","schema":{"type":"string"}},"CampaignRewardId":{"name":"campaignRewardId","in":"path","required":true,"description":"Campaign reward (`CampaignReward`) ID.","schema":{"type":"string"}}},"schemas":{"RewardUpdateRequest":{"allOf":[{"$ref":"#/components/schemas/RewardWritableFields"}],"description":"Request body for updating a campaign reward. All fields are optional; `type` is immutable and must not be supplied."},"RewardWritableFields":{"type":"object","description":"The writable fields shared by the create and update campaign reward requests.","properties":{"title":{"type":"string","description":"The reward title (internal only, never exposed to participants)."},"description":{"type":"string","description":"The reward description shown to the referrer."},"referralDescription":{"type":["string","null"],"description":"The reward description shown to the referred friend (double-sided rewards only)."},"imageUrl":{"type":["string","null"],"description":"An image URL for the reward."},"isVisible":{"type":"boolean","default":true,"description":"Whether the reward is enabled. When `false`, the reward is disabled: it is no longer awarded, and it is hidden from participants, including those who already earned it. Set `true` for the reward to be visible and awardable."},"isUnlimited":{"type":"boolean","default":true,"description":"Whether the reward can be earned an unlimited number of times. Defaults to `true`, except `MILESTONE` rewards, which can only be earned once."},"referredRewardUpfront":{"type":"boolean","default":false,"description":"For double-sided rewards, deliver the referred friend's reward upfront as a discount."},"limit":{"type":"integer","minimum":0,"default":1,"description":"The number of times a participant can earn the reward (overridden by `isUnlimited`)."},"conversionsRequired":{"type":"integer","minimum":1,"default":1,"description":"The number of referrals required to earn the reward."},"numberOfWinners":{"type":"integer","minimum":0,"description":"The maximum number of winners. Only applies to `LEADERBOARD` rewards. When `limitDuration` is `PER_MONTH`, this many top referrers win each month; otherwise this many win in total. A `LEADERBOARD` reward that omits it defaults to `3`."},"order":{"type":"integer","description":"The display order of the reward."},"limitDuration":{"type":"string","enum":["IN_TOTAL","PER_MONTH","PER_YEAR"],"default":"IN_TOTAL","description":"The window over which `limit` applies."},"nextMilestonePrefix":{"type":["string","null"],"description":"Text shown before a participant's referral count in milestone progress copy (e.g. `You are only`). Applies to `MILESTONE` rewards."},"nextMilestoneSuffix":{"type":["string","null"],"description":"Text shown after a participant's referral count in milestone progress copy (e.g. `referrals away from your next reward!`). Applies to `MILESTONE` rewards."},"couponCode":{"type":["string","null"],"description":"A static coupon code shown to the referrer in the reward-won email and webhook when this reward is earned. Display text only; GrowSurf does not create or validate it in any billing system. If the program has a connected billing integration (Stripe, Chargebee, or Recurly) that issues a coupon for the referral, that issued code is shown instead."},"referralCouponCode":{"type":["string","null"],"description":"A static coupon code shown to the referred friend in the reward-won email and webhook (double-sided rewards). Same behavior and caveats as `couponCode`: display text only, not created or validated in any billing system, and superseded by a connected billing integration's issued coupon when one exists."},"metadata":{"$ref":"#/components/schemas/Metadata","description":"Custom key/value metadata (single-level; keys are camelCased on save; values are stored as strings). Sending `metadata` REPLACES the stored object. Campaign copy can reference a key via `{{campaignReward['']['']}}` tokens: renaming a key (same value, new key) automatically rewrites those references; removing a key that campaign copy still references returns a `409` listing the referencing fields."},"commissionStructure":{"$ref":"#/components/schemas/CommissionStructure","description":"The affiliate commission structure (AFFILIATE rewards only). REQUIRED when creating an AFFILIATE reward — include `amount` (and optionally `amountISO`) for a `FIXED` commission, or `percent` for a `PERCENT` commission."},"value":{"oneOf":[{"$ref":"#/components/schemas/RewardTaxValuation"},{"type":"null"}],"description":"Tax valuation for the reward (the referrer's side of a double-sided reward). Used by tax documentation / 1099 reporting. `null` when no valuation is set."},"referredValue":{"oneOf":[{"$ref":"#/components/schemas/RewardTaxValuation"},{"type":"null"}],"description":"Tax valuation for the referred friend's side of a double-sided reward. Defaults to not tax-reportable (a purchase rebate). `null` when no valuation is set."}}},"Metadata":{"type":"object","description":"Shallow custom metadata object.","additionalProperties":true},"CommissionStructure":{"type":"object","description":"The commission configuration for an affiliate reward. Present only for affiliate programs.","properties":{"amount":{"type":["integer","null"],"description":"Fixed commission amount in the currency's smallest denomination, used when `type` is `FIXED`. `null` for percentage-based commissions."},"amountISO":{"type":["string","null"],"description":"ISO 4217 currency code for the fixed `amount`. Defaults to the program's currency when omitted. Must match the campaign `currencyISO` when provided. `null` for percentage-based commissions."},"event":{"type":["string","null"],"description":"The event that generates a commission (e.g., `SALE`)."},"type":{"type":["string","null"],"enum":["PERCENT","FIXED",null],"description":"How the commission is calculated: `PERCENT` (a percentage of the sale) or `FIXED` (a fixed `amount`)."},"minPaidReferrals":{"type":["integer","null"],"description":"The minimum number of paid referrals required before commissions are earned."},"holdDuration":{"type":["integer","null"],"description":"Number of days a commission is held before it can be paid out."},"duration":{"type":["string","null"],"description":"How long commissions continue to be earned for a referred customer."},"durationInMonths":{"type":["integer","null"],"description":"When `duration` is repeating, the number of months over which commissions are earned."},"approvalRequired":{"type":["boolean","null"],"description":"`true` if commissions require manual approval before they can be paid out."},"percent":{"type":["number","null"],"description":"The commission percentage, used when `type` is `PERCENT`."},"hasMaxAmount":{"type":["boolean","null"],"description":"`true` if a maximum commission amount cap is configured."},"maxAmount":{"type":["integer","null"],"description":"The maximum commission amount cap in the currency's smallest denomination. `null` if no cap is set."},"maxAmountISO":{"type":["string","null"],"description":"The [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code for `maxAmount`. Must match the campaign `currencyISO` when provided."},"hasIntro":{"type":["boolean","null"],"description":"`true` if an introductory commission rate is configured."},"introType":{"type":["string","null"],"description":"How the introductory commission is calculated: `PERCENT` or `FIXED`."},"introPercent":{"type":["number","null"],"description":"The introductory commission percentage, used when `introType` is `PERCENT`."},"introAmount":{"type":["integer","null"],"description":"The introductory commission amount in the currency's smallest denomination, used when `introType` is `FIXED`."},"introAmountISO":{"type":["string","null"],"description":"The [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code for `introAmount`. Must match the campaign `currencyISO` when provided."},"introDuration":{"type":["string","null"],"description":"How long the introductory rate applies."},"introDurationInMonths":{"type":["integer","null"],"description":"When `introDuration` is repeating, the number of months the introductory rate applies."}},"additionalProperties":false},"RewardTaxValuation":{"type":"object","description":"Tax valuation settings for a reward. Only relevant when the program collects tax documentation.","properties":{"fairMarketValueUSD":{"type":["number","null"],"minimum":0,"description":"Manual fair-market value in USD (major units) used as the fallback when the reward value cannot be resolved automatically. `null` = no manual value."},"isTaxReportable":{"type":["boolean","null"],"description":"Whether the reward's value counts toward 1099 thresholds/totals. `null` = use the smart default for the reward's source."}}},"Reward":{"type":"object","description":"A single campaign reward (also known as a `CampaignReward`). This is different from a `ParticipantReward`, which is a reward earned by a participant.","required":["id","type","isUnlimited","metadata"],"properties":{"id":{"type":"string","readOnly":true,"description":"The unique identifier of the campaign reward. You can find this ID from *Program Editor > 1. Rewards* and clicking the reward."},"type":{"$ref":"#/components/schemas/RewardType","description":"The reward type."},"title":{"type":["string","null"],"description":"The reward title (internal only, never exposed to participants)."},"isVisible":{"type":"boolean","description":"Whether the reward is enabled. When `false`, the reward is disabled: it is no longer awarded, and it is hidden from participants, including those who already earned it. Set `true` for the reward to be visible and awardable."},"description":{"type":["string","null"],"description":"The reward description shown to the referrer."},"referralDescription":{"type":["string","null"],"description":"The reward description shown to the referred friend (only applicable for double-sided reward types)."},"referredRewardUpfront":{"type":"boolean","description":"Only applies to double-sided rewards. When `true`, the referred friend's reward is delivered upfront as a discount and no `ParticipantReward` is created for them when the referral triggers."},"isUnlimited":{"type":"boolean","description":"`true` if this reward can be earned by a single participant an unlimited number of times."},"limit":{"type":["integer","null"],"description":"The number of times a participant can earn this reward (overridden when `isUnlimited` is `true`). `-1` represents an unlimited reward in REST responses."},"conversionsRequired":{"type":["integer","null"],"description":"The number of referrals a participant must make to earn this reward."},"numberOfWinners":{"type":["integer","null"],"description":"The maximum number of winners. Only applies to `LEADERBOARD` rewards. When `limitDuration` is `PER_MONTH`, this many top referrers win each month; otherwise this many win in total."},"limitDuration":{"type":["string","null"],"enum":["IN_TOTAL","PER_MONTH","PER_YEAR",null],"description":"Whether the reward can be earned in total, on a monthly basis, or on a yearly basis."},"imageUrl":{"type":["string","null"],"description":"The reward image URL."},"couponCode":{"type":["string","null"],"description":"A static coupon code shown to the referrer in the reward-won email and webhook. Display text only; GrowSurf does not create or validate it in any billing system. If the program has a connected billing integration (Stripe, Chargebee, or Recurly) that issues a coupon for the referral, that issued code is shown instead."},"order":{"type":["integer","null"],"description":"If there are multiple rewards, the order in which the reward should be displayed. `null` by default until set within the Design step of the program editor."},"nextMilestonePrefix":{"type":["string","null"],"description":"Text displayed in front of a participant's referral count for UI purposes (e.g., \"You are only\"). Applicable for milestone rewards (when `type` is `MILESTONE`)."},"nextMilestoneSuffix":{"type":["string","null"],"description":"Text displayed after a participant's referral count for UI purposes (e.g., \"referrals away from receiving a nice reward!\"). Applicable for milestone rewards (when `type` is `MILESTONE`)."},"metadata":{"$ref":"#/components/schemas/Metadata","description":"The reward metadata."},"commissionStructure":{"oneOf":[{"$ref":"#/components/schemas/CommissionStructure"},{"type":"null"}],"description":"The reward commission structure. Present only for affiliate programs."},"referralCouponCode":{"type":["string","null"],"description":"A static coupon code shown to the referred friend in the reward-won email and webhook (double-sided rewards). Same caveats as `couponCode`: display text only, not created or validated in any billing system, and superseded by a connected billing integration's issued coupon when one exists."},"value":{"oneOf":[{"$ref":"#/components/schemas/RewardTaxValuation"},{"type":"null"}],"description":"Tax valuation for the reward (the referrer's side of a double-sided reward). `null` when no valuation is set."},"referredValue":{"oneOf":[{"$ref":"#/components/schemas/RewardTaxValuation"},{"type":"null"}],"description":"Tax valuation for the referred friend's side of a double-sided reward. `null` when no valuation is set."}}},"RewardType":{"type":"string","enum":["SINGLE_SIDED","DOUBLE_SIDED","MILESTONE","LEADERBOARD","AFFILIATE"]},"Error":{"type":"object","properties":{"name":{"description":"Error name returned for the failed request.","type":"string"},"code":{"description":"Stable machine-readable error code.","type":"string"},"message":{"description":"Human-readable error message.","type":"string"},"errors":{"description":"Optional validation details for specific request fields.","type":"array","items":{"type":"object","additionalProperties":true}},"status":{"description":"HTTP status code for the error.","type":"integer"},"supportUrl":{"description":"Support URL related to the error, when available.","type":"string","format":"uri"},"policyName":{"description":"Rate-limit policy name for `429` errors, when available.","type":"string"},"level":{"description":"Error severity level, when available.","type":"string"},"timestamp":{"description":"When the error response was created.","type":"string","format":"date-time"}}}},"responses":{"BadRequest":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The API key is missing, invalid, revoked, outside its scope, or not allowed to perform this action.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Conflict":{"description":"Conflicting duplicate request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Too many requests.","headers":{"GrowSurf-RateLimit-Second-Limit":{"description":"Number of API requests allowed per second policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Second-Remaining":{"description":"Number of API requests remaining in the second policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Second-Milliseconds":{"description":"Milliseconds until the second policy window resets.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Minute-Limit":{"description":"Number of API requests allowed per minute policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Minute-Remaining":{"description":"Number of API requests remaining in the minute policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Minute-Milliseconds":{"description":"Milliseconds until the minute policy window resets.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Hour-Limit":{"description":"Number of API requests allowed per hour policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Hour-Remaining":{"description":"Number of API requests remaining in the hour policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Hour-Milliseconds":{"description":"Milliseconds until the hour policy window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/campaign/{id}/reward-configs/{campaignRewardId}":{"patch":{"tags":["Campaigns"],"operationId":"updateCampaignReward","summary":"Update a campaign reward","description":"Updates an existing campaign reward (`CampaignReward`). The reward `type` is immutable and cannot be changed. When the update replaces `metadata`, renamed keys automatically rewrite any `{{campaignReward[…]}}` references in campaign copy; removing a key that campaign copy still references returns a `409` listing the referencing fields.","parameters":[{"$ref":"#/components/parameters/CampaignId"},{"$ref":"#/components/parameters/CampaignRewardId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RewardUpdateRequest"}}}},"responses":{"200":{"description":"Campaign reward updated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Reward"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"}}}}}} ``` ## Delete a campaign reward > Deletes a campaign reward (\`CampaignReward\`). The reward is deactivated, removed from the program's reward set, and any connected upfront-discount coupons are cleaned up. If campaign copy still references any of the reward's metadata keys via \`{{campaignReward\[…]}}\` tokens, the delete returns a \`409\` listing the referencing fields — update those fields first. ```json {"openapi":"3.1.0","info":{"title":"GrowSurf REST API","version":"2.0.0"},"tags":[{"name":"Campaigns","description":"Program retrieval, listing, creation, updates, cloning, and configuration (design, emails, options, installation, and campaign rewards)."}],"servers":[{"url":"https://api.growsurf.com/v2","description":"Production"}],"security":[{"apiKeyAuth":[]}],"components":{"securitySchemes":{"apiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"API key","description":"GrowSurf REST API key supplied as `Authorization: Bearer `."}},"parameters":{"CampaignId":{"name":"id","in":"path","required":true,"description":"GrowSurf program ID.","schema":{"type":"string"}},"CampaignRewardId":{"name":"campaignRewardId","in":"path","required":true,"description":"Campaign reward (`CampaignReward`) ID.","schema":{"type":"string"}}},"schemas":{"DeleteRewardResponse":{"type":"object","required":["id","success"],"properties":{"id":{"type":"string","description":"The deleted reward ID."},"success":{"description":"Whether the campaign reward was deleted.","type":"boolean"}}},"Error":{"type":"object","properties":{"name":{"description":"Error name returned for the failed request.","type":"string"},"code":{"description":"Stable machine-readable error code.","type":"string"},"message":{"description":"Human-readable error message.","type":"string"},"errors":{"description":"Optional validation details for specific request fields.","type":"array","items":{"type":"object","additionalProperties":true}},"status":{"description":"HTTP status code for the error.","type":"integer"},"supportUrl":{"description":"Support URL related to the error, when available.","type":"string","format":"uri"},"policyName":{"description":"Rate-limit policy name for `429` errors, when available.","type":"string"},"level":{"description":"Error severity level, when available.","type":"string"},"timestamp":{"description":"When the error response was created.","type":"string","format":"date-time"}}}},"responses":{"BadRequest":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The API key is missing, invalid, revoked, outside its scope, or not allowed to perform this action.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Conflict":{"description":"Conflicting duplicate request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Too many requests.","headers":{"GrowSurf-RateLimit-Second-Limit":{"description":"Number of API requests allowed per second policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Second-Remaining":{"description":"Number of API requests remaining in the second policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Second-Milliseconds":{"description":"Milliseconds until the second policy window resets.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Minute-Limit":{"description":"Number of API requests allowed per minute policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Minute-Remaining":{"description":"Number of API requests remaining in the minute policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Minute-Milliseconds":{"description":"Milliseconds until the minute policy window resets.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Hour-Limit":{"description":"Number of API requests allowed per hour policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Hour-Remaining":{"description":"Number of API requests remaining in the hour policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Hour-Milliseconds":{"description":"Milliseconds until the hour policy window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/campaign/{id}/reward-configs/{campaignRewardId}":{"delete":{"tags":["Campaigns"],"operationId":"deleteCampaignReward","summary":"Delete a campaign reward","description":"Deletes a campaign reward (`CampaignReward`). The reward is deactivated, removed from the program's reward set, and any connected upfront-discount coupons are cleaned up. If campaign copy still references any of the reward's metadata keys via `{{campaignReward[…]}}` tokens, the delete returns a `409` listing the referencing fields — update those fields first.","parameters":[{"$ref":"#/components/parameters/CampaignId"},{"$ref":"#/components/parameters/CampaignRewardId"}],"responses":{"200":{"description":"Campaign reward deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeleteRewardResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"}}}}}} ``` *** ## CAMPAIGN DESIGN ↓ {% hint style="info" %} Read or update a program's **Design** tab — the GrowSurf window layout, header, share channels, signup form, portal/landing pages, and theme styling. This is a large, deeply nested object whose available fields depend on the program type (referral or affiliate); `PATCH` is a partial merge (send only what you want to change). Portal/landing-page custom code/JS is not editable via the API. {% endhint %} ## Retrieve campaign design > Retrieves a program's design configuration — the same surface as the dashboard Program Editor's \*\*Design\*\* tab: the GrowSurf window layout, header, share channels + invite, signup form, portal/landing pages, theme styling, and the referral/affiliate summary + status sections. This is a large object whose available fields depend on the program type; the response includes every field and its current value, which is the same shape you send back on \`PATCH\`. ```json {"openapi":"3.1.0","info":{"title":"GrowSurf REST API","version":"2.0.0"},"tags":[{"name":"Campaigns","description":"Program retrieval, listing, creation, updates, cloning, and configuration (design, emails, options, installation, and campaign rewards)."}],"servers":[{"url":"https://api.growsurf.com/v2","description":"Production"}],"security":[{"apiKeyAuth":[]}],"components":{"securitySchemes":{"apiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"API key","description":"GrowSurf REST API key supplied as `Authorization: Bearer `."}},"parameters":{"CampaignId":{"name":"id","in":"path","required":true,"description":"GrowSurf program ID.","schema":{"type":"string"}}},"schemas":{"CampaignDesign":{"type":"object","description":"A program's design configuration (the dashboard Program Editor's Design tab). This is a large, nested object organized by section; each section holds the design fields for that part of the GrowSurf window and landing pages. The exact fields available depend on the program type (e.g. `referralSummary` is referral-only; `affiliateSummary`, `commissions`, `payouts`, and `participantSettings` are affiliate-only). To see the full object with every field and its current value, `GET` this resource, then `PATCH` back only the sections or fields you want to change (arrays like `signup.fields` replace wholesale).","properties":{"window":{"type":"object","description":"How the sections inside the GrowSurf window are laid out. `navigationMode` chooses between a tabbed layout (`TABS`) and a single scrolling list (`LIST`)."},"header":{"type":"object","description":"Header content for participants (`postText`) and non-participants (`preText`)."},"stats":{"type":"object","description":"The stats panel a participant sees at the top of the GrowSurf window, summarizing their own referral progress. Only its heading text (`title`) is editable here."},"share":{"type":"object","description":"Share channels (`type..{isVisible,buttonText,message,order}`), invite settings, and share-button styling."},"signup":{"type":"object","description":"Signup form (`fields[]`, GDPR consent, button and login text)."},"referralStatus":{"type":"object","description":"The Referral Status section, which lists the people a participant has invited and each one's progress (invite sent, pending, awarded, or expired). Controls its title, icon, column and status labels, empty-state text, and whether invited emails are masked."},"leaderboard":{"type":"object","description":"The Leaderboard section that ranks participants against each other. Controls its title, icon, column labels, which time-period and ranking selectors appear, empty-state text, and how other participants' names are masked."},"referredExperience":{"type":"object","description":"The banner and headline shown to someone who arrives on your site through a referral link (for example, \"You were referred by Jane\"). Controls the banner and heading text, where they appear, whether they link to signup, and how the referrer's name is formatted."},"referralSummary":{"type":"object","description":"Referral programs only. The row of summary tiles a participant sees (clicks, leads, referrals, invites sent, rewards earned, and more). Controls each tile's label, tooltip, and visibility, plus the section's title and icon."},"affiliateSummary":{"type":"object","description":"Affiliate programs only. The row of summary tiles an affiliate sees (clicks, leads, referrals, referral revenue, upcoming payout, and total paid out). Controls each tile's label, tooltip, and visibility, plus the section's title and icon."},"commissions":{"type":"object","description":"Affiliate programs only. The Commissions section of the participant portal, which lists an affiliate's earned commissions and their status (pending, approved, paid, or reversed). Controls its title, icon, column labels, status labels and tooltips, and empty-state text."},"payouts":{"type":"object","description":"Affiliate programs only. The Payouts section of the participant portal, which lists an affiliate's payouts and their status (upcoming, queued, issued, or failed). Controls its title, icon, column labels, status labels and tooltips, and empty-state text."},"rewards":{"type":"object","description":"The heading, icon, and empty-state text of the rewards panel shown to participants. Which rewards appear, and the order they appear in, are managed through the campaign rewards endpoints, not here."},"participantSettings":{"type":"object","description":"The participant's account settings area in the portal. Controls the labels and messages for logging out, managing a PayPal payout email, and completing tax details (country of residency, VAT, and tax-form status). Applies to affiliate programs, and to referral programs that collect tax information or pay participants through PayPal."},"landingPages":{"type":"object","description":"Portal and landing pages — company info, `content` (FAQ/terms/labels), `styles` (fonts), third-party script IDs (GA/GTM/Facebook/HubSpot), and SEO meta tags. Custom code, CSS, and JS are not editable via the API."},"theme":{"type":"object","description":"Visual theme styling (colors, shadows, and similar)."}}},"Error":{"type":"object","properties":{"name":{"description":"Error name returned for the failed request.","type":"string"},"code":{"description":"Stable machine-readable error code.","type":"string"},"message":{"description":"Human-readable error message.","type":"string"},"errors":{"description":"Optional validation details for specific request fields.","type":"array","items":{"type":"object","additionalProperties":true}},"status":{"description":"HTTP status code for the error.","type":"integer"},"supportUrl":{"description":"Support URL related to the error, when available.","type":"string","format":"uri"},"policyName":{"description":"Rate-limit policy name for `429` errors, when available.","type":"string"},"level":{"description":"Error severity level, when available.","type":"string"},"timestamp":{"description":"When the error response was created.","type":"string","format":"date-time"}}}},"responses":{"BadRequest":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The API key is missing, invalid, revoked, outside its scope, or not allowed to perform this action.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Too many requests.","headers":{"GrowSurf-RateLimit-Second-Limit":{"description":"Number of API requests allowed per second policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Second-Remaining":{"description":"Number of API requests remaining in the second policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Second-Milliseconds":{"description":"Milliseconds until the second policy window resets.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Minute-Limit":{"description":"Number of API requests allowed per minute policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Minute-Remaining":{"description":"Number of API requests remaining in the minute policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Minute-Milliseconds":{"description":"Milliseconds until the minute policy window resets.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Hour-Limit":{"description":"Number of API requests allowed per hour policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Hour-Remaining":{"description":"Number of API requests remaining in the hour policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Hour-Milliseconds":{"description":"Milliseconds until the hour policy window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/campaign/{id}/design":{"get":{"tags":["Campaigns"],"operationId":"retrieveCampaignDesign","summary":"Retrieve campaign design","description":"Retrieves a program's design configuration — the same surface as the dashboard Program Editor's **Design** tab: the GrowSurf window layout, header, share channels + invite, signup form, portal/landing pages, theme styling, and the referral/affiliate summary + status sections. This is a large object whose available fields depend on the program type; the response includes every field and its current value, which is the same shape you send back on `PATCH`.","parameters":[{"$ref":"#/components/parameters/CampaignId"}],"responses":{"200":{"description":"Campaign design returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CampaignDesign"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}}}} ``` ## Update campaign design > Updates a program's design configuration. Only the fields you send are changed; anything you leave out is untouched (arrays such as \`signup.fields\` replace wholesale). Unknown fields, fields not available for the program type, and invalid values return a \`400\`. Landing-page custom code and JavaScript are not editable via the API. ```json {"openapi":"3.1.0","info":{"title":"GrowSurf REST API","version":"2.0.0"},"tags":[{"name":"Campaigns","description":"Program retrieval, listing, creation, updates, cloning, and configuration (design, emails, options, installation, and campaign rewards)."}],"servers":[{"url":"https://api.growsurf.com/v2","description":"Production"}],"security":[{"apiKeyAuth":[]}],"components":{"securitySchemes":{"apiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"API key","description":"GrowSurf REST API key supplied as `Authorization: Bearer `."}},"parameters":{"CampaignId":{"name":"id","in":"path","required":true,"description":"GrowSurf program ID.","schema":{"type":"string"}}},"schemas":{"CampaignDesign":{"type":"object","description":"A program's design configuration (the dashboard Program Editor's Design tab). This is a large, nested object organized by section; each section holds the design fields for that part of the GrowSurf window and landing pages. The exact fields available depend on the program type (e.g. `referralSummary` is referral-only; `affiliateSummary`, `commissions`, `payouts`, and `participantSettings` are affiliate-only). To see the full object with every field and its current value, `GET` this resource, then `PATCH` back only the sections or fields you want to change (arrays like `signup.fields` replace wholesale).","properties":{"window":{"type":"object","description":"How the sections inside the GrowSurf window are laid out. `navigationMode` chooses between a tabbed layout (`TABS`) and a single scrolling list (`LIST`)."},"header":{"type":"object","description":"Header content for participants (`postText`) and non-participants (`preText`)."},"stats":{"type":"object","description":"The stats panel a participant sees at the top of the GrowSurf window, summarizing their own referral progress. Only its heading text (`title`) is editable here."},"share":{"type":"object","description":"Share channels (`type..{isVisible,buttonText,message,order}`), invite settings, and share-button styling."},"signup":{"type":"object","description":"Signup form (`fields[]`, GDPR consent, button and login text)."},"referralStatus":{"type":"object","description":"The Referral Status section, which lists the people a participant has invited and each one's progress (invite sent, pending, awarded, or expired). Controls its title, icon, column and status labels, empty-state text, and whether invited emails are masked."},"leaderboard":{"type":"object","description":"The Leaderboard section that ranks participants against each other. Controls its title, icon, column labels, which time-period and ranking selectors appear, empty-state text, and how other participants' names are masked."},"referredExperience":{"type":"object","description":"The banner and headline shown to someone who arrives on your site through a referral link (for example, \"You were referred by Jane\"). Controls the banner and heading text, where they appear, whether they link to signup, and how the referrer's name is formatted."},"referralSummary":{"type":"object","description":"Referral programs only. The row of summary tiles a participant sees (clicks, leads, referrals, invites sent, rewards earned, and more). Controls each tile's label, tooltip, and visibility, plus the section's title and icon."},"affiliateSummary":{"type":"object","description":"Affiliate programs only. The row of summary tiles an affiliate sees (clicks, leads, referrals, referral revenue, upcoming payout, and total paid out). Controls each tile's label, tooltip, and visibility, plus the section's title and icon."},"commissions":{"type":"object","description":"Affiliate programs only. The Commissions section of the participant portal, which lists an affiliate's earned commissions and their status (pending, approved, paid, or reversed). Controls its title, icon, column labels, status labels and tooltips, and empty-state text."},"payouts":{"type":"object","description":"Affiliate programs only. The Payouts section of the participant portal, which lists an affiliate's payouts and their status (upcoming, queued, issued, or failed). Controls its title, icon, column labels, status labels and tooltips, and empty-state text."},"rewards":{"type":"object","description":"The heading, icon, and empty-state text of the rewards panel shown to participants. Which rewards appear, and the order they appear in, are managed through the campaign rewards endpoints, not here."},"participantSettings":{"type":"object","description":"The participant's account settings area in the portal. Controls the labels and messages for logging out, managing a PayPal payout email, and completing tax details (country of residency, VAT, and tax-form status). Applies to affiliate programs, and to referral programs that collect tax information or pay participants through PayPal."},"landingPages":{"type":"object","description":"Portal and landing pages — company info, `content` (FAQ/terms/labels), `styles` (fonts), third-party script IDs (GA/GTM/Facebook/HubSpot), and SEO meta tags. Custom code, CSS, and JS are not editable via the API."},"theme":{"type":"object","description":"Visual theme styling (colors, shadows, and similar)."}}},"Error":{"type":"object","properties":{"name":{"description":"Error name returned for the failed request.","type":"string"},"code":{"description":"Stable machine-readable error code.","type":"string"},"message":{"description":"Human-readable error message.","type":"string"},"errors":{"description":"Optional validation details for specific request fields.","type":"array","items":{"type":"object","additionalProperties":true}},"status":{"description":"HTTP status code for the error.","type":"integer"},"supportUrl":{"description":"Support URL related to the error, when available.","type":"string","format":"uri"},"policyName":{"description":"Rate-limit policy name for `429` errors, when available.","type":"string"},"level":{"description":"Error severity level, when available.","type":"string"},"timestamp":{"description":"When the error response was created.","type":"string","format":"date-time"}}}},"responses":{"BadRequest":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The API key is missing, invalid, revoked, outside its scope, or not allowed to perform this action.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Too many requests.","headers":{"GrowSurf-RateLimit-Second-Limit":{"description":"Number of API requests allowed per second policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Second-Remaining":{"description":"Number of API requests remaining in the second policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Second-Milliseconds":{"description":"Milliseconds until the second policy window resets.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Minute-Limit":{"description":"Number of API requests allowed per minute policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Minute-Remaining":{"description":"Number of API requests remaining in the minute policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Minute-Milliseconds":{"description":"Milliseconds until the minute policy window resets.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Hour-Limit":{"description":"Number of API requests allowed per hour policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Hour-Remaining":{"description":"Number of API requests remaining in the hour policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Hour-Milliseconds":{"description":"Milliseconds until the hour policy window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/campaign/{id}/design":{"patch":{"tags":["Campaigns"],"operationId":"updateCampaignDesign","summary":"Update campaign design","description":"Updates a program's design configuration. Only the fields you send are changed; anything you leave out is untouched (arrays such as `signup.fields` replace wholesale). Unknown fields, fields not available for the program type, and invalid values return a `400`. Landing-page custom code and JavaScript are not editable via the API.","parameters":[{"$ref":"#/components/parameters/CampaignId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CampaignDesign"}}}},"responses":{"200":{"description":"Campaign design updated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CampaignDesign"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}}}} ``` *** ## CAMPAIGN EMAILS ↓ {% hint style="info" %} Read or update a program's **Emails** tab — each editable email template (`subject`, `preheader`, `body`, `isEnabled`) plus the shared `settings` block (sender, contact, and design). The set of templates depends on the program type (referral or affiliate). `PATCH` is a partial merge (send only what you want to change); writing a template that is not available for the program type (referral or affiliate) returns a `400`, and the custom sender `fromEmail` is read-only (it requires dashboard domain verification). {% endhint %} ## Retrieve campaign emails > Retrieves a program's email configuration — the same surface as the dashboard Program Editor's \*\*Emails\*\* tab. Returns each editable email template (\`subject\`, \`preheader\`, \`body\`, \`isEnabled\`) plus the \`settings\` block (sender, contact, and design). The set of email templates returned depends on the program type (referral vs affiliate). ```json {"openapi":"3.1.0","info":{"title":"GrowSurf REST API","version":"2.0.0"},"tags":[{"name":"Campaigns","description":"Program retrieval, listing, creation, updates, cloning, and configuration (design, emails, options, installation, and campaign rewards)."}],"servers":[{"url":"https://api.growsurf.com/v2","description":"Production"}],"security":[{"apiKeyAuth":[]}],"components":{"securitySchemes":{"apiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"API key","description":"GrowSurf REST API key supplied as `Authorization: Bearer `."}},"parameters":{"CampaignId":{"name":"id","in":"path","required":true,"description":"GrowSurf program ID.","schema":{"type":"string"}}},"schemas":{"CampaignEmails":{"type":"object","description":"A program's email configuration (the dashboard Program Editor's Emails tab). Each property is an editable email template; the set of templates available depends on the program type (referral vs affiliate), and writing a template that is not available for the program type returns a `400`. The `settings` object holds sender, contact, and design settings. To see the full object with every template and its current values, `GET` this resource, then `PATCH` back only the fields you want to change.","properties":{"welcomeNonReferred":{"$ref":"#/components/schemas/CampaignEmailTemplate","description":"Welcome email sent to a participant who joins on their own, without being referred. Available for both referral and affiliate programs."},"welcomeReferred":{"$ref":"#/components/schemas/CampaignEmailTemplate","description":"Welcome email sent to someone who signs up through another participant's referral link (also covers referrals you add from the dashboard). Referral programs only."},"referralLinkViewedFirstTime":{"$ref":"#/components/schemas/CampaignEmailTemplate","description":"Sent to a participant the first time their referral link is viewed. It goes out only once. Available for both referral and affiliate programs."},"referralLinkUsed":{"$ref":"#/components/schemas/CampaignEmailTemplate","description":"Sent to a referrer when they earn referral credit because someone they referred completed the qualifying action. Most useful when a reward needs more than one referral to unlock. Labeled \"Referral Credit Received\" in the Program Editor. Referral programs only."},"referredSignup":{"$ref":"#/components/schemas/CampaignEmailTemplate","description":"Sent to a referrer each time someone signs up using their referral link. Labeled \"Referral Link Used\" in the Program Editor. Available for both referral and affiliate programs."},"goalAchieved":{"$ref":"#/components/schemas/CampaignEmailTemplate","description":"Sent to a participant when they unlock a reward (and to the referred friend as well, for double-sided rewards). Labeled \"Reward Unlocked\" in the Program Editor. Referral programs only."},"campaignEndedWinners":{"$ref":"#/components/schemas/CampaignEmailTemplate","description":"Sent to every participant who unlocked at least one reward, once the program ends. Referral programs only."},"campaignEndedNonWinners":{"$ref":"#/components/schemas/CampaignEmailTemplate","description":"Sent to every participant who did not unlock a reward, once the program ends. Referral programs only."},"progressUpdateMonthly":{"$ref":"#/components/schemas/CampaignEmailTemplate","description":"A month-end summary emailed to participants recapping how they are doing in the program. Available for both referral and affiliate programs."},"commissionGenerated":{"$ref":"#/components/schemas/CampaignEmailTemplate","description":"Sent to an affiliate when they earn a new commission, for example when a customer they referred makes a purchase. Affiliate programs only."},"commissionAdjusted":{"$ref":"#/components/schemas/CampaignEmailTemplate","description":"Sent to an affiliate when one of their commissions is adjusted because of a full refund, partial refund, or chargeback. Affiliate programs only."},"payoutPending":{"$ref":"#/components/schemas/CampaignEmailTemplate","description":"Sent to an affiliate when a batch payment is started and they have a payout on the way. Affiliate programs only."},"payoutSentSuccess":{"$ref":"#/components/schemas/CampaignEmailTemplate","description":"Sent to an affiliate when their payout completes successfully. Labeled \"Payout Sent Successfully\" in the Program Editor. Affiliate programs only."},"invite":{"$ref":"#/components/schemas/CampaignEmailTemplate","description":"The invitation email a participant sends to friends. Applies only when the program sends invites on the company's behalf (Design > Share > Invite, with your company as the sender). Its `useCompanyReplyTo` field sets whether replies go to your company or to the participant who sent the invite. Available for both referral and affiliate programs."},"loginLink":{"$ref":"#/components/schemas/CampaignEmailTemplate","description":"The one-time sign-in link emailed to returning participants. Applies when participant sign-in is required (in Options). Labeled \"One-Time Login Link\" in the Program Editor. This is a transactional email, so its on/off toggle cannot be changed. Available for both referral and affiliate programs."},"paypalEmailConfirmation":{"$ref":"#/components/schemas/CampaignEmailTemplate","description":"Asks a participant to set or confirm the PayPal email address where they will receive payouts. Applies when the confirm-email setting is on in the PayPal integration. This is a transactional email, so its on/off toggle cannot be changed. Available for both referral and affiliate programs."},"taxInfoMissing":{"$ref":"#/components/schemas/CampaignEmailTemplate","description":"Asks a participant to submit the tax information required before they can be paid. Sends only when the program collects tax information. Its on/off toggle cannot be changed. Available for both referral and affiliate programs."},"taxInfoReceived":{"$ref":"#/components/schemas/CampaignEmailTemplate","description":"Confirms to a participant that the tax information they submitted was received. Its on/off toggle cannot be changed. Available for both referral and affiliate programs."},"taxInfoApproved":{"$ref":"#/components/schemas/CampaignEmailTemplate","description":"Tells a participant that their tax form is complete and approved. Labeled \"Tax Form Complete\" in the Program Editor. Its on/off toggle cannot be changed. Available for both referral and affiliate programs."},"taxInfoRejected":{"$ref":"#/components/schemas/CampaignEmailTemplate","description":"Tells a participant that their tax information was rejected and needs to be resubmitted. Its on/off toggle cannot be changed. Available for both referral and affiliate programs."},"settings":{"$ref":"#/components/schemas/CampaignEmailSettings","description":"Sender, contact, and design settings for the program's emails (the Emails > Settings sub-page)."}}},"CampaignEmailTemplate":{"type":"object","description":"A single editable email template. `subject` and `preheader` are capped at 255 characters; `body` is HTML capped at 150000 characters.","properties":{"subject":{"type":"string","maxLength":255,"description":"The email's subject line. Supports dynamic text (`{{...}}` tokens), the same as the body."},"preheader":{"type":"string","maxLength":255,"description":"The preview text shown after the subject line in most inboxes."},"body":{"type":"string","maxLength":150000,"description":"The email body as HTML. You can personalize it with dynamic text, inserting `{{...}}` tokens like `{{firstName}}` or `{{shareUrl}}` to tailor each email to its recipient. See [Guide to using dynamic text in GrowSurf emails](https://support.growsurf.com/article/213-guide-to-using-dynamic-text-in-growsurf-emails)."},"isEnabled":{"type":"boolean","description":"Whether this email is enabled. Read-only for transactional and invite emails (only promotional emails can be toggled) — sending it for those emails returns a `400`."},"useCompanyReplyTo":{"type":"boolean","description":"Only applicable to the `invite` email. When `true`, replies go to your company's reply-to address instead of the referring participant, which keeps the participant's email address private (it is never exposed to the people they invite). When `false`, replies go to the referring participant."}}},"CampaignEmailSettings":{"type":"object","description":"Email sender, contact, and design settings (the Emails → Settings sub-page).","properties":{"sender":{"description":"Sender name and reply-to settings for program emails.","$ref":"#/components/schemas/CampaignEmailSenderSettings"},"contact":{"$ref":"#/components/schemas/CampaignEmailContactSettings"},"design":{"description":"Design settings shared across program emails.","$ref":"#/components/schemas/CampaignEmailDesignSettings"}}},"CampaignEmailSenderSettings":{"type":"object","properties":{"fromName":{"type":"string","maxLength":100,"description":"The email sender name. Required; cannot be an email address."},"replyToEmail":{"type":"string","maxLength":100,"description":"The reply-to email address. Required; must be a valid email address."},"fromEmail":{"type":"string","readOnly":true,"description":"The from email address. Read-only — setting a custom from-address requires domain verification in the dashboard."}}},"CampaignEmailContactSettings":{"type":"object","description":"The physical mailing address shown in your email footers (required by anti-spam laws such as the US CAN-SPAM Act).","properties":{"companyName":{"type":"string","maxLength":255,"description":"Required."},"addressLine1":{"type":"string","maxLength":255,"description":"Required."},"addressLine2":{"description":"Second address line shown in email footers.","type":["string","null"],"maxLength":255},"city":{"type":"string","maxLength":255,"description":"Required."},"state":{"description":"State, province, or region shown in email footers.","type":["string","null"],"maxLength":255},"postalCode":{"description":"Postal or ZIP code shown in email footers.","type":["string","null"],"maxLength":100},"country":{"type":["string","null"],"maxLength":100,"description":"Free-text country (not validated as an ISO code)."}}},"CampaignEmailDesignSettings":{"type":"object","properties":{"header":{"type":["string","null"],"maxLength":150000,"description":"Email header HTML."},"footer":{"type":["string","null"],"maxLength":150000,"description":"Email footer HTML."},"unsubscribePromotional":{"type":"string","maxLength":150000,"description":"Unsubscribe footer for promotional emails. Must contain the tokens `{{unsubscribeLink}}`, `{{companyName}}`, and `{{address}}`."},"unsubscribeInvite":{"type":"string","maxLength":150000,"description":"Unsubscribe footer for invite emails. Must contain the tokens `{{unsubscribeLink}}`, `{{companyName}}`, and `{{address}}`."},"unsubscribeTransactional":{"type":"string","maxLength":150000,"description":"Footer for transactional emails. Must contain the tokens `{{companyName}}` and `{{address}}`."}}},"Error":{"type":"object","properties":{"name":{"description":"Error name returned for the failed request.","type":"string"},"code":{"description":"Stable machine-readable error code.","type":"string"},"message":{"description":"Human-readable error message.","type":"string"},"errors":{"description":"Optional validation details for specific request fields.","type":"array","items":{"type":"object","additionalProperties":true}},"status":{"description":"HTTP status code for the error.","type":"integer"},"supportUrl":{"description":"Support URL related to the error, when available.","type":"string","format":"uri"},"policyName":{"description":"Rate-limit policy name for `429` errors, when available.","type":"string"},"level":{"description":"Error severity level, when available.","type":"string"},"timestamp":{"description":"When the error response was created.","type":"string","format":"date-time"}}}},"responses":{"BadRequest":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The API key is missing, invalid, revoked, outside its scope, or not allowed to perform this action.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Too many requests.","headers":{"GrowSurf-RateLimit-Second-Limit":{"description":"Number of API requests allowed per second policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Second-Remaining":{"description":"Number of API requests remaining in the second policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Second-Milliseconds":{"description":"Milliseconds until the second policy window resets.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Minute-Limit":{"description":"Number of API requests allowed per minute policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Minute-Remaining":{"description":"Number of API requests remaining in the minute policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Minute-Milliseconds":{"description":"Milliseconds until the minute policy window resets.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Hour-Limit":{"description":"Number of API requests allowed per hour policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Hour-Remaining":{"description":"Number of API requests remaining in the hour policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Hour-Milliseconds":{"description":"Milliseconds until the hour policy window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/campaign/{id}/emails":{"get":{"tags":["Campaigns"],"operationId":"retrieveCampaignEmails","summary":"Retrieve campaign emails","description":"Retrieves a program's email configuration — the same surface as the dashboard Program Editor's **Emails** tab. Returns each editable email template (`subject`, `preheader`, `body`, `isEnabled`) plus the `settings` block (sender, contact, and design). The set of email templates returned depends on the program type (referral vs affiliate).","parameters":[{"$ref":"#/components/parameters/CampaignId"}],"responses":{"200":{"description":"Campaign emails configuration returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CampaignEmails"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}}}} ``` ## Update campaign emails > Updates a program's email configuration. Only the fields you send are changed; omitted fields are left untouched. You may only write the email templates the dashboard exposes for the program type — writing a template that is not available for the program type returns a \`400\`. Some fields are read-only (\`settings.sender.fromEmail\`, whose custom value requires dashboard domain verification). ```json {"openapi":"3.1.0","info":{"title":"GrowSurf REST API","version":"2.0.0"},"tags":[{"name":"Campaigns","description":"Program retrieval, listing, creation, updates, cloning, and configuration (design, emails, options, installation, and campaign rewards)."}],"servers":[{"url":"https://api.growsurf.com/v2","description":"Production"}],"security":[{"apiKeyAuth":[]}],"components":{"securitySchemes":{"apiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"API key","description":"GrowSurf REST API key supplied as `Authorization: Bearer `."}},"parameters":{"CampaignId":{"name":"id","in":"path","required":true,"description":"GrowSurf program ID.","schema":{"type":"string"}}},"schemas":{"CampaignEmails":{"type":"object","description":"A program's email configuration (the dashboard Program Editor's Emails tab). Each property is an editable email template; the set of templates available depends on the program type (referral vs affiliate), and writing a template that is not available for the program type returns a `400`. The `settings` object holds sender, contact, and design settings. To see the full object with every template and its current values, `GET` this resource, then `PATCH` back only the fields you want to change.","properties":{"welcomeNonReferred":{"$ref":"#/components/schemas/CampaignEmailTemplate","description":"Welcome email sent to a participant who joins on their own, without being referred. Available for both referral and affiliate programs."},"welcomeReferred":{"$ref":"#/components/schemas/CampaignEmailTemplate","description":"Welcome email sent to someone who signs up through another participant's referral link (also covers referrals you add from the dashboard). Referral programs only."},"referralLinkViewedFirstTime":{"$ref":"#/components/schemas/CampaignEmailTemplate","description":"Sent to a participant the first time their referral link is viewed. It goes out only once. Available for both referral and affiliate programs."},"referralLinkUsed":{"$ref":"#/components/schemas/CampaignEmailTemplate","description":"Sent to a referrer when they earn referral credit because someone they referred completed the qualifying action. Most useful when a reward needs more than one referral to unlock. Labeled \"Referral Credit Received\" in the Program Editor. Referral programs only."},"referredSignup":{"$ref":"#/components/schemas/CampaignEmailTemplate","description":"Sent to a referrer each time someone signs up using their referral link. Labeled \"Referral Link Used\" in the Program Editor. Available for both referral and affiliate programs."},"goalAchieved":{"$ref":"#/components/schemas/CampaignEmailTemplate","description":"Sent to a participant when they unlock a reward (and to the referred friend as well, for double-sided rewards). Labeled \"Reward Unlocked\" in the Program Editor. Referral programs only."},"campaignEndedWinners":{"$ref":"#/components/schemas/CampaignEmailTemplate","description":"Sent to every participant who unlocked at least one reward, once the program ends. Referral programs only."},"campaignEndedNonWinners":{"$ref":"#/components/schemas/CampaignEmailTemplate","description":"Sent to every participant who did not unlock a reward, once the program ends. Referral programs only."},"progressUpdateMonthly":{"$ref":"#/components/schemas/CampaignEmailTemplate","description":"A month-end summary emailed to participants recapping how they are doing in the program. Available for both referral and affiliate programs."},"commissionGenerated":{"$ref":"#/components/schemas/CampaignEmailTemplate","description":"Sent to an affiliate when they earn a new commission, for example when a customer they referred makes a purchase. Affiliate programs only."},"commissionAdjusted":{"$ref":"#/components/schemas/CampaignEmailTemplate","description":"Sent to an affiliate when one of their commissions is adjusted because of a full refund, partial refund, or chargeback. Affiliate programs only."},"payoutPending":{"$ref":"#/components/schemas/CampaignEmailTemplate","description":"Sent to an affiliate when a batch payment is started and they have a payout on the way. Affiliate programs only."},"payoutSentSuccess":{"$ref":"#/components/schemas/CampaignEmailTemplate","description":"Sent to an affiliate when their payout completes successfully. Labeled \"Payout Sent Successfully\" in the Program Editor. Affiliate programs only."},"invite":{"$ref":"#/components/schemas/CampaignEmailTemplate","description":"The invitation email a participant sends to friends. Applies only when the program sends invites on the company's behalf (Design > Share > Invite, with your company as the sender). Its `useCompanyReplyTo` field sets whether replies go to your company or to the participant who sent the invite. Available for both referral and affiliate programs."},"loginLink":{"$ref":"#/components/schemas/CampaignEmailTemplate","description":"The one-time sign-in link emailed to returning participants. Applies when participant sign-in is required (in Options). Labeled \"One-Time Login Link\" in the Program Editor. This is a transactional email, so its on/off toggle cannot be changed. Available for both referral and affiliate programs."},"paypalEmailConfirmation":{"$ref":"#/components/schemas/CampaignEmailTemplate","description":"Asks a participant to set or confirm the PayPal email address where they will receive payouts. Applies when the confirm-email setting is on in the PayPal integration. This is a transactional email, so its on/off toggle cannot be changed. Available for both referral and affiliate programs."},"taxInfoMissing":{"$ref":"#/components/schemas/CampaignEmailTemplate","description":"Asks a participant to submit the tax information required before they can be paid. Sends only when the program collects tax information. Its on/off toggle cannot be changed. Available for both referral and affiliate programs."},"taxInfoReceived":{"$ref":"#/components/schemas/CampaignEmailTemplate","description":"Confirms to a participant that the tax information they submitted was received. Its on/off toggle cannot be changed. Available for both referral and affiliate programs."},"taxInfoApproved":{"$ref":"#/components/schemas/CampaignEmailTemplate","description":"Tells a participant that their tax form is complete and approved. Labeled \"Tax Form Complete\" in the Program Editor. Its on/off toggle cannot be changed. Available for both referral and affiliate programs."},"taxInfoRejected":{"$ref":"#/components/schemas/CampaignEmailTemplate","description":"Tells a participant that their tax information was rejected and needs to be resubmitted. Its on/off toggle cannot be changed. Available for both referral and affiliate programs."},"settings":{"$ref":"#/components/schemas/CampaignEmailSettings","description":"Sender, contact, and design settings for the program's emails (the Emails > Settings sub-page)."}}},"CampaignEmailTemplate":{"type":"object","description":"A single editable email template. `subject` and `preheader` are capped at 255 characters; `body` is HTML capped at 150000 characters.","properties":{"subject":{"type":"string","maxLength":255,"description":"The email's subject line. Supports dynamic text (`{{...}}` tokens), the same as the body."},"preheader":{"type":"string","maxLength":255,"description":"The preview text shown after the subject line in most inboxes."},"body":{"type":"string","maxLength":150000,"description":"The email body as HTML. You can personalize it with dynamic text, inserting `{{...}}` tokens like `{{firstName}}` or `{{shareUrl}}` to tailor each email to its recipient. See [Guide to using dynamic text in GrowSurf emails](https://support.growsurf.com/article/213-guide-to-using-dynamic-text-in-growsurf-emails)."},"isEnabled":{"type":"boolean","description":"Whether this email is enabled. Read-only for transactional and invite emails (only promotional emails can be toggled) — sending it for those emails returns a `400`."},"useCompanyReplyTo":{"type":"boolean","description":"Only applicable to the `invite` email. When `true`, replies go to your company's reply-to address instead of the referring participant, which keeps the participant's email address private (it is never exposed to the people they invite). When `false`, replies go to the referring participant."}}},"CampaignEmailSettings":{"type":"object","description":"Email sender, contact, and design settings (the Emails → Settings sub-page).","properties":{"sender":{"description":"Sender name and reply-to settings for program emails.","$ref":"#/components/schemas/CampaignEmailSenderSettings"},"contact":{"$ref":"#/components/schemas/CampaignEmailContactSettings"},"design":{"description":"Design settings shared across program emails.","$ref":"#/components/schemas/CampaignEmailDesignSettings"}}},"CampaignEmailSenderSettings":{"type":"object","properties":{"fromName":{"type":"string","maxLength":100,"description":"The email sender name. Required; cannot be an email address."},"replyToEmail":{"type":"string","maxLength":100,"description":"The reply-to email address. Required; must be a valid email address."},"fromEmail":{"type":"string","readOnly":true,"description":"The from email address. Read-only — setting a custom from-address requires domain verification in the dashboard."}}},"CampaignEmailContactSettings":{"type":"object","description":"The physical mailing address shown in your email footers (required by anti-spam laws such as the US CAN-SPAM Act).","properties":{"companyName":{"type":"string","maxLength":255,"description":"Required."},"addressLine1":{"type":"string","maxLength":255,"description":"Required."},"addressLine2":{"description":"Second address line shown in email footers.","type":["string","null"],"maxLength":255},"city":{"type":"string","maxLength":255,"description":"Required."},"state":{"description":"State, province, or region shown in email footers.","type":["string","null"],"maxLength":255},"postalCode":{"description":"Postal or ZIP code shown in email footers.","type":["string","null"],"maxLength":100},"country":{"type":["string","null"],"maxLength":100,"description":"Free-text country (not validated as an ISO code)."}}},"CampaignEmailDesignSettings":{"type":"object","properties":{"header":{"type":["string","null"],"maxLength":150000,"description":"Email header HTML."},"footer":{"type":["string","null"],"maxLength":150000,"description":"Email footer HTML."},"unsubscribePromotional":{"type":"string","maxLength":150000,"description":"Unsubscribe footer for promotional emails. Must contain the tokens `{{unsubscribeLink}}`, `{{companyName}}`, and `{{address}}`."},"unsubscribeInvite":{"type":"string","maxLength":150000,"description":"Unsubscribe footer for invite emails. Must contain the tokens `{{unsubscribeLink}}`, `{{companyName}}`, and `{{address}}`."},"unsubscribeTransactional":{"type":"string","maxLength":150000,"description":"Footer for transactional emails. Must contain the tokens `{{companyName}}` and `{{address}}`."}}},"Error":{"type":"object","properties":{"name":{"description":"Error name returned for the failed request.","type":"string"},"code":{"description":"Stable machine-readable error code.","type":"string"},"message":{"description":"Human-readable error message.","type":"string"},"errors":{"description":"Optional validation details for specific request fields.","type":"array","items":{"type":"object","additionalProperties":true}},"status":{"description":"HTTP status code for the error.","type":"integer"},"supportUrl":{"description":"Support URL related to the error, when available.","type":"string","format":"uri"},"policyName":{"description":"Rate-limit policy name for `429` errors, when available.","type":"string"},"level":{"description":"Error severity level, when available.","type":"string"},"timestamp":{"description":"When the error response was created.","type":"string","format":"date-time"}}}},"responses":{"BadRequest":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The API key is missing, invalid, revoked, outside its scope, or not allowed to perform this action.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Too many requests.","headers":{"GrowSurf-RateLimit-Second-Limit":{"description":"Number of API requests allowed per second policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Second-Remaining":{"description":"Number of API requests remaining in the second policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Second-Milliseconds":{"description":"Milliseconds until the second policy window resets.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Minute-Limit":{"description":"Number of API requests allowed per minute policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Minute-Remaining":{"description":"Number of API requests remaining in the minute policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Minute-Milliseconds":{"description":"Milliseconds until the minute policy window resets.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Hour-Limit":{"description":"Number of API requests allowed per hour policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Hour-Remaining":{"description":"Number of API requests remaining in the hour policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Hour-Milliseconds":{"description":"Milliseconds until the hour policy window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/campaign/{id}/emails":{"patch":{"tags":["Campaigns"],"operationId":"updateCampaignEmails","summary":"Update campaign emails","description":"Updates a program's email configuration. Only the fields you send are changed; omitted fields are left untouched. You may only write the email templates the dashboard exposes for the program type — writing a template that is not available for the program type returns a `400`. Some fields are read-only (`settings.sender.fromEmail`, whose custom value requires dashboard domain verification).","parameters":[{"$ref":"#/components/parameters/CampaignId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CampaignEmails"}}}},"responses":{"200":{"description":"Campaign emails configuration updated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CampaignEmails"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}}}} ``` *** ## CAMPAIGN OPTIONS ↓ {% hint style="info" %} Read or update a program's **Options** tab — reward/fraud approval, anti-fraud lists and toggles, referral cookie/credit windows, reCAPTCHA, payout threshold + tax settings (affiliate programs only), and notification-email settings. `PATCH` is a partial merge (send only what you want to change). Some fields are program-type specific (`requireManualRewardApproval`/`autoFulfillRewards` are referral program only; `payoutThreshold`/`taxDocumentation` are affiliate-only). `fraud.recaptcha.secretKey` is write-only (never returned), and `referralCreditWindowDays: null` means the credit never expires. {% endhint %} ## Retrieve campaign options > Retrieves a program's options — the same surface as the dashboard Program Editor's \*\*Options\*\* tab. Includes reward/fraud approval, anti-fraud lists + toggles, referral cookie/credit windows, reCAPTCHA, payout threshold + tax settings (affiliate only), and notification-email settings. \`fraud.recaptcha.secretKey\` is never returned. ```json {"openapi":"3.1.0","info":{"title":"GrowSurf REST API","version":"2.0.0"},"tags":[{"name":"Campaigns","description":"Program retrieval, listing, creation, updates, cloning, and configuration (design, emails, options, installation, and campaign rewards)."}],"servers":[{"url":"https://api.growsurf.com/v2","description":"Production"}],"security":[{"apiKeyAuth":[]}],"components":{"securitySchemes":{"apiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"API key","description":"GrowSurf REST API key supplied as `Authorization: Bearer `."}},"parameters":{"CampaignId":{"name":"id","in":"path","required":true,"description":"GrowSurf program ID.","schema":{"type":"string"}}},"schemas":{"CampaignOptions":{"type":"object","description":"A program's options (the dashboard Program Editor's Options tab). To see the full object with every field and its current value, `GET` this resource, then `PATCH` back only the fields you want to change. Some fields are program-type specific (see the per-field notes).","properties":{"requireManualRewardApproval":{"type":"boolean","description":"Referral programs only. When `true`, each reward a participant earns is held for you to manually approve before it unlocks (and before the reward-won email is sent); when `false`, earned rewards are approved automatically. Cannot be `true` together with `autoFulfillRewards`."},"autoFulfillRewards":{"type":"boolean","description":"Referral programs only. When `true`, rewards a participant earns are automatically marked as fulfilled (issued) instead of you marking each one by hand, usually paired with an automated reward-delivery integration. Cannot be `true` together with `requireManualRewardApproval`."},"requireManualFraudApproval":{"type":"boolean","description":"When `true`, no signup is automatically blocked for fraud. Every participant is allowed to join, and any suspected fraud is flagged in your dashboard for you to review. Cannot be `true` together with `autoBlockFraud`."},"autoBlockFraud":{"type":"boolean","description":"When `true`, signups flagged as high fraud risk are automatically blocked from joining; when `false`, they are allowed in and flagged in your dashboard for review. Cannot be `true` together with `requireManualFraudApproval`."},"requireParticipantAuth":{"type":"boolean","description":"Require returning participants to authenticate. Affiliate programs require this to be `true`."},"enforceGdprCompliance":{"type":"boolean","description":"When `true`, GrowSurf stores only the minimum participant data needed to help you meet GDPR/CCPA requirements — it does not store IP addresses, browser fingerprints, or mobile instance IDs. The anti-fraud checks that rely on those signals no longer apply while this is on."},"blockPaidAdsTraffic":{"type":"boolean","description":"When `true`, referrals from visitors who arrived through paid ads (for example Google or Facebook ads) are not attributed, so the referring participant is not credited for them. Recommended so participants don't compete with you for your own paid keywords."},"referralCookieWindowDays":{"type":"integer","enum":[1,3,7,14,30,60,90,180,365,400],"description":"How long, in days, a referral-link click is remembered in the visitor's browser. If the visitor signs up within this window, the referral is credited to the participant whose link they clicked."},"referralCreditWindowDays":{"type":["integer","null"],"enum":[1,3,7,14,30,60,90,180,365,null],"description":"How long, in days, a referred friend has to complete a qualifying action for their referrer to earn credit and unlock a reward. After this window the referral no longer counts toward rewards. `null` = never expires."},"payoutThreshold":{"type":["integer","null"],"minimum":0,"description":"Affiliate programs only. Minimum payout in the program's currency minor units (`0` or `null` = no minimum). Requires `currencyISO` to be set."},"fraud":{"$ref":"#/components/schemas/CampaignOptionsFraud","description":"Anti-fraud settings — block and allow lists for emails, IPs, and countries; toggles for blocking burner emails, data-center IPs, and referrals from high-risk referrers; per-IP signup rate limits; and reCAPTCHA."},"taxDocumentation":{"$ref":"#/components/schemas/CampaignOptionsTaxDocumentation","description":"Affiliate programs only. Your company's billing details (name, address, and VAT number) used on affiliate payout invoices and for VAT handling."},"notificationEmails":{"$ref":"#/components/schemas/CampaignOptionsNotificationEmails","description":"Owner notification-email settings — who receives program notifications and which events they are notified about."}}},"CampaignOptionsFraud":{"type":"object","description":"Anti-fraud settings.","properties":{"blockedEmails":{"type":"array","items":{"type":"string","maxLength":100},"description":"Blocked emails (wildcards allowed). Max 10000. Replaces the whole list."},"blockedIps":{"type":"array","items":{"type":"string","maxLength":100},"description":"Blocked IP addresses (wildcards allowed). Max 10000."},"blockedCountries":{"type":"array","items":{"type":"string","maxLength":100},"description":"Blocked countries (ISO 3166-1 alpha-2 codes)."},"allowedEmails":{"description":"Allowed email addresses or patterns. Replaces the whole list.","type":"array","items":{"type":"string","maxLength":100}},"allowedIps":{"description":"Allowed IP addresses or patterns. Replaces the whole list.","type":"array","items":{"type":"string","maxLength":100}},"allowedCountries":{"type":"array","items":{"type":"string","maxLength":100},"description":"Allowed countries (ISO 3166-1 alpha-2 codes)."},"blockBurnerEmails":{"description":"Whether signups from burner or disposable email addresses are blocked.","type":"boolean"},"blockDataCenterIps":{"description":"Whether signups from known data-center IP addresses are blocked.","type":"boolean"},"blockHighRiskReferrers":{"description":"Whether referrals from participants marked as high fraud risk are blocked.","type":"boolean"},"autoBlockHighRiskIps":{"description":"Whether high-risk signup IP addresses are added to the blocked IP list automatically.","type":"boolean"},"maxSignupsPerIp2Min":{"description":"Maximum signups allowed from one IP address in a 2-minute window.","type":"integer","minimum":1,"maximum":100},"maxSignupsPerIp10Min":{"description":"Maximum signups allowed from one IP address in a 10-minute window.","type":"integer","minimum":1,"maximum":100},"recaptcha":{"description":"reCAPTCHA settings for signup forms.","$ref":"#/components/schemas/CampaignOptionsRecaptcha"}}},"CampaignOptionsRecaptcha":{"type":"object","properties":{"isEnabled":{"description":"Whether reCAPTCHA is enabled on signup forms.","type":"boolean"},"siteKey":{"description":"Public reCAPTCHA site key used by the signup form.","type":["string","null"],"maxLength":100},"secretKey":{"type":["string","null"],"maxLength":100,"writeOnly":true,"description":"The reCAPTCHA secret key. Write-only — never returned by GET."}}},"CampaignOptionsTaxDocumentation":{"type":"object","description":"Affiliate programs only. Your company's billing details (name, address, and VAT number) used on affiliate payout invoices and for VAT handling.","properties":{"companyName":{"description":"Legal or billing company name used on affiliate payout invoices.","type":["string","null"],"maxLength":255},"vatNumber":{"description":"Your company VAT number, when VAT collection applies.","type":["string","null"],"maxLength":100},"addressLine1":{"description":"First line of the company address used on affiliate payout invoices.","type":["string","null"],"maxLength":255},"addressLine2":{"description":"Second line of the company address used on affiliate payout invoices.","type":["string","null"],"maxLength":255},"city":{"description":"City for the company address used on affiliate payout invoices.","type":["string","null"],"maxLength":255},"state":{"description":"State, province, or region for the company address used on affiliate payout invoices.","type":["string","null"],"maxLength":255},"postalCode":{"description":"Postal or ZIP code for the company address used on affiliate payout invoices.","type":["string","null"],"maxLength":100},"country":{"type":["string","null"],"description":"ISO 3166-1 alpha-2 country code."},"collectAffiliateVat":{"type":"boolean","description":"Requires `vatNumber` to be set."}}},"CampaignOptionsNotificationEmails":{"type":"object","description":"Owner notification-email settings.","properties":{"recipients":{"type":"array","items":{"type":"string"},"description":"Email addresses that receive program notifications."},"events":{"type":"object","description":"Per-event on/off toggles. The available events depend on the program type.","properties":{"PARTICIPANT_REACHED_A_GOAL":{"description":"Notify recipients when a participant unlocks a reward.","type":"boolean"},"NEW_PARTICIPANT_ADDED_NON_REFERRED":{"description":"Notify recipients when a participant joins without being referred.","type":"boolean"},"NEW_PARTICIPANT_ADDED_REFERRED":{"description":"Notify recipients when a participant joins through a referral link.","type":"boolean"},"CAMPAIGN_ENDED":{"description":"Notify recipients when the program ends.","type":"boolean"},"WEEKLY_PERFORMANCE_REPORT":{"description":"Send recipients the weekly performance report.","type":"boolean"},"MONTHLY_PERFORMANCE_REPORT":{"description":"Send recipients the monthly performance report.","type":"boolean"},"NEW_COMMISSION_ADDED":{"description":"Notify recipients when an affiliate earns a new commission.","type":"boolean"},"COMMISSION_ADJUSTED":{"description":"Notify recipients when an affiliate commission is adjusted.","type":"boolean"},"NEW_PAYOUT_ISSUED":{"description":"Notify recipients when an affiliate payout is issued.","type":"boolean"},"AFFILIATE_BATCH_PAYOUT_COMPLETED":{"description":"Notify recipients when an affiliate payout batch completes.","type":"boolean"},"MONTHLY_PAYOUT_REMINDER":{"description":"Send recipients the monthly affiliate payout reminder.","type":"boolean"}}}}},"Error":{"type":"object","properties":{"name":{"description":"Error name returned for the failed request.","type":"string"},"code":{"description":"Stable machine-readable error code.","type":"string"},"message":{"description":"Human-readable error message.","type":"string"},"errors":{"description":"Optional validation details for specific request fields.","type":"array","items":{"type":"object","additionalProperties":true}},"status":{"description":"HTTP status code for the error.","type":"integer"},"supportUrl":{"description":"Support URL related to the error, when available.","type":"string","format":"uri"},"policyName":{"description":"Rate-limit policy name for `429` errors, when available.","type":"string"},"level":{"description":"Error severity level, when available.","type":"string"},"timestamp":{"description":"When the error response was created.","type":"string","format":"date-time"}}}},"responses":{"BadRequest":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The API key is missing, invalid, revoked, outside its scope, or not allowed to perform this action.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Too many requests.","headers":{"GrowSurf-RateLimit-Second-Limit":{"description":"Number of API requests allowed per second policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Second-Remaining":{"description":"Number of API requests remaining in the second policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Second-Milliseconds":{"description":"Milliseconds until the second policy window resets.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Minute-Limit":{"description":"Number of API requests allowed per minute policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Minute-Remaining":{"description":"Number of API requests remaining in the minute policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Minute-Milliseconds":{"description":"Milliseconds until the minute policy window resets.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Hour-Limit":{"description":"Number of API requests allowed per hour policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Hour-Remaining":{"description":"Number of API requests remaining in the hour policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Hour-Milliseconds":{"description":"Milliseconds until the hour policy window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/campaign/{id}/options":{"get":{"tags":["Campaigns"],"operationId":"retrieveCampaignOptions","summary":"Retrieve campaign options","description":"Retrieves a program's options — the same surface as the dashboard Program Editor's **Options** tab. Includes reward/fraud approval, anti-fraud lists + toggles, referral cookie/credit windows, reCAPTCHA, payout threshold + tax settings (affiliate only), and notification-email settings. `fraud.recaptcha.secretKey` is never returned.","parameters":[{"$ref":"#/components/parameters/CampaignId"}],"responses":{"200":{"description":"Campaign options returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CampaignOptions"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}}}} ``` ## Update campaign options > Updates a program's options. Only the fields you send are changed. Some fields are program-type specific (\`requireManualRewardApproval\`/\`autoFulfillRewards\` are referral-only; \`payoutThreshold\`/\`taxDocumentation\` are affiliate-only, and affiliate programs require \`requireParticipantAuth: true\`). \`fraud.recaptcha.secretKey\` is write-only. \`referralCreditWindowDays: null\` means "never expires". ```json {"openapi":"3.1.0","info":{"title":"GrowSurf REST API","version":"2.0.0"},"tags":[{"name":"Campaigns","description":"Program retrieval, listing, creation, updates, cloning, and configuration (design, emails, options, installation, and campaign rewards)."}],"servers":[{"url":"https://api.growsurf.com/v2","description":"Production"}],"security":[{"apiKeyAuth":[]}],"components":{"securitySchemes":{"apiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"API key","description":"GrowSurf REST API key supplied as `Authorization: Bearer `."}},"parameters":{"CampaignId":{"name":"id","in":"path","required":true,"description":"GrowSurf program ID.","schema":{"type":"string"}}},"schemas":{"CampaignOptions":{"type":"object","description":"A program's options (the dashboard Program Editor's Options tab). To see the full object with every field and its current value, `GET` this resource, then `PATCH` back only the fields you want to change. Some fields are program-type specific (see the per-field notes).","properties":{"requireManualRewardApproval":{"type":"boolean","description":"Referral programs only. When `true`, each reward a participant earns is held for you to manually approve before it unlocks (and before the reward-won email is sent); when `false`, earned rewards are approved automatically. Cannot be `true` together with `autoFulfillRewards`."},"autoFulfillRewards":{"type":"boolean","description":"Referral programs only. When `true`, rewards a participant earns are automatically marked as fulfilled (issued) instead of you marking each one by hand, usually paired with an automated reward-delivery integration. Cannot be `true` together with `requireManualRewardApproval`."},"requireManualFraudApproval":{"type":"boolean","description":"When `true`, no signup is automatically blocked for fraud. Every participant is allowed to join, and any suspected fraud is flagged in your dashboard for you to review. Cannot be `true` together with `autoBlockFraud`."},"autoBlockFraud":{"type":"boolean","description":"When `true`, signups flagged as high fraud risk are automatically blocked from joining; when `false`, they are allowed in and flagged in your dashboard for review. Cannot be `true` together with `requireManualFraudApproval`."},"requireParticipantAuth":{"type":"boolean","description":"Require returning participants to authenticate. Affiliate programs require this to be `true`."},"enforceGdprCompliance":{"type":"boolean","description":"When `true`, GrowSurf stores only the minimum participant data needed to help you meet GDPR/CCPA requirements — it does not store IP addresses, browser fingerprints, or mobile instance IDs. The anti-fraud checks that rely on those signals no longer apply while this is on."},"blockPaidAdsTraffic":{"type":"boolean","description":"When `true`, referrals from visitors who arrived through paid ads (for example Google or Facebook ads) are not attributed, so the referring participant is not credited for them. Recommended so participants don't compete with you for your own paid keywords."},"referralCookieWindowDays":{"type":"integer","enum":[1,3,7,14,30,60,90,180,365,400],"description":"How long, in days, a referral-link click is remembered in the visitor's browser. If the visitor signs up within this window, the referral is credited to the participant whose link they clicked."},"referralCreditWindowDays":{"type":["integer","null"],"enum":[1,3,7,14,30,60,90,180,365,null],"description":"How long, in days, a referred friend has to complete a qualifying action for their referrer to earn credit and unlock a reward. After this window the referral no longer counts toward rewards. `null` = never expires."},"payoutThreshold":{"type":["integer","null"],"minimum":0,"description":"Affiliate programs only. Minimum payout in the program's currency minor units (`0` or `null` = no minimum). Requires `currencyISO` to be set."},"fraud":{"$ref":"#/components/schemas/CampaignOptionsFraud","description":"Anti-fraud settings — block and allow lists for emails, IPs, and countries; toggles for blocking burner emails, data-center IPs, and referrals from high-risk referrers; per-IP signup rate limits; and reCAPTCHA."},"taxDocumentation":{"$ref":"#/components/schemas/CampaignOptionsTaxDocumentation","description":"Affiliate programs only. Your company's billing details (name, address, and VAT number) used on affiliate payout invoices and for VAT handling."},"notificationEmails":{"$ref":"#/components/schemas/CampaignOptionsNotificationEmails","description":"Owner notification-email settings — who receives program notifications and which events they are notified about."}}},"CampaignOptionsFraud":{"type":"object","description":"Anti-fraud settings.","properties":{"blockedEmails":{"type":"array","items":{"type":"string","maxLength":100},"description":"Blocked emails (wildcards allowed). Max 10000. Replaces the whole list."},"blockedIps":{"type":"array","items":{"type":"string","maxLength":100},"description":"Blocked IP addresses (wildcards allowed). Max 10000."},"blockedCountries":{"type":"array","items":{"type":"string","maxLength":100},"description":"Blocked countries (ISO 3166-1 alpha-2 codes)."},"allowedEmails":{"description":"Allowed email addresses or patterns. Replaces the whole list.","type":"array","items":{"type":"string","maxLength":100}},"allowedIps":{"description":"Allowed IP addresses or patterns. Replaces the whole list.","type":"array","items":{"type":"string","maxLength":100}},"allowedCountries":{"type":"array","items":{"type":"string","maxLength":100},"description":"Allowed countries (ISO 3166-1 alpha-2 codes)."},"blockBurnerEmails":{"description":"Whether signups from burner or disposable email addresses are blocked.","type":"boolean"},"blockDataCenterIps":{"description":"Whether signups from known data-center IP addresses are blocked.","type":"boolean"},"blockHighRiskReferrers":{"description":"Whether referrals from participants marked as high fraud risk are blocked.","type":"boolean"},"autoBlockHighRiskIps":{"description":"Whether high-risk signup IP addresses are added to the blocked IP list automatically.","type":"boolean"},"maxSignupsPerIp2Min":{"description":"Maximum signups allowed from one IP address in a 2-minute window.","type":"integer","minimum":1,"maximum":100},"maxSignupsPerIp10Min":{"description":"Maximum signups allowed from one IP address in a 10-minute window.","type":"integer","minimum":1,"maximum":100},"recaptcha":{"description":"reCAPTCHA settings for signup forms.","$ref":"#/components/schemas/CampaignOptionsRecaptcha"}}},"CampaignOptionsRecaptcha":{"type":"object","properties":{"isEnabled":{"description":"Whether reCAPTCHA is enabled on signup forms.","type":"boolean"},"siteKey":{"description":"Public reCAPTCHA site key used by the signup form.","type":["string","null"],"maxLength":100},"secretKey":{"type":["string","null"],"maxLength":100,"writeOnly":true,"description":"The reCAPTCHA secret key. Write-only — never returned by GET."}}},"CampaignOptionsTaxDocumentation":{"type":"object","description":"Affiliate programs only. Your company's billing details (name, address, and VAT number) used on affiliate payout invoices and for VAT handling.","properties":{"companyName":{"description":"Legal or billing company name used on affiliate payout invoices.","type":["string","null"],"maxLength":255},"vatNumber":{"description":"Your company VAT number, when VAT collection applies.","type":["string","null"],"maxLength":100},"addressLine1":{"description":"First line of the company address used on affiliate payout invoices.","type":["string","null"],"maxLength":255},"addressLine2":{"description":"Second line of the company address used on affiliate payout invoices.","type":["string","null"],"maxLength":255},"city":{"description":"City for the company address used on affiliate payout invoices.","type":["string","null"],"maxLength":255},"state":{"description":"State, province, or region for the company address used on affiliate payout invoices.","type":["string","null"],"maxLength":255},"postalCode":{"description":"Postal or ZIP code for the company address used on affiliate payout invoices.","type":["string","null"],"maxLength":100},"country":{"type":["string","null"],"description":"ISO 3166-1 alpha-2 country code."},"collectAffiliateVat":{"type":"boolean","description":"Requires `vatNumber` to be set."}}},"CampaignOptionsNotificationEmails":{"type":"object","description":"Owner notification-email settings.","properties":{"recipients":{"type":"array","items":{"type":"string"},"description":"Email addresses that receive program notifications."},"events":{"type":"object","description":"Per-event on/off toggles. The available events depend on the program type.","properties":{"PARTICIPANT_REACHED_A_GOAL":{"description":"Notify recipients when a participant unlocks a reward.","type":"boolean"},"NEW_PARTICIPANT_ADDED_NON_REFERRED":{"description":"Notify recipients when a participant joins without being referred.","type":"boolean"},"NEW_PARTICIPANT_ADDED_REFERRED":{"description":"Notify recipients when a participant joins through a referral link.","type":"boolean"},"CAMPAIGN_ENDED":{"description":"Notify recipients when the program ends.","type":"boolean"},"WEEKLY_PERFORMANCE_REPORT":{"description":"Send recipients the weekly performance report.","type":"boolean"},"MONTHLY_PERFORMANCE_REPORT":{"description":"Send recipients the monthly performance report.","type":"boolean"},"NEW_COMMISSION_ADDED":{"description":"Notify recipients when an affiliate earns a new commission.","type":"boolean"},"COMMISSION_ADJUSTED":{"description":"Notify recipients when an affiliate commission is adjusted.","type":"boolean"},"NEW_PAYOUT_ISSUED":{"description":"Notify recipients when an affiliate payout is issued.","type":"boolean"},"AFFILIATE_BATCH_PAYOUT_COMPLETED":{"description":"Notify recipients when an affiliate payout batch completes.","type":"boolean"},"MONTHLY_PAYOUT_REMINDER":{"description":"Send recipients the monthly affiliate payout reminder.","type":"boolean"}}}}},"Error":{"type":"object","properties":{"name":{"description":"Error name returned for the failed request.","type":"string"},"code":{"description":"Stable machine-readable error code.","type":"string"},"message":{"description":"Human-readable error message.","type":"string"},"errors":{"description":"Optional validation details for specific request fields.","type":"array","items":{"type":"object","additionalProperties":true}},"status":{"description":"HTTP status code for the error.","type":"integer"},"supportUrl":{"description":"Support URL related to the error, when available.","type":"string","format":"uri"},"policyName":{"description":"Rate-limit policy name for `429` errors, when available.","type":"string"},"level":{"description":"Error severity level, when available.","type":"string"},"timestamp":{"description":"When the error response was created.","type":"string","format":"date-time"}}}},"responses":{"BadRequest":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The API key is missing, invalid, revoked, outside its scope, or not allowed to perform this action.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Too many requests.","headers":{"GrowSurf-RateLimit-Second-Limit":{"description":"Number of API requests allowed per second policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Second-Remaining":{"description":"Number of API requests remaining in the second policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Second-Milliseconds":{"description":"Milliseconds until the second policy window resets.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Minute-Limit":{"description":"Number of API requests allowed per minute policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Minute-Remaining":{"description":"Number of API requests remaining in the minute policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Minute-Milliseconds":{"description":"Milliseconds until the minute policy window resets.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Hour-Limit":{"description":"Number of API requests allowed per hour policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Hour-Remaining":{"description":"Number of API requests remaining in the hour policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Hour-Milliseconds":{"description":"Milliseconds until the hour policy window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/campaign/{id}/options":{"patch":{"tags":["Campaigns"],"operationId":"updateCampaignOptions","summary":"Update campaign options","description":"Updates a program's options. Only the fields you send are changed. Some fields are program-type specific (`requireManualRewardApproval`/`autoFulfillRewards` are referral-only; `payoutThreshold`/`taxDocumentation` are affiliate-only, and affiliate programs require `requireParticipantAuth: true`). `fraud.recaptcha.secretKey` is write-only. `referralCreditWindowDays: null` means \"never expires\".","parameters":[{"$ref":"#/components/parameters/CampaignId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CampaignOptions"}}}},"responses":{"200":{"description":"Campaign options updated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CampaignOptions"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}}}} ``` *** ## CAMPAIGN INSTALLATION ↓ {% hint style="info" %} Read or update a program's **Installation** tab (plus Mobile SDK settings) — the referral trigger (referral programs only), signup tracking method, share URL and whitelist, custom-form signup settings, and mobile SDK settings. `PATCH` is a partial merge (send only what you want to change). `mobile.publicKey` is read-only (server-generated), and any URLs you send must include an explicit `http://` or `https://` scheme. {% endhint %} ## Retrieve campaign installation > Retrieves a program's installation configuration — the same surface as the dashboard Program Editor's \*\*Installation\*\* tab (plus the Mobile SDK settings). Includes the referral trigger (referral programs only), signup tracking method, share URL and whitelist, custom-form signup settings, and mobile SDK settings. ```json {"openapi":"3.1.0","info":{"title":"GrowSurf REST API","version":"2.0.0"},"tags":[{"name":"Campaigns","description":"Program retrieval, listing, creation, updates, cloning, and configuration (design, emails, options, installation, and campaign rewards)."}],"servers":[{"url":"https://api.growsurf.com/v2","description":"Production"}],"security":[{"apiKeyAuth":[]}],"components":{"securitySchemes":{"apiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"API key","description":"GrowSurf REST API key supplied as `Authorization: Bearer `."}},"parameters":{"CampaignId":{"name":"id","in":"path","required":true,"description":"GrowSurf program ID.","schema":{"type":"string"}}},"schemas":{"CampaignInstallation":{"type":"object","description":"A program's installation configuration (the dashboard Program Editor's Installation tab). To see the full object with every field and its current value, `GET` this resource, then `PATCH` back only the fields you want to change. `referralTrigger` is only present and writable for referral programs.","properties":{"referralTrigger":{"type":"string","enum":["CUSTOM","ON_SIGNUP"],"description":"Referral programs only. Sets what a referred friend must do before a referral counts. `ON_SIGNUP` (\"Sign Up\") counts the referral as soon as they sign up. `CUSTOM` (\"Sign Up + Qualifying Action\") counts it only after they sign up and also complete a qualifying action you define, such as a first payment."},"signupEvent":{"type":"string","enum":["FORM_DETECTION","PROGRAMMATIC"],"description":"The signup tracking method. `FORM_DETECTION` = GrowSurf automatically detects submissions of an existing form on your site; `PROGRAMMATIC` = you add participants via the JavaScript/mobile SDKs or this API."},"shareUrl":{"type":"string","maxLength":500,"description":"The landing page referred friends are taken to when they click a participant's referral link — usually your homepage or a marketing page. Required; must include an `http(s)://` scheme and contain no `#`, `#!`, or `??`."},"useGrowSurfHostedLinks":{"type":"boolean","description":"When `true`, each participant's referral link becomes a GrowSurf-hosted link instead of a link to your own share URL, and clicks are routed by the visitor's device (Android to Google Play, iOS to your iOS attribution or App Store URL, desktop to your share URL). Mainly used by mobile apps. Applies to referral links everywhere they appear, including the SDKs, integrations, webhooks, the GrowSurf window, and participant exports."},"allowedUrls":{"type":"array","items":{"type":"string","maxLength":500},"description":"Extra domains, beyond your share URL, where the GrowSurf window and SDK are allowed to run — handy for testing on local or staging URLs. Adding an apex domain (e.g. `https://example.com`) also allows its subdomains. Each entry must include an `http(s)://` scheme. Sending this array replaces the entire list."},"signup":{"$ref":"#/components/schemas/CampaignInstallationSignup"},"mobile":{"$ref":"#/components/schemas/CampaignInstallationMobile"}}},"CampaignInstallationSignup":{"type":"object","description":"Custom signup-form settings (applies when the signup tracking method is `FORM_DETECTION`).","properties":{"isCustomForm":{"description":"Whether signups come from your own form instead of automatic form detection.","type":"boolean"},"url":{"type":["string","null"],"maxLength":500,"description":"The custom signup form URL. Must include an `http(s)://` scheme; no `#!` or `??`. Send `null` to clear."},"redirectAfterSignup":{"type":"boolean","description":"Whether the signup form redirects to another page after submission."},"redirectUrl":{"type":["string","null"],"maxLength":500,"description":"URL the signup form redirects to. Must include an `http(s)://` scheme. Send `null` to clear."},"trackInputFields":{"description":"Whether GrowSurf watches signup form fields for referral attribution.","type":"boolean"}}},"CampaignInstallationMobile":{"type":"object","description":"Settings for the GrowSurf iOS and Android mobile SDKs — enable the mobile SDK, the read-only publishable key, and the iOS/Android attribution and app-store URLs used to route mobile referral-link clicks.","properties":{"isEnabled":{"type":"boolean","description":"Whether the mobile SDK is enabled for the campaign."},"publicKey":{"type":"string","readOnly":true,"description":"The publishable mobile SDK key used by the GrowSurf iOS and Android SDKs. Read-only."},"iosAttributionUrl":{"type":["string","null"],"maxLength":500,"description":"iOS attribution URL. Must include an `http(s)://` scheme; no `#!` or `??`. Send `null` to clear."},"iosAppStoreUrl":{"description":"iOS App Store URL used for mobile referral links.","type":["string","null"],"maxLength":500},"androidPackageName":{"type":["string","null"],"maxLength":255,"description":"Android package name, e.g. `com.example.app` (pattern: `^[a-zA-Z][\\w]*(\\.[a-zA-Z][\\w]*)+$`)."},"androidAppStoreUrl":{"description":"Google Play Store URL used for mobile referral links.","type":["string","null"],"maxLength":500}}},"Error":{"type":"object","properties":{"name":{"description":"Error name returned for the failed request.","type":"string"},"code":{"description":"Stable machine-readable error code.","type":"string"},"message":{"description":"Human-readable error message.","type":"string"},"errors":{"description":"Optional validation details for specific request fields.","type":"array","items":{"type":"object","additionalProperties":true}},"status":{"description":"HTTP status code for the error.","type":"integer"},"supportUrl":{"description":"Support URL related to the error, when available.","type":"string","format":"uri"},"policyName":{"description":"Rate-limit policy name for `429` errors, when available.","type":"string"},"level":{"description":"Error severity level, when available.","type":"string"},"timestamp":{"description":"When the error response was created.","type":"string","format":"date-time"}}}},"responses":{"BadRequest":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The API key is missing, invalid, revoked, outside its scope, or not allowed to perform this action.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Too many requests.","headers":{"GrowSurf-RateLimit-Second-Limit":{"description":"Number of API requests allowed per second policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Second-Remaining":{"description":"Number of API requests remaining in the second policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Second-Milliseconds":{"description":"Milliseconds until the second policy window resets.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Minute-Limit":{"description":"Number of API requests allowed per minute policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Minute-Remaining":{"description":"Number of API requests remaining in the minute policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Minute-Milliseconds":{"description":"Milliseconds until the minute policy window resets.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Hour-Limit":{"description":"Number of API requests allowed per hour policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Hour-Remaining":{"description":"Number of API requests remaining in the hour policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Hour-Milliseconds":{"description":"Milliseconds until the hour policy window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/campaign/{id}/installation":{"get":{"tags":["Campaigns"],"operationId":"retrieveCampaignInstallation","summary":"Retrieve campaign installation","description":"Retrieves a program's installation configuration — the same surface as the dashboard Program Editor's **Installation** tab (plus the Mobile SDK settings). Includes the referral trigger (referral programs only), signup tracking method, share URL and whitelist, custom-form signup settings, and mobile SDK settings.","parameters":[{"$ref":"#/components/parameters/CampaignId"}],"responses":{"200":{"description":"Campaign installation configuration returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CampaignInstallation"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}}}} ``` ## Update campaign installation > Updates a program's installation configuration. Only the fields you send are changed; omitted fields are left untouched. \`referralTrigger\` is only available for referral programs. \`mobile.publicKey\` is read-only; if no key exists yet, enabling \`mobile.isEnabled\` creates one. Changing \`shareUrl\` re-resolves its redirect destinations, which may take a moment to complete. URLs must include an explicit \`http\://\` or \`https\://\` scheme. ```json {"openapi":"3.1.0","info":{"title":"GrowSurf REST API","version":"2.0.0"},"tags":[{"name":"Campaigns","description":"Program retrieval, listing, creation, updates, cloning, and configuration (design, emails, options, installation, and campaign rewards)."}],"servers":[{"url":"https://api.growsurf.com/v2","description":"Production"}],"security":[{"apiKeyAuth":[]}],"components":{"securitySchemes":{"apiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"API key","description":"GrowSurf REST API key supplied as `Authorization: Bearer `."}},"parameters":{"CampaignId":{"name":"id","in":"path","required":true,"description":"GrowSurf program ID.","schema":{"type":"string"}}},"schemas":{"CampaignInstallation":{"type":"object","description":"A program's installation configuration (the dashboard Program Editor's Installation tab). To see the full object with every field and its current value, `GET` this resource, then `PATCH` back only the fields you want to change. `referralTrigger` is only present and writable for referral programs.","properties":{"referralTrigger":{"type":"string","enum":["CUSTOM","ON_SIGNUP"],"description":"Referral programs only. Sets what a referred friend must do before a referral counts. `ON_SIGNUP` (\"Sign Up\") counts the referral as soon as they sign up. `CUSTOM` (\"Sign Up + Qualifying Action\") counts it only after they sign up and also complete a qualifying action you define, such as a first payment."},"signupEvent":{"type":"string","enum":["FORM_DETECTION","PROGRAMMATIC"],"description":"The signup tracking method. `FORM_DETECTION` = GrowSurf automatically detects submissions of an existing form on your site; `PROGRAMMATIC` = you add participants via the JavaScript/mobile SDKs or this API."},"shareUrl":{"type":"string","maxLength":500,"description":"The landing page referred friends are taken to when they click a participant's referral link — usually your homepage or a marketing page. Required; must include an `http(s)://` scheme and contain no `#`, `#!`, or `??`."},"useGrowSurfHostedLinks":{"type":"boolean","description":"When `true`, each participant's referral link becomes a GrowSurf-hosted link instead of a link to your own share URL, and clicks are routed by the visitor's device (Android to Google Play, iOS to your iOS attribution or App Store URL, desktop to your share URL). Mainly used by mobile apps. Applies to referral links everywhere they appear, including the SDKs, integrations, webhooks, the GrowSurf window, and participant exports."},"allowedUrls":{"type":"array","items":{"type":"string","maxLength":500},"description":"Extra domains, beyond your share URL, where the GrowSurf window and SDK are allowed to run — handy for testing on local or staging URLs. Adding an apex domain (e.g. `https://example.com`) also allows its subdomains. Each entry must include an `http(s)://` scheme. Sending this array replaces the entire list."},"signup":{"$ref":"#/components/schemas/CampaignInstallationSignup"},"mobile":{"$ref":"#/components/schemas/CampaignInstallationMobile"}}},"CampaignInstallationSignup":{"type":"object","description":"Custom signup-form settings (applies when the signup tracking method is `FORM_DETECTION`).","properties":{"isCustomForm":{"description":"Whether signups come from your own form instead of automatic form detection.","type":"boolean"},"url":{"type":["string","null"],"maxLength":500,"description":"The custom signup form URL. Must include an `http(s)://` scheme; no `#!` or `??`. Send `null` to clear."},"redirectAfterSignup":{"type":"boolean","description":"Whether the signup form redirects to another page after submission."},"redirectUrl":{"type":["string","null"],"maxLength":500,"description":"URL the signup form redirects to. Must include an `http(s)://` scheme. Send `null` to clear."},"trackInputFields":{"description":"Whether GrowSurf watches signup form fields for referral attribution.","type":"boolean"}}},"CampaignInstallationMobile":{"type":"object","description":"Settings for the GrowSurf iOS and Android mobile SDKs — enable the mobile SDK, the read-only publishable key, and the iOS/Android attribution and app-store URLs used to route mobile referral-link clicks.","properties":{"isEnabled":{"type":"boolean","description":"Whether the mobile SDK is enabled for the campaign."},"publicKey":{"type":"string","readOnly":true,"description":"The publishable mobile SDK key used by the GrowSurf iOS and Android SDKs. Read-only."},"iosAttributionUrl":{"type":["string","null"],"maxLength":500,"description":"iOS attribution URL. Must include an `http(s)://` scheme; no `#!` or `??`. Send `null` to clear."},"iosAppStoreUrl":{"description":"iOS App Store URL used for mobile referral links.","type":["string","null"],"maxLength":500},"androidPackageName":{"type":["string","null"],"maxLength":255,"description":"Android package name, e.g. `com.example.app` (pattern: `^[a-zA-Z][\\w]*(\\.[a-zA-Z][\\w]*)+$`)."},"androidAppStoreUrl":{"description":"Google Play Store URL used for mobile referral links.","type":["string","null"],"maxLength":500}}},"Error":{"type":"object","properties":{"name":{"description":"Error name returned for the failed request.","type":"string"},"code":{"description":"Stable machine-readable error code.","type":"string"},"message":{"description":"Human-readable error message.","type":"string"},"errors":{"description":"Optional validation details for specific request fields.","type":"array","items":{"type":"object","additionalProperties":true}},"status":{"description":"HTTP status code for the error.","type":"integer"},"supportUrl":{"description":"Support URL related to the error, when available.","type":"string","format":"uri"},"policyName":{"description":"Rate-limit policy name for `429` errors, when available.","type":"string"},"level":{"description":"Error severity level, when available.","type":"string"},"timestamp":{"description":"When the error response was created.","type":"string","format":"date-time"}}}},"responses":{"BadRequest":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The API key is missing, invalid, revoked, outside its scope, or not allowed to perform this action.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Too many requests.","headers":{"GrowSurf-RateLimit-Second-Limit":{"description":"Number of API requests allowed per second policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Second-Remaining":{"description":"Number of API requests remaining in the second policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Second-Milliseconds":{"description":"Milliseconds until the second policy window resets.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Minute-Limit":{"description":"Number of API requests allowed per minute policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Minute-Remaining":{"description":"Number of API requests remaining in the minute policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Minute-Milliseconds":{"description":"Milliseconds until the minute policy window resets.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Hour-Limit":{"description":"Number of API requests allowed per hour policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Hour-Remaining":{"description":"Number of API requests remaining in the hour policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Hour-Milliseconds":{"description":"Milliseconds until the hour policy window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/campaign/{id}/installation":{"patch":{"tags":["Campaigns"],"operationId":"updateCampaignInstallation","summary":"Update campaign installation","description":"Updates a program's installation configuration. Only the fields you send are changed; omitted fields are left untouched. `referralTrigger` is only available for referral programs. `mobile.publicKey` is read-only; if no key exists yet, enabling `mobile.isEnabled` creates one. Changing `shareUrl` re-resolves its redirect destinations, which may take a moment to complete. URLs must include an explicit `http://` or `https://` scheme.","parameters":[{"$ref":"#/components/parameters/CampaignId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CampaignInstallation"}}}},"responses":{"200":{"description":"Campaign installation configuration updated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CampaignInstallation"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}}}} ``` *** ## CAMPAIGN WEBHOOKS ↓ {% hint style="info" %} Manage a program's webhooks — the HTTP endpoints GrowSurf calls when program events occur. `secret` is write-only (used to sign the `GrowSurf-Signature` HMAC header, and never returned), each webhook has a persistent `id` (the program's default webhook is `primary`), and `events` is the array of event types the webhook is subscribed to. Use the test endpoint to send a live sample event to a saved webhook using its stored URL and secret. {% endhint %} ## List webhooks > Lists a program's webhooks (secrets are never returned). ```json {"openapi":"3.1.0","info":{"title":"GrowSurf REST API","version":"2.0.0"},"tags":[{"name":"Campaign Webhooks","description":"Program webhook configuration (create, update, delete, and test webhooks)."}],"servers":[{"url":"https://api.growsurf.com/v2","description":"Production"}],"security":[{"apiKeyAuth":[]}],"components":{"securitySchemes":{"apiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"API key","description":"GrowSurf REST API key supplied as `Authorization: Bearer `."}},"parameters":{"CampaignId":{"name":"id","in":"path","required":true,"description":"GrowSurf program ID.","schema":{"type":"string"}}},"schemas":{"WebhookListResponse":{"type":"object","required":["webhooks"],"properties":{"webhooks":{"description":"Webhooks configured for the program.","type":"array","items":{"$ref":"#/components/schemas/Webhook"}}}},"Webhook":{"type":"object","description":"A program webhook's configuration (payload URL, subscribed events, enabled state) plus read-only delivery-health fields.","required":["id","events","isEnabled","autoDisabledDueToFailures","failureCount"],"properties":{"id":{"type":"string","readOnly":true,"description":"The webhook id (`primary` for the program's primary webhook)."},"payloadUrl":{"type":"string","nullable":true,"description":"The URL that receives webhook deliveries."},"events":{"description":"Webhook events this endpoint is subscribed to.","type":"array","items":{"$ref":"#/components/schemas/WebhookEvent"}},"isEnabled":{"description":"Whether deliveries to this webhook are enabled.","type":"boolean"},"autoDisabledDueToFailures":{"type":"boolean","readOnly":true,"description":"Read-only. Whether GrowSurf auto-disabled this webhook after repeated delivery failures."},"failureCount":{"type":"integer","readOnly":true,"description":"Read-only. Consecutive delivery failures."},"lastFailureAt":{"type":"integer","format":"int64","nullable":true,"readOnly":true,"description":"Read-only. When the last delivery failure occurred, as a Unix timestamp in milliseconds."}}},"WebhookEvent":{"type":"string","description":"A webhook event name (the events GrowSurf delivers to subscribed webhooks).","enum":["PARTICIPANT_REACHED_A_GOAL","NEW_PARTICIPANT_ADDED","CAMPAIGN_ENDED","PARTICIPANT_FRAUD_STATUS_UPDATED","NEW_COMMISSION_ADDED","COMMISSION_ADJUSTED","NEW_PAYOUT_ISSUED"]},"Error":{"type":"object","properties":{"name":{"description":"Error name returned for the failed request.","type":"string"},"code":{"description":"Stable machine-readable error code.","type":"string"},"message":{"description":"Human-readable error message.","type":"string"},"errors":{"description":"Optional validation details for specific request fields.","type":"array","items":{"type":"object","additionalProperties":true}},"status":{"description":"HTTP status code for the error.","type":"integer"},"supportUrl":{"description":"Support URL related to the error, when available.","type":"string","format":"uri"},"policyName":{"description":"Rate-limit policy name for `429` errors, when available.","type":"string"},"level":{"description":"Error severity level, when available.","type":"string"},"timestamp":{"description":"When the error response was created.","type":"string","format":"date-time"}}}},"responses":{"Forbidden":{"description":"The API key is missing, invalid, revoked, outside its scope, or not allowed to perform this action.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Too many requests.","headers":{"GrowSurf-RateLimit-Second-Limit":{"description":"Number of API requests allowed per second policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Second-Remaining":{"description":"Number of API requests remaining in the second policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Second-Milliseconds":{"description":"Milliseconds until the second policy window resets.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Minute-Limit":{"description":"Number of API requests allowed per minute policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Minute-Remaining":{"description":"Number of API requests remaining in the minute policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Minute-Milliseconds":{"description":"Milliseconds until the minute policy window resets.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Hour-Limit":{"description":"Number of API requests allowed per hour policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Hour-Remaining":{"description":"Number of API requests remaining in the hour policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Hour-Milliseconds":{"description":"Milliseconds until the hour policy window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/campaign/{id}/webhooks":{"get":{"tags":["Campaign Webhooks"],"operationId":"listWebhooks","summary":"List webhooks","description":"Lists a program's webhooks (secrets are never returned).","parameters":[{"$ref":"#/components/parameters/CampaignId"}],"responses":{"200":{"description":"Webhooks returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookListResponse"}}}},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}}}} ``` ## Create webhook > Adds a webhook to the program. ```json {"openapi":"3.1.0","info":{"title":"GrowSurf REST API","version":"2.0.0"},"tags":[{"name":"Campaign Webhooks","description":"Program webhook configuration (create, update, delete, and test webhooks)."}],"servers":[{"url":"https://api.growsurf.com/v2","description":"Production"}],"security":[{"apiKeyAuth":[]}],"components":{"securitySchemes":{"apiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"API key","description":"GrowSurf REST API key supplied as `Authorization: Bearer `."}},"parameters":{"CampaignId":{"name":"id","in":"path","required":true,"description":"GrowSurf program ID.","schema":{"type":"string"}}},"schemas":{"CreateWebhookRequest":{"type":"object","required":["payloadUrl"],"additionalProperties":false,"properties":{"payloadUrl":{"type":"string","description":"The URL that receives webhook deliveries."},"events":{"type":"array","items":{"$ref":"#/components/schemas/WebhookEvent"},"default":[],"description":"The events this webhook is subscribed to. When omitted, the webhook is created subscribed to no events."},"secret":{"type":"string","writeOnly":true,"description":"Write-only. Used to sign deliveries (the `GrowSurf-Signature` HMAC header). Never returned."},"isEnabled":{"description":"Whether the webhook should start enabled. Defaults to `true`.","type":"boolean","default":true}}},"WebhookEvent":{"type":"string","description":"A webhook event name (the events GrowSurf delivers to subscribed webhooks).","enum":["PARTICIPANT_REACHED_A_GOAL","NEW_PARTICIPANT_ADDED","CAMPAIGN_ENDED","PARTICIPANT_FRAUD_STATUS_UPDATED","NEW_COMMISSION_ADDED","COMMISSION_ADJUSTED","NEW_PAYOUT_ISSUED"]},"Webhook":{"type":"object","description":"A program webhook's configuration (payload URL, subscribed events, enabled state) plus read-only delivery-health fields.","required":["id","events","isEnabled","autoDisabledDueToFailures","failureCount"],"properties":{"id":{"type":"string","readOnly":true,"description":"The webhook id (`primary` for the program's primary webhook)."},"payloadUrl":{"type":"string","nullable":true,"description":"The URL that receives webhook deliveries."},"events":{"description":"Webhook events this endpoint is subscribed to.","type":"array","items":{"$ref":"#/components/schemas/WebhookEvent"}},"isEnabled":{"description":"Whether deliveries to this webhook are enabled.","type":"boolean"},"autoDisabledDueToFailures":{"type":"boolean","readOnly":true,"description":"Read-only. Whether GrowSurf auto-disabled this webhook after repeated delivery failures."},"failureCount":{"type":"integer","readOnly":true,"description":"Read-only. Consecutive delivery failures."},"lastFailureAt":{"type":"integer","format":"int64","nullable":true,"readOnly":true,"description":"Read-only. When the last delivery failure occurred, as a Unix timestamp in milliseconds."}}},"Error":{"type":"object","properties":{"name":{"description":"Error name returned for the failed request.","type":"string"},"code":{"description":"Stable machine-readable error code.","type":"string"},"message":{"description":"Human-readable error message.","type":"string"},"errors":{"description":"Optional validation details for specific request fields.","type":"array","items":{"type":"object","additionalProperties":true}},"status":{"description":"HTTP status code for the error.","type":"integer"},"supportUrl":{"description":"Support URL related to the error, when available.","type":"string","format":"uri"},"policyName":{"description":"Rate-limit policy name for `429` errors, when available.","type":"string"},"level":{"description":"Error severity level, when available.","type":"string"},"timestamp":{"description":"When the error response was created.","type":"string","format":"date-time"}}}},"responses":{"BadRequest":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The API key is missing, invalid, revoked, outside its scope, or not allowed to perform this action.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Too many requests.","headers":{"GrowSurf-RateLimit-Second-Limit":{"description":"Number of API requests allowed per second policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Second-Remaining":{"description":"Number of API requests remaining in the second policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Second-Milliseconds":{"description":"Milliseconds until the second policy window resets.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Minute-Limit":{"description":"Number of API requests allowed per minute policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Minute-Remaining":{"description":"Number of API requests remaining in the minute policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Minute-Milliseconds":{"description":"Milliseconds until the minute policy window resets.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Hour-Limit":{"description":"Number of API requests allowed per hour policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Hour-Remaining":{"description":"Number of API requests remaining in the hour policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Hour-Milliseconds":{"description":"Milliseconds until the hour policy window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/campaign/{id}/webhooks":{"post":{"tags":["Campaign Webhooks"],"operationId":"createWebhook","summary":"Create webhook","description":"Adds a webhook to the program.","parameters":[{"$ref":"#/components/parameters/CampaignId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateWebhookRequest"}}}},"responses":{"200":{"description":"Webhook created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Webhook"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}}}} ``` ## Update webhook > Updates a webhook by id. ```json {"openapi":"3.1.0","info":{"title":"GrowSurf REST API","version":"2.0.0"},"tags":[{"name":"Campaign Webhooks","description":"Program webhook configuration (create, update, delete, and test webhooks)."}],"servers":[{"url":"https://api.growsurf.com/v2","description":"Production"}],"security":[{"apiKeyAuth":[]}],"components":{"securitySchemes":{"apiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"API key","description":"GrowSurf REST API key supplied as `Authorization: Bearer `."}},"parameters":{"CampaignId":{"name":"id","in":"path","required":true,"description":"GrowSurf program ID.","schema":{"type":"string"}},"WebhookId":{"name":"webhookId","in":"path","required":true,"description":"Webhook ID (`primary` for the program's primary webhook, or the id of an additional webhook).","schema":{"type":"string"}}},"schemas":{"UpdateWebhookRequest":{"type":"object","additionalProperties":false,"properties":{"payloadUrl":{"description":"New URL that receives webhook deliveries.","type":"string"},"events":{"description":"Replacement event subscription list for this webhook.","type":"array","items":{"$ref":"#/components/schemas/WebhookEvent"}},"secret":{"type":"string","writeOnly":true,"description":"Write-only."},"isEnabled":{"description":"Whether deliveries to this webhook are enabled.","type":"boolean"}}},"WebhookEvent":{"type":"string","description":"A webhook event name (the events GrowSurf delivers to subscribed webhooks).","enum":["PARTICIPANT_REACHED_A_GOAL","NEW_PARTICIPANT_ADDED","CAMPAIGN_ENDED","PARTICIPANT_FRAUD_STATUS_UPDATED","NEW_COMMISSION_ADDED","COMMISSION_ADJUSTED","NEW_PAYOUT_ISSUED"]},"Webhook":{"type":"object","description":"A program webhook's configuration (payload URL, subscribed events, enabled state) plus read-only delivery-health fields.","required":["id","events","isEnabled","autoDisabledDueToFailures","failureCount"],"properties":{"id":{"type":"string","readOnly":true,"description":"The webhook id (`primary` for the program's primary webhook)."},"payloadUrl":{"type":"string","nullable":true,"description":"The URL that receives webhook deliveries."},"events":{"description":"Webhook events this endpoint is subscribed to.","type":"array","items":{"$ref":"#/components/schemas/WebhookEvent"}},"isEnabled":{"description":"Whether deliveries to this webhook are enabled.","type":"boolean"},"autoDisabledDueToFailures":{"type":"boolean","readOnly":true,"description":"Read-only. Whether GrowSurf auto-disabled this webhook after repeated delivery failures."},"failureCount":{"type":"integer","readOnly":true,"description":"Read-only. Consecutive delivery failures."},"lastFailureAt":{"type":"integer","format":"int64","nullable":true,"readOnly":true,"description":"Read-only. When the last delivery failure occurred, as a Unix timestamp in milliseconds."}}},"Error":{"type":"object","properties":{"name":{"description":"Error name returned for the failed request.","type":"string"},"code":{"description":"Stable machine-readable error code.","type":"string"},"message":{"description":"Human-readable error message.","type":"string"},"errors":{"description":"Optional validation details for specific request fields.","type":"array","items":{"type":"object","additionalProperties":true}},"status":{"description":"HTTP status code for the error.","type":"integer"},"supportUrl":{"description":"Support URL related to the error, when available.","type":"string","format":"uri"},"policyName":{"description":"Rate-limit policy name for `429` errors, when available.","type":"string"},"level":{"description":"Error severity level, when available.","type":"string"},"timestamp":{"description":"When the error response was created.","type":"string","format":"date-time"}}}},"responses":{"BadRequest":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The API key is missing, invalid, revoked, outside its scope, or not allowed to perform this action.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Too many requests.","headers":{"GrowSurf-RateLimit-Second-Limit":{"description":"Number of API requests allowed per second policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Second-Remaining":{"description":"Number of API requests remaining in the second policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Second-Milliseconds":{"description":"Milliseconds until the second policy window resets.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Minute-Limit":{"description":"Number of API requests allowed per minute policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Minute-Remaining":{"description":"Number of API requests remaining in the minute policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Minute-Milliseconds":{"description":"Milliseconds until the minute policy window resets.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Hour-Limit":{"description":"Number of API requests allowed per hour policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Hour-Remaining":{"description":"Number of API requests remaining in the hour policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Hour-Milliseconds":{"description":"Milliseconds until the hour policy window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/campaign/{id}/webhooks/{webhookId}":{"patch":{"tags":["Campaign Webhooks"],"operationId":"updateWebhook","summary":"Update webhook","description":"Updates a webhook by id.","parameters":[{"$ref":"#/components/parameters/CampaignId"},{"$ref":"#/components/parameters/WebhookId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateWebhookRequest"}}}},"responses":{"200":{"description":"Webhook updated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Webhook"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}}}} ``` ## Delete webhook > Removes a webhook by id. ```json {"openapi":"3.1.0","info":{"title":"GrowSurf REST API","version":"2.0.0"},"tags":[{"name":"Campaign Webhooks","description":"Program webhook configuration (create, update, delete, and test webhooks)."}],"servers":[{"url":"https://api.growsurf.com/v2","description":"Production"}],"security":[{"apiKeyAuth":[]}],"components":{"securitySchemes":{"apiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"API key","description":"GrowSurf REST API key supplied as `Authorization: Bearer `."}},"parameters":{"CampaignId":{"name":"id","in":"path","required":true,"description":"GrowSurf program ID.","schema":{"type":"string"}},"WebhookId":{"name":"webhookId","in":"path","required":true,"description":"Webhook ID (`primary` for the program's primary webhook, or the id of an additional webhook).","schema":{"type":"string"}}},"schemas":{"DeleteWebhookResponse":{"type":"object","required":["id","success"],"properties":{"id":{"description":"ID of the webhook that was deleted.","type":"string"},"success":{"description":"Whether the webhook was deleted.","type":"boolean"}}},"Error":{"type":"object","properties":{"name":{"description":"Error name returned for the failed request.","type":"string"},"code":{"description":"Stable machine-readable error code.","type":"string"},"message":{"description":"Human-readable error message.","type":"string"},"errors":{"description":"Optional validation details for specific request fields.","type":"array","items":{"type":"object","additionalProperties":true}},"status":{"description":"HTTP status code for the error.","type":"integer"},"supportUrl":{"description":"Support URL related to the error, when available.","type":"string","format":"uri"},"policyName":{"description":"Rate-limit policy name for `429` errors, when available.","type":"string"},"level":{"description":"Error severity level, when available.","type":"string"},"timestamp":{"description":"When the error response was created.","type":"string","format":"date-time"}}}},"responses":{"Forbidden":{"description":"The API key is missing, invalid, revoked, outside its scope, or not allowed to perform this action.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Too many requests.","headers":{"GrowSurf-RateLimit-Second-Limit":{"description":"Number of API requests allowed per second policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Second-Remaining":{"description":"Number of API requests remaining in the second policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Second-Milliseconds":{"description":"Milliseconds until the second policy window resets.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Minute-Limit":{"description":"Number of API requests allowed per minute policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Minute-Remaining":{"description":"Number of API requests remaining in the minute policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Minute-Milliseconds":{"description":"Milliseconds until the minute policy window resets.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Hour-Limit":{"description":"Number of API requests allowed per hour policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Hour-Remaining":{"description":"Number of API requests remaining in the hour policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Hour-Milliseconds":{"description":"Milliseconds until the hour policy window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/campaign/{id}/webhooks/{webhookId}":{"delete":{"tags":["Campaign Webhooks"],"operationId":"deleteWebhook","summary":"Delete webhook","description":"Removes a webhook by id.","parameters":[{"$ref":"#/components/parameters/CampaignId"},{"$ref":"#/components/parameters/WebhookId"}],"responses":{"200":{"description":"Webhook deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeleteWebhookResponse"}}}},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}}}} ``` ## Test webhook > Sends a live test event to a webhook using its stored URL and secret. ```json {"openapi":"3.1.0","info":{"title":"GrowSurf REST API","version":"2.0.0"},"tags":[{"name":"Campaign Webhooks","description":"Program webhook configuration (create, update, delete, and test webhooks)."}],"servers":[{"url":"https://api.growsurf.com/v2","description":"Production"}],"security":[{"apiKeyAuth":[]}],"components":{"securitySchemes":{"apiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"API key","description":"GrowSurf REST API key supplied as `Authorization: Bearer `."}},"parameters":{"CampaignId":{"name":"id","in":"path","required":true,"description":"GrowSurf program ID.","schema":{"type":"string"}},"WebhookId":{"name":"webhookId","in":"path","required":true,"description":"Webhook ID (`primary` for the program's primary webhook, or the id of an additional webhook).","schema":{"type":"string"}}},"schemas":{"WebhookTestRequest":{"type":"object","additionalProperties":false,"properties":{"event":{"$ref":"#/components/schemas/WebhookEvent","description":"The event to simulate. When omitted, the webhook's first enabled event is used, and the request returns `400` if the webhook has no enabled events."}}},"WebhookEvent":{"type":"string","description":"A webhook event name (the events GrowSurf delivers to subscribed webhooks).","enum":["PARTICIPANT_REACHED_A_GOAL","NEW_PARTICIPANT_ADDED","CAMPAIGN_ENDED","PARTICIPANT_FRAUD_STATUS_UPDATED","NEW_COMMISSION_ADDED","COMMISSION_ADJUSTED","NEW_PAYOUT_ISSUED"]},"WebhookTestResponse":{"type":"object","required":["success"],"properties":{"success":{"description":"Whether the test webhook request completed.","type":"boolean"},"payload":{"type":"object","additionalProperties":true,"description":"The mock event payload that was sent."},"response":{"description":"Response returned by the webhook endpoint during the test.","type":"object","properties":{"msg":{"description":"Response message returned by the webhook endpoint.","type":"string"},"statusCode":{"description":"HTTP status code returned by the webhook endpoint.","type":"integer"}}}}},"Error":{"type":"object","properties":{"name":{"description":"Error name returned for the failed request.","type":"string"},"code":{"description":"Stable machine-readable error code.","type":"string"},"message":{"description":"Human-readable error message.","type":"string"},"errors":{"description":"Optional validation details for specific request fields.","type":"array","items":{"type":"object","additionalProperties":true}},"status":{"description":"HTTP status code for the error.","type":"integer"},"supportUrl":{"description":"Support URL related to the error, when available.","type":"string","format":"uri"},"policyName":{"description":"Rate-limit policy name for `429` errors, when available.","type":"string"},"level":{"description":"Error severity level, when available.","type":"string"},"timestamp":{"description":"When the error response was created.","type":"string","format":"date-time"}}}},"responses":{"BadRequest":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The API key is missing, invalid, revoked, outside its scope, or not allowed to perform this action.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Too many requests.","headers":{"GrowSurf-RateLimit-Second-Limit":{"description":"Number of API requests allowed per second policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Second-Remaining":{"description":"Number of API requests remaining in the second policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Second-Milliseconds":{"description":"Milliseconds until the second policy window resets.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Minute-Limit":{"description":"Number of API requests allowed per minute policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Minute-Remaining":{"description":"Number of API requests remaining in the minute policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Minute-Milliseconds":{"description":"Milliseconds until the minute policy window resets.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Hour-Limit":{"description":"Number of API requests allowed per hour policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Hour-Remaining":{"description":"Number of API requests remaining in the hour policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Hour-Milliseconds":{"description":"Milliseconds until the hour policy window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/campaign/{id}/webhooks/{webhookId}/test":{"post":{"tags":["Campaign Webhooks"],"operationId":"testWebhook","summary":"Test webhook","description":"Sends a live test event to a webhook using its stored URL and secret.","parameters":[{"$ref":"#/components/parameters/CampaignId"},{"$ref":"#/components/parameters/WebhookId"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookTestRequest"}}}},"responses":{"200":{"description":"Test result.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookTestResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}}}} ``` *** ## PARTICIPANTS ↓ ## List participants > Retrieves a paged list of participants in a program. ```json {"openapi":"3.1.0","info":{"title":"GrowSurf REST API","version":"2.0.0"},"tags":[{"name":"Participants","description":"Program participant retrieval, creation, updates, deletion, and referral triggering."}],"servers":[{"url":"https://api.growsurf.com/v2","description":"Production"}],"security":[{"apiKeyAuth":[]}],"components":{"securitySchemes":{"apiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"API key","description":"GrowSurf REST API key supplied as `Authorization: Bearer `."}},"parameters":{"CampaignId":{"name":"id","in":"path","required":true,"description":"GrowSurf program ID.","schema":{"type":"string"}},"NextId":{"name":"nextId","in":"query","required":false,"description":"ID to start the next paged result set with.","schema":{"type":"string"}},"Limit100":{"name":"limit","in":"query","required":false,"description":"Number of results to return. Maximum 100.","schema":{"type":"integer","minimum":1,"maximum":100,"default":10}}},"schemas":{"ParticipantListResponse":{"type":"object","required":["participants","limit","nextId"],"properties":{"participants":{"description":"Participants returned for this page.","type":"array","items":{"$ref":"#/components/schemas/Participant"}},"limit":{"description":"Maximum number of participants requested for this page.","type":"integer"},"nextId":{"description":"Participant ID to pass as `nextId` for the next page, or `null` when there are no more results.","type":["string","null"]}}},"Participant":{"type":"object","description":"Detailed information about a program participant.","required":["id","referralCount","monthlyReferralCount","rank","monthlyRank","shareUrl","rewards","email"],"properties":{"id":{"type":"string","readOnly":true,"description":"The unique identifier of the participant."},"firstName":{"type":["string","null"],"description":"The first name of the participant."},"lastName":{"type":["string","null"],"description":"The last name of the participant."},"email":{"type":"string","description":"The email of the participant."},"paypalEmailAddress":{"type":"string","format":"email","description":"The PayPal email address on file for the participant, used for affiliate or PayPal reward payouts."},"referralCount":{"type":"integer","readOnly":true,"description":"The total number of referrals made by the participant."},"monthlyReferralCount":{"type":"integer","readOnly":true,"description":"The total number of referrals made this month by the participant (resets at the end of the month)."},"prevMonthlyReferralCount":{"type":"integer","readOnly":true,"description":"The total number of referrals made the previous month by the participant."},"rank":{"type":"integer","readOnly":true,"description":"The rank of the participant."},"monthlyRank":{"type":"integer","readOnly":true,"description":"The monthly rank of the participant. This rank resets to 0 at the end of each month."},"prevMonthlyRank":{"type":"integer","readOnly":true,"description":"The previous monthly rank of the participant. Not returned if the participant did not exist in your program during the previous month."},"shareUrl":{"type":"string","readOnly":true,"description":"The unique share URL of the participant."},"createdAt":{"type":"integer","format":"int64","readOnly":true,"description":"The date the participant was added to the program (UTC milliseconds)."},"referralSource":{"$ref":"#/components/schemas/ReferralSource","readOnly":true,"description":"The source of how the participant joined the program."},"referralStatus":{"$ref":"#/components/schemas/ReferralStatus","description":"If the participant was referred, the referrer's status in receiving the referral credit. Only applicable if the participant was referred into the program."},"referredBy":{"type":"string","description":"The ID of the referrer. Only applicable if the participant was referred into the program."},"fraudRiskLevel":{"$ref":"#/components/schemas/FraudRiskLevel","readOnly":true,"description":"A value that represents the integrity of the participant."},"fraudReasonCode":{"type":"string","readOnly":true,"description":"The reason for the participant's `fraudRiskLevel`:\n\n- `UNIQUE_IDENTITY` — They have a unique identity (no other participant has the same identity).\n- `DUPLICATE_EMAIL` — Their email is not unique and is identical to another participant's email (e.g., gavin@hooli.com = gavin+1@hooli.com).\n- `DUPLICATE_IDENTITY` — Their identity (fingerprint or mobile instance ID) is not unique and matches another participant's.\n- `DUPLICATE_IDENTITY_EXCESSIVE` — Within a small window of time, they had an excessive number of referred participants who also shared the same IP address.\n- `EMAIL_FRAUD` — Their email was found to match another participant's when updated in a connected billing or payment integration.\n- `SIMILAR_EMAIL` — Their browser fingerprint matches another participant's and their email looks suspiciously similar.\n- `SIMILAR_FIRST_NAME` — Their browser fingerprint matches another participant's and their first name looks suspiciously similar.\n- `SIMILAR_LAST_NAME` — Their browser fingerprint matches another participant's and their last name looks suspiciously similar.\n- `REFERRAL_EMAIL_PATTERN` — (Status for a referred person) Their email matched a similar pattern to their referrer's email.\n- `REFERRAL_CHAIN_FRAUD` — (Status for a referrer or referred person) Their characteristics matched a pattern with other referrals the referrer made, indicating a fraud ring.\n- `REFERRAL_VELOCITY_FRAUD` — (Status for a referrer or referred person) The referrer made an excessive number of referrals in a short period of time.\n- `DOMAIN_CLUSTERING_FRAUD` — (Status for a referrer or referred person) The referrer made an excessive number of referrals sharing the same suspicious domain in a short period of time.\n- `MANUAL_UPDATE` — They were manually marked as a fraudster from the GrowSurf dashboard.\n- `WHITELISTED` — They were allowed to join the program because one of their properties matched an allowed value.\n- `BLACKLIST_MATCH` — They were not allowed to join the program because one of their properties matched a blocked value.\n- `BLOCKED_IP` — They were not allowed to join the program because their IP address was recently blocked by antifraud IP throttling.\n- `REFERRER_HIGH_RISK` — They were not allowed to join the program because their referrer was a high-risk fraudster."},"isWinner":{"type":"boolean","readOnly":true,"description":"`true` if the participant has earned one or more rewards."},"shareCount":{"type":"object","readOnly":true,"additionalProperties":{"type":"integer"},"description":"An object containing counts of how many times the participant has shared their referral link, keyed by channel. Standard web channels include `email`, `facebook`, and `twitter`; SDK/native-share channels include `iosNativeShare` and `androidNativeShare`."},"impressionCount":{"type":"integer","readOnly":true,"description":"The total number of impressions the participant has made."},"uniqueImpressionCount":{"type":"integer","readOnly":true,"description":"The total number of unique impressions the participant has made."},"inviteCount":{"type":"integer","readOnly":true,"description":"The total number of invites the participant has sent."},"referrals":{"type":"array","readOnly":true,"items":{"type":"string"},"description":"A list of `Participant` IDs who were successfully referred by the participant. Limited to the 100 most recently referred friends."},"monthlyReferrals":{"type":"array","readOnly":true,"items":{"type":"string"},"description":"A list of `Participant` IDs successfully referred by the participant this month (resets at the end of the month). Limited to the 100 most recent."},"referrer":{"readOnly":true,"oneOf":[{"$ref":"#/components/schemas/ParticipantReferrer"},{"type":"null"}],"description":"An object containing the participant's referrer information. Only applicable if the participant was referred into the program."},"ipAddress":{"type":["string","null"],"description":"The IP address associated with the participant, used for anti-fraud matching."},"fingerprint":{"type":["string","null"],"description":"The browser fingerprint associated with the participant, used for anti-fraud matching."},"mobileInstanceId":{"type":["string","null"],"description":"App-install scoped mobile identifier used for anti-fraud matching when provided by native mobile apps. The official mobile SDKs generate this as a lowercase UUID. Not stored when strict GDPR/CCPA mode is enabled."},"metadata":{"$ref":"#/components/schemas/Metadata","description":"An object containing any custom key-value data, useful for saving additional data for the participant (e.g., `company`, `companySize`). Metadata is never used by GrowSurf and usage is optional. Metadata is returned only in REST API calls, and never in JavaScript Web API calls. See [API Guidelines](https://docs.growsurf.com/developer-tools/rest-api/api-guidelines)."},"notes":{"type":["string","null"],"description":"Internal notes about the participant, added via the [GrowSurf Dashboard](https://growsurf.com/dashboard)."},"unsubscribed":{"type":"boolean","description":"`true` if the participant has unsubscribed from program emails."},"rewards":{"type":"array","readOnly":true,"items":{"$ref":"#/components/schemas/ParticipantReward"},"description":"A list of the rewards the participant has earned."},"vanityKeys":{"type":"array","items":{"type":"string"},"description":"The list of vanity keys that the participant has."},"unreadCommissionsCount":{"type":"integer","readOnly":true,"description":"Affiliate programs only. The number of commissions the participant has not yet viewed."},"unreadPayoutsCount":{"type":"integer","readOnly":true,"description":"Affiliate programs only. The number of payouts the participant has not yet viewed."},"isNew":{"type":"boolean","readOnly":true,"description":"Whether this participant was newly created by the request. Returned by participant creation calls; `false` when the participant already existed."},"allMatchingFraudsters":{"type":"array","readOnly":true,"items":{"type":"object","additionalProperties":true},"description":"A list of other participants flagged as matching this participant during anti-fraud checks."},"payoutSettings":{"type":"object","readOnly":true,"description":"Payout-related actions the participant must complete before a payout can be released (e.g. confirming a PayPal email or submitting a W-9/W-8 tax form). Always present; the requiredActions array is empty when no action is required.","properties":{"requiredActions":{"description":"Actions the participant must complete before payouts can be sent.","type":"array","readOnly":true,"items":{"type":"string","enum":["PAYPAL_EMAIL","TAX_INFO"]}}}}}},"ReferralSource":{"type":"string","enum":["DIRECT","PARTICIPANT"]},"ReferralStatus":{"type":"string","enum":["CREDIT_PENDING","CREDIT_AWARDED","CREDIT_EXPIRED","INVITE_SENT"]},"FraudRiskLevel":{"type":"string","enum":["LOW","MEDIUM","HIGH"]},"ParticipantReferrer":{"type":"object","description":"Summary information about a participant's referrer, returned within the `referrer` field of a `Participant`.","properties":{"id":{"type":"string","description":"The unique identifier of the referrer."},"firstName":{"type":["string","null"],"description":"The first name of the referrer."},"lastName":{"type":["string","null"],"description":"The last name of the referrer."},"email":{"type":"string","description":"The email of the referrer."},"referralCount":{"type":"integer","description":"The total number of referrals made by the referrer."},"monthlyReferralCount":{"type":"integer","description":"The total number of referrals made this month by the referrer (resets at the end of the month)."},"prevMonthlyReferralCount":{"type":"integer","description":"The total number of referrals made the previous month by the referrer."},"rank":{"type":"integer","description":"The rank of the referrer."},"monthlyRank":{"type":"integer","description":"The monthly rank of the referrer. This rank resets to 0 at the end of each month."},"prevMonthlyRank":{"type":"integer","description":"The previous monthly rank of the referrer."},"shareUrl":{"type":"string","description":"The unique share URL of the referrer."},"createdAt":{"type":"integer","format":"int64","description":"The date the referrer was added to the program (UTC milliseconds)."},"referralSource":{"$ref":"#/components/schemas/ReferralSource","description":"The source of how the referrer joined the program."},"referralStatus":{"$ref":"#/components/schemas/ReferralStatus","description":"If the referrer was themselves referred, their referrer's status in receiving the referral credit."},"fraudRiskLevel":{"$ref":"#/components/schemas/FraudRiskLevel","description":"A value that represents the integrity of the referrer."},"fraudReasonCode":{"type":"string","description":"The reason for the referrer's `fraudRiskLevel`. See `Participant.fraudReasonCode` for the list of possible values."},"isWinner":{"type":"boolean","description":"`true` if the referrer has earned one or more rewards."},"shareCount":{"type":"object","additionalProperties":{"type":"integer"},"description":"An object containing counts of how many times the referrer has shared their referral link, keyed by channel."},"impressionCount":{"type":"integer","description":"The total number of impressions the referrer has made."},"uniqueImpressionCount":{"type":"integer","description":"The total number of unique impressions the referrer has made."},"inviteCount":{"type":"integer","description":"The total number of invites the referrer has sent."},"referrals":{"type":"array","items":{"type":"string"},"description":"A list of `Participant` IDs who were successfully referred by the referrer. Limited to the 100 most recent."},"monthlyReferrals":{"type":"array","items":{"type":"string"},"description":"A list of `Participant` IDs successfully referred by the referrer this month (resets at the end of the month). Limited to the 100 most recent."},"ipAddress":{"type":["string","null"],"description":"The IP address associated with the referrer, used for anti-fraud matching."},"fingerprint":{"type":["string","null"],"description":"The browser fingerprint associated with the referrer, used for anti-fraud matching."},"metadata":{"$ref":"#/components/schemas/Metadata","description":"An object containing any custom key-value data for the referrer."},"unsubscribed":{"type":"boolean","description":"`true` if the referrer has unsubscribed from program emails."}}},"Metadata":{"type":"object","description":"Shallow custom metadata object.","additionalProperties":true},"ParticipantReward":{"type":"object","description":"A reward that a participant has earned. This is different from a program `Reward` Object and contains information pertinent only to the participant that earned the reward.","required":["id","rewardId","status"],"properties":{"id":{"type":"string","readOnly":true,"description":"The unique identifier of the participant's reward. This is different for every new reward the participant earns."},"rewardId":{"type":"string","readOnly":true,"description":"The ID of the program `Reward` (`CampaignReward`) that this participant has earned."},"status":{"$ref":"#/components/schemas/RewardStatus","readOnly":true,"description":"The status of the participant's reward."},"unread":{"type":"boolean","readOnly":true,"description":"`true` if the participant has not yet seen the reward in a GrowSurf window."},"approved":{"type":"boolean","readOnly":true,"description":"`true` if the participant's reward has been approved."},"approvedAt":{"type":["integer","null"],"format":"int64","readOnly":true,"description":"The date and time the reward was approved for this participant (UTC milliseconds). `null` for unapproved rewards."},"fulfilledAt":{"type":["integer","null"],"format":"int64","readOnly":true,"description":"The date and time the reward was fulfilled for this participant (UTC milliseconds). `null` for unapproved or unfulfilled rewards."},"isReferrer":{"type":"boolean","readOnly":true,"description":"`true` if the participant earned the reward as the referrer; `false` if they earned it as the referred friend (only applicable for double-sided reward types)."},"isAvailable":{"type":"boolean","readOnly":true,"description":"`true` if the reward is available for the participant to claim or redeem."},"isFulfilled":{"type":"boolean","readOnly":true,"description":"`true` if the participant's reward has been fulfilled."},"referredId":{"type":"string","readOnly":true,"description":"The ID of the friend that was referred."},"referrerId":{"type":"string","readOnly":true,"description":"The ID of the participant that made the referral."},"commissionStructure":{"readOnly":true,"oneOf":[{"$ref":"#/components/schemas/CommissionStructure"},{"type":"null"}],"description":"The commission structure associated with this reward. Present only for affiliate programs."}}},"RewardStatus":{"type":"string","enum":["PENDING","FULFILLED"]},"CommissionStructure":{"type":"object","description":"The commission configuration for an affiliate reward. Present only for affiliate programs.","properties":{"amount":{"type":["integer","null"],"description":"Fixed commission amount in the currency's smallest denomination, used when `type` is `FIXED`. `null` for percentage-based commissions."},"amountISO":{"type":["string","null"],"description":"ISO 4217 currency code for the fixed `amount`. Defaults to the program's currency when omitted. Must match the campaign `currencyISO` when provided. `null` for percentage-based commissions."},"event":{"type":["string","null"],"description":"The event that generates a commission (e.g., `SALE`)."},"type":{"type":["string","null"],"enum":["PERCENT","FIXED",null],"description":"How the commission is calculated: `PERCENT` (a percentage of the sale) or `FIXED` (a fixed `amount`)."},"minPaidReferrals":{"type":["integer","null"],"description":"The minimum number of paid referrals required before commissions are earned."},"holdDuration":{"type":["integer","null"],"description":"Number of days a commission is held before it can be paid out."},"duration":{"type":["string","null"],"description":"How long commissions continue to be earned for a referred customer."},"durationInMonths":{"type":["integer","null"],"description":"When `duration` is repeating, the number of months over which commissions are earned."},"approvalRequired":{"type":["boolean","null"],"description":"`true` if commissions require manual approval before they can be paid out."},"percent":{"type":["number","null"],"description":"The commission percentage, used when `type` is `PERCENT`."},"hasMaxAmount":{"type":["boolean","null"],"description":"`true` if a maximum commission amount cap is configured."},"maxAmount":{"type":["integer","null"],"description":"The maximum commission amount cap in the currency's smallest denomination. `null` if no cap is set."},"maxAmountISO":{"type":["string","null"],"description":"The [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code for `maxAmount`. Must match the campaign `currencyISO` when provided."},"hasIntro":{"type":["boolean","null"],"description":"`true` if an introductory commission rate is configured."},"introType":{"type":["string","null"],"description":"How the introductory commission is calculated: `PERCENT` or `FIXED`."},"introPercent":{"type":["number","null"],"description":"The introductory commission percentage, used when `introType` is `PERCENT`."},"introAmount":{"type":["integer","null"],"description":"The introductory commission amount in the currency's smallest denomination, used when `introType` is `FIXED`."},"introAmountISO":{"type":["string","null"],"description":"The [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code for `introAmount`. Must match the campaign `currencyISO` when provided."},"introDuration":{"type":["string","null"],"description":"How long the introductory rate applies."},"introDurationInMonths":{"type":["integer","null"],"description":"When `introDuration` is repeating, the number of months the introductory rate applies."}},"additionalProperties":false},"Error":{"type":"object","properties":{"name":{"description":"Error name returned for the failed request.","type":"string"},"code":{"description":"Stable machine-readable error code.","type":"string"},"message":{"description":"Human-readable error message.","type":"string"},"errors":{"description":"Optional validation details for specific request fields.","type":"array","items":{"type":"object","additionalProperties":true}},"status":{"description":"HTTP status code for the error.","type":"integer"},"supportUrl":{"description":"Support URL related to the error, when available.","type":"string","format":"uri"},"policyName":{"description":"Rate-limit policy name for `429` errors, when available.","type":"string"},"level":{"description":"Error severity level, when available.","type":"string"},"timestamp":{"description":"When the error response was created.","type":"string","format":"date-time"}}}},"responses":{"BadRequest":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The API key is missing, invalid, revoked, outside its scope, or not allowed to perform this action.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Too many requests.","headers":{"GrowSurf-RateLimit-Second-Limit":{"description":"Number of API requests allowed per second policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Second-Remaining":{"description":"Number of API requests remaining in the second policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Second-Milliseconds":{"description":"Milliseconds until the second policy window resets.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Minute-Limit":{"description":"Number of API requests allowed per minute policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Minute-Remaining":{"description":"Number of API requests remaining in the minute policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Minute-Milliseconds":{"description":"Milliseconds until the minute policy window resets.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Hour-Limit":{"description":"Number of API requests allowed per hour policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Hour-Remaining":{"description":"Number of API requests remaining in the hour policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Hour-Milliseconds":{"description":"Milliseconds until the hour policy window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/campaign/{id}/participants":{"get":{"tags":["Participants"],"operationId":"listParticipants","summary":"List participants","description":"Retrieves a paged list of participants in a program.","parameters":[{"$ref":"#/components/parameters/CampaignId"},{"$ref":"#/components/parameters/NextId"},{"$ref":"#/components/parameters/Limit100"}],"responses":{"200":{"description":"Participants returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ParticipantListResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}}}} ``` ## List leaderboard participants > Retrieves participants in leaderboard order for the specified leaderboard type. ```json {"openapi":"3.1.0","info":{"title":"GrowSurf REST API","version":"2.0.0"},"tags":[{"name":"Participants","description":"Program participant retrieval, creation, updates, deletion, and referral triggering."}],"servers":[{"url":"https://api.growsurf.com/v2","description":"Production"}],"security":[{"apiKeyAuth":[]}],"components":{"securitySchemes":{"apiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"API key","description":"GrowSurf REST API key supplied as `Authorization: Bearer `."}},"parameters":{"CampaignId":{"name":"id","in":"path","required":true,"description":"GrowSurf program ID.","schema":{"type":"string"}},"NextId":{"name":"nextId","in":"query","required":false,"description":"ID to start the next paged result set with.","schema":{"type":"string"}},"Limit100":{"name":"limit","in":"query","required":false,"description":"Number of results to return. Maximum 100.","schema":{"type":"integer","minimum":1,"maximum":100,"default":10}}},"schemas":{"LeaderboardType":{"type":"string","enum":["ALL_TIME","CURRENT_MONTH","PREV_MONTH","TOTAL_IMPRESSION_COUNT","UNIQUE_IMPRESSION_COUNT","BY_COMMISSIONS","BY_REVENUE","BY_REFERRALS","BY_LEADS"],"default":"ALL_TIME"},"ParticipantListResponse":{"type":"object","required":["participants","limit","nextId"],"properties":{"participants":{"description":"Participants returned for this page.","type":"array","items":{"$ref":"#/components/schemas/Participant"}},"limit":{"description":"Maximum number of participants requested for this page.","type":"integer"},"nextId":{"description":"Participant ID to pass as `nextId` for the next page, or `null` when there are no more results.","type":["string","null"]}}},"Participant":{"type":"object","description":"Detailed information about a program participant.","required":["id","referralCount","monthlyReferralCount","rank","monthlyRank","shareUrl","rewards","email"],"properties":{"id":{"type":"string","readOnly":true,"description":"The unique identifier of the participant."},"firstName":{"type":["string","null"],"description":"The first name of the participant."},"lastName":{"type":["string","null"],"description":"The last name of the participant."},"email":{"type":"string","description":"The email of the participant."},"paypalEmailAddress":{"type":"string","format":"email","description":"The PayPal email address on file for the participant, used for affiliate or PayPal reward payouts."},"referralCount":{"type":"integer","readOnly":true,"description":"The total number of referrals made by the participant."},"monthlyReferralCount":{"type":"integer","readOnly":true,"description":"The total number of referrals made this month by the participant (resets at the end of the month)."},"prevMonthlyReferralCount":{"type":"integer","readOnly":true,"description":"The total number of referrals made the previous month by the participant."},"rank":{"type":"integer","readOnly":true,"description":"The rank of the participant."},"monthlyRank":{"type":"integer","readOnly":true,"description":"The monthly rank of the participant. This rank resets to 0 at the end of each month."},"prevMonthlyRank":{"type":"integer","readOnly":true,"description":"The previous monthly rank of the participant. Not returned if the participant did not exist in your program during the previous month."},"shareUrl":{"type":"string","readOnly":true,"description":"The unique share URL of the participant."},"createdAt":{"type":"integer","format":"int64","readOnly":true,"description":"The date the participant was added to the program (UTC milliseconds)."},"referralSource":{"$ref":"#/components/schemas/ReferralSource","readOnly":true,"description":"The source of how the participant joined the program."},"referralStatus":{"$ref":"#/components/schemas/ReferralStatus","description":"If the participant was referred, the referrer's status in receiving the referral credit. Only applicable if the participant was referred into the program."},"referredBy":{"type":"string","description":"The ID of the referrer. Only applicable if the participant was referred into the program."},"fraudRiskLevel":{"$ref":"#/components/schemas/FraudRiskLevel","readOnly":true,"description":"A value that represents the integrity of the participant."},"fraudReasonCode":{"type":"string","readOnly":true,"description":"The reason for the participant's `fraudRiskLevel`:\n\n- `UNIQUE_IDENTITY` — They have a unique identity (no other participant has the same identity).\n- `DUPLICATE_EMAIL` — Their email is not unique and is identical to another participant's email (e.g., gavin@hooli.com = gavin+1@hooli.com).\n- `DUPLICATE_IDENTITY` — Their identity (fingerprint or mobile instance ID) is not unique and matches another participant's.\n- `DUPLICATE_IDENTITY_EXCESSIVE` — Within a small window of time, they had an excessive number of referred participants who also shared the same IP address.\n- `EMAIL_FRAUD` — Their email was found to match another participant's when updated in a connected billing or payment integration.\n- `SIMILAR_EMAIL` — Their browser fingerprint matches another participant's and their email looks suspiciously similar.\n- `SIMILAR_FIRST_NAME` — Their browser fingerprint matches another participant's and their first name looks suspiciously similar.\n- `SIMILAR_LAST_NAME` — Their browser fingerprint matches another participant's and their last name looks suspiciously similar.\n- `REFERRAL_EMAIL_PATTERN` — (Status for a referred person) Their email matched a similar pattern to their referrer's email.\n- `REFERRAL_CHAIN_FRAUD` — (Status for a referrer or referred person) Their characteristics matched a pattern with other referrals the referrer made, indicating a fraud ring.\n- `REFERRAL_VELOCITY_FRAUD` — (Status for a referrer or referred person) The referrer made an excessive number of referrals in a short period of time.\n- `DOMAIN_CLUSTERING_FRAUD` — (Status for a referrer or referred person) The referrer made an excessive number of referrals sharing the same suspicious domain in a short period of time.\n- `MANUAL_UPDATE` — They were manually marked as a fraudster from the GrowSurf dashboard.\n- `WHITELISTED` — They were allowed to join the program because one of their properties matched an allowed value.\n- `BLACKLIST_MATCH` — They were not allowed to join the program because one of their properties matched a blocked value.\n- `BLOCKED_IP` — They were not allowed to join the program because their IP address was recently blocked by antifraud IP throttling.\n- `REFERRER_HIGH_RISK` — They were not allowed to join the program because their referrer was a high-risk fraudster."},"isWinner":{"type":"boolean","readOnly":true,"description":"`true` if the participant has earned one or more rewards."},"shareCount":{"type":"object","readOnly":true,"additionalProperties":{"type":"integer"},"description":"An object containing counts of how many times the participant has shared their referral link, keyed by channel. Standard web channels include `email`, `facebook`, and `twitter`; SDK/native-share channels include `iosNativeShare` and `androidNativeShare`."},"impressionCount":{"type":"integer","readOnly":true,"description":"The total number of impressions the participant has made."},"uniqueImpressionCount":{"type":"integer","readOnly":true,"description":"The total number of unique impressions the participant has made."},"inviteCount":{"type":"integer","readOnly":true,"description":"The total number of invites the participant has sent."},"referrals":{"type":"array","readOnly":true,"items":{"type":"string"},"description":"A list of `Participant` IDs who were successfully referred by the participant. Limited to the 100 most recently referred friends."},"monthlyReferrals":{"type":"array","readOnly":true,"items":{"type":"string"},"description":"A list of `Participant` IDs successfully referred by the participant this month (resets at the end of the month). Limited to the 100 most recent."},"referrer":{"readOnly":true,"oneOf":[{"$ref":"#/components/schemas/ParticipantReferrer"},{"type":"null"}],"description":"An object containing the participant's referrer information. Only applicable if the participant was referred into the program."},"ipAddress":{"type":["string","null"],"description":"The IP address associated with the participant, used for anti-fraud matching."},"fingerprint":{"type":["string","null"],"description":"The browser fingerprint associated with the participant, used for anti-fraud matching."},"mobileInstanceId":{"type":["string","null"],"description":"App-install scoped mobile identifier used for anti-fraud matching when provided by native mobile apps. The official mobile SDKs generate this as a lowercase UUID. Not stored when strict GDPR/CCPA mode is enabled."},"metadata":{"$ref":"#/components/schemas/Metadata","description":"An object containing any custom key-value data, useful for saving additional data for the participant (e.g., `company`, `companySize`). Metadata is never used by GrowSurf and usage is optional. Metadata is returned only in REST API calls, and never in JavaScript Web API calls. See [API Guidelines](https://docs.growsurf.com/developer-tools/rest-api/api-guidelines)."},"notes":{"type":["string","null"],"description":"Internal notes about the participant, added via the [GrowSurf Dashboard](https://growsurf.com/dashboard)."},"unsubscribed":{"type":"boolean","description":"`true` if the participant has unsubscribed from program emails."},"rewards":{"type":"array","readOnly":true,"items":{"$ref":"#/components/schemas/ParticipantReward"},"description":"A list of the rewards the participant has earned."},"vanityKeys":{"type":"array","items":{"type":"string"},"description":"The list of vanity keys that the participant has."},"unreadCommissionsCount":{"type":"integer","readOnly":true,"description":"Affiliate programs only. The number of commissions the participant has not yet viewed."},"unreadPayoutsCount":{"type":"integer","readOnly":true,"description":"Affiliate programs only. The number of payouts the participant has not yet viewed."},"isNew":{"type":"boolean","readOnly":true,"description":"Whether this participant was newly created by the request. Returned by participant creation calls; `false` when the participant already existed."},"allMatchingFraudsters":{"type":"array","readOnly":true,"items":{"type":"object","additionalProperties":true},"description":"A list of other participants flagged as matching this participant during anti-fraud checks."},"payoutSettings":{"type":"object","readOnly":true,"description":"Payout-related actions the participant must complete before a payout can be released (e.g. confirming a PayPal email or submitting a W-9/W-8 tax form). Always present; the requiredActions array is empty when no action is required.","properties":{"requiredActions":{"description":"Actions the participant must complete before payouts can be sent.","type":"array","readOnly":true,"items":{"type":"string","enum":["PAYPAL_EMAIL","TAX_INFO"]}}}}}},"ReferralSource":{"type":"string","enum":["DIRECT","PARTICIPANT"]},"ReferralStatus":{"type":"string","enum":["CREDIT_PENDING","CREDIT_AWARDED","CREDIT_EXPIRED","INVITE_SENT"]},"FraudRiskLevel":{"type":"string","enum":["LOW","MEDIUM","HIGH"]},"ParticipantReferrer":{"type":"object","description":"Summary information about a participant's referrer, returned within the `referrer` field of a `Participant`.","properties":{"id":{"type":"string","description":"The unique identifier of the referrer."},"firstName":{"type":["string","null"],"description":"The first name of the referrer."},"lastName":{"type":["string","null"],"description":"The last name of the referrer."},"email":{"type":"string","description":"The email of the referrer."},"referralCount":{"type":"integer","description":"The total number of referrals made by the referrer."},"monthlyReferralCount":{"type":"integer","description":"The total number of referrals made this month by the referrer (resets at the end of the month)."},"prevMonthlyReferralCount":{"type":"integer","description":"The total number of referrals made the previous month by the referrer."},"rank":{"type":"integer","description":"The rank of the referrer."},"monthlyRank":{"type":"integer","description":"The monthly rank of the referrer. This rank resets to 0 at the end of each month."},"prevMonthlyRank":{"type":"integer","description":"The previous monthly rank of the referrer."},"shareUrl":{"type":"string","description":"The unique share URL of the referrer."},"createdAt":{"type":"integer","format":"int64","description":"The date the referrer was added to the program (UTC milliseconds)."},"referralSource":{"$ref":"#/components/schemas/ReferralSource","description":"The source of how the referrer joined the program."},"referralStatus":{"$ref":"#/components/schemas/ReferralStatus","description":"If the referrer was themselves referred, their referrer's status in receiving the referral credit."},"fraudRiskLevel":{"$ref":"#/components/schemas/FraudRiskLevel","description":"A value that represents the integrity of the referrer."},"fraudReasonCode":{"type":"string","description":"The reason for the referrer's `fraudRiskLevel`. See `Participant.fraudReasonCode` for the list of possible values."},"isWinner":{"type":"boolean","description":"`true` if the referrer has earned one or more rewards."},"shareCount":{"type":"object","additionalProperties":{"type":"integer"},"description":"An object containing counts of how many times the referrer has shared their referral link, keyed by channel."},"impressionCount":{"type":"integer","description":"The total number of impressions the referrer has made."},"uniqueImpressionCount":{"type":"integer","description":"The total number of unique impressions the referrer has made."},"inviteCount":{"type":"integer","description":"The total number of invites the referrer has sent."},"referrals":{"type":"array","items":{"type":"string"},"description":"A list of `Participant` IDs who were successfully referred by the referrer. Limited to the 100 most recent."},"monthlyReferrals":{"type":"array","items":{"type":"string"},"description":"A list of `Participant` IDs successfully referred by the referrer this month (resets at the end of the month). Limited to the 100 most recent."},"ipAddress":{"type":["string","null"],"description":"The IP address associated with the referrer, used for anti-fraud matching."},"fingerprint":{"type":["string","null"],"description":"The browser fingerprint associated with the referrer, used for anti-fraud matching."},"metadata":{"$ref":"#/components/schemas/Metadata","description":"An object containing any custom key-value data for the referrer."},"unsubscribed":{"type":"boolean","description":"`true` if the referrer has unsubscribed from program emails."}}},"Metadata":{"type":"object","description":"Shallow custom metadata object.","additionalProperties":true},"ParticipantReward":{"type":"object","description":"A reward that a participant has earned. This is different from a program `Reward` Object and contains information pertinent only to the participant that earned the reward.","required":["id","rewardId","status"],"properties":{"id":{"type":"string","readOnly":true,"description":"The unique identifier of the participant's reward. This is different for every new reward the participant earns."},"rewardId":{"type":"string","readOnly":true,"description":"The ID of the program `Reward` (`CampaignReward`) that this participant has earned."},"status":{"$ref":"#/components/schemas/RewardStatus","readOnly":true,"description":"The status of the participant's reward."},"unread":{"type":"boolean","readOnly":true,"description":"`true` if the participant has not yet seen the reward in a GrowSurf window."},"approved":{"type":"boolean","readOnly":true,"description":"`true` if the participant's reward has been approved."},"approvedAt":{"type":["integer","null"],"format":"int64","readOnly":true,"description":"The date and time the reward was approved for this participant (UTC milliseconds). `null` for unapproved rewards."},"fulfilledAt":{"type":["integer","null"],"format":"int64","readOnly":true,"description":"The date and time the reward was fulfilled for this participant (UTC milliseconds). `null` for unapproved or unfulfilled rewards."},"isReferrer":{"type":"boolean","readOnly":true,"description":"`true` if the participant earned the reward as the referrer; `false` if they earned it as the referred friend (only applicable for double-sided reward types)."},"isAvailable":{"type":"boolean","readOnly":true,"description":"`true` if the reward is available for the participant to claim or redeem."},"isFulfilled":{"type":"boolean","readOnly":true,"description":"`true` if the participant's reward has been fulfilled."},"referredId":{"type":"string","readOnly":true,"description":"The ID of the friend that was referred."},"referrerId":{"type":"string","readOnly":true,"description":"The ID of the participant that made the referral."},"commissionStructure":{"readOnly":true,"oneOf":[{"$ref":"#/components/schemas/CommissionStructure"},{"type":"null"}],"description":"The commission structure associated with this reward. Present only for affiliate programs."}}},"RewardStatus":{"type":"string","enum":["PENDING","FULFILLED"]},"CommissionStructure":{"type":"object","description":"The commission configuration for an affiliate reward. Present only for affiliate programs.","properties":{"amount":{"type":["integer","null"],"description":"Fixed commission amount in the currency's smallest denomination, used when `type` is `FIXED`. `null` for percentage-based commissions."},"amountISO":{"type":["string","null"],"description":"ISO 4217 currency code for the fixed `amount`. Defaults to the program's currency when omitted. Must match the campaign `currencyISO` when provided. `null` for percentage-based commissions."},"event":{"type":["string","null"],"description":"The event that generates a commission (e.g., `SALE`)."},"type":{"type":["string","null"],"enum":["PERCENT","FIXED",null],"description":"How the commission is calculated: `PERCENT` (a percentage of the sale) or `FIXED` (a fixed `amount`)."},"minPaidReferrals":{"type":["integer","null"],"description":"The minimum number of paid referrals required before commissions are earned."},"holdDuration":{"type":["integer","null"],"description":"Number of days a commission is held before it can be paid out."},"duration":{"type":["string","null"],"description":"How long commissions continue to be earned for a referred customer."},"durationInMonths":{"type":["integer","null"],"description":"When `duration` is repeating, the number of months over which commissions are earned."},"approvalRequired":{"type":["boolean","null"],"description":"`true` if commissions require manual approval before they can be paid out."},"percent":{"type":["number","null"],"description":"The commission percentage, used when `type` is `PERCENT`."},"hasMaxAmount":{"type":["boolean","null"],"description":"`true` if a maximum commission amount cap is configured."},"maxAmount":{"type":["integer","null"],"description":"The maximum commission amount cap in the currency's smallest denomination. `null` if no cap is set."},"maxAmountISO":{"type":["string","null"],"description":"The [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code for `maxAmount`. Must match the campaign `currencyISO` when provided."},"hasIntro":{"type":["boolean","null"],"description":"`true` if an introductory commission rate is configured."},"introType":{"type":["string","null"],"description":"How the introductory commission is calculated: `PERCENT` or `FIXED`."},"introPercent":{"type":["number","null"],"description":"The introductory commission percentage, used when `introType` is `PERCENT`."},"introAmount":{"type":["integer","null"],"description":"The introductory commission amount in the currency's smallest denomination, used when `introType` is `FIXED`."},"introAmountISO":{"type":["string","null"],"description":"The [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code for `introAmount`. Must match the campaign `currencyISO` when provided."},"introDuration":{"type":["string","null"],"description":"How long the introductory rate applies."},"introDurationInMonths":{"type":["integer","null"],"description":"When `introDuration` is repeating, the number of months the introductory rate applies."}},"additionalProperties":false},"Error":{"type":"object","properties":{"name":{"description":"Error name returned for the failed request.","type":"string"},"code":{"description":"Stable machine-readable error code.","type":"string"},"message":{"description":"Human-readable error message.","type":"string"},"errors":{"description":"Optional validation details for specific request fields.","type":"array","items":{"type":"object","additionalProperties":true}},"status":{"description":"HTTP status code for the error.","type":"integer"},"supportUrl":{"description":"Support URL related to the error, when available.","type":"string","format":"uri"},"policyName":{"description":"Rate-limit policy name for `429` errors, when available.","type":"string"},"level":{"description":"Error severity level, when available.","type":"string"},"timestamp":{"description":"When the error response was created.","type":"string","format":"date-time"}}}},"responses":{"BadRequest":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The API key is missing, invalid, revoked, outside its scope, or not allowed to perform this action.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"UnprocessableEntity":{"description":"Request is not valid for the current program or participant state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Too many requests.","headers":{"GrowSurf-RateLimit-Second-Limit":{"description":"Number of API requests allowed per second policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Second-Remaining":{"description":"Number of API requests remaining in the second policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Second-Milliseconds":{"description":"Milliseconds until the second policy window resets.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Minute-Limit":{"description":"Number of API requests allowed per minute policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Minute-Remaining":{"description":"Number of API requests remaining in the minute policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Minute-Milliseconds":{"description":"Milliseconds until the minute policy window resets.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Hour-Limit":{"description":"Number of API requests allowed per hour policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Hour-Remaining":{"description":"Number of API requests remaining in the hour policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Hour-Milliseconds":{"description":"Milliseconds until the hour policy window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/campaign/{id}/leaderboard":{"get":{"tags":["Participants"],"operationId":"listLeaderboard","summary":"List leaderboard participants","description":"Retrieves participants in leaderboard order for the specified leaderboard type.","parameters":[{"$ref":"#/components/parameters/CampaignId"},{"$ref":"#/components/parameters/NextId"},{"$ref":"#/components/parameters/Limit100"},{"name":"isMonthly","in":"query","deprecated":true,"description":"Deprecated. Use `leaderboardType=CURRENT_MONTH` instead.","schema":{"type":"boolean","default":false}},{"name":"leaderboardType","in":"query","description":"Leaderboard ordering mode.","schema":{"$ref":"#/components/schemas/LeaderboardType"}}],"responses":{"200":{"description":"Leaderboard participants returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ParticipantListResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"}}}}}} ``` ## Add participant > Adds a new participant to the program. If the email already exists, the existing participant is returned. ```json {"openapi":"3.1.0","info":{"title":"GrowSurf REST API","version":"2.0.0"},"tags":[{"name":"Participants","description":"Program participant retrieval, creation, updates, deletion, and referral triggering."}],"servers":[{"url":"https://api.growsurf.com/v2","description":"Production"}],"security":[{"apiKeyAuth":[]}],"components":{"securitySchemes":{"apiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"API key","description":"GrowSurf REST API key supplied as `Authorization: Bearer `."}},"parameters":{"CampaignId":{"name":"id","in":"path","required":true,"description":"GrowSurf program ID.","schema":{"type":"string"}}},"schemas":{"CreateParticipantRequest":{"type":"object","required":["email"],"properties":{"email":{"description":"Participant email address.","type":"string","format":"email"},"referredBy":{"type":"string","description":"Referrer participant ID or email address.","maxLength":100},"referralStatus":{"type":"string","enum":["CREDIT_PENDING","CREDIT_AWARDED"],"description":"The referral credit status, only meaningful when `referredBy` resolves to a referrer. When omitted, it is derived from the program's referral trigger: `CREDIT_AWARDED`, `CREDIT_PENDING` (manual or custom trigger), or `CREDIT_EXPIRED` (past the credit window). Left unset when no referrer resolves."},"firstName":{"description":"Participant first name.","type":"string","maxLength":255},"lastName":{"description":"Participant last name.","type":"string","maxLength":255},"ipAddress":{"description":"Participant IP address, used for fraud checks when provided.","type":"string"},"fingerprint":{"description":"Browser fingerprint, used for fraud checks when provided.","type":"string"},"mobileInstanceId":{"type":"string","description":"Optional app-install scoped identifier for native mobile anti-fraud. Recommended for mobile participant creation and mobile participant token flows. The official mobile SDKs generate this as a lowercase UUID."},"metadata":{"$ref":"#/components/schemas/Metadata"}}},"Metadata":{"type":"object","description":"Shallow custom metadata object.","additionalProperties":true},"Participant":{"type":"object","description":"Detailed information about a program participant.","required":["id","referralCount","monthlyReferralCount","rank","monthlyRank","shareUrl","rewards","email"],"properties":{"id":{"type":"string","readOnly":true,"description":"The unique identifier of the participant."},"firstName":{"type":["string","null"],"description":"The first name of the participant."},"lastName":{"type":["string","null"],"description":"The last name of the participant."},"email":{"type":"string","description":"The email of the participant."},"paypalEmailAddress":{"type":"string","format":"email","description":"The PayPal email address on file for the participant, used for affiliate or PayPal reward payouts."},"referralCount":{"type":"integer","readOnly":true,"description":"The total number of referrals made by the participant."},"monthlyReferralCount":{"type":"integer","readOnly":true,"description":"The total number of referrals made this month by the participant (resets at the end of the month)."},"prevMonthlyReferralCount":{"type":"integer","readOnly":true,"description":"The total number of referrals made the previous month by the participant."},"rank":{"type":"integer","readOnly":true,"description":"The rank of the participant."},"monthlyRank":{"type":"integer","readOnly":true,"description":"The monthly rank of the participant. This rank resets to 0 at the end of each month."},"prevMonthlyRank":{"type":"integer","readOnly":true,"description":"The previous monthly rank of the participant. Not returned if the participant did not exist in your program during the previous month."},"shareUrl":{"type":"string","readOnly":true,"description":"The unique share URL of the participant."},"createdAt":{"type":"integer","format":"int64","readOnly":true,"description":"The date the participant was added to the program (UTC milliseconds)."},"referralSource":{"$ref":"#/components/schemas/ReferralSource","readOnly":true,"description":"The source of how the participant joined the program."},"referralStatus":{"$ref":"#/components/schemas/ReferralStatus","description":"If the participant was referred, the referrer's status in receiving the referral credit. Only applicable if the participant was referred into the program."},"referredBy":{"type":"string","description":"The ID of the referrer. Only applicable if the participant was referred into the program."},"fraudRiskLevel":{"$ref":"#/components/schemas/FraudRiskLevel","readOnly":true,"description":"A value that represents the integrity of the participant."},"fraudReasonCode":{"type":"string","readOnly":true,"description":"The reason for the participant's `fraudRiskLevel`:\n\n- `UNIQUE_IDENTITY` — They have a unique identity (no other participant has the same identity).\n- `DUPLICATE_EMAIL` — Their email is not unique and is identical to another participant's email (e.g., gavin@hooli.com = gavin+1@hooli.com).\n- `DUPLICATE_IDENTITY` — Their identity (fingerprint or mobile instance ID) is not unique and matches another participant's.\n- `DUPLICATE_IDENTITY_EXCESSIVE` — Within a small window of time, they had an excessive number of referred participants who also shared the same IP address.\n- `EMAIL_FRAUD` — Their email was found to match another participant's when updated in a connected billing or payment integration.\n- `SIMILAR_EMAIL` — Their browser fingerprint matches another participant's and their email looks suspiciously similar.\n- `SIMILAR_FIRST_NAME` — Their browser fingerprint matches another participant's and their first name looks suspiciously similar.\n- `SIMILAR_LAST_NAME` — Their browser fingerprint matches another participant's and their last name looks suspiciously similar.\n- `REFERRAL_EMAIL_PATTERN` — (Status for a referred person) Their email matched a similar pattern to their referrer's email.\n- `REFERRAL_CHAIN_FRAUD` — (Status for a referrer or referred person) Their characteristics matched a pattern with other referrals the referrer made, indicating a fraud ring.\n- `REFERRAL_VELOCITY_FRAUD` — (Status for a referrer or referred person) The referrer made an excessive number of referrals in a short period of time.\n- `DOMAIN_CLUSTERING_FRAUD` — (Status for a referrer or referred person) The referrer made an excessive number of referrals sharing the same suspicious domain in a short period of time.\n- `MANUAL_UPDATE` — They were manually marked as a fraudster from the GrowSurf dashboard.\n- `WHITELISTED` — They were allowed to join the program because one of their properties matched an allowed value.\n- `BLACKLIST_MATCH` — They were not allowed to join the program because one of their properties matched a blocked value.\n- `BLOCKED_IP` — They were not allowed to join the program because their IP address was recently blocked by antifraud IP throttling.\n- `REFERRER_HIGH_RISK` — They were not allowed to join the program because their referrer was a high-risk fraudster."},"isWinner":{"type":"boolean","readOnly":true,"description":"`true` if the participant has earned one or more rewards."},"shareCount":{"type":"object","readOnly":true,"additionalProperties":{"type":"integer"},"description":"An object containing counts of how many times the participant has shared their referral link, keyed by channel. Standard web channels include `email`, `facebook`, and `twitter`; SDK/native-share channels include `iosNativeShare` and `androidNativeShare`."},"impressionCount":{"type":"integer","readOnly":true,"description":"The total number of impressions the participant has made."},"uniqueImpressionCount":{"type":"integer","readOnly":true,"description":"The total number of unique impressions the participant has made."},"inviteCount":{"type":"integer","readOnly":true,"description":"The total number of invites the participant has sent."},"referrals":{"type":"array","readOnly":true,"items":{"type":"string"},"description":"A list of `Participant` IDs who were successfully referred by the participant. Limited to the 100 most recently referred friends."},"monthlyReferrals":{"type":"array","readOnly":true,"items":{"type":"string"},"description":"A list of `Participant` IDs successfully referred by the participant this month (resets at the end of the month). Limited to the 100 most recent."},"referrer":{"readOnly":true,"oneOf":[{"$ref":"#/components/schemas/ParticipantReferrer"},{"type":"null"}],"description":"An object containing the participant's referrer information. Only applicable if the participant was referred into the program."},"ipAddress":{"type":["string","null"],"description":"The IP address associated with the participant, used for anti-fraud matching."},"fingerprint":{"type":["string","null"],"description":"The browser fingerprint associated with the participant, used for anti-fraud matching."},"mobileInstanceId":{"type":["string","null"],"description":"App-install scoped mobile identifier used for anti-fraud matching when provided by native mobile apps. The official mobile SDKs generate this as a lowercase UUID. Not stored when strict GDPR/CCPA mode is enabled."},"metadata":{"$ref":"#/components/schemas/Metadata","description":"An object containing any custom key-value data, useful for saving additional data for the participant (e.g., `company`, `companySize`). Metadata is never used by GrowSurf and usage is optional. Metadata is returned only in REST API calls, and never in JavaScript Web API calls. See [API Guidelines](https://docs.growsurf.com/developer-tools/rest-api/api-guidelines)."},"notes":{"type":["string","null"],"description":"Internal notes about the participant, added via the [GrowSurf Dashboard](https://growsurf.com/dashboard)."},"unsubscribed":{"type":"boolean","description":"`true` if the participant has unsubscribed from program emails."},"rewards":{"type":"array","readOnly":true,"items":{"$ref":"#/components/schemas/ParticipantReward"},"description":"A list of the rewards the participant has earned."},"vanityKeys":{"type":"array","items":{"type":"string"},"description":"The list of vanity keys that the participant has."},"unreadCommissionsCount":{"type":"integer","readOnly":true,"description":"Affiliate programs only. The number of commissions the participant has not yet viewed."},"unreadPayoutsCount":{"type":"integer","readOnly":true,"description":"Affiliate programs only. The number of payouts the participant has not yet viewed."},"isNew":{"type":"boolean","readOnly":true,"description":"Whether this participant was newly created by the request. Returned by participant creation calls; `false` when the participant already existed."},"allMatchingFraudsters":{"type":"array","readOnly":true,"items":{"type":"object","additionalProperties":true},"description":"A list of other participants flagged as matching this participant during anti-fraud checks."},"payoutSettings":{"type":"object","readOnly":true,"description":"Payout-related actions the participant must complete before a payout can be released (e.g. confirming a PayPal email or submitting a W-9/W-8 tax form). Always present; the requiredActions array is empty when no action is required.","properties":{"requiredActions":{"description":"Actions the participant must complete before payouts can be sent.","type":"array","readOnly":true,"items":{"type":"string","enum":["PAYPAL_EMAIL","TAX_INFO"]}}}}}},"ReferralSource":{"type":"string","enum":["DIRECT","PARTICIPANT"]},"ReferralStatus":{"type":"string","enum":["CREDIT_PENDING","CREDIT_AWARDED","CREDIT_EXPIRED","INVITE_SENT"]},"FraudRiskLevel":{"type":"string","enum":["LOW","MEDIUM","HIGH"]},"ParticipantReferrer":{"type":"object","description":"Summary information about a participant's referrer, returned within the `referrer` field of a `Participant`.","properties":{"id":{"type":"string","description":"The unique identifier of the referrer."},"firstName":{"type":["string","null"],"description":"The first name of the referrer."},"lastName":{"type":["string","null"],"description":"The last name of the referrer."},"email":{"type":"string","description":"The email of the referrer."},"referralCount":{"type":"integer","description":"The total number of referrals made by the referrer."},"monthlyReferralCount":{"type":"integer","description":"The total number of referrals made this month by the referrer (resets at the end of the month)."},"prevMonthlyReferralCount":{"type":"integer","description":"The total number of referrals made the previous month by the referrer."},"rank":{"type":"integer","description":"The rank of the referrer."},"monthlyRank":{"type":"integer","description":"The monthly rank of the referrer. This rank resets to 0 at the end of each month."},"prevMonthlyRank":{"type":"integer","description":"The previous monthly rank of the referrer."},"shareUrl":{"type":"string","description":"The unique share URL of the referrer."},"createdAt":{"type":"integer","format":"int64","description":"The date the referrer was added to the program (UTC milliseconds)."},"referralSource":{"$ref":"#/components/schemas/ReferralSource","description":"The source of how the referrer joined the program."},"referralStatus":{"$ref":"#/components/schemas/ReferralStatus","description":"If the referrer was themselves referred, their referrer's status in receiving the referral credit."},"fraudRiskLevel":{"$ref":"#/components/schemas/FraudRiskLevel","description":"A value that represents the integrity of the referrer."},"fraudReasonCode":{"type":"string","description":"The reason for the referrer's `fraudRiskLevel`. See `Participant.fraudReasonCode` for the list of possible values."},"isWinner":{"type":"boolean","description":"`true` if the referrer has earned one or more rewards."},"shareCount":{"type":"object","additionalProperties":{"type":"integer"},"description":"An object containing counts of how many times the referrer has shared their referral link, keyed by channel."},"impressionCount":{"type":"integer","description":"The total number of impressions the referrer has made."},"uniqueImpressionCount":{"type":"integer","description":"The total number of unique impressions the referrer has made."},"inviteCount":{"type":"integer","description":"The total number of invites the referrer has sent."},"referrals":{"type":"array","items":{"type":"string"},"description":"A list of `Participant` IDs who were successfully referred by the referrer. Limited to the 100 most recent."},"monthlyReferrals":{"type":"array","items":{"type":"string"},"description":"A list of `Participant` IDs successfully referred by the referrer this month (resets at the end of the month). Limited to the 100 most recent."},"ipAddress":{"type":["string","null"],"description":"The IP address associated with the referrer, used for anti-fraud matching."},"fingerprint":{"type":["string","null"],"description":"The browser fingerprint associated with the referrer, used for anti-fraud matching."},"metadata":{"$ref":"#/components/schemas/Metadata","description":"An object containing any custom key-value data for the referrer."},"unsubscribed":{"type":"boolean","description":"`true` if the referrer has unsubscribed from program emails."}}},"ParticipantReward":{"type":"object","description":"A reward that a participant has earned. This is different from a program `Reward` Object and contains information pertinent only to the participant that earned the reward.","required":["id","rewardId","status"],"properties":{"id":{"type":"string","readOnly":true,"description":"The unique identifier of the participant's reward. This is different for every new reward the participant earns."},"rewardId":{"type":"string","readOnly":true,"description":"The ID of the program `Reward` (`CampaignReward`) that this participant has earned."},"status":{"$ref":"#/components/schemas/RewardStatus","readOnly":true,"description":"The status of the participant's reward."},"unread":{"type":"boolean","readOnly":true,"description":"`true` if the participant has not yet seen the reward in a GrowSurf window."},"approved":{"type":"boolean","readOnly":true,"description":"`true` if the participant's reward has been approved."},"approvedAt":{"type":["integer","null"],"format":"int64","readOnly":true,"description":"The date and time the reward was approved for this participant (UTC milliseconds). `null` for unapproved rewards."},"fulfilledAt":{"type":["integer","null"],"format":"int64","readOnly":true,"description":"The date and time the reward was fulfilled for this participant (UTC milliseconds). `null` for unapproved or unfulfilled rewards."},"isReferrer":{"type":"boolean","readOnly":true,"description":"`true` if the participant earned the reward as the referrer; `false` if they earned it as the referred friend (only applicable for double-sided reward types)."},"isAvailable":{"type":"boolean","readOnly":true,"description":"`true` if the reward is available for the participant to claim or redeem."},"isFulfilled":{"type":"boolean","readOnly":true,"description":"`true` if the participant's reward has been fulfilled."},"referredId":{"type":"string","readOnly":true,"description":"The ID of the friend that was referred."},"referrerId":{"type":"string","readOnly":true,"description":"The ID of the participant that made the referral."},"commissionStructure":{"readOnly":true,"oneOf":[{"$ref":"#/components/schemas/CommissionStructure"},{"type":"null"}],"description":"The commission structure associated with this reward. Present only for affiliate programs."}}},"RewardStatus":{"type":"string","enum":["PENDING","FULFILLED"]},"CommissionStructure":{"type":"object","description":"The commission configuration for an affiliate reward. Present only for affiliate programs.","properties":{"amount":{"type":["integer","null"],"description":"Fixed commission amount in the currency's smallest denomination, used when `type` is `FIXED`. `null` for percentage-based commissions."},"amountISO":{"type":["string","null"],"description":"ISO 4217 currency code for the fixed `amount`. Defaults to the program's currency when omitted. Must match the campaign `currencyISO` when provided. `null` for percentage-based commissions."},"event":{"type":["string","null"],"description":"The event that generates a commission (e.g., `SALE`)."},"type":{"type":["string","null"],"enum":["PERCENT","FIXED",null],"description":"How the commission is calculated: `PERCENT` (a percentage of the sale) or `FIXED` (a fixed `amount`)."},"minPaidReferrals":{"type":["integer","null"],"description":"The minimum number of paid referrals required before commissions are earned."},"holdDuration":{"type":["integer","null"],"description":"Number of days a commission is held before it can be paid out."},"duration":{"type":["string","null"],"description":"How long commissions continue to be earned for a referred customer."},"durationInMonths":{"type":["integer","null"],"description":"When `duration` is repeating, the number of months over which commissions are earned."},"approvalRequired":{"type":["boolean","null"],"description":"`true` if commissions require manual approval before they can be paid out."},"percent":{"type":["number","null"],"description":"The commission percentage, used when `type` is `PERCENT`."},"hasMaxAmount":{"type":["boolean","null"],"description":"`true` if a maximum commission amount cap is configured."},"maxAmount":{"type":["integer","null"],"description":"The maximum commission amount cap in the currency's smallest denomination. `null` if no cap is set."},"maxAmountISO":{"type":["string","null"],"description":"The [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code for `maxAmount`. Must match the campaign `currencyISO` when provided."},"hasIntro":{"type":["boolean","null"],"description":"`true` if an introductory commission rate is configured."},"introType":{"type":["string","null"],"description":"How the introductory commission is calculated: `PERCENT` or `FIXED`."},"introPercent":{"type":["number","null"],"description":"The introductory commission percentage, used when `introType` is `PERCENT`."},"introAmount":{"type":["integer","null"],"description":"The introductory commission amount in the currency's smallest denomination, used when `introType` is `FIXED`."},"introAmountISO":{"type":["string","null"],"description":"The [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code for `introAmount`. Must match the campaign `currencyISO` when provided."},"introDuration":{"type":["string","null"],"description":"How long the introductory rate applies."},"introDurationInMonths":{"type":["integer","null"],"description":"When `introDuration` is repeating, the number of months the introductory rate applies."}},"additionalProperties":false},"Error":{"type":"object","properties":{"name":{"description":"Error name returned for the failed request.","type":"string"},"code":{"description":"Stable machine-readable error code.","type":"string"},"message":{"description":"Human-readable error message.","type":"string"},"errors":{"description":"Optional validation details for specific request fields.","type":"array","items":{"type":"object","additionalProperties":true}},"status":{"description":"HTTP status code for the error.","type":"integer"},"supportUrl":{"description":"Support URL related to the error, when available.","type":"string","format":"uri"},"policyName":{"description":"Rate-limit policy name for `429` errors, when available.","type":"string"},"level":{"description":"Error severity level, when available.","type":"string"},"timestamp":{"description":"When the error response was created.","type":"string","format":"date-time"}}},"ParticipantBlockedError":{"allOf":[{"$ref":"#/components/schemas/Error"},{"type":"object","properties":{"fraudRiskLevel":{"description":"Fraud risk level assigned to the blocked signup.","$ref":"#/components/schemas/FraudRiskLevel"},"fraudReasonCode":{"description":"Machine-readable reason code for the fraud decision.","type":"string"},"matchedParticipantIds":{"description":"Existing participant IDs related to the fraud match.","type":"array","items":{"type":"string"}},"email":{"description":"Email address from the blocked signup attempt.","type":"string","format":"email"},"referrerId":{"description":"Referrer participant ID supplied with the blocked signup, or `null`.","type":["string","null"]},"ipAddress":{"description":"IP address supplied with the blocked signup, or `null`.","type":["string","null"]},"fingerprint":{"description":"Browser fingerprint supplied with the blocked signup, or `null`.","type":["string","null"]},"blockedAt":{"description":"When the signup was blocked.","type":"string","format":"date-time"}}}]}},"responses":{"BadRequest":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The API key is missing, invalid, revoked, outside its scope, or not allowed to perform this action.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Conflict":{"description":"Conflicting duplicate request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Too many requests.","headers":{"GrowSurf-RateLimit-Second-Limit":{"description":"Number of API requests allowed per second policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Second-Remaining":{"description":"Number of API requests remaining in the second policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Second-Milliseconds":{"description":"Milliseconds until the second policy window resets.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Minute-Limit":{"description":"Number of API requests allowed per minute policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Minute-Remaining":{"description":"Number of API requests remaining in the minute policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Minute-Milliseconds":{"description":"Milliseconds until the minute policy window resets.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Hour-Limit":{"description":"Number of API requests allowed per hour policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Hour-Remaining":{"description":"Number of API requests remaining in the hour policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Hour-Milliseconds":{"description":"Milliseconds until the hour policy window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/campaign/{id}/participant":{"post":{"tags":["Participants"],"operationId":"createParticipant","summary":"Add participant","description":"Adds a new participant to the program. If the email already exists, the existing participant is returned.","parameters":[{"$ref":"#/components/parameters/CampaignId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateParticipantRequest"}}}},"responses":{"200":{"description":"Participant returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Participant"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"description":"Participant was blocked or the endpoint is not available for this program type.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ParticipantBlockedError"},{"$ref":"#/components/schemas/Error"}]}}}},"429":{"$ref":"#/components/responses/RateLimited"}}}}}} ``` ## Retrieve participant > Retrieves a single participant by GrowSurf participant ID or email address. ```json {"openapi":"3.1.0","info":{"title":"GrowSurf REST API","version":"2.0.0"},"tags":[{"name":"Participants","description":"Program participant retrieval, creation, updates, deletion, and referral triggering."}],"servers":[{"url":"https://api.growsurf.com/v2","description":"Production"}],"security":[{"apiKeyAuth":[]}],"components":{"securitySchemes":{"apiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"API key","description":"GrowSurf REST API key supplied as `Authorization: Bearer `."}},"parameters":{"CampaignId":{"name":"id","in":"path","required":true,"description":"GrowSurf program ID.","schema":{"type":"string"}},"ParticipantIdOrEmail":{"name":"participantIdOrEmail","in":"path","required":true,"description":"GrowSurf participant ID or URL-encoded participant email address.","schema":{"type":"string"}}},"schemas":{"Participant":{"type":"object","description":"Detailed information about a program participant.","required":["id","referralCount","monthlyReferralCount","rank","monthlyRank","shareUrl","rewards","email"],"properties":{"id":{"type":"string","readOnly":true,"description":"The unique identifier of the participant."},"firstName":{"type":["string","null"],"description":"The first name of the participant."},"lastName":{"type":["string","null"],"description":"The last name of the participant."},"email":{"type":"string","description":"The email of the participant."},"paypalEmailAddress":{"type":"string","format":"email","description":"The PayPal email address on file for the participant, used for affiliate or PayPal reward payouts."},"referralCount":{"type":"integer","readOnly":true,"description":"The total number of referrals made by the participant."},"monthlyReferralCount":{"type":"integer","readOnly":true,"description":"The total number of referrals made this month by the participant (resets at the end of the month)."},"prevMonthlyReferralCount":{"type":"integer","readOnly":true,"description":"The total number of referrals made the previous month by the participant."},"rank":{"type":"integer","readOnly":true,"description":"The rank of the participant."},"monthlyRank":{"type":"integer","readOnly":true,"description":"The monthly rank of the participant. This rank resets to 0 at the end of each month."},"prevMonthlyRank":{"type":"integer","readOnly":true,"description":"The previous monthly rank of the participant. Not returned if the participant did not exist in your program during the previous month."},"shareUrl":{"type":"string","readOnly":true,"description":"The unique share URL of the participant."},"createdAt":{"type":"integer","format":"int64","readOnly":true,"description":"The date the participant was added to the program (UTC milliseconds)."},"referralSource":{"$ref":"#/components/schemas/ReferralSource","readOnly":true,"description":"The source of how the participant joined the program."},"referralStatus":{"$ref":"#/components/schemas/ReferralStatus","description":"If the participant was referred, the referrer's status in receiving the referral credit. Only applicable if the participant was referred into the program."},"referredBy":{"type":"string","description":"The ID of the referrer. Only applicable if the participant was referred into the program."},"fraudRiskLevel":{"$ref":"#/components/schemas/FraudRiskLevel","readOnly":true,"description":"A value that represents the integrity of the participant."},"fraudReasonCode":{"type":"string","readOnly":true,"description":"The reason for the participant's `fraudRiskLevel`:\n\n- `UNIQUE_IDENTITY` — They have a unique identity (no other participant has the same identity).\n- `DUPLICATE_EMAIL` — Their email is not unique and is identical to another participant's email (e.g., gavin@hooli.com = gavin+1@hooli.com).\n- `DUPLICATE_IDENTITY` — Their identity (fingerprint or mobile instance ID) is not unique and matches another participant's.\n- `DUPLICATE_IDENTITY_EXCESSIVE` — Within a small window of time, they had an excessive number of referred participants who also shared the same IP address.\n- `EMAIL_FRAUD` — Their email was found to match another participant's when updated in a connected billing or payment integration.\n- `SIMILAR_EMAIL` — Their browser fingerprint matches another participant's and their email looks suspiciously similar.\n- `SIMILAR_FIRST_NAME` — Their browser fingerprint matches another participant's and their first name looks suspiciously similar.\n- `SIMILAR_LAST_NAME` — Their browser fingerprint matches another participant's and their last name looks suspiciously similar.\n- `REFERRAL_EMAIL_PATTERN` — (Status for a referred person) Their email matched a similar pattern to their referrer's email.\n- `REFERRAL_CHAIN_FRAUD` — (Status for a referrer or referred person) Their characteristics matched a pattern with other referrals the referrer made, indicating a fraud ring.\n- `REFERRAL_VELOCITY_FRAUD` — (Status for a referrer or referred person) The referrer made an excessive number of referrals in a short period of time.\n- `DOMAIN_CLUSTERING_FRAUD` — (Status for a referrer or referred person) The referrer made an excessive number of referrals sharing the same suspicious domain in a short period of time.\n- `MANUAL_UPDATE` — They were manually marked as a fraudster from the GrowSurf dashboard.\n- `WHITELISTED` — They were allowed to join the program because one of their properties matched an allowed value.\n- `BLACKLIST_MATCH` — They were not allowed to join the program because one of their properties matched a blocked value.\n- `BLOCKED_IP` — They were not allowed to join the program because their IP address was recently blocked by antifraud IP throttling.\n- `REFERRER_HIGH_RISK` — They were not allowed to join the program because their referrer was a high-risk fraudster."},"isWinner":{"type":"boolean","readOnly":true,"description":"`true` if the participant has earned one or more rewards."},"shareCount":{"type":"object","readOnly":true,"additionalProperties":{"type":"integer"},"description":"An object containing counts of how many times the participant has shared their referral link, keyed by channel. Standard web channels include `email`, `facebook`, and `twitter`; SDK/native-share channels include `iosNativeShare` and `androidNativeShare`."},"impressionCount":{"type":"integer","readOnly":true,"description":"The total number of impressions the participant has made."},"uniqueImpressionCount":{"type":"integer","readOnly":true,"description":"The total number of unique impressions the participant has made."},"inviteCount":{"type":"integer","readOnly":true,"description":"The total number of invites the participant has sent."},"referrals":{"type":"array","readOnly":true,"items":{"type":"string"},"description":"A list of `Participant` IDs who were successfully referred by the participant. Limited to the 100 most recently referred friends."},"monthlyReferrals":{"type":"array","readOnly":true,"items":{"type":"string"},"description":"A list of `Participant` IDs successfully referred by the participant this month (resets at the end of the month). Limited to the 100 most recent."},"referrer":{"readOnly":true,"oneOf":[{"$ref":"#/components/schemas/ParticipantReferrer"},{"type":"null"}],"description":"An object containing the participant's referrer information. Only applicable if the participant was referred into the program."},"ipAddress":{"type":["string","null"],"description":"The IP address associated with the participant, used for anti-fraud matching."},"fingerprint":{"type":["string","null"],"description":"The browser fingerprint associated with the participant, used for anti-fraud matching."},"mobileInstanceId":{"type":["string","null"],"description":"App-install scoped mobile identifier used for anti-fraud matching when provided by native mobile apps. The official mobile SDKs generate this as a lowercase UUID. Not stored when strict GDPR/CCPA mode is enabled."},"metadata":{"$ref":"#/components/schemas/Metadata","description":"An object containing any custom key-value data, useful for saving additional data for the participant (e.g., `company`, `companySize`). Metadata is never used by GrowSurf and usage is optional. Metadata is returned only in REST API calls, and never in JavaScript Web API calls. See [API Guidelines](https://docs.growsurf.com/developer-tools/rest-api/api-guidelines)."},"notes":{"type":["string","null"],"description":"Internal notes about the participant, added via the [GrowSurf Dashboard](https://growsurf.com/dashboard)."},"unsubscribed":{"type":"boolean","description":"`true` if the participant has unsubscribed from program emails."},"rewards":{"type":"array","readOnly":true,"items":{"$ref":"#/components/schemas/ParticipantReward"},"description":"A list of the rewards the participant has earned."},"vanityKeys":{"type":"array","items":{"type":"string"},"description":"The list of vanity keys that the participant has."},"unreadCommissionsCount":{"type":"integer","readOnly":true,"description":"Affiliate programs only. The number of commissions the participant has not yet viewed."},"unreadPayoutsCount":{"type":"integer","readOnly":true,"description":"Affiliate programs only. The number of payouts the participant has not yet viewed."},"isNew":{"type":"boolean","readOnly":true,"description":"Whether this participant was newly created by the request. Returned by participant creation calls; `false` when the participant already existed."},"allMatchingFraudsters":{"type":"array","readOnly":true,"items":{"type":"object","additionalProperties":true},"description":"A list of other participants flagged as matching this participant during anti-fraud checks."},"payoutSettings":{"type":"object","readOnly":true,"description":"Payout-related actions the participant must complete before a payout can be released (e.g. confirming a PayPal email or submitting a W-9/W-8 tax form). Always present; the requiredActions array is empty when no action is required.","properties":{"requiredActions":{"description":"Actions the participant must complete before payouts can be sent.","type":"array","readOnly":true,"items":{"type":"string","enum":["PAYPAL_EMAIL","TAX_INFO"]}}}}}},"ReferralSource":{"type":"string","enum":["DIRECT","PARTICIPANT"]},"ReferralStatus":{"type":"string","enum":["CREDIT_PENDING","CREDIT_AWARDED","CREDIT_EXPIRED","INVITE_SENT"]},"FraudRiskLevel":{"type":"string","enum":["LOW","MEDIUM","HIGH"]},"ParticipantReferrer":{"type":"object","description":"Summary information about a participant's referrer, returned within the `referrer` field of a `Participant`.","properties":{"id":{"type":"string","description":"The unique identifier of the referrer."},"firstName":{"type":["string","null"],"description":"The first name of the referrer."},"lastName":{"type":["string","null"],"description":"The last name of the referrer."},"email":{"type":"string","description":"The email of the referrer."},"referralCount":{"type":"integer","description":"The total number of referrals made by the referrer."},"monthlyReferralCount":{"type":"integer","description":"The total number of referrals made this month by the referrer (resets at the end of the month)."},"prevMonthlyReferralCount":{"type":"integer","description":"The total number of referrals made the previous month by the referrer."},"rank":{"type":"integer","description":"The rank of the referrer."},"monthlyRank":{"type":"integer","description":"The monthly rank of the referrer. This rank resets to 0 at the end of each month."},"prevMonthlyRank":{"type":"integer","description":"The previous monthly rank of the referrer."},"shareUrl":{"type":"string","description":"The unique share URL of the referrer."},"createdAt":{"type":"integer","format":"int64","description":"The date the referrer was added to the program (UTC milliseconds)."},"referralSource":{"$ref":"#/components/schemas/ReferralSource","description":"The source of how the referrer joined the program."},"referralStatus":{"$ref":"#/components/schemas/ReferralStatus","description":"If the referrer was themselves referred, their referrer's status in receiving the referral credit."},"fraudRiskLevel":{"$ref":"#/components/schemas/FraudRiskLevel","description":"A value that represents the integrity of the referrer."},"fraudReasonCode":{"type":"string","description":"The reason for the referrer's `fraudRiskLevel`. See `Participant.fraudReasonCode` for the list of possible values."},"isWinner":{"type":"boolean","description":"`true` if the referrer has earned one or more rewards."},"shareCount":{"type":"object","additionalProperties":{"type":"integer"},"description":"An object containing counts of how many times the referrer has shared their referral link, keyed by channel."},"impressionCount":{"type":"integer","description":"The total number of impressions the referrer has made."},"uniqueImpressionCount":{"type":"integer","description":"The total number of unique impressions the referrer has made."},"inviteCount":{"type":"integer","description":"The total number of invites the referrer has sent."},"referrals":{"type":"array","items":{"type":"string"},"description":"A list of `Participant` IDs who were successfully referred by the referrer. Limited to the 100 most recent."},"monthlyReferrals":{"type":"array","items":{"type":"string"},"description":"A list of `Participant` IDs successfully referred by the referrer this month (resets at the end of the month). Limited to the 100 most recent."},"ipAddress":{"type":["string","null"],"description":"The IP address associated with the referrer, used for anti-fraud matching."},"fingerprint":{"type":["string","null"],"description":"The browser fingerprint associated with the referrer, used for anti-fraud matching."},"metadata":{"$ref":"#/components/schemas/Metadata","description":"An object containing any custom key-value data for the referrer."},"unsubscribed":{"type":"boolean","description":"`true` if the referrer has unsubscribed from program emails."}}},"Metadata":{"type":"object","description":"Shallow custom metadata object.","additionalProperties":true},"ParticipantReward":{"type":"object","description":"A reward that a participant has earned. This is different from a program `Reward` Object and contains information pertinent only to the participant that earned the reward.","required":["id","rewardId","status"],"properties":{"id":{"type":"string","readOnly":true,"description":"The unique identifier of the participant's reward. This is different for every new reward the participant earns."},"rewardId":{"type":"string","readOnly":true,"description":"The ID of the program `Reward` (`CampaignReward`) that this participant has earned."},"status":{"$ref":"#/components/schemas/RewardStatus","readOnly":true,"description":"The status of the participant's reward."},"unread":{"type":"boolean","readOnly":true,"description":"`true` if the participant has not yet seen the reward in a GrowSurf window."},"approved":{"type":"boolean","readOnly":true,"description":"`true` if the participant's reward has been approved."},"approvedAt":{"type":["integer","null"],"format":"int64","readOnly":true,"description":"The date and time the reward was approved for this participant (UTC milliseconds). `null` for unapproved rewards."},"fulfilledAt":{"type":["integer","null"],"format":"int64","readOnly":true,"description":"The date and time the reward was fulfilled for this participant (UTC milliseconds). `null` for unapproved or unfulfilled rewards."},"isReferrer":{"type":"boolean","readOnly":true,"description":"`true` if the participant earned the reward as the referrer; `false` if they earned it as the referred friend (only applicable for double-sided reward types)."},"isAvailable":{"type":"boolean","readOnly":true,"description":"`true` if the reward is available for the participant to claim or redeem."},"isFulfilled":{"type":"boolean","readOnly":true,"description":"`true` if the participant's reward has been fulfilled."},"referredId":{"type":"string","readOnly":true,"description":"The ID of the friend that was referred."},"referrerId":{"type":"string","readOnly":true,"description":"The ID of the participant that made the referral."},"commissionStructure":{"readOnly":true,"oneOf":[{"$ref":"#/components/schemas/CommissionStructure"},{"type":"null"}],"description":"The commission structure associated with this reward. Present only for affiliate programs."}}},"RewardStatus":{"type":"string","enum":["PENDING","FULFILLED"]},"CommissionStructure":{"type":"object","description":"The commission configuration for an affiliate reward. Present only for affiliate programs.","properties":{"amount":{"type":["integer","null"],"description":"Fixed commission amount in the currency's smallest denomination, used when `type` is `FIXED`. `null` for percentage-based commissions."},"amountISO":{"type":["string","null"],"description":"ISO 4217 currency code for the fixed `amount`. Defaults to the program's currency when omitted. Must match the campaign `currencyISO` when provided. `null` for percentage-based commissions."},"event":{"type":["string","null"],"description":"The event that generates a commission (e.g., `SALE`)."},"type":{"type":["string","null"],"enum":["PERCENT","FIXED",null],"description":"How the commission is calculated: `PERCENT` (a percentage of the sale) or `FIXED` (a fixed `amount`)."},"minPaidReferrals":{"type":["integer","null"],"description":"The minimum number of paid referrals required before commissions are earned."},"holdDuration":{"type":["integer","null"],"description":"Number of days a commission is held before it can be paid out."},"duration":{"type":["string","null"],"description":"How long commissions continue to be earned for a referred customer."},"durationInMonths":{"type":["integer","null"],"description":"When `duration` is repeating, the number of months over which commissions are earned."},"approvalRequired":{"type":["boolean","null"],"description":"`true` if commissions require manual approval before they can be paid out."},"percent":{"type":["number","null"],"description":"The commission percentage, used when `type` is `PERCENT`."},"hasMaxAmount":{"type":["boolean","null"],"description":"`true` if a maximum commission amount cap is configured."},"maxAmount":{"type":["integer","null"],"description":"The maximum commission amount cap in the currency's smallest denomination. `null` if no cap is set."},"maxAmountISO":{"type":["string","null"],"description":"The [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code for `maxAmount`. Must match the campaign `currencyISO` when provided."},"hasIntro":{"type":["boolean","null"],"description":"`true` if an introductory commission rate is configured."},"introType":{"type":["string","null"],"description":"How the introductory commission is calculated: `PERCENT` or `FIXED`."},"introPercent":{"type":["number","null"],"description":"The introductory commission percentage, used when `introType` is `PERCENT`."},"introAmount":{"type":["integer","null"],"description":"The introductory commission amount in the currency's smallest denomination, used when `introType` is `FIXED`."},"introAmountISO":{"type":["string","null"],"description":"The [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code for `introAmount`. Must match the campaign `currencyISO` when provided."},"introDuration":{"type":["string","null"],"description":"How long the introductory rate applies."},"introDurationInMonths":{"type":["integer","null"],"description":"When `introDuration` is repeating, the number of months the introductory rate applies."}},"additionalProperties":false},"Error":{"type":"object","properties":{"name":{"description":"Error name returned for the failed request.","type":"string"},"code":{"description":"Stable machine-readable error code.","type":"string"},"message":{"description":"Human-readable error message.","type":"string"},"errors":{"description":"Optional validation details for specific request fields.","type":"array","items":{"type":"object","additionalProperties":true}},"status":{"description":"HTTP status code for the error.","type":"integer"},"supportUrl":{"description":"Support URL related to the error, when available.","type":"string","format":"uri"},"policyName":{"description":"Rate-limit policy name for `429` errors, when available.","type":"string"},"level":{"description":"Error severity level, when available.","type":"string"},"timestamp":{"description":"When the error response was created.","type":"string","format":"date-time"}}}},"responses":{"BadRequest":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The API key is missing, invalid, revoked, outside its scope, or not allowed to perform this action.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Too many requests.","headers":{"GrowSurf-RateLimit-Second-Limit":{"description":"Number of API requests allowed per second policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Second-Remaining":{"description":"Number of API requests remaining in the second policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Second-Milliseconds":{"description":"Milliseconds until the second policy window resets.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Minute-Limit":{"description":"Number of API requests allowed per minute policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Minute-Remaining":{"description":"Number of API requests remaining in the minute policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Minute-Milliseconds":{"description":"Milliseconds until the minute policy window resets.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Hour-Limit":{"description":"Number of API requests allowed per hour policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Hour-Remaining":{"description":"Number of API requests remaining in the hour policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Hour-Milliseconds":{"description":"Milliseconds until the hour policy window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/campaign/{id}/participant/{participantIdOrEmail}":{"get":{"tags":["Participants"],"operationId":"retrieveParticipant","summary":"Retrieve participant","description":"Retrieves a single participant by GrowSurf participant ID or email address.","parameters":[{"$ref":"#/components/parameters/CampaignId"},{"$ref":"#/components/parameters/ParticipantIdOrEmail"}],"responses":{"200":{"description":"Participant returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Participant"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}}}} ``` ## Update participant > Updates a participant by GrowSurf participant ID or email address. ```json {"openapi":"3.1.0","info":{"title":"GrowSurf REST API","version":"2.0.0"},"tags":[{"name":"Participants","description":"Program participant retrieval, creation, updates, deletion, and referral triggering."}],"servers":[{"url":"https://api.growsurf.com/v2","description":"Production"}],"security":[{"apiKeyAuth":[]}],"components":{"securitySchemes":{"apiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"API key","description":"GrowSurf REST API key supplied as `Authorization: Bearer `."}},"parameters":{"CampaignId":{"name":"id","in":"path","required":true,"description":"GrowSurf program ID.","schema":{"type":"string"}},"ParticipantIdOrEmail":{"name":"participantIdOrEmail","in":"path","required":true,"description":"GrowSurf participant ID or URL-encoded participant email address.","schema":{"type":"string"}}},"schemas":{"UpdateParticipantRequest":{"type":"object","description":"The participant fields you can update. Any property not listed here is rejected with a `400` (you cannot update read-only fields such as counters, `origin`, or fraud state).","additionalProperties":false,"properties":{"referredBy":{"description":"Referrer participant ID or email address to assign to this participant.","type":"string","maxLength":100},"email":{"description":"Participant email address.","type":"string","format":"email"},"firstName":{"description":"Participant first name.","type":"string","maxLength":255},"lastName":{"description":"Participant last name.","type":"string","maxLength":255},"metadata":{"$ref":"#/components/schemas/Metadata"},"referralStatus":{"description":"Referral credit status for this participant.","type":"string","enum":["CREDIT_PENDING","CREDIT_AWARDED","CREDIT_EXPIRED"]},"vanityKeys":{"description":"Custom referral-code aliases for this participant. Sending this array replaces the existing aliases.","type":"array","maxItems":5,"items":{"type":"string","minLength":1,"maxLength":20,"pattern":"^[A-Za-z0-9_-]+$"}},"unsubscribed":{"description":"Whether the participant is unsubscribed from program emails.","type":"boolean"},"notes":{"type":"string","maxLength":500,"description":"Freeform internal notes about the participant (internal only, never exposed to participants)."},"paypalEmail":{"type":"string","format":"email","description":"The participant's PayPal email address, used for affiliate payouts."}}},"Metadata":{"type":"object","description":"Shallow custom metadata object.","additionalProperties":true},"Participant":{"type":"object","description":"Detailed information about a program participant.","required":["id","referralCount","monthlyReferralCount","rank","monthlyRank","shareUrl","rewards","email"],"properties":{"id":{"type":"string","readOnly":true,"description":"The unique identifier of the participant."},"firstName":{"type":["string","null"],"description":"The first name of the participant."},"lastName":{"type":["string","null"],"description":"The last name of the participant."},"email":{"type":"string","description":"The email of the participant."},"paypalEmailAddress":{"type":"string","format":"email","description":"The PayPal email address on file for the participant, used for affiliate or PayPal reward payouts."},"referralCount":{"type":"integer","readOnly":true,"description":"The total number of referrals made by the participant."},"monthlyReferralCount":{"type":"integer","readOnly":true,"description":"The total number of referrals made this month by the participant (resets at the end of the month)."},"prevMonthlyReferralCount":{"type":"integer","readOnly":true,"description":"The total number of referrals made the previous month by the participant."},"rank":{"type":"integer","readOnly":true,"description":"The rank of the participant."},"monthlyRank":{"type":"integer","readOnly":true,"description":"The monthly rank of the participant. This rank resets to 0 at the end of each month."},"prevMonthlyRank":{"type":"integer","readOnly":true,"description":"The previous monthly rank of the participant. Not returned if the participant did not exist in your program during the previous month."},"shareUrl":{"type":"string","readOnly":true,"description":"The unique share URL of the participant."},"createdAt":{"type":"integer","format":"int64","readOnly":true,"description":"The date the participant was added to the program (UTC milliseconds)."},"referralSource":{"$ref":"#/components/schemas/ReferralSource","readOnly":true,"description":"The source of how the participant joined the program."},"referralStatus":{"$ref":"#/components/schemas/ReferralStatus","description":"If the participant was referred, the referrer's status in receiving the referral credit. Only applicable if the participant was referred into the program."},"referredBy":{"type":"string","description":"The ID of the referrer. Only applicable if the participant was referred into the program."},"fraudRiskLevel":{"$ref":"#/components/schemas/FraudRiskLevel","readOnly":true,"description":"A value that represents the integrity of the participant."},"fraudReasonCode":{"type":"string","readOnly":true,"description":"The reason for the participant's `fraudRiskLevel`:\n\n- `UNIQUE_IDENTITY` — They have a unique identity (no other participant has the same identity).\n- `DUPLICATE_EMAIL` — Their email is not unique and is identical to another participant's email (e.g., gavin@hooli.com = gavin+1@hooli.com).\n- `DUPLICATE_IDENTITY` — Their identity (fingerprint or mobile instance ID) is not unique and matches another participant's.\n- `DUPLICATE_IDENTITY_EXCESSIVE` — Within a small window of time, they had an excessive number of referred participants who also shared the same IP address.\n- `EMAIL_FRAUD` — Their email was found to match another participant's when updated in a connected billing or payment integration.\n- `SIMILAR_EMAIL` — Their browser fingerprint matches another participant's and their email looks suspiciously similar.\n- `SIMILAR_FIRST_NAME` — Their browser fingerprint matches another participant's and their first name looks suspiciously similar.\n- `SIMILAR_LAST_NAME` — Their browser fingerprint matches another participant's and their last name looks suspiciously similar.\n- `REFERRAL_EMAIL_PATTERN` — (Status for a referred person) Their email matched a similar pattern to their referrer's email.\n- `REFERRAL_CHAIN_FRAUD` — (Status for a referrer or referred person) Their characteristics matched a pattern with other referrals the referrer made, indicating a fraud ring.\n- `REFERRAL_VELOCITY_FRAUD` — (Status for a referrer or referred person) The referrer made an excessive number of referrals in a short period of time.\n- `DOMAIN_CLUSTERING_FRAUD` — (Status for a referrer or referred person) The referrer made an excessive number of referrals sharing the same suspicious domain in a short period of time.\n- `MANUAL_UPDATE` — They were manually marked as a fraudster from the GrowSurf dashboard.\n- `WHITELISTED` — They were allowed to join the program because one of their properties matched an allowed value.\n- `BLACKLIST_MATCH` — They were not allowed to join the program because one of their properties matched a blocked value.\n- `BLOCKED_IP` — They were not allowed to join the program because their IP address was recently blocked by antifraud IP throttling.\n- `REFERRER_HIGH_RISK` — They were not allowed to join the program because their referrer was a high-risk fraudster."},"isWinner":{"type":"boolean","readOnly":true,"description":"`true` if the participant has earned one or more rewards."},"shareCount":{"type":"object","readOnly":true,"additionalProperties":{"type":"integer"},"description":"An object containing counts of how many times the participant has shared their referral link, keyed by channel. Standard web channels include `email`, `facebook`, and `twitter`; SDK/native-share channels include `iosNativeShare` and `androidNativeShare`."},"impressionCount":{"type":"integer","readOnly":true,"description":"The total number of impressions the participant has made."},"uniqueImpressionCount":{"type":"integer","readOnly":true,"description":"The total number of unique impressions the participant has made."},"inviteCount":{"type":"integer","readOnly":true,"description":"The total number of invites the participant has sent."},"referrals":{"type":"array","readOnly":true,"items":{"type":"string"},"description":"A list of `Participant` IDs who were successfully referred by the participant. Limited to the 100 most recently referred friends."},"monthlyReferrals":{"type":"array","readOnly":true,"items":{"type":"string"},"description":"A list of `Participant` IDs successfully referred by the participant this month (resets at the end of the month). Limited to the 100 most recent."},"referrer":{"readOnly":true,"oneOf":[{"$ref":"#/components/schemas/ParticipantReferrer"},{"type":"null"}],"description":"An object containing the participant's referrer information. Only applicable if the participant was referred into the program."},"ipAddress":{"type":["string","null"],"description":"The IP address associated with the participant, used for anti-fraud matching."},"fingerprint":{"type":["string","null"],"description":"The browser fingerprint associated with the participant, used for anti-fraud matching."},"mobileInstanceId":{"type":["string","null"],"description":"App-install scoped mobile identifier used for anti-fraud matching when provided by native mobile apps. The official mobile SDKs generate this as a lowercase UUID. Not stored when strict GDPR/CCPA mode is enabled."},"metadata":{"$ref":"#/components/schemas/Metadata","description":"An object containing any custom key-value data, useful for saving additional data for the participant (e.g., `company`, `companySize`). Metadata is never used by GrowSurf and usage is optional. Metadata is returned only in REST API calls, and never in JavaScript Web API calls. See [API Guidelines](https://docs.growsurf.com/developer-tools/rest-api/api-guidelines)."},"notes":{"type":["string","null"],"description":"Internal notes about the participant, added via the [GrowSurf Dashboard](https://growsurf.com/dashboard)."},"unsubscribed":{"type":"boolean","description":"`true` if the participant has unsubscribed from program emails."},"rewards":{"type":"array","readOnly":true,"items":{"$ref":"#/components/schemas/ParticipantReward"},"description":"A list of the rewards the participant has earned."},"vanityKeys":{"type":"array","items":{"type":"string"},"description":"The list of vanity keys that the participant has."},"unreadCommissionsCount":{"type":"integer","readOnly":true,"description":"Affiliate programs only. The number of commissions the participant has not yet viewed."},"unreadPayoutsCount":{"type":"integer","readOnly":true,"description":"Affiliate programs only. The number of payouts the participant has not yet viewed."},"isNew":{"type":"boolean","readOnly":true,"description":"Whether this participant was newly created by the request. Returned by participant creation calls; `false` when the participant already existed."},"allMatchingFraudsters":{"type":"array","readOnly":true,"items":{"type":"object","additionalProperties":true},"description":"A list of other participants flagged as matching this participant during anti-fraud checks."},"payoutSettings":{"type":"object","readOnly":true,"description":"Payout-related actions the participant must complete before a payout can be released (e.g. confirming a PayPal email or submitting a W-9/W-8 tax form). Always present; the requiredActions array is empty when no action is required.","properties":{"requiredActions":{"description":"Actions the participant must complete before payouts can be sent.","type":"array","readOnly":true,"items":{"type":"string","enum":["PAYPAL_EMAIL","TAX_INFO"]}}}}}},"ReferralSource":{"type":"string","enum":["DIRECT","PARTICIPANT"]},"ReferralStatus":{"type":"string","enum":["CREDIT_PENDING","CREDIT_AWARDED","CREDIT_EXPIRED","INVITE_SENT"]},"FraudRiskLevel":{"type":"string","enum":["LOW","MEDIUM","HIGH"]},"ParticipantReferrer":{"type":"object","description":"Summary information about a participant's referrer, returned within the `referrer` field of a `Participant`.","properties":{"id":{"type":"string","description":"The unique identifier of the referrer."},"firstName":{"type":["string","null"],"description":"The first name of the referrer."},"lastName":{"type":["string","null"],"description":"The last name of the referrer."},"email":{"type":"string","description":"The email of the referrer."},"referralCount":{"type":"integer","description":"The total number of referrals made by the referrer."},"monthlyReferralCount":{"type":"integer","description":"The total number of referrals made this month by the referrer (resets at the end of the month)."},"prevMonthlyReferralCount":{"type":"integer","description":"The total number of referrals made the previous month by the referrer."},"rank":{"type":"integer","description":"The rank of the referrer."},"monthlyRank":{"type":"integer","description":"The monthly rank of the referrer. This rank resets to 0 at the end of each month."},"prevMonthlyRank":{"type":"integer","description":"The previous monthly rank of the referrer."},"shareUrl":{"type":"string","description":"The unique share URL of the referrer."},"createdAt":{"type":"integer","format":"int64","description":"The date the referrer was added to the program (UTC milliseconds)."},"referralSource":{"$ref":"#/components/schemas/ReferralSource","description":"The source of how the referrer joined the program."},"referralStatus":{"$ref":"#/components/schemas/ReferralStatus","description":"If the referrer was themselves referred, their referrer's status in receiving the referral credit."},"fraudRiskLevel":{"$ref":"#/components/schemas/FraudRiskLevel","description":"A value that represents the integrity of the referrer."},"fraudReasonCode":{"type":"string","description":"The reason for the referrer's `fraudRiskLevel`. See `Participant.fraudReasonCode` for the list of possible values."},"isWinner":{"type":"boolean","description":"`true` if the referrer has earned one or more rewards."},"shareCount":{"type":"object","additionalProperties":{"type":"integer"},"description":"An object containing counts of how many times the referrer has shared their referral link, keyed by channel."},"impressionCount":{"type":"integer","description":"The total number of impressions the referrer has made."},"uniqueImpressionCount":{"type":"integer","description":"The total number of unique impressions the referrer has made."},"inviteCount":{"type":"integer","description":"The total number of invites the referrer has sent."},"referrals":{"type":"array","items":{"type":"string"},"description":"A list of `Participant` IDs who were successfully referred by the referrer. Limited to the 100 most recent."},"monthlyReferrals":{"type":"array","items":{"type":"string"},"description":"A list of `Participant` IDs successfully referred by the referrer this month (resets at the end of the month). Limited to the 100 most recent."},"ipAddress":{"type":["string","null"],"description":"The IP address associated with the referrer, used for anti-fraud matching."},"fingerprint":{"type":["string","null"],"description":"The browser fingerprint associated with the referrer, used for anti-fraud matching."},"metadata":{"$ref":"#/components/schemas/Metadata","description":"An object containing any custom key-value data for the referrer."},"unsubscribed":{"type":"boolean","description":"`true` if the referrer has unsubscribed from program emails."}}},"ParticipantReward":{"type":"object","description":"A reward that a participant has earned. This is different from a program `Reward` Object and contains information pertinent only to the participant that earned the reward.","required":["id","rewardId","status"],"properties":{"id":{"type":"string","readOnly":true,"description":"The unique identifier of the participant's reward. This is different for every new reward the participant earns."},"rewardId":{"type":"string","readOnly":true,"description":"The ID of the program `Reward` (`CampaignReward`) that this participant has earned."},"status":{"$ref":"#/components/schemas/RewardStatus","readOnly":true,"description":"The status of the participant's reward."},"unread":{"type":"boolean","readOnly":true,"description":"`true` if the participant has not yet seen the reward in a GrowSurf window."},"approved":{"type":"boolean","readOnly":true,"description":"`true` if the participant's reward has been approved."},"approvedAt":{"type":["integer","null"],"format":"int64","readOnly":true,"description":"The date and time the reward was approved for this participant (UTC milliseconds). `null` for unapproved rewards."},"fulfilledAt":{"type":["integer","null"],"format":"int64","readOnly":true,"description":"The date and time the reward was fulfilled for this participant (UTC milliseconds). `null` for unapproved or unfulfilled rewards."},"isReferrer":{"type":"boolean","readOnly":true,"description":"`true` if the participant earned the reward as the referrer; `false` if they earned it as the referred friend (only applicable for double-sided reward types)."},"isAvailable":{"type":"boolean","readOnly":true,"description":"`true` if the reward is available for the participant to claim or redeem."},"isFulfilled":{"type":"boolean","readOnly":true,"description":"`true` if the participant's reward has been fulfilled."},"referredId":{"type":"string","readOnly":true,"description":"The ID of the friend that was referred."},"referrerId":{"type":"string","readOnly":true,"description":"The ID of the participant that made the referral."},"commissionStructure":{"readOnly":true,"oneOf":[{"$ref":"#/components/schemas/CommissionStructure"},{"type":"null"}],"description":"The commission structure associated with this reward. Present only for affiliate programs."}}},"RewardStatus":{"type":"string","enum":["PENDING","FULFILLED"]},"CommissionStructure":{"type":"object","description":"The commission configuration for an affiliate reward. Present only for affiliate programs.","properties":{"amount":{"type":["integer","null"],"description":"Fixed commission amount in the currency's smallest denomination, used when `type` is `FIXED`. `null` for percentage-based commissions."},"amountISO":{"type":["string","null"],"description":"ISO 4217 currency code for the fixed `amount`. Defaults to the program's currency when omitted. Must match the campaign `currencyISO` when provided. `null` for percentage-based commissions."},"event":{"type":["string","null"],"description":"The event that generates a commission (e.g., `SALE`)."},"type":{"type":["string","null"],"enum":["PERCENT","FIXED",null],"description":"How the commission is calculated: `PERCENT` (a percentage of the sale) or `FIXED` (a fixed `amount`)."},"minPaidReferrals":{"type":["integer","null"],"description":"The minimum number of paid referrals required before commissions are earned."},"holdDuration":{"type":["integer","null"],"description":"Number of days a commission is held before it can be paid out."},"duration":{"type":["string","null"],"description":"How long commissions continue to be earned for a referred customer."},"durationInMonths":{"type":["integer","null"],"description":"When `duration` is repeating, the number of months over which commissions are earned."},"approvalRequired":{"type":["boolean","null"],"description":"`true` if commissions require manual approval before they can be paid out."},"percent":{"type":["number","null"],"description":"The commission percentage, used when `type` is `PERCENT`."},"hasMaxAmount":{"type":["boolean","null"],"description":"`true` if a maximum commission amount cap is configured."},"maxAmount":{"type":["integer","null"],"description":"The maximum commission amount cap in the currency's smallest denomination. `null` if no cap is set."},"maxAmountISO":{"type":["string","null"],"description":"The [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code for `maxAmount`. Must match the campaign `currencyISO` when provided."},"hasIntro":{"type":["boolean","null"],"description":"`true` if an introductory commission rate is configured."},"introType":{"type":["string","null"],"description":"How the introductory commission is calculated: `PERCENT` or `FIXED`."},"introPercent":{"type":["number","null"],"description":"The introductory commission percentage, used when `introType` is `PERCENT`."},"introAmount":{"type":["integer","null"],"description":"The introductory commission amount in the currency's smallest denomination, used when `introType` is `FIXED`."},"introAmountISO":{"type":["string","null"],"description":"The [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code for `introAmount`. Must match the campaign `currencyISO` when provided."},"introDuration":{"type":["string","null"],"description":"How long the introductory rate applies."},"introDurationInMonths":{"type":["integer","null"],"description":"When `introDuration` is repeating, the number of months the introductory rate applies."}},"additionalProperties":false},"Error":{"type":"object","properties":{"name":{"description":"Error name returned for the failed request.","type":"string"},"code":{"description":"Stable machine-readable error code.","type":"string"},"message":{"description":"Human-readable error message.","type":"string"},"errors":{"description":"Optional validation details for specific request fields.","type":"array","items":{"type":"object","additionalProperties":true}},"status":{"description":"HTTP status code for the error.","type":"integer"},"supportUrl":{"description":"Support URL related to the error, when available.","type":"string","format":"uri"},"policyName":{"description":"Rate-limit policy name for `429` errors, when available.","type":"string"},"level":{"description":"Error severity level, when available.","type":"string"},"timestamp":{"description":"When the error response was created.","type":"string","format":"date-time"}}}},"responses":{"BadRequest":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The API key is missing, invalid, revoked, outside its scope, or not allowed to perform this action.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Conflict":{"description":"Conflicting duplicate request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Too many requests.","headers":{"GrowSurf-RateLimit-Second-Limit":{"description":"Number of API requests allowed per second policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Second-Remaining":{"description":"Number of API requests remaining in the second policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Second-Milliseconds":{"description":"Milliseconds until the second policy window resets.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Minute-Limit":{"description":"Number of API requests allowed per minute policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Minute-Remaining":{"description":"Number of API requests remaining in the minute policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Minute-Milliseconds":{"description":"Milliseconds until the minute policy window resets.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Hour-Limit":{"description":"Number of API requests allowed per hour policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Hour-Remaining":{"description":"Number of API requests remaining in the hour policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Hour-Milliseconds":{"description":"Milliseconds until the hour policy window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/campaign/{id}/participant/{participantIdOrEmail}":{"post":{"tags":["Participants"],"operationId":"updateParticipant","summary":"Update participant","description":"Updates a participant by GrowSurf participant ID or email address.","parameters":[{"$ref":"#/components/parameters/CampaignId"},{"$ref":"#/components/parameters/ParticipantIdOrEmail"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateParticipantRequest"}}}},"responses":{"200":{"description":"Updated participant returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Participant"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"}}}}}} ``` ## Delete participant > Removes a participant by GrowSurf participant ID or email address. ```json {"openapi":"3.1.0","info":{"title":"GrowSurf REST API","version":"2.0.0"},"tags":[{"name":"Participants","description":"Program participant retrieval, creation, updates, deletion, and referral triggering."}],"servers":[{"url":"https://api.growsurf.com/v2","description":"Production"}],"security":[{"apiKeyAuth":[]}],"components":{"securitySchemes":{"apiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"API key","description":"GrowSurf REST API key supplied as `Authorization: Bearer `."}},"parameters":{"CampaignId":{"name":"id","in":"path","required":true,"description":"GrowSurf program ID.","schema":{"type":"string"}},"ParticipantIdOrEmail":{"name":"participantIdOrEmail","in":"path","required":true,"description":"GrowSurf participant ID or URL-encoded participant email address.","schema":{"type":"string"}}},"responses":{"Success":{"description":"Success response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"BadRequest":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The API key is missing, invalid, revoked, outside its scope, or not allowed to perform this action.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Too many requests.","headers":{"GrowSurf-RateLimit-Second-Limit":{"description":"Number of API requests allowed per second policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Second-Remaining":{"description":"Number of API requests remaining in the second policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Second-Milliseconds":{"description":"Milliseconds until the second policy window resets.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Minute-Limit":{"description":"Number of API requests allowed per minute policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Minute-Remaining":{"description":"Number of API requests remaining in the minute policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Minute-Milliseconds":{"description":"Milliseconds until the minute policy window resets.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Hour-Limit":{"description":"Number of API requests allowed per hour policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Hour-Remaining":{"description":"Number of API requests remaining in the hour policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Hour-Milliseconds":{"description":"Milliseconds until the hour policy window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"SuccessResponse":{"type":"object","required":["success"],"properties":{"success":{"description":"Whether the request succeeded.","type":"boolean"}}},"Error":{"type":"object","properties":{"name":{"description":"Error name returned for the failed request.","type":"string"},"code":{"description":"Stable machine-readable error code.","type":"string"},"message":{"description":"Human-readable error message.","type":"string"},"errors":{"description":"Optional validation details for specific request fields.","type":"array","items":{"type":"object","additionalProperties":true}},"status":{"description":"HTTP status code for the error.","type":"integer"},"supportUrl":{"description":"Support URL related to the error, when available.","type":"string","format":"uri"},"policyName":{"description":"Rate-limit policy name for `429` errors, when available.","type":"string"},"level":{"description":"Error severity level, when available.","type":"string"},"timestamp":{"description":"When the error response was created.","type":"string","format":"date-time"}}}}},"paths":{"/campaign/{id}/participant/{participantIdOrEmail}":{"delete":{"tags":["Participants"],"operationId":"deleteParticipant","summary":"Delete participant","description":"Removes a participant by GrowSurf participant ID or email address.","parameters":[{"$ref":"#/components/parameters/CampaignId"},{"$ref":"#/components/parameters/ParticipantIdOrEmail"}],"responses":{"200":{"$ref":"#/components/responses/Success"},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}}}} ``` ## Bulk delete participants > Deletes a list of participants from a program in one request. Each entry in \`participants\` is a GrowSurf participant ID or an email address (mixed lists are allowed). Up to \`200\` entries per request — chunk larger lists across multiple calls. The response reports a per-row \`status\` for every submitted entry, so a \`200\` can include rows that were \`NOT\_FOUND\` or failed. Deletion is permanent and removes the participants' referrals, rewards, commissions, and payout records. ```json {"openapi":"3.1.0","info":{"title":"GrowSurf REST API","version":"2.0.0"},"tags":[{"name":"Participants","description":"Program participant retrieval, creation, updates, deletion, and referral triggering."}],"servers":[{"url":"https://api.growsurf.com/v2","description":"Production"}],"security":[{"apiKeyAuth":[]}],"components":{"securitySchemes":{"apiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"API key","description":"GrowSurf REST API key supplied as `Authorization: Bearer `."}},"parameters":{"CampaignId":{"name":"id","in":"path","required":true,"description":"GrowSurf program ID.","schema":{"type":"string"}}},"schemas":{"BulkDeleteParticipantsRequest":{"type":"object","required":["participants"],"additionalProperties":false,"properties":{"participants":{"type":"array","minItems":1,"maxItems":200,"description":"GrowSurf participant IDs and/or email addresses to delete. Mixed entries are allowed.","items":{"type":"string","minLength":1}}}},"BulkDeleteParticipantsResponse":{"type":"object","required":["summary","results"],"properties":{"summary":{"description":"Counts of submitted, deleted, not-found, duplicate, and failed entries.","$ref":"#/components/schemas/BulkDeleteParticipantsSummary"},"results":{"type":"array","description":"One entry per submitted identifier, in the same order as the request.","items":{"$ref":"#/components/schemas/BulkDeleteParticipantResult"}}}},"BulkDeleteParticipantsSummary":{"type":"object","required":["total","deletedCount","notFoundCount","duplicateCount","errorCount"],"properties":{"total":{"type":"integer","description":"Number of entries submitted in this request."},"deletedCount":{"type":"integer","description":"Entries that resolved to a participant and were deleted."},"notFoundCount":{"type":"integer","description":"Entries that did not match any participant."},"duplicateCount":{"type":"integer","description":"Entries that resolved to the same participant as an earlier entry."},"errorCount":{"type":"integer","description":"Entries that failed to look up or delete."}}},"BulkDeleteParticipantResult":{"type":"object","required":["index","identifier","status"],"properties":{"index":{"type":"integer","description":"Zero-based position of this entry in the submitted `participants` array."},"identifier":{"type":"string","description":"The submitted participant ID or email address, echoed back as received."},"status":{"$ref":"#/components/schemas/BulkDeleteParticipantStatus"},"participantId":{"type":"string","description":"The resolved GrowSurf participant ID. Present when the entry resolved to a participant."},"email":{"type":"string","format":"email","description":"The resolved participant's email address. Present on `DELETED` rows."},"message":{"type":"string","description":"Human-readable detail for `NOT_FOUND`, `DUPLICATE`, and `ERROR` rows."}}},"BulkDeleteParticipantStatus":{"type":"string","enum":["DELETED","NOT_FOUND","DUPLICATE","ERROR"],"description":"Per-row outcome. `DELETED` — the participant was resolved and removed. `NOT_FOUND` — no participant matches the ID or email. `DUPLICATE` — the entry resolves to the same participant as an earlier entry in the same request. `ERROR` — the lookup or deletion failed for this row."},"Error":{"type":"object","properties":{"name":{"description":"Error name returned for the failed request.","type":"string"},"code":{"description":"Stable machine-readable error code.","type":"string"},"message":{"description":"Human-readable error message.","type":"string"},"errors":{"description":"Optional validation details for specific request fields.","type":"array","items":{"type":"object","additionalProperties":true}},"status":{"description":"HTTP status code for the error.","type":"integer"},"supportUrl":{"description":"Support URL related to the error, when available.","type":"string","format":"uri"},"policyName":{"description":"Rate-limit policy name for `429` errors, when available.","type":"string"},"level":{"description":"Error severity level, when available.","type":"string"},"timestamp":{"description":"When the error response was created.","type":"string","format":"date-time"}}}},"responses":{"BadRequest":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The API key is missing, invalid, revoked, outside its scope, or not allowed to perform this action.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Too many requests.","headers":{"GrowSurf-RateLimit-Second-Limit":{"description":"Number of API requests allowed per second policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Second-Remaining":{"description":"Number of API requests remaining in the second policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Second-Milliseconds":{"description":"Milliseconds until the second policy window resets.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Minute-Limit":{"description":"Number of API requests allowed per minute policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Minute-Remaining":{"description":"Number of API requests remaining in the minute policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Minute-Milliseconds":{"description":"Milliseconds until the minute policy window resets.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Hour-Limit":{"description":"Number of API requests allowed per hour policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Hour-Remaining":{"description":"Number of API requests remaining in the hour policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Hour-Milliseconds":{"description":"Milliseconds until the hour policy window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/campaign/{id}/participants/bulk-delete":{"post":{"tags":["Participants"],"operationId":"bulkDeleteParticipants","summary":"Bulk delete participants","description":"Deletes a list of participants from a program in one request. Each entry in `participants` is a GrowSurf participant ID or an email address (mixed lists are allowed). Up to `200` entries per request — chunk larger lists across multiple calls. The response reports a per-row `status` for every submitted entry, so a `200` can include rows that were `NOT_FOUND` or failed. Deletion is permanent and removes the participants' referrals, rewards, commissions, and payout records.","parameters":[{"$ref":"#/components/parameters/CampaignId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkDeleteParticipantsRequest"}}}},"responses":{"200":{"description":"Per-row outcomes returned (individual rows may still be `NOT_FOUND`, `DUPLICATE`, or `ERROR`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkDeleteParticipantsResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}}}} ``` ## Trigger referral > Triggers referral credit for an existing referred participant by GrowSurf participant ID or email address. Optionally pass \`delayInDays\` to hold the credit for a number of days before it is awarded (for example, to cover your own refund window). A delayed trigger can be cancelled before it is awarded with the Cancel delayed referral trigger request (DELETE on this same path). ```json {"openapi":"3.1.0","info":{"title":"GrowSurf REST API","version":"2.0.0"},"tags":[{"name":"Participants","description":"Program participant retrieval, creation, updates, deletion, and referral triggering."}],"servers":[{"url":"https://api.growsurf.com/v2","description":"Production"}],"security":[{"apiKeyAuth":[]}],"components":{"securitySchemes":{"apiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"API key","description":"GrowSurf REST API key supplied as `Authorization: Bearer `."}},"parameters":{"CampaignId":{"name":"id","in":"path","required":true,"description":"GrowSurf program ID.","schema":{"type":"string"}},"ParticipantIdOrEmail":{"name":"participantIdOrEmail","in":"path","required":true,"description":"GrowSurf participant ID or URL-encoded participant email address.","schema":{"type":"string"}}},"schemas":{"TriggerReferralRequest":{"type":"object","description":"Optional body for a referral trigger. Omit it (or send an empty object) to award credit immediately.","properties":{"delayInDays":{"type":"integer","minimum":1,"maximum":90,"description":"Number of whole days to hold referral credit before it is awarded. Useful for honoring a refund window before crediting a referrer. Omit this field to award credit immediately. The credit is awarded automatically once the delay elapses, and can be cancelled before then with the Cancel delayed referral trigger request."}}},"ReferralTriggerResponse":{"type":"object","required":["success"],"properties":{"success":{"description":"Whether referral credit was awarded or scheduled.","type":"boolean"},"message":{"description":"Human-readable result message, present when credit was not awarded immediately or when a delayed trigger was scheduled.","type":"string"}}},"Error":{"type":"object","properties":{"name":{"description":"Error name returned for the failed request.","type":"string"},"code":{"description":"Stable machine-readable error code.","type":"string"},"message":{"description":"Human-readable error message.","type":"string"},"errors":{"description":"Optional validation details for specific request fields.","type":"array","items":{"type":"object","additionalProperties":true}},"status":{"description":"HTTP status code for the error.","type":"integer"},"supportUrl":{"description":"Support URL related to the error, when available.","type":"string","format":"uri"},"policyName":{"description":"Rate-limit policy name for `429` errors, when available.","type":"string"},"level":{"description":"Error severity level, when available.","type":"string"},"timestamp":{"description":"When the error response was created.","type":"string","format":"date-time"}}}},"responses":{"BadRequest":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The API key is missing, invalid, revoked, outside its scope, or not allowed to perform this action.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"UnprocessableEntity":{"description":"Request is not valid for the current program or participant state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Too many requests.","headers":{"GrowSurf-RateLimit-Second-Limit":{"description":"Number of API requests allowed per second policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Second-Remaining":{"description":"Number of API requests remaining in the second policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Second-Milliseconds":{"description":"Milliseconds until the second policy window resets.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Minute-Limit":{"description":"Number of API requests allowed per minute policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Minute-Remaining":{"description":"Number of API requests remaining in the minute policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Minute-Milliseconds":{"description":"Milliseconds until the minute policy window resets.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Hour-Limit":{"description":"Number of API requests allowed per hour policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Hour-Remaining":{"description":"Number of API requests remaining in the hour policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Hour-Milliseconds":{"description":"Milliseconds until the hour policy window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/campaign/{id}/participant/{participantIdOrEmail}/ref":{"post":{"tags":["Participants"],"operationId":"triggerReferral","summary":"Trigger referral","description":"Triggers referral credit for an existing referred participant by GrowSurf participant ID or email address. Optionally pass `delayInDays` to hold the credit for a number of days before it is awarded (for example, to cover your own refund window). A delayed trigger can be cancelled before it is awarded with the Cancel delayed referral trigger request (DELETE on this same path).","parameters":[{"$ref":"#/components/parameters/CampaignId"},{"$ref":"#/components/parameters/ParticipantIdOrEmail"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TriggerReferralRequest"}}}},"responses":{"200":{"description":"Referral trigger result returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReferralTriggerResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"}}}}}} ``` ## Cancel delayed referral trigger > Cancels a pending delayed referral trigger for a participant (the companion to a delayed Trigger referral request). Use this to undo a scheduled referral credit before it is awarded, for example when a refund occurs inside your refund window. If the participant has no pending delayed trigger, \`success\` is returned as \`false\`. ```json {"openapi":"3.1.0","info":{"title":"GrowSurf REST API","version":"2.0.0"},"tags":[{"name":"Participants","description":"Program participant retrieval, creation, updates, deletion, and referral triggering."}],"servers":[{"url":"https://api.growsurf.com/v2","description":"Production"}],"security":[{"apiKeyAuth":[]}],"components":{"securitySchemes":{"apiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"API key","description":"GrowSurf REST API key supplied as `Authorization: Bearer `."}},"parameters":{"CampaignId":{"name":"id","in":"path","required":true,"description":"GrowSurf program ID.","schema":{"type":"string"}},"ParticipantIdOrEmail":{"name":"participantIdOrEmail","in":"path","required":true,"description":"GrowSurf participant ID or URL-encoded participant email address.","schema":{"type":"string"}}},"schemas":{"ReferralTriggerResponse":{"type":"object","required":["success"],"properties":{"success":{"description":"Whether referral credit was awarded or scheduled.","type":"boolean"},"message":{"description":"Human-readable result message, present when credit was not awarded immediately or when a delayed trigger was scheduled.","type":"string"}}},"Error":{"type":"object","properties":{"name":{"description":"Error name returned for the failed request.","type":"string"},"code":{"description":"Stable machine-readable error code.","type":"string"},"message":{"description":"Human-readable error message.","type":"string"},"errors":{"description":"Optional validation details for specific request fields.","type":"array","items":{"type":"object","additionalProperties":true}},"status":{"description":"HTTP status code for the error.","type":"integer"},"supportUrl":{"description":"Support URL related to the error, when available.","type":"string","format":"uri"},"policyName":{"description":"Rate-limit policy name for `429` errors, when available.","type":"string"},"level":{"description":"Error severity level, when available.","type":"string"},"timestamp":{"description":"When the error response was created.","type":"string","format":"date-time"}}}},"responses":{"BadRequest":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The API key is missing, invalid, revoked, outside its scope, or not allowed to perform this action.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"UnprocessableEntity":{"description":"Request is not valid for the current program or participant state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Too many requests.","headers":{"GrowSurf-RateLimit-Second-Limit":{"description":"Number of API requests allowed per second policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Second-Remaining":{"description":"Number of API requests remaining in the second policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Second-Milliseconds":{"description":"Milliseconds until the second policy window resets.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Minute-Limit":{"description":"Number of API requests allowed per minute policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Minute-Remaining":{"description":"Number of API requests remaining in the minute policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Minute-Milliseconds":{"description":"Milliseconds until the minute policy window resets.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Hour-Limit":{"description":"Number of API requests allowed per hour policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Hour-Remaining":{"description":"Number of API requests remaining in the hour policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Hour-Milliseconds":{"description":"Milliseconds until the hour policy window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/campaign/{id}/participant/{participantIdOrEmail}/ref":{"delete":{"tags":["Participants"],"operationId":"cancelDelayedReferral","summary":"Cancel delayed referral trigger","description":"Cancels a pending delayed referral trigger for a participant (the companion to a delayed Trigger referral request). Use this to undo a scheduled referral credit before it is awarded, for example when a refund occurs inside your refund window. If the participant has no pending delayed trigger, `success` is returned as `false`.","parameters":[{"$ref":"#/components/parameters/CampaignId"},{"$ref":"#/components/parameters/ParticipantIdOrEmail"}],"responses":{"200":{"description":"Delayed referral trigger cancellation result returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReferralTriggerResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"}}}}}} ``` ## Create mobile participant token > Creates or returns a participant using the same input behavior as Add Participant, then returns a participant-scoped token for GrowSurf mobile SDK participant endpoints. Use this endpoint from your backend after your mobile app authenticates a signed-in user. The program must have mobile SDK access enabled. ```json {"openapi":"3.1.0","info":{"title":"GrowSurf REST API","version":"2.0.0"},"tags":[{"name":"Participants","description":"Program participant retrieval, creation, updates, deletion, and referral triggering."}],"servers":[{"url":"https://api.growsurf.com/v2","description":"Production"}],"security":[{"apiKeyAuth":[]}],"components":{"securitySchemes":{"apiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"API key","description":"GrowSurf REST API key supplied as `Authorization: Bearer `."}},"parameters":{"CampaignId":{"name":"id","in":"path","required":true,"description":"GrowSurf program ID.","schema":{"type":"string"}}},"schemas":{"CreateParticipantRequest":{"type":"object","required":["email"],"properties":{"email":{"description":"Participant email address.","type":"string","format":"email"},"referredBy":{"type":"string","description":"Referrer participant ID or email address.","maxLength":100},"referralStatus":{"type":"string","enum":["CREDIT_PENDING","CREDIT_AWARDED"],"description":"The referral credit status, only meaningful when `referredBy` resolves to a referrer. When omitted, it is derived from the program's referral trigger: `CREDIT_AWARDED`, `CREDIT_PENDING` (manual or custom trigger), or `CREDIT_EXPIRED` (past the credit window). Left unset when no referrer resolves."},"firstName":{"description":"Participant first name.","type":"string","maxLength":255},"lastName":{"description":"Participant last name.","type":"string","maxLength":255},"ipAddress":{"description":"Participant IP address, used for fraud checks when provided.","type":"string"},"fingerprint":{"description":"Browser fingerprint, used for fraud checks when provided.","type":"string"},"mobileInstanceId":{"type":"string","description":"Optional app-install scoped identifier for native mobile anti-fraud. Recommended for mobile participant creation and mobile participant token flows. The official mobile SDKs generate this as a lowercase UUID."},"metadata":{"$ref":"#/components/schemas/Metadata"}}},"Metadata":{"type":"object","description":"Shallow custom metadata object.","additionalProperties":true},"MobileParticipantTokenResponse":{"type":"object","required":["participantToken","expiresIn","participant","isNew"],"properties":{"participantToken":{"type":"string","description":"Participant-scoped bearer token for GrowSurf mobile SDK participant endpoints."},"expiresIn":{"type":"integer","description":"Token lifetime in seconds."},"participant":{"$ref":"#/components/schemas/Participant"},"isNew":{"type":"boolean","description":"Whether this request created a new participant. Returns false when the participant already existed."}}},"Participant":{"type":"object","description":"Detailed information about a program participant.","required":["id","referralCount","monthlyReferralCount","rank","monthlyRank","shareUrl","rewards","email"],"properties":{"id":{"type":"string","readOnly":true,"description":"The unique identifier of the participant."},"firstName":{"type":["string","null"],"description":"The first name of the participant."},"lastName":{"type":["string","null"],"description":"The last name of the participant."},"email":{"type":"string","description":"The email of the participant."},"paypalEmailAddress":{"type":"string","format":"email","description":"The PayPal email address on file for the participant, used for affiliate or PayPal reward payouts."},"referralCount":{"type":"integer","readOnly":true,"description":"The total number of referrals made by the participant."},"monthlyReferralCount":{"type":"integer","readOnly":true,"description":"The total number of referrals made this month by the participant (resets at the end of the month)."},"prevMonthlyReferralCount":{"type":"integer","readOnly":true,"description":"The total number of referrals made the previous month by the participant."},"rank":{"type":"integer","readOnly":true,"description":"The rank of the participant."},"monthlyRank":{"type":"integer","readOnly":true,"description":"The monthly rank of the participant. This rank resets to 0 at the end of each month."},"prevMonthlyRank":{"type":"integer","readOnly":true,"description":"The previous monthly rank of the participant. Not returned if the participant did not exist in your program during the previous month."},"shareUrl":{"type":"string","readOnly":true,"description":"The unique share URL of the participant."},"createdAt":{"type":"integer","format":"int64","readOnly":true,"description":"The date the participant was added to the program (UTC milliseconds)."},"referralSource":{"$ref":"#/components/schemas/ReferralSource","readOnly":true,"description":"The source of how the participant joined the program."},"referralStatus":{"$ref":"#/components/schemas/ReferralStatus","description":"If the participant was referred, the referrer's status in receiving the referral credit. Only applicable if the participant was referred into the program."},"referredBy":{"type":"string","description":"The ID of the referrer. Only applicable if the participant was referred into the program."},"fraudRiskLevel":{"$ref":"#/components/schemas/FraudRiskLevel","readOnly":true,"description":"A value that represents the integrity of the participant."},"fraudReasonCode":{"type":"string","readOnly":true,"description":"The reason for the participant's `fraudRiskLevel`:\n\n- `UNIQUE_IDENTITY` — They have a unique identity (no other participant has the same identity).\n- `DUPLICATE_EMAIL` — Their email is not unique and is identical to another participant's email (e.g., gavin@hooli.com = gavin+1@hooli.com).\n- `DUPLICATE_IDENTITY` — Their identity (fingerprint or mobile instance ID) is not unique and matches another participant's.\n- `DUPLICATE_IDENTITY_EXCESSIVE` — Within a small window of time, they had an excessive number of referred participants who also shared the same IP address.\n- `EMAIL_FRAUD` — Their email was found to match another participant's when updated in a connected billing or payment integration.\n- `SIMILAR_EMAIL` — Their browser fingerprint matches another participant's and their email looks suspiciously similar.\n- `SIMILAR_FIRST_NAME` — Their browser fingerprint matches another participant's and their first name looks suspiciously similar.\n- `SIMILAR_LAST_NAME` — Their browser fingerprint matches another participant's and their last name looks suspiciously similar.\n- `REFERRAL_EMAIL_PATTERN` — (Status for a referred person) Their email matched a similar pattern to their referrer's email.\n- `REFERRAL_CHAIN_FRAUD` — (Status for a referrer or referred person) Their characteristics matched a pattern with other referrals the referrer made, indicating a fraud ring.\n- `REFERRAL_VELOCITY_FRAUD` — (Status for a referrer or referred person) The referrer made an excessive number of referrals in a short period of time.\n- `DOMAIN_CLUSTERING_FRAUD` — (Status for a referrer or referred person) The referrer made an excessive number of referrals sharing the same suspicious domain in a short period of time.\n- `MANUAL_UPDATE` — They were manually marked as a fraudster from the GrowSurf dashboard.\n- `WHITELISTED` — They were allowed to join the program because one of their properties matched an allowed value.\n- `BLACKLIST_MATCH` — They were not allowed to join the program because one of their properties matched a blocked value.\n- `BLOCKED_IP` — They were not allowed to join the program because their IP address was recently blocked by antifraud IP throttling.\n- `REFERRER_HIGH_RISK` — They were not allowed to join the program because their referrer was a high-risk fraudster."},"isWinner":{"type":"boolean","readOnly":true,"description":"`true` if the participant has earned one or more rewards."},"shareCount":{"type":"object","readOnly":true,"additionalProperties":{"type":"integer"},"description":"An object containing counts of how many times the participant has shared their referral link, keyed by channel. Standard web channels include `email`, `facebook`, and `twitter`; SDK/native-share channels include `iosNativeShare` and `androidNativeShare`."},"impressionCount":{"type":"integer","readOnly":true,"description":"The total number of impressions the participant has made."},"uniqueImpressionCount":{"type":"integer","readOnly":true,"description":"The total number of unique impressions the participant has made."},"inviteCount":{"type":"integer","readOnly":true,"description":"The total number of invites the participant has sent."},"referrals":{"type":"array","readOnly":true,"items":{"type":"string"},"description":"A list of `Participant` IDs who were successfully referred by the participant. Limited to the 100 most recently referred friends."},"monthlyReferrals":{"type":"array","readOnly":true,"items":{"type":"string"},"description":"A list of `Participant` IDs successfully referred by the participant this month (resets at the end of the month). Limited to the 100 most recent."},"referrer":{"readOnly":true,"oneOf":[{"$ref":"#/components/schemas/ParticipantReferrer"},{"type":"null"}],"description":"An object containing the participant's referrer information. Only applicable if the participant was referred into the program."},"ipAddress":{"type":["string","null"],"description":"The IP address associated with the participant, used for anti-fraud matching."},"fingerprint":{"type":["string","null"],"description":"The browser fingerprint associated with the participant, used for anti-fraud matching."},"mobileInstanceId":{"type":["string","null"],"description":"App-install scoped mobile identifier used for anti-fraud matching when provided by native mobile apps. The official mobile SDKs generate this as a lowercase UUID. Not stored when strict GDPR/CCPA mode is enabled."},"metadata":{"$ref":"#/components/schemas/Metadata","description":"An object containing any custom key-value data, useful for saving additional data for the participant (e.g., `company`, `companySize`). Metadata is never used by GrowSurf and usage is optional. Metadata is returned only in REST API calls, and never in JavaScript Web API calls. See [API Guidelines](https://docs.growsurf.com/developer-tools/rest-api/api-guidelines)."},"notes":{"type":["string","null"],"description":"Internal notes about the participant, added via the [GrowSurf Dashboard](https://growsurf.com/dashboard)."},"unsubscribed":{"type":"boolean","description":"`true` if the participant has unsubscribed from program emails."},"rewards":{"type":"array","readOnly":true,"items":{"$ref":"#/components/schemas/ParticipantReward"},"description":"A list of the rewards the participant has earned."},"vanityKeys":{"type":"array","items":{"type":"string"},"description":"The list of vanity keys that the participant has."},"unreadCommissionsCount":{"type":"integer","readOnly":true,"description":"Affiliate programs only. The number of commissions the participant has not yet viewed."},"unreadPayoutsCount":{"type":"integer","readOnly":true,"description":"Affiliate programs only. The number of payouts the participant has not yet viewed."},"isNew":{"type":"boolean","readOnly":true,"description":"Whether this participant was newly created by the request. Returned by participant creation calls; `false` when the participant already existed."},"allMatchingFraudsters":{"type":"array","readOnly":true,"items":{"type":"object","additionalProperties":true},"description":"A list of other participants flagged as matching this participant during anti-fraud checks."},"payoutSettings":{"type":"object","readOnly":true,"description":"Payout-related actions the participant must complete before a payout can be released (e.g. confirming a PayPal email or submitting a W-9/W-8 tax form). Always present; the requiredActions array is empty when no action is required.","properties":{"requiredActions":{"description":"Actions the participant must complete before payouts can be sent.","type":"array","readOnly":true,"items":{"type":"string","enum":["PAYPAL_EMAIL","TAX_INFO"]}}}}}},"ReferralSource":{"type":"string","enum":["DIRECT","PARTICIPANT"]},"ReferralStatus":{"type":"string","enum":["CREDIT_PENDING","CREDIT_AWARDED","CREDIT_EXPIRED","INVITE_SENT"]},"FraudRiskLevel":{"type":"string","enum":["LOW","MEDIUM","HIGH"]},"ParticipantReferrer":{"type":"object","description":"Summary information about a participant's referrer, returned within the `referrer` field of a `Participant`.","properties":{"id":{"type":"string","description":"The unique identifier of the referrer."},"firstName":{"type":["string","null"],"description":"The first name of the referrer."},"lastName":{"type":["string","null"],"description":"The last name of the referrer."},"email":{"type":"string","description":"The email of the referrer."},"referralCount":{"type":"integer","description":"The total number of referrals made by the referrer."},"monthlyReferralCount":{"type":"integer","description":"The total number of referrals made this month by the referrer (resets at the end of the month)."},"prevMonthlyReferralCount":{"type":"integer","description":"The total number of referrals made the previous month by the referrer."},"rank":{"type":"integer","description":"The rank of the referrer."},"monthlyRank":{"type":"integer","description":"The monthly rank of the referrer. This rank resets to 0 at the end of each month."},"prevMonthlyRank":{"type":"integer","description":"The previous monthly rank of the referrer."},"shareUrl":{"type":"string","description":"The unique share URL of the referrer."},"createdAt":{"type":"integer","format":"int64","description":"The date the referrer was added to the program (UTC milliseconds)."},"referralSource":{"$ref":"#/components/schemas/ReferralSource","description":"The source of how the referrer joined the program."},"referralStatus":{"$ref":"#/components/schemas/ReferralStatus","description":"If the referrer was themselves referred, their referrer's status in receiving the referral credit."},"fraudRiskLevel":{"$ref":"#/components/schemas/FraudRiskLevel","description":"A value that represents the integrity of the referrer."},"fraudReasonCode":{"type":"string","description":"The reason for the referrer's `fraudRiskLevel`. See `Participant.fraudReasonCode` for the list of possible values."},"isWinner":{"type":"boolean","description":"`true` if the referrer has earned one or more rewards."},"shareCount":{"type":"object","additionalProperties":{"type":"integer"},"description":"An object containing counts of how many times the referrer has shared their referral link, keyed by channel."},"impressionCount":{"type":"integer","description":"The total number of impressions the referrer has made."},"uniqueImpressionCount":{"type":"integer","description":"The total number of unique impressions the referrer has made."},"inviteCount":{"type":"integer","description":"The total number of invites the referrer has sent."},"referrals":{"type":"array","items":{"type":"string"},"description":"A list of `Participant` IDs who were successfully referred by the referrer. Limited to the 100 most recent."},"monthlyReferrals":{"type":"array","items":{"type":"string"},"description":"A list of `Participant` IDs successfully referred by the referrer this month (resets at the end of the month). Limited to the 100 most recent."},"ipAddress":{"type":["string","null"],"description":"The IP address associated with the referrer, used for anti-fraud matching."},"fingerprint":{"type":["string","null"],"description":"The browser fingerprint associated with the referrer, used for anti-fraud matching."},"metadata":{"$ref":"#/components/schemas/Metadata","description":"An object containing any custom key-value data for the referrer."},"unsubscribed":{"type":"boolean","description":"`true` if the referrer has unsubscribed from program emails."}}},"ParticipantReward":{"type":"object","description":"A reward that a participant has earned. This is different from a program `Reward` Object and contains information pertinent only to the participant that earned the reward.","required":["id","rewardId","status"],"properties":{"id":{"type":"string","readOnly":true,"description":"The unique identifier of the participant's reward. This is different for every new reward the participant earns."},"rewardId":{"type":"string","readOnly":true,"description":"The ID of the program `Reward` (`CampaignReward`) that this participant has earned."},"status":{"$ref":"#/components/schemas/RewardStatus","readOnly":true,"description":"The status of the participant's reward."},"unread":{"type":"boolean","readOnly":true,"description":"`true` if the participant has not yet seen the reward in a GrowSurf window."},"approved":{"type":"boolean","readOnly":true,"description":"`true` if the participant's reward has been approved."},"approvedAt":{"type":["integer","null"],"format":"int64","readOnly":true,"description":"The date and time the reward was approved for this participant (UTC milliseconds). `null` for unapproved rewards."},"fulfilledAt":{"type":["integer","null"],"format":"int64","readOnly":true,"description":"The date and time the reward was fulfilled for this participant (UTC milliseconds). `null` for unapproved or unfulfilled rewards."},"isReferrer":{"type":"boolean","readOnly":true,"description":"`true` if the participant earned the reward as the referrer; `false` if they earned it as the referred friend (only applicable for double-sided reward types)."},"isAvailable":{"type":"boolean","readOnly":true,"description":"`true` if the reward is available for the participant to claim or redeem."},"isFulfilled":{"type":"boolean","readOnly":true,"description":"`true` if the participant's reward has been fulfilled."},"referredId":{"type":"string","readOnly":true,"description":"The ID of the friend that was referred."},"referrerId":{"type":"string","readOnly":true,"description":"The ID of the participant that made the referral."},"commissionStructure":{"readOnly":true,"oneOf":[{"$ref":"#/components/schemas/CommissionStructure"},{"type":"null"}],"description":"The commission structure associated with this reward. Present only for affiliate programs."}}},"RewardStatus":{"type":"string","enum":["PENDING","FULFILLED"]},"CommissionStructure":{"type":"object","description":"The commission configuration for an affiliate reward. Present only for affiliate programs.","properties":{"amount":{"type":["integer","null"],"description":"Fixed commission amount in the currency's smallest denomination, used when `type` is `FIXED`. `null` for percentage-based commissions."},"amountISO":{"type":["string","null"],"description":"ISO 4217 currency code for the fixed `amount`. Defaults to the program's currency when omitted. Must match the campaign `currencyISO` when provided. `null` for percentage-based commissions."},"event":{"type":["string","null"],"description":"The event that generates a commission (e.g., `SALE`)."},"type":{"type":["string","null"],"enum":["PERCENT","FIXED",null],"description":"How the commission is calculated: `PERCENT` (a percentage of the sale) or `FIXED` (a fixed `amount`)."},"minPaidReferrals":{"type":["integer","null"],"description":"The minimum number of paid referrals required before commissions are earned."},"holdDuration":{"type":["integer","null"],"description":"Number of days a commission is held before it can be paid out."},"duration":{"type":["string","null"],"description":"How long commissions continue to be earned for a referred customer."},"durationInMonths":{"type":["integer","null"],"description":"When `duration` is repeating, the number of months over which commissions are earned."},"approvalRequired":{"type":["boolean","null"],"description":"`true` if commissions require manual approval before they can be paid out."},"percent":{"type":["number","null"],"description":"The commission percentage, used when `type` is `PERCENT`."},"hasMaxAmount":{"type":["boolean","null"],"description":"`true` if a maximum commission amount cap is configured."},"maxAmount":{"type":["integer","null"],"description":"The maximum commission amount cap in the currency's smallest denomination. `null` if no cap is set."},"maxAmountISO":{"type":["string","null"],"description":"The [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code for `maxAmount`. Must match the campaign `currencyISO` when provided."},"hasIntro":{"type":["boolean","null"],"description":"`true` if an introductory commission rate is configured."},"introType":{"type":["string","null"],"description":"How the introductory commission is calculated: `PERCENT` or `FIXED`."},"introPercent":{"type":["number","null"],"description":"The introductory commission percentage, used when `introType` is `PERCENT`."},"introAmount":{"type":["integer","null"],"description":"The introductory commission amount in the currency's smallest denomination, used when `introType` is `FIXED`."},"introAmountISO":{"type":["string","null"],"description":"The [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code for `introAmount`. Must match the campaign `currencyISO` when provided."},"introDuration":{"type":["string","null"],"description":"How long the introductory rate applies."},"introDurationInMonths":{"type":["integer","null"],"description":"When `introDuration` is repeating, the number of months the introductory rate applies."}},"additionalProperties":false},"Error":{"type":"object","properties":{"name":{"description":"Error name returned for the failed request.","type":"string"},"code":{"description":"Stable machine-readable error code.","type":"string"},"message":{"description":"Human-readable error message.","type":"string"},"errors":{"description":"Optional validation details for specific request fields.","type":"array","items":{"type":"object","additionalProperties":true}},"status":{"description":"HTTP status code for the error.","type":"integer"},"supportUrl":{"description":"Support URL related to the error, when available.","type":"string","format":"uri"},"policyName":{"description":"Rate-limit policy name for `429` errors, when available.","type":"string"},"level":{"description":"Error severity level, when available.","type":"string"},"timestamp":{"description":"When the error response was created.","type":"string","format":"date-time"}}},"ParticipantBlockedError":{"allOf":[{"$ref":"#/components/schemas/Error"},{"type":"object","properties":{"fraudRiskLevel":{"description":"Fraud risk level assigned to the blocked signup.","$ref":"#/components/schemas/FraudRiskLevel"},"fraudReasonCode":{"description":"Machine-readable reason code for the fraud decision.","type":"string"},"matchedParticipantIds":{"description":"Existing participant IDs related to the fraud match.","type":"array","items":{"type":"string"}},"email":{"description":"Email address from the blocked signup attempt.","type":"string","format":"email"},"referrerId":{"description":"Referrer participant ID supplied with the blocked signup, or `null`.","type":["string","null"]},"ipAddress":{"description":"IP address supplied with the blocked signup, or `null`.","type":["string","null"]},"fingerprint":{"description":"Browser fingerprint supplied with the blocked signup, or `null`.","type":["string","null"]},"blockedAt":{"description":"When the signup was blocked.","type":"string","format":"date-time"}}}]}},"responses":{"BadRequest":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The API key is missing, invalid, revoked, outside its scope, or not allowed to perform this action.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Conflict":{"description":"Conflicting duplicate request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Too many requests.","headers":{"GrowSurf-RateLimit-Second-Limit":{"description":"Number of API requests allowed per second policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Second-Remaining":{"description":"Number of API requests remaining in the second policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Second-Milliseconds":{"description":"Milliseconds until the second policy window resets.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Minute-Limit":{"description":"Number of API requests allowed per minute policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Minute-Remaining":{"description":"Number of API requests remaining in the minute policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Minute-Milliseconds":{"description":"Milliseconds until the minute policy window resets.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Hour-Limit":{"description":"Number of API requests allowed per hour policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Hour-Remaining":{"description":"Number of API requests remaining in the hour policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Hour-Milliseconds":{"description":"Milliseconds until the hour policy window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/campaign/{id}/mobile-participant-token":{"post":{"tags":["Participants"],"operationId":"createMobileParticipantToken","summary":"Create mobile participant token","description":"Creates or returns a participant using the same input behavior as Add Participant, then returns a participant-scoped token for GrowSurf mobile SDK participant endpoints. Use this endpoint from your backend after your mobile app authenticates a signed-in user. The program must have mobile SDK access enabled.","parameters":[{"$ref":"#/components/parameters/CampaignId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateParticipantRequest"}}}},"responses":{"200":{"description":"Participant and mobile participant token returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MobileParticipantTokenResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"description":"Participant was blocked or the endpoint is not available for this program type.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ParticipantBlockedError"},{"$ref":"#/components/schemas/Error"}]}}}},"429":{"$ref":"#/components/responses/RateLimited"}}}}}} ``` ## Email participant > Sends an email to a participant. Provide EITHER \`emailType\` to trigger one of the program's configured email templates, OR \`subject\` + \`body\` for a free-form email. Free-form emails are sent with the same compliance handling (company name, postal address, and an unsubscribe link are added automatically, and unsubscribed participants are suppressed). Sending requires the team to be verified by GrowSurf. Requires a \*\*verified custom email domain\*\* on the program (which can be completed in \*Campaign Editor > 3. Emails > Email Settings\*). Returns \`400\` until one is verified. The email is accepted for delivery. ```json {"openapi":"3.1.0","info":{"title":"GrowSurf REST API","version":"2.0.0"},"tags":[{"name":"Participants","description":"Program participant retrieval, creation, updates, deletion, and referral triggering."}],"servers":[{"url":"https://api.growsurf.com/v2","description":"Production"}],"security":[{"apiKeyAuth":[]}],"components":{"securitySchemes":{"apiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"API key","description":"GrowSurf REST API key supplied as `Authorization: Bearer `."}},"parameters":{"CampaignId":{"name":"id","in":"path","required":true,"description":"GrowSurf program ID.","schema":{"type":"string"}},"ParticipantIdOrEmail":{"name":"participantIdOrEmail","in":"path","required":true,"description":"GrowSurf participant ID or URL-encoded participant email address.","schema":{"type":"string"}}},"schemas":{"EmailParticipantRequest":{"type":"object","additionalProperties":false,"description":"Provide EITHER `emailType` (template mode) OR `subject` + `body` (free-form mode), not both.","properties":{"emailType":{"type":"string","description":"The program email template to trigger (template mode). Send the camelCase email-type key. The available types depend on the program type; the template's `isEnabled` setting controls automatic sends only. This endpoint can trigger any sendable template. System and transactional types (login link, PayPal confirmation, tax notifications) and the invite email cannot be sent. Referral programs: `welcomeNonReferred`, `referralLinkViewedFirstTime`, `referralLinkUsed`, `referredSignup`, `welcomeReferred`, `goalAchieved`, `campaignEndedWinners`, `campaignEndedNonWinners`, `progressUpdateMonthly`. Affiliate programs: `welcomeNonReferred`, `referralLinkViewedFirstTime`, `referredSignup`, `commissionGenerated`, `commissionAdjusted`, `payoutPending`, `payoutSentSuccess`, `progressUpdateMonthly`."},"subject":{"type":"string","maxLength":255,"description":"Subject line for a free-form email. Supports dynamic text (`{{...}}` tokens), the same as the body."},"body":{"type":"string","description":"HTML body for a free-form email. You can personalize it with dynamic text, inserting `{{...}}` tokens like `{{firstName}}` or `{{shareUrl}}`. See [Guide to using dynamic text in GrowSurf emails](https://support.growsurf.com/article/213-guide-to-using-dynamic-text-in-growsurf-emails)."},"preheader":{"type":"string","description":"Optional preheader text for a free-form email."}}},"EmailParticipantResponse":{"type":"object","required":["success","status"],"properties":{"success":{"description":"Whether the email request was accepted.","type":"boolean"},"status":{"type":"string","enum":["queued"],"description":"The email was accepted for delivery."}}},"Error":{"type":"object","properties":{"name":{"description":"Error name returned for the failed request.","type":"string"},"code":{"description":"Stable machine-readable error code.","type":"string"},"message":{"description":"Human-readable error message.","type":"string"},"errors":{"description":"Optional validation details for specific request fields.","type":"array","items":{"type":"object","additionalProperties":true}},"status":{"description":"HTTP status code for the error.","type":"integer"},"supportUrl":{"description":"Support URL related to the error, when available.","type":"string","format":"uri"},"policyName":{"description":"Rate-limit policy name for `429` errors, when available.","type":"string"},"level":{"description":"Error severity level, when available.","type":"string"},"timestamp":{"description":"When the error response was created.","type":"string","format":"date-time"}}}},"responses":{"BadRequest":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The API key is missing, invalid, revoked, outside its scope, or not allowed to perform this action.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Too many requests.","headers":{"GrowSurf-RateLimit-Second-Limit":{"description":"Number of API requests allowed per second policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Second-Remaining":{"description":"Number of API requests remaining in the second policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Second-Milliseconds":{"description":"Milliseconds until the second policy window resets.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Minute-Limit":{"description":"Number of API requests allowed per minute policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Minute-Remaining":{"description":"Number of API requests remaining in the minute policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Minute-Milliseconds":{"description":"Milliseconds until the minute policy window resets.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Hour-Limit":{"description":"Number of API requests allowed per hour policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Hour-Remaining":{"description":"Number of API requests remaining in the hour policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Hour-Milliseconds":{"description":"Milliseconds until the hour policy window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/campaign/{id}/participant/{participantIdOrEmail}/email":{"post":{"tags":["Participants"],"operationId":"emailParticipant","summary":"Email participant","description":"Sends an email to a participant. Provide EITHER `emailType` to trigger one of the program's configured email templates, OR `subject` + `body` for a free-form email. Free-form emails are sent with the same compliance handling (company name, postal address, and an unsubscribe link are added automatically, and unsubscribed participants are suppressed). Sending requires the team to be verified by GrowSurf. Requires a **verified custom email domain** on the program (which can be completed in *Campaign Editor > 3. Emails > Email Settings*). Returns `400` until one is verified. The email is accepted for delivery.","parameters":[{"$ref":"#/components/parameters/CampaignId"},{"$ref":"#/components/parameters/ParticipantIdOrEmail"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailParticipantRequest"}}}},"responses":{"200":{"description":"Email accepted for delivery.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailParticipantResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}}}} ``` ## Retrieve participant analytics > Retrieves analytics for a single participant — all-time engagement counters, leaderboard ranks, and per-channel share counts (plus affiliate money metrics for affiliate programs). Useful for segmenting and re-engaging participants. Pass \`include=series\` to also get this participant's own activity over time. ```json {"openapi":"3.1.0","info":{"title":"GrowSurf REST API","version":"2.0.0"},"tags":[{"name":"Analytics","description":"Program analytics."}],"servers":[{"url":"https://api.growsurf.com/v2","description":"Production"}],"security":[{"apiKeyAuth":[]}],"components":{"securitySchemes":{"apiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"API key","description":"GrowSurf REST API key supplied as `Authorization: Bearer `."}},"parameters":{"CampaignId":{"name":"id","in":"path","required":true,"description":"GrowSurf program ID.","schema":{"type":"string"}},"ParticipantIdOrEmail":{"name":"participantIdOrEmail","in":"path","required":true,"description":"GrowSurf participant ID or URL-encoded participant email address.","schema":{"type":"string"}},"AnalyticsDays":{"name":"days","in":"query","required":false,"description":"Last number of days to retrieve analytics for. Defaults to 365. Maximum 1825.","schema":{"type":"integer","minimum":1,"maximum":1825,"default":365}},"AnalyticsStartDate":{"name":"startDate","in":"query","required":false,"description":"Start date of the analytics timeframe as a Unix timestamp in milliseconds. Required if `days` is not set.","schema":{"type":"integer","format":"int64"}},"AnalyticsEndDate":{"name":"endDate","in":"query","required":false,"description":"End date of the analytics timeframe as a Unix timestamp in milliseconds. Required if `days` is not set.","schema":{"type":"integer","format":"int64"}}},"schemas":{"ParticipantAnalyticsResponse":{"type":"object","required":["analytics","ranks","shareCount"],"properties":{"analytics":{"description":"Participant analytics totals.","type":"object","properties":{"referrals":{"description":"All-time referrals credited to this participant.","type":"integer"},"monthlyReferrals":{"description":"Referrals credited to this participant in the current month.","type":"integer"},"leads":{"description":"Pending referral credits for this participant.","type":"integer"},"expiredReferrals":{"description":"Expired referral credits for this participant.","type":"integer"},"impressions":{"description":"Total referral-link views for this participant.","type":"integer"},"uniqueImpressions":{"description":"Unique referral-link views for this participant.","type":"integer"},"invitesSent":{"description":"Invites sent by this participant.","type":"integer"},"rewardsEarned":{"description":"Approved rewards earned by this participant.","type":"integer"},"pendingRewards":{"description":"Rewards earned by this participant that are awaiting approval.","type":"integer"},"referralRevenue":{"type":"integer","description":"Affiliate only. Revenue attributed to this participant's referrals, in minor currency units."},"totalCommissions":{"type":"integer","description":"Affiliate only. Total commissions earned, in minor currency units."},"totalPaidOut":{"type":"integer","description":"Affiliate only. Total paid out, in minor currency units."},"upcomingPayout":{"type":"integer","description":"Affiliate only. Approved commissions ready to pay, in minor currency units."},"currencyISO":{"description":"Program currency for this participant's money metrics.","type":"string"}}},"ranks":{"description":"Leaderboard ranks for this participant.","type":"object","properties":{"rank":{"type":"integer","nullable":true,"description":"All-time rank (1-indexed), or null when unranked."},"monthlyRank":{"description":"Current-month rank, or `null` when unranked.","type":"integer","nullable":true},"prevMonthlyRank":{"description":"Previous-month rank, or `null` when unranked.","type":"integer","nullable":true}}},"shareCount":{"type":"object","additionalProperties":{"type":"integer"},"description":"Per-channel share counts (e.g. `email`, `facebook`, `twitter`, ...)."},"series":{"type":"array","description":"Present only when `include=series`. This participant's own referral-link activity per period (ascending), windowed by `days`/`startDate`/`endDate` and bucketed by `interval`.","items":{"allOf":[{"type":"object","properties":{"periodStart":{"type":"integer","format":"int64","description":"Start of the period, as a Unix timestamp in milliseconds (UTC)."}}},{"$ref":"#/components/schemas/CampaignAnalytics"}]}},"startDate":{"type":"integer","format":"int64","description":"Present only with `include=series`. Window start (Unix ms)."},"endDate":{"type":"integer","format":"int64","description":"Present only with `include=series`. Window end (Unix ms)."}}},"CampaignAnalytics":{"type":"object","properties":{"invites":{"description":"Number of invites sent by participants.","type":"integer"},"impressions":{"description":"Total referral-link views.","type":"integer"},"uniqueImpressions":{"description":"Unique referral-link views.","type":"integer"},"participants":{"description":"Number of participants added.","type":"integer"},"referrals":{"description":"Number of referrals credited.","type":"integer"},"referralCreditPendings":{"description":"Number of referrals waiting for credit.","type":"integer"},"referralCreditExpireds":{"description":"Number of referrals whose credit window expired.","type":"integer"},"emailShares":{"description":"Number of shares through email.","type":"integer"},"facebookShares":{"description":"Number of shares through Facebook.","type":"integer"},"twitterShares":{"description":"Number of shares through Twitter/X.","type":"integer"},"threadsShares":{"description":"Number of shares through Threads.","type":"integer"},"blueskyShares":{"description":"Number of shares through Bluesky.","type":"integer"},"pinterestShares":{"description":"Number of shares through Pinterest.","type":"integer"},"linkedInShares":{"description":"Number of shares through LinkedIn.","type":"integer"},"smsShares":{"description":"Number of shares through SMS.","type":"integer"},"messengerShares":{"description":"Number of shares through Messenger.","type":"integer"},"whatsAppShares":{"description":"Number of shares through WhatsApp.","type":"integer"},"wechatShares":{"description":"Number of shares through WeChat.","type":"integer"},"telegramShares":{"description":"Number of shares through Telegram.","type":"integer"},"qrcodeShares":{"description":"Number of shares through QR code.","type":"integer"},"redditShares":{"description":"Number of shares through Reddit.","type":"integer"},"tumblrShares":{"description":"Number of shares through Tumblr.","type":"integer"},"copyRefLinkShares":{"description":"Number of times participants copied their referral link.","type":"integer"},"iosNativeShares":{"description":"Number of shares through iOS native sharing.","type":"integer"},"androidNativeShares":{"description":"Number of shares through Android native sharing.","type":"integer"},"totalRevenue":{"type":"integer","description":"Affiliate programs only. Revenue in the smallest unit of the program currency."},"totalCommissions":{"type":"integer","description":"Affiliate programs only. Commissions in the smallest unit of the program currency."},"totalCommissionCount":{"type":"integer","description":"Affiliate programs only. Number of commission records."}}},"Error":{"type":"object","properties":{"name":{"description":"Error name returned for the failed request.","type":"string"},"code":{"description":"Stable machine-readable error code.","type":"string"},"message":{"description":"Human-readable error message.","type":"string"},"errors":{"description":"Optional validation details for specific request fields.","type":"array","items":{"type":"object","additionalProperties":true}},"status":{"description":"HTTP status code for the error.","type":"integer"},"supportUrl":{"description":"Support URL related to the error, when available.","type":"string","format":"uri"},"policyName":{"description":"Rate-limit policy name for `429` errors, when available.","type":"string"},"level":{"description":"Error severity level, when available.","type":"string"},"timestamp":{"description":"When the error response was created.","type":"string","format":"date-time"}}}},"responses":{"Forbidden":{"description":"The API key is missing, invalid, revoked, outside its scope, or not allowed to perform this action.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Too many requests.","headers":{"GrowSurf-RateLimit-Second-Limit":{"description":"Number of API requests allowed per second policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Second-Remaining":{"description":"Number of API requests remaining in the second policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Second-Milliseconds":{"description":"Milliseconds until the second policy window resets.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Minute-Limit":{"description":"Number of API requests allowed per minute policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Minute-Remaining":{"description":"Number of API requests remaining in the minute policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Minute-Milliseconds":{"description":"Milliseconds until the minute policy window resets.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Hour-Limit":{"description":"Number of API requests allowed per hour policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Hour-Remaining":{"description":"Number of API requests remaining in the hour policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Hour-Milliseconds":{"description":"Milliseconds until the hour policy window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/campaign/{id}/participant/{participantIdOrEmail}/analytics":{"get":{"tags":["Analytics"],"operationId":"retrieveParticipantAnalytics","summary":"Retrieve participant analytics","description":"Retrieves analytics for a single participant — all-time engagement counters, leaderboard ranks, and per-channel share counts (plus affiliate money metrics for affiliate programs). Useful for segmenting and re-engaging participants. Pass `include=series` to also get this participant's own activity over time.","parameters":[{"$ref":"#/components/parameters/CampaignId"},{"$ref":"#/components/parameters/ParticipantIdOrEmail"},{"name":"include","in":"query","description":"Set to `series` to also return this participant's own activity per period.","schema":{"type":"string","enum":["series"]}},{"$ref":"#/components/parameters/AnalyticsDays"},{"$ref":"#/components/parameters/AnalyticsStartDate"},{"$ref":"#/components/parameters/AnalyticsEndDate"},{"name":"interval","in":"query","description":"Bucket size for the `series` (only used with `include=series`). Defaults to `day`.","schema":{"type":"string","enum":["day","week","month"],"default":"day"}}],"responses":{"200":{"description":"Participant analytics returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ParticipantAnalyticsResponse"}}}},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}}}} ``` ## List participant activity logs > Returns a participant's activity logs, most recent first (offset/limit paginated). ```json {"openapi":"3.1.0","info":{"title":"GrowSurf REST API","version":"2.0.0"},"tags":[{"name":"Participants","description":"Program participant retrieval, creation, updates, deletion, and referral triggering."}],"servers":[{"url":"https://api.growsurf.com/v2","description":"Production"}],"security":[{"apiKeyAuth":[]}],"components":{"securitySchemes":{"apiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"API key","description":"GrowSurf REST API key supplied as `Authorization: Bearer `."}},"parameters":{"CampaignId":{"name":"id","in":"path","required":true,"description":"GrowSurf program ID.","schema":{"type":"string"}},"ParticipantIdOrEmail":{"name":"participantIdOrEmail","in":"path","required":true,"description":"GrowSurf participant ID or URL-encoded participant email address.","schema":{"type":"string"}}},"schemas":{"ParticipantActivityLogsResponse":{"type":"object","required":["activityLogs","limit"],"properties":{"activityLogs":{"description":"Activity log entries for the participant.","type":"array","items":{"$ref":"#/components/schemas/ParticipantActivityLog"}},"offset":{"type":"integer","nullable":true,"description":"The offset for the next page, or null when there are no more logs."},"limit":{"description":"Number of activity logs returned per page.","type":"integer"}}},"ParticipantActivityLog":{"type":"object","required":["type","text","createdAt"],"properties":{"type":{"type":"string","description":"The activity family (e.g. `REFERRAL`, `SHARE`, `REWARD`, `EMAIL`, `COMMON`)."},"text":{"type":"string","description":"A human-readable description of the activity."},"createdAt":{"type":"integer","format":"int64","description":"When the activity occurred, as a Unix timestamp in milliseconds."}}},"Error":{"type":"object","properties":{"name":{"description":"Error name returned for the failed request.","type":"string"},"code":{"description":"Stable machine-readable error code.","type":"string"},"message":{"description":"Human-readable error message.","type":"string"},"errors":{"description":"Optional validation details for specific request fields.","type":"array","items":{"type":"object","additionalProperties":true}},"status":{"description":"HTTP status code for the error.","type":"integer"},"supportUrl":{"description":"Support URL related to the error, when available.","type":"string","format":"uri"},"policyName":{"description":"Rate-limit policy name for `429` errors, when available.","type":"string"},"level":{"description":"Error severity level, when available.","type":"string"},"timestamp":{"description":"When the error response was created.","type":"string","format":"date-time"}}}},"responses":{"Forbidden":{"description":"The API key is missing, invalid, revoked, outside its scope, or not allowed to perform this action.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Too many requests.","headers":{"GrowSurf-RateLimit-Second-Limit":{"description":"Number of API requests allowed per second policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Second-Remaining":{"description":"Number of API requests remaining in the second policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Second-Milliseconds":{"description":"Milliseconds until the second policy window resets.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Minute-Limit":{"description":"Number of API requests allowed per minute policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Minute-Remaining":{"description":"Number of API requests remaining in the minute policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Minute-Milliseconds":{"description":"Milliseconds until the minute policy window resets.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Hour-Limit":{"description":"Number of API requests allowed per hour policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Hour-Remaining":{"description":"Number of API requests remaining in the hour policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Hour-Milliseconds":{"description":"Milliseconds until the hour policy window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/campaign/{id}/participant/{participantIdOrEmail}/activity-logs":{"get":{"tags":["Participants"],"operationId":"listParticipantActivityLogs","summary":"List participant activity logs","description":"Returns a participant's activity logs, most recent first (offset/limit paginated).","parameters":[{"$ref":"#/components/parameters/CampaignId"},{"$ref":"#/components/parameters/ParticipantIdOrEmail"},{"name":"limit","in":"query","description":"Number of logs to return (1–100, default 20).","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"offset","in":"query","description":"Number of logs to skip.","schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"Activity logs returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ParticipantActivityLogsResponse"}}}},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}}}} ``` *** ## PARTICIPANT REWARDS ↓ ## List participant rewards > Retrieves a paged list of rewards earned by a participant. ```json {"openapi":"3.1.0","info":{"title":"GrowSurf REST API","version":"2.0.0"},"tags":[{"name":"Participant Rewards","description":"Participant reward retrieval and manual reward operations."}],"servers":[{"url":"https://api.growsurf.com/v2","description":"Production"}],"security":[{"apiKeyAuth":[]}],"components":{"securitySchemes":{"apiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"API key","description":"GrowSurf REST API key supplied as `Authorization: Bearer `."}},"parameters":{"CampaignId":{"name":"id","in":"path","required":true,"description":"GrowSurf program ID.","schema":{"type":"string"}},"ParticipantIdOrEmail":{"name":"participantIdOrEmail","in":"path","required":true,"description":"GrowSurf participant ID or URL-encoded participant email address.","schema":{"type":"string"}},"NextId":{"name":"nextId","in":"query","required":false,"description":"ID to start the next paged result set with.","schema":{"type":"string"}},"Limit100":{"name":"limit","in":"query","required":false,"description":"Number of results to return. Maximum 100.","schema":{"type":"integer","minimum":1,"maximum":100,"default":10}}},"schemas":{"ParticipantRewardListResponse":{"type":"object","required":["rewards","limit","nextId"],"properties":{"rewards":{"description":"Participant rewards returned for this page.","type":"array","items":{"$ref":"#/components/schemas/ParticipantReward"}},"limit":{"description":"Maximum number of rewards requested for this page.","type":"integer"},"nextId":{"description":"Reward ID to pass as `nextId` for the next page, or `null` when there are no more results.","type":["string","null"]}}},"ParticipantReward":{"type":"object","description":"A reward that a participant has earned. This is different from a program `Reward` Object and contains information pertinent only to the participant that earned the reward.","required":["id","rewardId","status"],"properties":{"id":{"type":"string","readOnly":true,"description":"The unique identifier of the participant's reward. This is different for every new reward the participant earns."},"rewardId":{"type":"string","readOnly":true,"description":"The ID of the program `Reward` (`CampaignReward`) that this participant has earned."},"status":{"$ref":"#/components/schemas/RewardStatus","readOnly":true,"description":"The status of the participant's reward."},"unread":{"type":"boolean","readOnly":true,"description":"`true` if the participant has not yet seen the reward in a GrowSurf window."},"approved":{"type":"boolean","readOnly":true,"description":"`true` if the participant's reward has been approved."},"approvedAt":{"type":["integer","null"],"format":"int64","readOnly":true,"description":"The date and time the reward was approved for this participant (UTC milliseconds). `null` for unapproved rewards."},"fulfilledAt":{"type":["integer","null"],"format":"int64","readOnly":true,"description":"The date and time the reward was fulfilled for this participant (UTC milliseconds). `null` for unapproved or unfulfilled rewards."},"isReferrer":{"type":"boolean","readOnly":true,"description":"`true` if the participant earned the reward as the referrer; `false` if they earned it as the referred friend (only applicable for double-sided reward types)."},"isAvailable":{"type":"boolean","readOnly":true,"description":"`true` if the reward is available for the participant to claim or redeem."},"isFulfilled":{"type":"boolean","readOnly":true,"description":"`true` if the participant's reward has been fulfilled."},"referredId":{"type":"string","readOnly":true,"description":"The ID of the friend that was referred."},"referrerId":{"type":"string","readOnly":true,"description":"The ID of the participant that made the referral."},"commissionStructure":{"readOnly":true,"oneOf":[{"$ref":"#/components/schemas/CommissionStructure"},{"type":"null"}],"description":"The commission structure associated with this reward. Present only for affiliate programs."}}},"RewardStatus":{"type":"string","enum":["PENDING","FULFILLED"]},"CommissionStructure":{"type":"object","description":"The commission configuration for an affiliate reward. Present only for affiliate programs.","properties":{"amount":{"type":["integer","null"],"description":"Fixed commission amount in the currency's smallest denomination, used when `type` is `FIXED`. `null` for percentage-based commissions."},"amountISO":{"type":["string","null"],"description":"ISO 4217 currency code for the fixed `amount`. Defaults to the program's currency when omitted. Must match the campaign `currencyISO` when provided. `null` for percentage-based commissions."},"event":{"type":["string","null"],"description":"The event that generates a commission (e.g., `SALE`)."},"type":{"type":["string","null"],"enum":["PERCENT","FIXED",null],"description":"How the commission is calculated: `PERCENT` (a percentage of the sale) or `FIXED` (a fixed `amount`)."},"minPaidReferrals":{"type":["integer","null"],"description":"The minimum number of paid referrals required before commissions are earned."},"holdDuration":{"type":["integer","null"],"description":"Number of days a commission is held before it can be paid out."},"duration":{"type":["string","null"],"description":"How long commissions continue to be earned for a referred customer."},"durationInMonths":{"type":["integer","null"],"description":"When `duration` is repeating, the number of months over which commissions are earned."},"approvalRequired":{"type":["boolean","null"],"description":"`true` if commissions require manual approval before they can be paid out."},"percent":{"type":["number","null"],"description":"The commission percentage, used when `type` is `PERCENT`."},"hasMaxAmount":{"type":["boolean","null"],"description":"`true` if a maximum commission amount cap is configured."},"maxAmount":{"type":["integer","null"],"description":"The maximum commission amount cap in the currency's smallest denomination. `null` if no cap is set."},"maxAmountISO":{"type":["string","null"],"description":"The [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code for `maxAmount`. Must match the campaign `currencyISO` when provided."},"hasIntro":{"type":["boolean","null"],"description":"`true` if an introductory commission rate is configured."},"introType":{"type":["string","null"],"description":"How the introductory commission is calculated: `PERCENT` or `FIXED`."},"introPercent":{"type":["number","null"],"description":"The introductory commission percentage, used when `introType` is `PERCENT`."},"introAmount":{"type":["integer","null"],"description":"The introductory commission amount in the currency's smallest denomination, used when `introType` is `FIXED`."},"introAmountISO":{"type":["string","null"],"description":"The [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code for `introAmount`. Must match the campaign `currencyISO` when provided."},"introDuration":{"type":["string","null"],"description":"How long the introductory rate applies."},"introDurationInMonths":{"type":["integer","null"],"description":"When `introDuration` is repeating, the number of months the introductory rate applies."}},"additionalProperties":false},"Error":{"type":"object","properties":{"name":{"description":"Error name returned for the failed request.","type":"string"},"code":{"description":"Stable machine-readable error code.","type":"string"},"message":{"description":"Human-readable error message.","type":"string"},"errors":{"description":"Optional validation details for specific request fields.","type":"array","items":{"type":"object","additionalProperties":true}},"status":{"description":"HTTP status code for the error.","type":"integer"},"supportUrl":{"description":"Support URL related to the error, when available.","type":"string","format":"uri"},"policyName":{"description":"Rate-limit policy name for `429` errors, when available.","type":"string"},"level":{"description":"Error severity level, when available.","type":"string"},"timestamp":{"description":"When the error response was created.","type":"string","format":"date-time"}}}},"responses":{"BadRequest":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The API key is missing, invalid, revoked, outside its scope, or not allowed to perform this action.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"UnprocessableEntity":{"description":"Request is not valid for the current program or participant state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Too many requests.","headers":{"GrowSurf-RateLimit-Second-Limit":{"description":"Number of API requests allowed per second policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Second-Remaining":{"description":"Number of API requests remaining in the second policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Second-Milliseconds":{"description":"Milliseconds until the second policy window resets.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Minute-Limit":{"description":"Number of API requests allowed per minute policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Minute-Remaining":{"description":"Number of API requests remaining in the minute policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Minute-Milliseconds":{"description":"Milliseconds until the minute policy window resets.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Hour-Limit":{"description":"Number of API requests allowed per hour policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Hour-Remaining":{"description":"Number of API requests remaining in the hour policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Hour-Milliseconds":{"description":"Milliseconds until the hour policy window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/campaign/{id}/participant/{participantIdOrEmail}/rewards":{"get":{"tags":["Participant Rewards"],"operationId":"listParticipantRewards","summary":"List participant rewards","description":"Retrieves a paged list of rewards earned by a participant.","parameters":[{"$ref":"#/components/parameters/CampaignId"},{"$ref":"#/components/parameters/ParticipantIdOrEmail"},{"$ref":"#/components/parameters/NextId"},{"$ref":"#/components/parameters/Limit100"}],"responses":{"200":{"description":"Participant rewards returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ParticipantRewardListResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"}}}}}} ``` ## Approve participant reward > Approves a manually approved reward earned by a participant. This requires \`reward:write\`. When the request also sets \`fulfill\` to \`true\`, it additionally requires \`reward:fulfill\`. ```json {"openapi":"3.1.0","info":{"title":"GrowSurf REST API","version":"2.0.0"},"tags":[{"name":"Participant Rewards","description":"Participant reward retrieval and manual reward operations."}],"servers":[{"url":"https://api.growsurf.com/v2","description":"Production"}],"security":[{"apiKeyAuth":[]}],"components":{"securitySchemes":{"apiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"API key","description":"GrowSurf REST API key supplied as `Authorization: Bearer `."}},"parameters":{"CampaignId":{"name":"id","in":"path","required":true,"description":"GrowSurf program ID.","schema":{"type":"string"}},"RewardId":{"name":"rewardId","in":"path","required":true,"description":"Participant reward ID.","schema":{"type":"string"}}},"schemas":{"ApproveRewardRequest":{"type":"object","properties":{"fulfill":{"type":"boolean","default":false,"description":"Set true to mark the reward as fulfilled after approval."}}},"SuccessResponse":{"type":"object","required":["success"],"properties":{"success":{"description":"Whether the request succeeded.","type":"boolean"}}},"Error":{"type":"object","properties":{"name":{"description":"Error name returned for the failed request.","type":"string"},"code":{"description":"Stable machine-readable error code.","type":"string"},"message":{"description":"Human-readable error message.","type":"string"},"errors":{"description":"Optional validation details for specific request fields.","type":"array","items":{"type":"object","additionalProperties":true}},"status":{"description":"HTTP status code for the error.","type":"integer"},"supportUrl":{"description":"Support URL related to the error, when available.","type":"string","format":"uri"},"policyName":{"description":"Rate-limit policy name for `429` errors, when available.","type":"string"},"level":{"description":"Error severity level, when available.","type":"string"},"timestamp":{"description":"When the error response was created.","type":"string","format":"date-time"}}}},"responses":{"Success":{"description":"Success response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"BadRequest":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The API key is missing, invalid, revoked, outside its scope, or not allowed to perform this action.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InvalidState":{"description":"Resource is not in a state that permits this operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"UnprocessableEntity":{"description":"Request is not valid for the current program or participant state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Too many requests.","headers":{"GrowSurf-RateLimit-Second-Limit":{"description":"Number of API requests allowed per second policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Second-Remaining":{"description":"Number of API requests remaining in the second policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Second-Milliseconds":{"description":"Milliseconds until the second policy window resets.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Minute-Limit":{"description":"Number of API requests allowed per minute policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Minute-Remaining":{"description":"Number of API requests remaining in the minute policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Minute-Milliseconds":{"description":"Milliseconds until the minute policy window resets.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Hour-Limit":{"description":"Number of API requests allowed per hour policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Hour-Remaining":{"description":"Number of API requests remaining in the hour policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Hour-Milliseconds":{"description":"Milliseconds until the hour policy window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/campaign/{id}/reward/{rewardId}/approve":{"post":{"tags":["Participant Rewards"],"operationId":"approveParticipantReward","summary":"Approve participant reward","description":"Approves a manually approved reward earned by a participant. This requires `reward:write`. When the request also sets `fulfill` to `true`, it additionally requires `reward:fulfill`.","parameters":[{"$ref":"#/components/parameters/CampaignId"},{"$ref":"#/components/parameters/RewardId"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApproveRewardRequest"}}}},"responses":{"200":{"$ref":"#/components/responses/Success"},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"406":{"$ref":"#/components/responses/InvalidState"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"}}}}}} ``` ## Fulfill participant reward > Marks an approved participant reward as fulfilled. ```json {"openapi":"3.1.0","info":{"title":"GrowSurf REST API","version":"2.0.0"},"tags":[{"name":"Participant Rewards","description":"Participant reward retrieval and manual reward operations."}],"servers":[{"url":"https://api.growsurf.com/v2","description":"Production"}],"security":[{"apiKeyAuth":[]}],"components":{"securitySchemes":{"apiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"API key","description":"GrowSurf REST API key supplied as `Authorization: Bearer `."}},"parameters":{"CampaignId":{"name":"id","in":"path","required":true,"description":"GrowSurf program ID.","schema":{"type":"string"}},"RewardId":{"name":"rewardId","in":"path","required":true,"description":"Participant reward ID.","schema":{"type":"string"}}},"responses":{"Success":{"description":"Success response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"BadRequest":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The API key is missing, invalid, revoked, outside its scope, or not allowed to perform this action.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InvalidState":{"description":"Resource is not in a state that permits this operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"UnprocessableEntity":{"description":"Request is not valid for the current program or participant state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Too many requests.","headers":{"GrowSurf-RateLimit-Second-Limit":{"description":"Number of API requests allowed per second policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Second-Remaining":{"description":"Number of API requests remaining in the second policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Second-Milliseconds":{"description":"Milliseconds until the second policy window resets.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Minute-Limit":{"description":"Number of API requests allowed per minute policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Minute-Remaining":{"description":"Number of API requests remaining in the minute policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Minute-Milliseconds":{"description":"Milliseconds until the minute policy window resets.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Hour-Limit":{"description":"Number of API requests allowed per hour policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Hour-Remaining":{"description":"Number of API requests remaining in the hour policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Hour-Milliseconds":{"description":"Milliseconds until the hour policy window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"SuccessResponse":{"type":"object","required":["success"],"properties":{"success":{"description":"Whether the request succeeded.","type":"boolean"}}},"Error":{"type":"object","properties":{"name":{"description":"Error name returned for the failed request.","type":"string"},"code":{"description":"Stable machine-readable error code.","type":"string"},"message":{"description":"Human-readable error message.","type":"string"},"errors":{"description":"Optional validation details for specific request fields.","type":"array","items":{"type":"object","additionalProperties":true}},"status":{"description":"HTTP status code for the error.","type":"integer"},"supportUrl":{"description":"Support URL related to the error, when available.","type":"string","format":"uri"},"policyName":{"description":"Rate-limit policy name for `429` errors, when available.","type":"string"},"level":{"description":"Error severity level, when available.","type":"string"},"timestamp":{"description":"When the error response was created.","type":"string","format":"date-time"}}}}},"paths":{"/campaign/{id}/reward/{rewardId}/fulfill":{"post":{"tags":["Participant Rewards"],"operationId":"fulfillParticipantReward","summary":"Fulfill participant reward","description":"Marks an approved participant reward as fulfilled.","parameters":[{"$ref":"#/components/parameters/CampaignId"},{"$ref":"#/components/parameters/RewardId"}],"responses":{"200":{"$ref":"#/components/responses/Success"},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"406":{"$ref":"#/components/responses/InvalidState"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"}}}}}} ``` ## Delete participant reward > Removes a manually approved participant reward that has not already been approved. ```json {"openapi":"3.1.0","info":{"title":"GrowSurf REST API","version":"2.0.0"},"tags":[{"name":"Participant Rewards","description":"Participant reward retrieval and manual reward operations."}],"servers":[{"url":"https://api.growsurf.com/v2","description":"Production"}],"security":[{"apiKeyAuth":[]}],"components":{"securitySchemes":{"apiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"API key","description":"GrowSurf REST API key supplied as `Authorization: Bearer `."}},"parameters":{"CampaignId":{"name":"id","in":"path","required":true,"description":"GrowSurf program ID.","schema":{"type":"string"}},"RewardId":{"name":"rewardId","in":"path","required":true,"description":"Participant reward ID.","schema":{"type":"string"}}},"responses":{"Success":{"description":"Success response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"BadRequest":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The API key is missing, invalid, revoked, outside its scope, or not allowed to perform this action.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InvalidState":{"description":"Resource is not in a state that permits this operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"UnprocessableEntity":{"description":"Request is not valid for the current program or participant state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Too many requests.","headers":{"GrowSurf-RateLimit-Second-Limit":{"description":"Number of API requests allowed per second policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Second-Remaining":{"description":"Number of API requests remaining in the second policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Second-Milliseconds":{"description":"Milliseconds until the second policy window resets.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Minute-Limit":{"description":"Number of API requests allowed per minute policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Minute-Remaining":{"description":"Number of API requests remaining in the minute policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Minute-Milliseconds":{"description":"Milliseconds until the minute policy window resets.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Hour-Limit":{"description":"Number of API requests allowed per hour policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Hour-Remaining":{"description":"Number of API requests remaining in the hour policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Hour-Milliseconds":{"description":"Milliseconds until the hour policy window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"SuccessResponse":{"type":"object","required":["success"],"properties":{"success":{"description":"Whether the request succeeded.","type":"boolean"}}},"Error":{"type":"object","properties":{"name":{"description":"Error name returned for the failed request.","type":"string"},"code":{"description":"Stable machine-readable error code.","type":"string"},"message":{"description":"Human-readable error message.","type":"string"},"errors":{"description":"Optional validation details for specific request fields.","type":"array","items":{"type":"object","additionalProperties":true}},"status":{"description":"HTTP status code for the error.","type":"integer"},"supportUrl":{"description":"Support URL related to the error, when available.","type":"string","format":"uri"},"policyName":{"description":"Rate-limit policy name for `429` errors, when available.","type":"string"},"level":{"description":"Error severity level, when available.","type":"string"},"timestamp":{"description":"When the error response was created.","type":"string","format":"date-time"}}}}},"paths":{"/campaign/{id}/reward/{rewardId}":{"delete":{"tags":["Participant Rewards"],"operationId":"deleteParticipantReward","summary":"Delete participant reward","description":"Removes a manually approved participant reward that has not already been approved.","parameters":[{"$ref":"#/components/parameters/CampaignId"},{"$ref":"#/components/parameters/RewardId"}],"responses":{"200":{"$ref":"#/components/responses/Success"},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"406":{"$ref":"#/components/responses/InvalidState"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"}}}}}} ``` *** ## REFERRALS AND INVITES ↓ ## List referrals and invites > Retrieves a list of all referrals and email invites made by participants in a program. ```json {"openapi":"3.1.0","info":{"title":"GrowSurf REST API","version":"2.0.0"},"tags":[{"name":"Referrals and Invites","description":"Referral, invite, and participant email invite operations."}],"servers":[{"url":"https://api.growsurf.com/v2","description":"Production"}],"security":[{"apiKeyAuth":[]}],"components":{"securitySchemes":{"apiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"API key","description":"GrowSurf REST API key supplied as `Authorization: Bearer `."}},"parameters":{"CampaignId":{"name":"id","in":"path","required":true,"description":"GrowSurf program ID.","schema":{"type":"string"}},"ReferralSortBy":{"name":"sortBy","in":"query","required":false,"description":"Field used to sort referral results.","schema":{"type":"string","enum":["updatedAt","createdAt","email","firstName","lastName","referralStatus","referralTriggeredAt"],"default":"updatedAt"}},"Desc":{"name":"desc","in":"query","required":false,"description":"Return results in descending order when true.","schema":{"type":"boolean","default":true}},"Limit100":{"name":"limit","in":"query","required":false,"description":"Number of results to return. Maximum 100.","schema":{"type":"integer","minimum":1,"maximum":100,"default":10}},"Offset":{"name":"offset","in":"query","required":false,"description":"Offset number used to skip through a result set.","schema":{"type":"integer","minimum":0,"default":0}},"ReferralEmailFilter":{"name":"email","in":"query","required":false,"description":"URL-encoded email value to filter referral results.","schema":{"type":"string"}},"FirstNameFilter":{"name":"firstName","in":"query","required":false,"description":"First name value to filter results.","schema":{"type":"string"}},"LastNameFilter":{"name":"lastName","in":"query","required":false,"description":"Last name value to filter results.","schema":{"type":"string"}},"ReferralStatusFilter":{"name":"referralStatus","in":"query","required":false,"description":"Referral status to filter results.","schema":{"$ref":"#/components/schemas/ReferralStatus"}},"NextId":{"name":"nextId","in":"query","required":false,"description":"ID to start the next paged result set with.","schema":{"type":"string"}}},"schemas":{"ReferralStatus":{"type":"string","enum":["CREDIT_PENDING","CREDIT_AWARDED","CREDIT_EXPIRED","INVITE_SENT"]},"ReferralListResponse":{"type":"object","required":["referrals","limit","more"],"properties":{"referrals":{"description":"Referrals and invites returned for this page.","type":"array","items":{"$ref":"#/components/schemas/Referral"}},"limit":{"description":"Maximum number of referrals requested for this page.","type":"integer"},"nextOffset":{"description":"Offset to pass as `offset` for the next page, or `null` when offset pagination is not used.","type":["integer","null"]},"nextId":{"description":"Referral ID to pass as `nextId` for the next page, or `null` when there are no more results.","type":["string","null"]},"more":{"description":"Whether another page of referrals is available.","type":"boolean"}}},"Referral":{"type":"object","required":["id","email","referralStatus","referredBy","createdAt","updatedAt"],"properties":{"id":{"description":"Participant ID for the referred friend or invitee.","type":"string"},"email":{"description":"Email address for the referred friend or invitee.","type":"string"},"firstName":{"description":"First name for the referred friend or invitee.","type":["string","null"]},"lastName":{"description":"Last name for the referred friend or invitee.","type":["string","null"]},"referralStatus":{"description":"Current referral status for this referred friend or invite.","$ref":"#/components/schemas/ReferralStatus"},"referredBy":{"description":"Participant ID of the referrer.","type":"string"},"createdAt":{"description":"When the referral or invite was created, as a Unix timestamp in milliseconds.","type":"integer","format":"int64"},"updatedAt":{"description":"When the referral or invite was last updated, as a Unix timestamp in milliseconds.","type":"integer","format":"int64"}}},"Error":{"type":"object","properties":{"name":{"description":"Error name returned for the failed request.","type":"string"},"code":{"description":"Stable machine-readable error code.","type":"string"},"message":{"description":"Human-readable error message.","type":"string"},"errors":{"description":"Optional validation details for specific request fields.","type":"array","items":{"type":"object","additionalProperties":true}},"status":{"description":"HTTP status code for the error.","type":"integer"},"supportUrl":{"description":"Support URL related to the error, when available.","type":"string","format":"uri"},"policyName":{"description":"Rate-limit policy name for `429` errors, when available.","type":"string"},"level":{"description":"Error severity level, when available.","type":"string"},"timestamp":{"description":"When the error response was created.","type":"string","format":"date-time"}}}},"responses":{"BadRequest":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The API key is missing, invalid, revoked, outside its scope, or not allowed to perform this action.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Too many requests.","headers":{"GrowSurf-RateLimit-Second-Limit":{"description":"Number of API requests allowed per second policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Second-Remaining":{"description":"Number of API requests remaining in the second policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Second-Milliseconds":{"description":"Milliseconds until the second policy window resets.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Minute-Limit":{"description":"Number of API requests allowed per minute policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Minute-Remaining":{"description":"Number of API requests remaining in the minute policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Minute-Milliseconds":{"description":"Milliseconds until the minute policy window resets.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Hour-Limit":{"description":"Number of API requests allowed per hour policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Hour-Remaining":{"description":"Number of API requests remaining in the hour policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Hour-Milliseconds":{"description":"Milliseconds until the hour policy window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/campaign/{id}/referrals":{"get":{"tags":["Referrals and Invites"],"operationId":"listReferrals","summary":"List referrals and invites","description":"Retrieves a list of all referrals and email invites made by participants in a program.","parameters":[{"$ref":"#/components/parameters/CampaignId"},{"$ref":"#/components/parameters/ReferralSortBy"},{"$ref":"#/components/parameters/Desc"},{"$ref":"#/components/parameters/Limit100"},{"$ref":"#/components/parameters/Offset"},{"$ref":"#/components/parameters/ReferralEmailFilter"},{"$ref":"#/components/parameters/FirstNameFilter"},{"$ref":"#/components/parameters/LastNameFilter"},{"$ref":"#/components/parameters/ReferralStatusFilter"},{"$ref":"#/components/parameters/NextId"}],"responses":{"200":{"description":"Referrals and invites returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReferralListResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}}}} ``` ## List participant referrals and invites > Retrieves referrals and email invites made by a participant. ```json {"openapi":"3.1.0","info":{"title":"GrowSurf REST API","version":"2.0.0"},"tags":[{"name":"Referrals and Invites","description":"Referral, invite, and participant email invite operations."}],"servers":[{"url":"https://api.growsurf.com/v2","description":"Production"}],"security":[{"apiKeyAuth":[]}],"components":{"securitySchemes":{"apiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"API key","description":"GrowSurf REST API key supplied as `Authorization: Bearer `."}},"parameters":{"CampaignId":{"name":"id","in":"path","required":true,"description":"GrowSurf program ID.","schema":{"type":"string"}},"ParticipantIdOrEmail":{"name":"participantIdOrEmail","in":"path","required":true,"description":"GrowSurf participant ID or URL-encoded participant email address.","schema":{"type":"string"}},"ReferralSortBy":{"name":"sortBy","in":"query","required":false,"description":"Field used to sort referral results.","schema":{"type":"string","enum":["updatedAt","createdAt","email","firstName","lastName","referralStatus","referralTriggeredAt"],"default":"updatedAt"}},"Desc":{"name":"desc","in":"query","required":false,"description":"Return results in descending order when true.","schema":{"type":"boolean","default":true}},"Limit100":{"name":"limit","in":"query","required":false,"description":"Number of results to return. Maximum 100.","schema":{"type":"integer","minimum":1,"maximum":100,"default":10}},"Offset":{"name":"offset","in":"query","required":false,"description":"Offset number used to skip through a result set.","schema":{"type":"integer","minimum":0,"default":0}},"ReferralEmailFilter":{"name":"email","in":"query","required":false,"description":"URL-encoded email value to filter referral results.","schema":{"type":"string"}},"FirstNameFilter":{"name":"firstName","in":"query","required":false,"description":"First name value to filter results.","schema":{"type":"string"}},"LastNameFilter":{"name":"lastName","in":"query","required":false,"description":"Last name value to filter results.","schema":{"type":"string"}},"ReferralStatusFilter":{"name":"referralStatus","in":"query","required":false,"description":"Referral status to filter results.","schema":{"$ref":"#/components/schemas/ReferralStatus"}},"NextId":{"name":"nextId","in":"query","required":false,"description":"ID to start the next paged result set with.","schema":{"type":"string"}}},"schemas":{"ReferralStatus":{"type":"string","enum":["CREDIT_PENDING","CREDIT_AWARDED","CREDIT_EXPIRED","INVITE_SENT"]},"ReferralListResponse":{"type":"object","required":["referrals","limit","more"],"properties":{"referrals":{"description":"Referrals and invites returned for this page.","type":"array","items":{"$ref":"#/components/schemas/Referral"}},"limit":{"description":"Maximum number of referrals requested for this page.","type":"integer"},"nextOffset":{"description":"Offset to pass as `offset` for the next page, or `null` when offset pagination is not used.","type":["integer","null"]},"nextId":{"description":"Referral ID to pass as `nextId` for the next page, or `null` when there are no more results.","type":["string","null"]},"more":{"description":"Whether another page of referrals is available.","type":"boolean"}}},"Referral":{"type":"object","required":["id","email","referralStatus","referredBy","createdAt","updatedAt"],"properties":{"id":{"description":"Participant ID for the referred friend or invitee.","type":"string"},"email":{"description":"Email address for the referred friend or invitee.","type":"string"},"firstName":{"description":"First name for the referred friend or invitee.","type":["string","null"]},"lastName":{"description":"Last name for the referred friend or invitee.","type":["string","null"]},"referralStatus":{"description":"Current referral status for this referred friend or invite.","$ref":"#/components/schemas/ReferralStatus"},"referredBy":{"description":"Participant ID of the referrer.","type":"string"},"createdAt":{"description":"When the referral or invite was created, as a Unix timestamp in milliseconds.","type":"integer","format":"int64"},"updatedAt":{"description":"When the referral or invite was last updated, as a Unix timestamp in milliseconds.","type":"integer","format":"int64"}}},"Error":{"type":"object","properties":{"name":{"description":"Error name returned for the failed request.","type":"string"},"code":{"description":"Stable machine-readable error code.","type":"string"},"message":{"description":"Human-readable error message.","type":"string"},"errors":{"description":"Optional validation details for specific request fields.","type":"array","items":{"type":"object","additionalProperties":true}},"status":{"description":"HTTP status code for the error.","type":"integer"},"supportUrl":{"description":"Support URL related to the error, when available.","type":"string","format":"uri"},"policyName":{"description":"Rate-limit policy name for `429` errors, when available.","type":"string"},"level":{"description":"Error severity level, when available.","type":"string"},"timestamp":{"description":"When the error response was created.","type":"string","format":"date-time"}}}},"responses":{"BadRequest":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The API key is missing, invalid, revoked, outside its scope, or not allowed to perform this action.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Too many requests.","headers":{"GrowSurf-RateLimit-Second-Limit":{"description":"Number of API requests allowed per second policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Second-Remaining":{"description":"Number of API requests remaining in the second policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Second-Milliseconds":{"description":"Milliseconds until the second policy window resets.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Minute-Limit":{"description":"Number of API requests allowed per minute policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Minute-Remaining":{"description":"Number of API requests remaining in the minute policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Minute-Milliseconds":{"description":"Milliseconds until the minute policy window resets.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Hour-Limit":{"description":"Number of API requests allowed per hour policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Hour-Remaining":{"description":"Number of API requests remaining in the hour policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Hour-Milliseconds":{"description":"Milliseconds until the hour policy window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/campaign/{id}/participant/{participantIdOrEmail}/referrals":{"get":{"tags":["Referrals and Invites"],"operationId":"listParticipantReferrals","summary":"List participant referrals and invites","description":"Retrieves referrals and email invites made by a participant.","parameters":[{"$ref":"#/components/parameters/CampaignId"},{"$ref":"#/components/parameters/ParticipantIdOrEmail"},{"$ref":"#/components/parameters/ReferralSortBy"},{"$ref":"#/components/parameters/Desc"},{"$ref":"#/components/parameters/Limit100"},{"$ref":"#/components/parameters/Offset"},{"$ref":"#/components/parameters/ReferralEmailFilter"},{"$ref":"#/components/parameters/FirstNameFilter"},{"$ref":"#/components/parameters/LastNameFilter"},{"$ref":"#/components/parameters/ReferralStatusFilter"},{"$ref":"#/components/parameters/NextId"}],"responses":{"200":{"description":"Participant referrals and invites returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReferralListResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}}}} ``` ## Send participant invites > Sends email invites on behalf of a participant to a list of email addresses. Sending invites via the API requires a \*\*verified custom email domain\*\* on the program; the request fails until one is verified. ```json {"openapi":"3.1.0","info":{"title":"GrowSurf REST API","version":"2.0.0"},"tags":[{"name":"Referrals and Invites","description":"Referral, invite, and participant email invite operations."}],"servers":[{"url":"https://api.growsurf.com/v2","description":"Production"}],"security":[{"apiKeyAuth":[]}],"components":{"securitySchemes":{"apiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"API key","description":"GrowSurf REST API key supplied as `Authorization: Bearer `."}},"parameters":{"CampaignId":{"name":"id","in":"path","required":true,"description":"GrowSurf program ID.","schema":{"type":"string"}},"ParticipantIdOrEmail":{"name":"participantIdOrEmail","in":"path","required":true,"description":"GrowSurf participant ID or URL-encoded participant email address.","schema":{"type":"string"}}},"schemas":{"SendInvitesRequest":{"type":"object","required":["emailAddresses","messageText","subjectText"],"properties":{"emailAddresses":{"description":"Email addresses to invite.","type":"array","minItems":1,"items":{"type":"string","format":"email"}},"messageText":{"description":"Message body for the invite email.","type":"string"},"subjectText":{"description":"Subject line for the invite email.","type":"string"}}},"SendInvitesResponse":{"type":"object","required":["success","messageType","invitesSent"],"properties":{"success":{"description":"Whether the invites request succeeded.","type":"boolean"},"messageType":{"description":"Result category for the invites request.","type":"string"},"invitesSent":{"description":"Number of invite emails sent.","type":"integer"}}},"Error":{"type":"object","properties":{"name":{"description":"Error name returned for the failed request.","type":"string"},"code":{"description":"Stable machine-readable error code.","type":"string"},"message":{"description":"Human-readable error message.","type":"string"},"errors":{"description":"Optional validation details for specific request fields.","type":"array","items":{"type":"object","additionalProperties":true}},"status":{"description":"HTTP status code for the error.","type":"integer"},"supportUrl":{"description":"Support URL related to the error, when available.","type":"string","format":"uri"},"policyName":{"description":"Rate-limit policy name for `429` errors, when available.","type":"string"},"level":{"description":"Error severity level, when available.","type":"string"},"timestamp":{"description":"When the error response was created.","type":"string","format":"date-time"}}}},"responses":{"BadRequest":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The API key is missing, invalid, revoked, outside its scope, or not allowed to perform this action.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Too many requests.","headers":{"GrowSurf-RateLimit-Second-Limit":{"description":"Number of API requests allowed per second policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Second-Remaining":{"description":"Number of API requests remaining in the second policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Second-Milliseconds":{"description":"Milliseconds until the second policy window resets.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Minute-Limit":{"description":"Number of API requests allowed per minute policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Minute-Remaining":{"description":"Number of API requests remaining in the minute policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Minute-Milliseconds":{"description":"Milliseconds until the minute policy window resets.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Hour-Limit":{"description":"Number of API requests allowed per hour policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Hour-Remaining":{"description":"Number of API requests remaining in the hour policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Hour-Milliseconds":{"description":"Milliseconds until the hour policy window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/campaign/{id}/participant/{participantIdOrEmail}/invites":{"post":{"tags":["Referrals and Invites"],"operationId":"sendParticipantInvites","summary":"Send participant invites","description":"Sends email invites on behalf of a participant to a list of email addresses. Sending invites via the API requires a **verified custom email domain** on the program; the request fails until one is verified.","parameters":[{"$ref":"#/components/parameters/CampaignId"},{"$ref":"#/components/parameters/ParticipantIdOrEmail"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendInvitesRequest"}}}},"responses":{"200":{"description":"Invite send result returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendInvitesResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}}}} ``` *** ## ANALYTICS ↓ ## Retrieve campaign analytics > Retrieves analytics for a program. Pass \`interval\` to also get a time-series (\`series\`) alongside the totals, and \`include\` to add previous-period totals, status breakdowns, or derived rates — useful for detecting trends over time. ```json {"openapi":"3.1.0","info":{"title":"GrowSurf REST API","version":"2.0.0"},"tags":[{"name":"Analytics","description":"Program analytics."}],"servers":[{"url":"https://api.growsurf.com/v2","description":"Production"}],"security":[{"apiKeyAuth":[]}],"components":{"securitySchemes":{"apiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"API key","description":"GrowSurf REST API key supplied as `Authorization: Bearer `."}},"parameters":{"CampaignId":{"name":"id","in":"path","required":true,"description":"GrowSurf program ID.","schema":{"type":"string"}},"AnalyticsDays":{"name":"days","in":"query","required":false,"description":"Last number of days to retrieve analytics for. Defaults to 365. Maximum 1825.","schema":{"type":"integer","minimum":1,"maximum":1825,"default":365}},"AnalyticsStartDate":{"name":"startDate","in":"query","required":false,"description":"Start date of the analytics timeframe as a Unix timestamp in milliseconds. Required if `days` is not set.","schema":{"type":"integer","format":"int64"}},"AnalyticsEndDate":{"name":"endDate","in":"query","required":false,"description":"End date of the analytics timeframe as a Unix timestamp in milliseconds. Required if `days` is not set.","schema":{"type":"integer","format":"int64"}}},"schemas":{"CampaignAnalyticsResponse":{"type":"object","required":["analytics","startDate","endDate"],"properties":{"analytics":{"description":"Campaign analytics totals for the requested timeframe.","$ref":"#/components/schemas/CampaignAnalytics"},"startDate":{"description":"Start of the analytics timeframe, as a Unix timestamp in milliseconds.","type":"integer","format":"int64"},"endDate":{"description":"End of the analytics timeframe, as a Unix timestamp in milliseconds.","type":"integer","format":"int64"},"series":{"type":"array","description":"Present only when `interval` is `day`, `week`, or `month`. Per-period totals, ascending.","items":{"allOf":[{"type":"object","properties":{"periodStart":{"type":"integer","format":"int64","description":"Start of the period, as a Unix timestamp in milliseconds (UTC)."}}},{"$ref":"#/components/schemas/CampaignAnalytics"}]}},"previousPeriod":{"description":"Present only when `include` contains `previousPeriod`.","allOf":[{"$ref":"#/components/schemas/PreviousPeriodAnalytics"}]},"statusCounts":{"description":"Present only when `include` contains `statusCounts`.","allOf":[{"$ref":"#/components/schemas/CampaignStatusCounts"}]},"rates":{"description":"Present only when `include` contains `rates`.","allOf":[{"$ref":"#/components/schemas/CampaignAnalyticsRates"}]}}},"CampaignAnalytics":{"type":"object","properties":{"invites":{"description":"Number of invites sent by participants.","type":"integer"},"impressions":{"description":"Total referral-link views.","type":"integer"},"uniqueImpressions":{"description":"Unique referral-link views.","type":"integer"},"participants":{"description":"Number of participants added.","type":"integer"},"referrals":{"description":"Number of referrals credited.","type":"integer"},"referralCreditPendings":{"description":"Number of referrals waiting for credit.","type":"integer"},"referralCreditExpireds":{"description":"Number of referrals whose credit window expired.","type":"integer"},"emailShares":{"description":"Number of shares through email.","type":"integer"},"facebookShares":{"description":"Number of shares through Facebook.","type":"integer"},"twitterShares":{"description":"Number of shares through Twitter/X.","type":"integer"},"threadsShares":{"description":"Number of shares through Threads.","type":"integer"},"blueskyShares":{"description":"Number of shares through Bluesky.","type":"integer"},"pinterestShares":{"description":"Number of shares through Pinterest.","type":"integer"},"linkedInShares":{"description":"Number of shares through LinkedIn.","type":"integer"},"smsShares":{"description":"Number of shares through SMS.","type":"integer"},"messengerShares":{"description":"Number of shares through Messenger.","type":"integer"},"whatsAppShares":{"description":"Number of shares through WhatsApp.","type":"integer"},"wechatShares":{"description":"Number of shares through WeChat.","type":"integer"},"telegramShares":{"description":"Number of shares through Telegram.","type":"integer"},"qrcodeShares":{"description":"Number of shares through QR code.","type":"integer"},"redditShares":{"description":"Number of shares through Reddit.","type":"integer"},"tumblrShares":{"description":"Number of shares through Tumblr.","type":"integer"},"copyRefLinkShares":{"description":"Number of times participants copied their referral link.","type":"integer"},"iosNativeShares":{"description":"Number of shares through iOS native sharing.","type":"integer"},"androidNativeShares":{"description":"Number of shares through Android native sharing.","type":"integer"},"totalRevenue":{"type":"integer","description":"Affiliate programs only. Revenue in the smallest unit of the program currency."},"totalCommissions":{"type":"integer","description":"Affiliate programs only. Commissions in the smallest unit of the program currency."},"totalCommissionCount":{"type":"integer","description":"Affiliate programs only. Number of commission records."}}},"PreviousPeriodAnalytics":{"type":"object","description":"Totals for the equal-length window immediately preceding the requested one.","required":["analytics","startDate","endDate"],"properties":{"analytics":{"description":"Campaign analytics totals for the previous comparison timeframe.","$ref":"#/components/schemas/CampaignAnalytics"},"startDate":{"description":"Start of the previous comparison timeframe, as a Unix timestamp in milliseconds.","type":"integer","format":"int64"},"endDate":{"description":"End of the previous comparison timeframe, as a Unix timestamp in milliseconds.","type":"integer","format":"int64"}}},"CampaignStatusCounts":{"type":"object","description":"Status-count breakdowns. `rewardStatus` is present for every program; `affiliateStatus`, `commissionStatus`, and `payoutStatus` are present only for affiliate programs. Money amounts are in minor units of `currencyISO`.","properties":{"currencyISO":{"description":"Program currency for money amounts in the status-count breakdown.","type":"string"},"rewardStatus":{"description":"Reward counts by approval status.","type":"object","properties":{"pending":{"type":"integer","description":"Unapproved rewards awaiting fulfillment."},"approved":{"description":"Approved rewards.","type":"integer"}}},"affiliateStatus":{"type":"object","description":"Affiliate only. Participant counts keyed by affiliate status.","additionalProperties":{"type":"integer"}},"commissionStatus":{"type":"object","description":"Affiliate only. Commission counts and amounts by status.","properties":{"pending":{"description":"Pending commissions.","$ref":"#/components/schemas/CommissionStatusMetric"},"approved":{"description":"Approved commissions.","$ref":"#/components/schemas/CommissionStatusMetric"},"paid":{"description":"Paid commissions.","$ref":"#/components/schemas/CommissionStatusMetric"},"reversed":{"description":"Reversed commissions.","$ref":"#/components/schemas/CommissionStatusMetric"}}},"payoutStatus":{"type":"object","description":"Affiliate only. Payout counts and amounts by status.","properties":{"upcoming":{"description":"Upcoming payouts.","$ref":"#/components/schemas/PayoutStatusMetric"},"queued":{"description":"Queued payouts.","$ref":"#/components/schemas/PayoutStatusMetric"},"issued":{"description":"Issued payouts.","$ref":"#/components/schemas/PayoutStatusMetric"},"failed":{"description":"Failed payouts.","$ref":"#/components/schemas/PayoutStatusMetric"}}}}},"CommissionStatusMetric":{"type":"object","properties":{"count":{"description":"Number of commissions in this status.","type":"integer"},"totalAmount":{"type":"integer","description":"Total commission amount in minor currency units."},"totalRevenue":{"type":"integer","description":"Total attributed revenue in minor currency units."}}},"PayoutStatusMetric":{"type":"object","properties":{"count":{"description":"Number of payouts in this status.","type":"integer"},"totalAmount":{"type":"integer","description":"Total payout amount in minor currency units."}}},"CampaignAnalyticsRates":{"type":"object","description":"Derived referral rates, each a ratio in the range 0–1 (0 when its denominator is 0).","properties":{"referralConversionRate":{"type":"number","format":"float","description":"`referrals` divided by `uniqueImpressions`."},"participationRate":{"type":"number","format":"float","description":"`participants` divided by `uniqueImpressions`."},"sharesPerParticipant":{"type":"number","format":"float","description":"Total shares across all channels divided by `participants`."}}},"Error":{"type":"object","properties":{"name":{"description":"Error name returned for the failed request.","type":"string"},"code":{"description":"Stable machine-readable error code.","type":"string"},"message":{"description":"Human-readable error message.","type":"string"},"errors":{"description":"Optional validation details for specific request fields.","type":"array","items":{"type":"object","additionalProperties":true}},"status":{"description":"HTTP status code for the error.","type":"integer"},"supportUrl":{"description":"Support URL related to the error, when available.","type":"string","format":"uri"},"policyName":{"description":"Rate-limit policy name for `429` errors, when available.","type":"string"},"level":{"description":"Error severity level, when available.","type":"string"},"timestamp":{"description":"When the error response was created.","type":"string","format":"date-time"}}}},"responses":{"BadRequest":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The API key is missing, invalid, revoked, outside its scope, or not allowed to perform this action.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Too many requests.","headers":{"GrowSurf-RateLimit-Second-Limit":{"description":"Number of API requests allowed per second policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Second-Remaining":{"description":"Number of API requests remaining in the second policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Second-Milliseconds":{"description":"Milliseconds until the second policy window resets.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Minute-Limit":{"description":"Number of API requests allowed per minute policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Minute-Remaining":{"description":"Number of API requests remaining in the minute policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Minute-Milliseconds":{"description":"Milliseconds until the minute policy window resets.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Hour-Limit":{"description":"Number of API requests allowed per hour policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Hour-Remaining":{"description":"Number of API requests remaining in the hour policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Hour-Milliseconds":{"description":"Milliseconds until the hour policy window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/campaign/{id}/analytics":{"get":{"tags":["Analytics"],"operationId":"retrieveCampaignAnalytics","summary":"Retrieve campaign analytics","description":"Retrieves analytics for a program. Pass `interval` to also get a time-series (`series`) alongside the totals, and `include` to add previous-period totals, status breakdowns, or derived rates — useful for detecting trends over time.","parameters":[{"$ref":"#/components/parameters/CampaignId"},{"$ref":"#/components/parameters/AnalyticsDays"},{"$ref":"#/components/parameters/AnalyticsStartDate"},{"$ref":"#/components/parameters/AnalyticsEndDate"},{"name":"interval","in":"query","description":"When set to `day`, `week`, or `month`, the response also includes a `series` array with per-period totals. Defaults to `total` (no series).","schema":{"type":"string","enum":["day","week","month","total"],"default":"total"}},{"name":"include","in":"query","description":"Comma-separated list of optional enrichments (opt-in to keep the default response lean): `previousPeriod` adds totals for the equal-length window immediately before the requested one; `statusCounts` adds reward (and, for affiliate programs, affiliate/commission/payout) status breakdowns; `rates` adds derived referral rates.","schema":{"type":"string"}}],"responses":{"200":{"description":"Campaign analytics returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CampaignAnalyticsResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}}}} ``` *** ## AFFILIATE PROGRAMS ↓ ## Record affiliate transaction > \*\*Affiliate programs only.\*\* Records a sale made by a referred customer and generates affiliate commissions for their referrer when applicable. Requires at least one transaction identifier (externalId, transactionId, orderId, paymentId, invoiceId, paymentIntentId, or chargeId) so repeated requests can be de-duplicated — without one, a resent sale would create a second commission. Reuse the same identifier(s) when refunding. ```json {"openapi":"3.1.0","info":{"title":"GrowSurf REST API","version":"2.0.0"},"tags":[{"name":"Affiliate Programs","description":"Affiliate transaction, commission, and payout operations."}],"servers":[{"url":"https://api.growsurf.com/v2","description":"Production"}],"security":[{"apiKeyAuth":[]}],"components":{"securitySchemes":{"apiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"API key","description":"GrowSurf REST API key supplied as `Authorization: Bearer `."}},"parameters":{"CampaignId":{"name":"id","in":"path","required":true,"description":"GrowSurf program ID.","schema":{"type":"string"}},"ParticipantIdOrEmail":{"name":"participantIdOrEmail","in":"path","required":true,"description":"GrowSurf participant ID or URL-encoded participant email address.","schema":{"type":"string"}}},"schemas":{"RecordTransactionRequest":{"type":"object","required":["currency","grossAmount"],"properties":{"currency":{"description":"3-letter ISO 4217 currency code for the sale. Must match the program currency.","type":"string","minLength":3,"maxLength":3,"pattern":"^[A-Za-z]{3}$"},"grossAmount":{"description":"Total sale amount in the currency's minor unit. Must be a positive integer.","type":"integer","minimum":1},"netAmount":{"description":"Net-of-tax sale amount in the currency's minor unit. Used as the commissionable base when supplied.","type":"integer","minimum":0},"taxAmount":{"description":"Tax collected in the currency's minor unit. Used to derive the commissionable base when `netAmount` is absent.","type":"integer","minimum":0},"amountCashNet":{"description":"Explicit post-tax cash amount in the currency's minor unit. Overrides derived net amounts.","type":"integer","minimum":0},"amountPaid":{"description":"Amount actually paid in the currency's minor unit, when reported by your payment processor.","type":"integer","minimum":0},"paidAt":{"description":"When the payment was captured or settled, as a Unix timestamp in milliseconds.","type":"integer","format":"int64"},"externalId":{"description":"Primary transaction identifier from your billing system. Used to detect duplicate submissions.","type":"string","maxLength":500},"transactionId":{"description":"Transaction identifier to store for this sale. Used to detect duplicate submissions.","type":"string","maxLength":500},"customerId":{"description":"Customer record identifier, such as a payment-provider customer ID.","type":"string","maxLength":500},"orderId":{"description":"Order identifier. Used to detect duplicate submissions when supplied.","type":"string","maxLength":500},"paymentId":{"description":"Payment identifier. Used to detect duplicate submissions when supplied.","type":"string","maxLength":500},"invoiceId":{"description":"Invoice identifier. Used to detect duplicate submissions when supplied.","type":"string","maxLength":500},"subscriptionId":{"description":"Subscription identifier for recurring payments.","type":"string","maxLength":500},"paymentIntentId":{"description":"Payment intent identifier. Used to detect duplicate submissions when supplied.","type":"string","maxLength":500},"chargeId":{"description":"Charge identifier. Used to detect duplicate submissions when supplied.","type":"string","maxLength":500},"description":{"description":"Freeform sale description shown in dashboard context and reports.","type":"string","maxLength":500},"invoiceTotal":{"description":"Invoice total including tax, in the currency's minor unit.","type":"integer","minimum":0},"invoiceTotalExcludingTax":{"description":"Invoice total excluding tax, in the currency's minor unit.","type":"integer","minimum":0},"invoiceSubtotalExcludingTax":{"description":"Invoice subtotal excluding tax, in the currency's minor unit.","type":"integer","minimum":0},"totalTaxAmount":{"description":"Aggregate tax amount in the currency's minor unit.","type":"integer","minimum":0},"totalTaxAmounts":{"description":"Detailed tax breakdown objects from your payment processor.","type":"array","items":{"type":"object","additionalProperties":true}},"totalTaxes":{"description":"Alternate detailed tax breakdown objects from your payment processor.","type":"array","items":{"type":"object","additionalProperties":true}}}},"RecordTransactionResponse":{"oneOf":[{"type":"object","required":["success","firstSale","duplicate","message"],"properties":{"success":{"description":"Whether the sale was recorded.","type":"boolean","const":true},"firstSale":{"description":"Whether this was the referred customer's first recorded sale.","type":"boolean"},"duplicate":{"description":"Always `false` when the sale is newly recorded.","type":"boolean","const":false},"message":{"description":"Human-readable result message for the sale.","type":"string"}}},{"type":"object","required":["success","duplicate","commissionsCreated","duplicateFields","matchingCommissionIds","message"],"properties":{"success":{"description":"Always `false` when the sale matched an existing transaction.","type":"boolean","const":false},"duplicate":{"description":"Always `true` when the sale matched an existing transaction.","type":"boolean","const":true},"commissionsCreated":{"description":"Number of commissions created by this duplicate request.","type":"integer"},"duplicateFields":{"description":"Identifier fields that matched an existing transaction.","type":"array","items":{"type":"string"}},"matchingCommissionIds":{"description":"Commission IDs that matched the submitted identifiers.","type":"array","items":{"type":"string"}},"message":{"description":"Human-readable result message for the duplicate sale.","type":"string"}}}]},"Error":{"type":"object","properties":{"name":{"description":"Error name returned for the failed request.","type":"string"},"code":{"description":"Stable machine-readable error code.","type":"string"},"message":{"description":"Human-readable error message.","type":"string"},"errors":{"description":"Optional validation details for specific request fields.","type":"array","items":{"type":"object","additionalProperties":true}},"status":{"description":"HTTP status code for the error.","type":"integer"},"supportUrl":{"description":"Support URL related to the error, when available.","type":"string","format":"uri"},"policyName":{"description":"Rate-limit policy name for `429` errors, when available.","type":"string"},"level":{"description":"Error severity level, when available.","type":"string"},"timestamp":{"description":"When the error response was created.","type":"string","format":"date-time"}}}},"responses":{"BadRequest":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The API key is missing, invalid, revoked, outside its scope, or not allowed to perform this action.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"UnprocessableEntity":{"description":"Request is not valid for the current program or participant state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Too many requests.","headers":{"GrowSurf-RateLimit-Second-Limit":{"description":"Number of API requests allowed per second policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Second-Remaining":{"description":"Number of API requests remaining in the second policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Second-Milliseconds":{"description":"Milliseconds until the second policy window resets.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Minute-Limit":{"description":"Number of API requests allowed per minute policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Minute-Remaining":{"description":"Number of API requests remaining in the minute policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Minute-Milliseconds":{"description":"Milliseconds until the minute policy window resets.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Hour-Limit":{"description":"Number of API requests allowed per hour policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Hour-Remaining":{"description":"Number of API requests remaining in the hour policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Hour-Milliseconds":{"description":"Milliseconds until the hour policy window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/campaign/{id}/participant/{participantIdOrEmail}/transaction":{"post":{"tags":["Affiliate Programs"],"operationId":"recordTransaction","summary":"Record affiliate transaction","description":"**Affiliate programs only.** Records a sale made by a referred customer and generates affiliate commissions for their referrer when applicable. Requires at least one transaction identifier (externalId, transactionId, orderId, paymentId, invoiceId, paymentIntentId, or chargeId) so repeated requests can be de-duplicated — without one, a resent sale would create a second commission. Reuse the same identifier(s) when refunding.","parameters":[{"$ref":"#/components/parameters/CampaignId"},{"$ref":"#/components/parameters/ParticipantIdOrEmail"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecordTransactionRequest"}}}},"responses":{"200":{"description":"Transaction result returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecordTransactionResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"}}}}}} ``` ## Refund or amend affiliate transaction > \*\*Affiliate programs only.\*\* Records an amendment (refund, partial refund, refund cancellation, or chargeback) against a previously recorded transaction and reverses or adjusts the referrer's commission. The inverse of Record Affiliate Transaction. Identify the original transaction with the same identifier(s) you sent when recording it. Commissions already paid out to the affiliate are not clawed back; the amendment is recorded for tax reporting only. ```json {"openapi":"3.1.0","info":{"title":"GrowSurf REST API","version":"2.0.0"},"tags":[{"name":"Affiliate Programs","description":"Affiliate transaction, commission, and payout operations."}],"servers":[{"url":"https://api.growsurf.com/v2","description":"Production"}],"security":[{"apiKeyAuth":[]}],"components":{"securitySchemes":{"apiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"API key","description":"GrowSurf REST API key supplied as `Authorization: Bearer `."}},"parameters":{"CampaignId":{"name":"id","in":"path","required":true,"description":"GrowSurf program ID.","schema":{"type":"string"}},"ParticipantIdOrEmail":{"name":"participantIdOrEmail","in":"path","required":true,"description":"GrowSurf participant ID or URL-encoded participant email address.","schema":{"type":"string"}}},"schemas":{"RefundTransactionRequest":{"type":"object","description":"At least one transaction identifier (externalId, transactionId, orderId, paymentId, invoiceId, paymentIntentId, or chargeId) is required to locate the original transaction. Send the same one(s) you used when recording the transaction.","properties":{"amendmentType":{"type":"string","enum":["REFUND","CHARGEBACK"],"default":"REFUND","description":"REFUND covers full refunds, partial refunds, and refund cancellations; CHARGEBACK is always a full reversal."},"amountRefunded":{"type":"integer","minimum":0,"description":"Cumulative amount refunded so far, in the currency's minor unit. Omit for a full refund. For a partial refund send the running total, not the per-refund delta."},"amount":{"type":"integer","minimum":1,"description":"Original sale gross (minor units). Optional — the value stored when the transaction was recorded is used when available; only needed for partial refunds of older records."},"refundId":{"type":"string","maxLength":500,"description":"Stable per-refund identifier. Recommended for partial refunds so repeated calls stay idempotent."},"refundStatus":{"type":"string","maxLength":500,"description":"Refund status. Send \"canceled\" with a lowered amountRefunded to restore a previously reduced commission."},"refundAmount":{"type":"integer","minimum":0,"description":"The per-refund delta (minor units). Optional bookkeeping field."},"currency":{"type":"string","minLength":3,"maxLength":3,"pattern":"^[A-Za-z]{3}$","description":"3-letter ISO currency. Optional — resolved from the original commission when available."},"externalId":{"description":"Original transaction identifier from your billing system.","type":"string","maxLength":500},"transactionId":{"description":"Original transaction identifier to match against.","type":"string","maxLength":500},"orderId":{"description":"Original order identifier to match against.","type":"string","maxLength":500},"paymentId":{"description":"Original payment identifier to match against.","type":"string","maxLength":500},"invoiceId":{"description":"Original invoice identifier to match against.","type":"string","maxLength":500},"paymentIntentId":{"description":"Original payment intent identifier to match against.","type":"string","maxLength":500},"chargeId":{"description":"Original charge identifier to match against.","type":"string","maxLength":500},"description":{"description":"Freeform amendment description shown in dashboard context and reports.","type":"string","maxLength":500}}},"RefundTransactionResponse":{"type":"object","required":["success","amendmentType","matched","reversed","adjusted","deleted","matchingCommissionIds","message"],"properties":{"success":{"type":"boolean","description":"true when the amendment was processed (including the tax-only case for already-paid commissions); false when no matching transaction was found."},"notFound":{"type":"boolean","description":"Present and true when no commission matched the provided identifiers."},"amendmentType":{"description":"Amendment type that was processed.","type":"string","enum":["REFUND","CHARGEBACK"]},"matched":{"type":"integer","description":"Number of commissions found for the provided identifiers."},"reversed":{"type":"integer","description":"Number of commissions reversed (set to zero amount)."},"adjusted":{"type":"integer","description":"Number of commissions partially adjusted."},"deleted":{"description":"Number of pending commissions deleted by the amendment.","type":"integer"},"matchingCommissionIds":{"description":"Commission IDs that matched the submitted identifiers.","type":"array","items":{"type":"string"}},"message":{"description":"Human-readable result message for the amendment.","type":"string"}}},"Error":{"type":"object","properties":{"name":{"description":"Error name returned for the failed request.","type":"string"},"code":{"description":"Stable machine-readable error code.","type":"string"},"message":{"description":"Human-readable error message.","type":"string"},"errors":{"description":"Optional validation details for specific request fields.","type":"array","items":{"type":"object","additionalProperties":true}},"status":{"description":"HTTP status code for the error.","type":"integer"},"supportUrl":{"description":"Support URL related to the error, when available.","type":"string","format":"uri"},"policyName":{"description":"Rate-limit policy name for `429` errors, when available.","type":"string"},"level":{"description":"Error severity level, when available.","type":"string"},"timestamp":{"description":"When the error response was created.","type":"string","format":"date-time"}}}},"responses":{"BadRequest":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The API key is missing, invalid, revoked, outside its scope, or not allowed to perform this action.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"UnprocessableEntity":{"description":"Request is not valid for the current program or participant state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Too many requests.","headers":{"GrowSurf-RateLimit-Second-Limit":{"description":"Number of API requests allowed per second policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Second-Remaining":{"description":"Number of API requests remaining in the second policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Second-Milliseconds":{"description":"Milliseconds until the second policy window resets.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Minute-Limit":{"description":"Number of API requests allowed per minute policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Minute-Remaining":{"description":"Number of API requests remaining in the minute policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Minute-Milliseconds":{"description":"Milliseconds until the minute policy window resets.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Hour-Limit":{"description":"Number of API requests allowed per hour policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Hour-Remaining":{"description":"Number of API requests remaining in the hour policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Hour-Milliseconds":{"description":"Milliseconds until the hour policy window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/campaign/{id}/participant/{participantIdOrEmail}/transaction/refund":{"post":{"tags":["Affiliate Programs"],"operationId":"refundTransaction","summary":"Refund or amend affiliate transaction","description":"**Affiliate programs only.** Records an amendment (refund, partial refund, refund cancellation, or chargeback) against a previously recorded transaction and reverses or adjusts the referrer's commission. The inverse of Record Affiliate Transaction. Identify the original transaction with the same identifier(s) you sent when recording it. Commissions already paid out to the affiliate are not clawed back; the amendment is recorded for tax reporting only.","parameters":[{"$ref":"#/components/parameters/CampaignId"},{"$ref":"#/components/parameters/ParticipantIdOrEmail"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RefundTransactionRequest"}}}},"responses":{"200":{"description":"Amendment result returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RefundTransactionResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"}}}}}} ``` ## List participant commissions > \*\*Affiliate programs only.\*\* Retrieves a paged list of all participant commissions in an affiliate program. ```json {"openapi":"3.1.0","info":{"title":"GrowSurf REST API","version":"2.0.0"},"tags":[{"name":"Affiliate Programs","description":"Affiliate transaction, commission, and payout operations."}],"servers":[{"url":"https://api.growsurf.com/v2","description":"Production"}],"security":[{"apiKeyAuth":[]}],"components":{"securitySchemes":{"apiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"API key","description":"GrowSurf REST API key supplied as `Authorization: Bearer `."}},"parameters":{"CampaignId":{"name":"id","in":"path","required":true,"description":"GrowSurf program ID.","schema":{"type":"string"}},"NextId":{"name":"nextId","in":"query","required":false,"description":"ID to start the next paged result set with.","schema":{"type":"string"}},"Limit100":{"name":"limit","in":"query","required":false,"description":"Number of results to return. Maximum 100.","schema":{"type":"integer","minimum":1,"maximum":100,"default":10}},"CommissionStatus":{"name":"status","in":"query","required":false,"description":"Participant commission status.","schema":{"$ref":"#/components/schemas/CommissionStatus"}}},"schemas":{"CommissionStatus":{"type":"string","enum":["PENDING","APPROVED","PAID","REVERSED","DELETED"]},"ParticipantCommissionListResponse":{"type":"object","required":["commissions","limit","nextId"],"properties":{"commissions":{"description":"Participant commissions returned for this page.","type":"array","items":{"$ref":"#/components/schemas/ParticipantCommission"}},"limit":{"description":"Maximum number of commissions requested for this page.","type":"integer"},"nextId":{"description":"Commission ID to pass as `nextId` for the next page, or `null` when there are no more results.","type":["string","null"]}}},"ParticipantCommission":{"type":"object","description":"**Affiliate programs only.** A commission generated for a (referrer) participant in an affiliate program.","required":["id","referrerId","referredId","amount","saleAmount","currencyISO","status","createdAt"],"properties":{"id":{"type":"string","readOnly":true,"description":"The unique identifier of the participant commission."},"referrerId":{"type":"string","readOnly":true,"description":"The participant ID of the referrer who earned the commission."},"referredId":{"type":"string","readOnly":true,"description":"The participant ID of the referred friend (the conversion that triggered the commission)."},"amount":{"type":["integer","null"],"readOnly":true,"description":"Commission amount (what the affiliate earned) in the currency's smallest denomination (e.g., `100` cents equals $1.00 USD, and `100` equals ¥100 for a zero-decimal currency). Always non-negative when present; `null` if it could not be computed."},"saleAmount":{"type":["integer","null"],"readOnly":true,"description":"The sale amount from the transaction the referral paid, in the currency's smallest denomination. Always non-negative when present; `null` for commissions whose provider does not report a sale amount."},"currencyISO":{"type":"string","readOnly":true,"description":"The [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code of the commission (e.g., `USD`, `GBP`)."},"status":{"$ref":"#/components/schemas/CommissionStatus","readOnly":true,"description":"Current lifecycle state of the commission."},"approvedAt":{"type":["integer","null"],"format":"int64","readOnly":true,"description":"UTC timestamp (in milliseconds) when the commission was approved. `null` until the commission transitions to `APPROVED`."},"paidAt":{"type":["integer","null"],"format":"int64","readOnly":true,"description":"UTC timestamp (in milliseconds) when the commission was sent in a payout. `null` until the commission transitions to `PAID`."},"reversedAt":{"type":["integer","null"],"format":"int64","readOnly":true,"description":"UTC timestamp (in milliseconds) when the commission was reversed (for example, due to a refund or chargeback). `null` unless the commission transitions to `REVERSED`."},"holdDuration":{"type":["integer","null"],"readOnly":true,"description":"Number of days the commission must age before it can be processed for payout. Defaults to `0` (no hold)."},"payoutQueuedAt":{"type":["integer","null"],"format":"int64","readOnly":true,"description":"UTC timestamp (in milliseconds) when the commission was queued for payout. `null` if it has not been scheduled."},"provider":{"type":["string","null"],"readOnly":true,"description":"Origin of the commission event. For example, `stripe` or `api`."},"createdAt":{"type":"integer","format":"int64","readOnly":true,"description":"UTC timestamp (in milliseconds) when the commission record was created."},"amountInCampaignCurrency":{"type":["integer","null"],"readOnly":true,"description":"Commission amount converted to the program's currency, in the currency's smallest denomination. Always non-negative. `null` if the commission is still pending FX conversion."},"saleAmountInCampaignCurrency":{"type":["integer","null"],"readOnly":true,"description":"The sale amount converted to the program's currency, in the currency's smallest denomination. Always non-negative. `null` if the commission is still pending FX conversion."},"exchangeRate":{"type":["number","null"],"readOnly":true,"description":"The currency exchange rate used for conversion. `null` if the commission is still pending FX conversion."},"campaignCurrencyISO":{"type":["string","null"],"readOnly":true,"description":"The [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code of the program used in currency conversion (e.g., `USD`, `GBP`). `null` if the commission is still pending FX conversion."},"exchangeRateAt":{"type":["integer","null"],"format":"int64","readOnly":true,"description":"UTC timestamp (in milliseconds) when the currency exchange rate was received. `null` if the commission is still pending FX conversion."},"fxError":{"type":["string","null"],"readOnly":true,"description":"If there was an error with FX conversion, the specific details. `null` if conversion was successful."}}},"Error":{"type":"object","properties":{"name":{"description":"Error name returned for the failed request.","type":"string"},"code":{"description":"Stable machine-readable error code.","type":"string"},"message":{"description":"Human-readable error message.","type":"string"},"errors":{"description":"Optional validation details for specific request fields.","type":"array","items":{"type":"object","additionalProperties":true}},"status":{"description":"HTTP status code for the error.","type":"integer"},"supportUrl":{"description":"Support URL related to the error, when available.","type":"string","format":"uri"},"policyName":{"description":"Rate-limit policy name for `429` errors, when available.","type":"string"},"level":{"description":"Error severity level, when available.","type":"string"},"timestamp":{"description":"When the error response was created.","type":"string","format":"date-time"}}}},"responses":{"BadRequest":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The API key is missing, invalid, revoked, outside its scope, or not allowed to perform this action.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"UnprocessableEntity":{"description":"Request is not valid for the current program or participant state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Too many requests.","headers":{"GrowSurf-RateLimit-Second-Limit":{"description":"Number of API requests allowed per second policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Second-Remaining":{"description":"Number of API requests remaining in the second policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Second-Milliseconds":{"description":"Milliseconds until the second policy window resets.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Minute-Limit":{"description":"Number of API requests allowed per minute policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Minute-Remaining":{"description":"Number of API requests remaining in the minute policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Minute-Milliseconds":{"description":"Milliseconds until the minute policy window resets.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Hour-Limit":{"description":"Number of API requests allowed per hour policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Hour-Remaining":{"description":"Number of API requests remaining in the hour policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Hour-Milliseconds":{"description":"Milliseconds until the hour policy window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/campaign/{id}/commissions":{"get":{"tags":["Affiliate Programs"],"operationId":"listCommissions","summary":"List participant commissions","description":"**Affiliate programs only.** Retrieves a paged list of all participant commissions in an affiliate program.","parameters":[{"$ref":"#/components/parameters/CampaignId"},{"$ref":"#/components/parameters/NextId"},{"$ref":"#/components/parameters/Limit100"},{"$ref":"#/components/parameters/CommissionStatus"}],"responses":{"200":{"description":"Participant commissions returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ParticipantCommissionListResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"}}}}}} ``` ## List commissions for a participant > \*\*Affiliate programs only.\*\* Retrieves a paged list of commissions earned by a participant. ```json {"openapi":"3.1.0","info":{"title":"GrowSurf REST API","version":"2.0.0"},"tags":[{"name":"Affiliate Programs","description":"Affiliate transaction, commission, and payout operations."}],"servers":[{"url":"https://api.growsurf.com/v2","description":"Production"}],"security":[{"apiKeyAuth":[]}],"components":{"securitySchemes":{"apiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"API key","description":"GrowSurf REST API key supplied as `Authorization: Bearer `."}},"parameters":{"CampaignId":{"name":"id","in":"path","required":true,"description":"GrowSurf program ID.","schema":{"type":"string"}},"ParticipantIdOrEmail":{"name":"participantIdOrEmail","in":"path","required":true,"description":"GrowSurf participant ID or URL-encoded participant email address.","schema":{"type":"string"}},"NextId":{"name":"nextId","in":"query","required":false,"description":"ID to start the next paged result set with.","schema":{"type":"string"}},"Limit100":{"name":"limit","in":"query","required":false,"description":"Number of results to return. Maximum 100.","schema":{"type":"integer","minimum":1,"maximum":100,"default":10}},"CommissionStatus":{"name":"status","in":"query","required":false,"description":"Participant commission status.","schema":{"$ref":"#/components/schemas/CommissionStatus"}}},"schemas":{"CommissionStatus":{"type":"string","enum":["PENDING","APPROVED","PAID","REVERSED","DELETED"]},"ParticipantCommissionListResponse":{"type":"object","required":["commissions","limit","nextId"],"properties":{"commissions":{"description":"Participant commissions returned for this page.","type":"array","items":{"$ref":"#/components/schemas/ParticipantCommission"}},"limit":{"description":"Maximum number of commissions requested for this page.","type":"integer"},"nextId":{"description":"Commission ID to pass as `nextId` for the next page, or `null` when there are no more results.","type":["string","null"]}}},"ParticipantCommission":{"type":"object","description":"**Affiliate programs only.** A commission generated for a (referrer) participant in an affiliate program.","required":["id","referrerId","referredId","amount","saleAmount","currencyISO","status","createdAt"],"properties":{"id":{"type":"string","readOnly":true,"description":"The unique identifier of the participant commission."},"referrerId":{"type":"string","readOnly":true,"description":"The participant ID of the referrer who earned the commission."},"referredId":{"type":"string","readOnly":true,"description":"The participant ID of the referred friend (the conversion that triggered the commission)."},"amount":{"type":["integer","null"],"readOnly":true,"description":"Commission amount (what the affiliate earned) in the currency's smallest denomination (e.g., `100` cents equals $1.00 USD, and `100` equals ¥100 for a zero-decimal currency). Always non-negative when present; `null` if it could not be computed."},"saleAmount":{"type":["integer","null"],"readOnly":true,"description":"The sale amount from the transaction the referral paid, in the currency's smallest denomination. Always non-negative when present; `null` for commissions whose provider does not report a sale amount."},"currencyISO":{"type":"string","readOnly":true,"description":"The [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code of the commission (e.g., `USD`, `GBP`)."},"status":{"$ref":"#/components/schemas/CommissionStatus","readOnly":true,"description":"Current lifecycle state of the commission."},"approvedAt":{"type":["integer","null"],"format":"int64","readOnly":true,"description":"UTC timestamp (in milliseconds) when the commission was approved. `null` until the commission transitions to `APPROVED`."},"paidAt":{"type":["integer","null"],"format":"int64","readOnly":true,"description":"UTC timestamp (in milliseconds) when the commission was sent in a payout. `null` until the commission transitions to `PAID`."},"reversedAt":{"type":["integer","null"],"format":"int64","readOnly":true,"description":"UTC timestamp (in milliseconds) when the commission was reversed (for example, due to a refund or chargeback). `null` unless the commission transitions to `REVERSED`."},"holdDuration":{"type":["integer","null"],"readOnly":true,"description":"Number of days the commission must age before it can be processed for payout. Defaults to `0` (no hold)."},"payoutQueuedAt":{"type":["integer","null"],"format":"int64","readOnly":true,"description":"UTC timestamp (in milliseconds) when the commission was queued for payout. `null` if it has not been scheduled."},"provider":{"type":["string","null"],"readOnly":true,"description":"Origin of the commission event. For example, `stripe` or `api`."},"createdAt":{"type":"integer","format":"int64","readOnly":true,"description":"UTC timestamp (in milliseconds) when the commission record was created."},"amountInCampaignCurrency":{"type":["integer","null"],"readOnly":true,"description":"Commission amount converted to the program's currency, in the currency's smallest denomination. Always non-negative. `null` if the commission is still pending FX conversion."},"saleAmountInCampaignCurrency":{"type":["integer","null"],"readOnly":true,"description":"The sale amount converted to the program's currency, in the currency's smallest denomination. Always non-negative. `null` if the commission is still pending FX conversion."},"exchangeRate":{"type":["number","null"],"readOnly":true,"description":"The currency exchange rate used for conversion. `null` if the commission is still pending FX conversion."},"campaignCurrencyISO":{"type":["string","null"],"readOnly":true,"description":"The [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code of the program used in currency conversion (e.g., `USD`, `GBP`). `null` if the commission is still pending FX conversion."},"exchangeRateAt":{"type":["integer","null"],"format":"int64","readOnly":true,"description":"UTC timestamp (in milliseconds) when the currency exchange rate was received. `null` if the commission is still pending FX conversion."},"fxError":{"type":["string","null"],"readOnly":true,"description":"If there was an error with FX conversion, the specific details. `null` if conversion was successful."}}},"Error":{"type":"object","properties":{"name":{"description":"Error name returned for the failed request.","type":"string"},"code":{"description":"Stable machine-readable error code.","type":"string"},"message":{"description":"Human-readable error message.","type":"string"},"errors":{"description":"Optional validation details for specific request fields.","type":"array","items":{"type":"object","additionalProperties":true}},"status":{"description":"HTTP status code for the error.","type":"integer"},"supportUrl":{"description":"Support URL related to the error, when available.","type":"string","format":"uri"},"policyName":{"description":"Rate-limit policy name for `429` errors, when available.","type":"string"},"level":{"description":"Error severity level, when available.","type":"string"},"timestamp":{"description":"When the error response was created.","type":"string","format":"date-time"}}}},"responses":{"BadRequest":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The API key is missing, invalid, revoked, outside its scope, or not allowed to perform this action.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"UnprocessableEntity":{"description":"Request is not valid for the current program or participant state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Too many requests.","headers":{"GrowSurf-RateLimit-Second-Limit":{"description":"Number of API requests allowed per second policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Second-Remaining":{"description":"Number of API requests remaining in the second policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Second-Milliseconds":{"description":"Milliseconds until the second policy window resets.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Minute-Limit":{"description":"Number of API requests allowed per minute policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Minute-Remaining":{"description":"Number of API requests remaining in the minute policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Minute-Milliseconds":{"description":"Milliseconds until the minute policy window resets.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Hour-Limit":{"description":"Number of API requests allowed per hour policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Hour-Remaining":{"description":"Number of API requests remaining in the hour policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Hour-Milliseconds":{"description":"Milliseconds until the hour policy window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/campaign/{id}/participant/{participantIdOrEmail}/commissions":{"get":{"tags":["Affiliate Programs"],"operationId":"listParticipantCommissions","summary":"List commissions for a participant","description":"**Affiliate programs only.** Retrieves a paged list of commissions earned by a participant.","parameters":[{"$ref":"#/components/parameters/CampaignId"},{"$ref":"#/components/parameters/ParticipantIdOrEmail"},{"$ref":"#/components/parameters/NextId"},{"$ref":"#/components/parameters/Limit100"},{"$ref":"#/components/parameters/CommissionStatus"}],"responses":{"200":{"description":"Participant commissions returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ParticipantCommissionListResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"}}}}}} ``` ## Approve participant commission > \*\*Affiliate programs only.\*\* Approves a pending participant commission so it can become eligible for payout. ```json {"openapi":"3.1.0","info":{"title":"GrowSurf REST API","version":"2.0.0"},"tags":[{"name":"Affiliate Programs","description":"Affiliate transaction, commission, and payout operations."}],"servers":[{"url":"https://api.growsurf.com/v2","description":"Production"}],"security":[{"apiKeyAuth":[]}],"components":{"securitySchemes":{"apiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"API key","description":"GrowSurf REST API key supplied as `Authorization: Bearer `."}},"parameters":{"CampaignId":{"name":"id","in":"path","required":true,"description":"GrowSurf program ID.","schema":{"type":"string"}},"CommissionId":{"name":"commissionId","in":"path","required":true,"description":"Participant commission ID.","schema":{"type":"string"}}},"responses":{"Success":{"description":"Success response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"BadRequest":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The API key is missing, invalid, revoked, outside its scope, or not allowed to perform this action.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InvalidState":{"description":"Resource is not in a state that permits this operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"UnprocessableEntity":{"description":"Request is not valid for the current program or participant state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Too many requests.","headers":{"GrowSurf-RateLimit-Second-Limit":{"description":"Number of API requests allowed per second policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Second-Remaining":{"description":"Number of API requests remaining in the second policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Second-Milliseconds":{"description":"Milliseconds until the second policy window resets.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Minute-Limit":{"description":"Number of API requests allowed per minute policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Minute-Remaining":{"description":"Number of API requests remaining in the minute policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Minute-Milliseconds":{"description":"Milliseconds until the minute policy window resets.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Hour-Limit":{"description":"Number of API requests allowed per hour policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Hour-Remaining":{"description":"Number of API requests remaining in the hour policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Hour-Milliseconds":{"description":"Milliseconds until the hour policy window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"SuccessResponse":{"type":"object","required":["success"],"properties":{"success":{"description":"Whether the request succeeded.","type":"boolean"}}},"Error":{"type":"object","properties":{"name":{"description":"Error name returned for the failed request.","type":"string"},"code":{"description":"Stable machine-readable error code.","type":"string"},"message":{"description":"Human-readable error message.","type":"string"},"errors":{"description":"Optional validation details for specific request fields.","type":"array","items":{"type":"object","additionalProperties":true}},"status":{"description":"HTTP status code for the error.","type":"integer"},"supportUrl":{"description":"Support URL related to the error, when available.","type":"string","format":"uri"},"policyName":{"description":"Rate-limit policy name for `429` errors, when available.","type":"string"},"level":{"description":"Error severity level, when available.","type":"string"},"timestamp":{"description":"When the error response was created.","type":"string","format":"date-time"}}}}},"paths":{"/campaign/{id}/commission/{commissionId}/approve":{"post":{"tags":["Affiliate Programs"],"operationId":"approveCommission","summary":"Approve participant commission","description":"**Affiliate programs only.** Approves a pending participant commission so it can become eligible for payout.","parameters":[{"$ref":"#/components/parameters/CampaignId"},{"$ref":"#/components/parameters/CommissionId"}],"responses":{"200":{"$ref":"#/components/responses/Success"},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"406":{"$ref":"#/components/responses/InvalidState"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"}}}}}} ``` ## Delete participant commission > \*\*Affiliate programs only.\*\* Removes a pending participant commission. ```json {"openapi":"3.1.0","info":{"title":"GrowSurf REST API","version":"2.0.0"},"tags":[{"name":"Affiliate Programs","description":"Affiliate transaction, commission, and payout operations."}],"servers":[{"url":"https://api.growsurf.com/v2","description":"Production"}],"security":[{"apiKeyAuth":[]}],"components":{"securitySchemes":{"apiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"API key","description":"GrowSurf REST API key supplied as `Authorization: Bearer `."}},"parameters":{"CampaignId":{"name":"id","in":"path","required":true,"description":"GrowSurf program ID.","schema":{"type":"string"}},"CommissionId":{"name":"commissionId","in":"path","required":true,"description":"Participant commission ID.","schema":{"type":"string"}}},"responses":{"Success":{"description":"Success response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"BadRequest":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The API key is missing, invalid, revoked, outside its scope, or not allowed to perform this action.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InvalidState":{"description":"Resource is not in a state that permits this operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"UnprocessableEntity":{"description":"Request is not valid for the current program or participant state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Too many requests.","headers":{"GrowSurf-RateLimit-Second-Limit":{"description":"Number of API requests allowed per second policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Second-Remaining":{"description":"Number of API requests remaining in the second policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Second-Milliseconds":{"description":"Milliseconds until the second policy window resets.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Minute-Limit":{"description":"Number of API requests allowed per minute policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Minute-Remaining":{"description":"Number of API requests remaining in the minute policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Minute-Milliseconds":{"description":"Milliseconds until the minute policy window resets.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Hour-Limit":{"description":"Number of API requests allowed per hour policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Hour-Remaining":{"description":"Number of API requests remaining in the hour policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Hour-Milliseconds":{"description":"Milliseconds until the hour policy window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"SuccessResponse":{"type":"object","required":["success"],"properties":{"success":{"description":"Whether the request succeeded.","type":"boolean"}}},"Error":{"type":"object","properties":{"name":{"description":"Error name returned for the failed request.","type":"string"},"code":{"description":"Stable machine-readable error code.","type":"string"},"message":{"description":"Human-readable error message.","type":"string"},"errors":{"description":"Optional validation details for specific request fields.","type":"array","items":{"type":"object","additionalProperties":true}},"status":{"description":"HTTP status code for the error.","type":"integer"},"supportUrl":{"description":"Support URL related to the error, when available.","type":"string","format":"uri"},"policyName":{"description":"Rate-limit policy name for `429` errors, when available.","type":"string"},"level":{"description":"Error severity level, when available.","type":"string"},"timestamp":{"description":"When the error response was created.","type":"string","format":"date-time"}}}}},"paths":{"/campaign/{id}/commission/{commissionId}":{"delete":{"tags":["Affiliate Programs"],"operationId":"deleteCommission","summary":"Delete participant commission","description":"**Affiliate programs only.** Removes a pending participant commission.","parameters":[{"$ref":"#/components/parameters/CampaignId"},{"$ref":"#/components/parameters/CommissionId"}],"responses":{"200":{"$ref":"#/components/responses/Success"},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"406":{"$ref":"#/components/responses/InvalidState"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"}}}}}} ``` ## List participant payouts > \*\*Affiliate programs only.\*\* Retrieves a paged list of all participant payouts in an affiliate program. ```json {"openapi":"3.1.0","info":{"title":"GrowSurf REST API","version":"2.0.0"},"tags":[{"name":"Affiliate Programs","description":"Affiliate transaction, commission, and payout operations."}],"servers":[{"url":"https://api.growsurf.com/v2","description":"Production"}],"security":[{"apiKeyAuth":[]}],"components":{"securitySchemes":{"apiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"API key","description":"GrowSurf REST API key supplied as `Authorization: Bearer `."}},"parameters":{"CampaignId":{"name":"id","in":"path","required":true,"description":"GrowSurf program ID.","schema":{"type":"string"}},"NextId":{"name":"nextId","in":"query","required":false,"description":"ID to start the next paged result set with.","schema":{"type":"string"}},"Limit100":{"name":"limit","in":"query","required":false,"description":"Number of results to return. Maximum 100.","schema":{"type":"integer","minimum":1,"maximum":100,"default":10}},"PayoutStatus":{"name":"status","in":"query","required":false,"description":"Participant payout status.","schema":{"$ref":"#/components/schemas/PayoutStatus"}}},"schemas":{"PayoutStatus":{"type":"string","enum":["UPCOMING","QUEUED","ISSUED","FAILED"]},"ParticipantPayoutListResponse":{"type":"object","required":["payouts","limit","nextId"],"properties":{"payouts":{"description":"Participant payouts returned for this page.","type":"array","items":{"$ref":"#/components/schemas/ParticipantPayout"}},"limit":{"description":"Maximum number of payouts requested for this page.","type":"integer"},"nextId":{"description":"Payout ID to pass as `nextId` for the next page, or `null` when there are no more results.","type":["string","null"]}}},"ParticipantPayout":{"type":"object","description":"**Affiliate programs only.** A payout generated for a participant in an affiliate program. All payouts start with a status of `UPCOMING`, which represents an aggregation of the participant's `ParticipantCommission` amounts, and is adjusted in real time as commissions change.","required":["id","participantId","commissionIds","amount","currencyISO","status","createdAt"],"properties":{"id":{"type":"string","readOnly":true,"description":"The unique identifier of the participant payout."},"participantId":{"type":"string","readOnly":true,"description":"The participant ID of the referrer who earned the payout."},"commissionIds":{"type":"array","readOnly":true,"items":{"type":"string"},"description":"The IDs of the associated `ParticipantCommission`s."},"amount":{"type":"integer","readOnly":true,"description":"Payout amount in the currency's smallest denomination (e.g., `100` cents equals $1.00 USD, and `100` equals ¥100 for a zero-decimal currency). Always non-negative."},"currencyISO":{"type":"string","readOnly":true,"description":"The [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code of the payout (e.g., `USD`, `GBP`)."},"status":{"$ref":"#/components/schemas/PayoutStatus","readOnly":true,"description":"Current lifecycle state of the payout."},"createdAt":{"type":"integer","format":"int64","readOnly":true,"description":"UTC timestamp (in milliseconds) when the payout record was created."},"queuedAt":{"type":["integer","null"],"format":"int64","readOnly":true,"description":"UTC timestamp (in milliseconds) when the payout was queued for processing (status `QUEUED`). `null` until the payout is queued."},"issuedAt":{"type":["integer","null"],"format":"int64","readOnly":true,"description":"UTC timestamp (in milliseconds) when the payout was issued. `null` if the payout was not successfully issued."},"failedAt":{"type":["integer","null"],"format":"int64","readOnly":true,"description":"UTC timestamp (in milliseconds) when the payout failed to be issued. `null` if the payout did not fail to be issued."},"provider":{"type":["string","null"],"readOnly":true,"description":"The payment provider used to issue the payout (e.g., `paypal`). `null` for payouts with a status of `UPCOMING`."},"amountInCampaignCurrency":{"type":["integer","null"],"readOnly":true,"description":"Payout amount converted to the program's currency, in the currency's smallest denomination. Always non-negative. `null` if the payout status is `UPCOMING` or if it is still pending FX conversion."},"campaignCurrencyISO":{"type":["string","null"],"readOnly":true,"description":"The [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code of the program used in currency conversion (e.g., `USD`, `GBP`). `null` if the payout status is `UPCOMING` or if it is still pending FX conversion."},"exchangeRateAt":{"type":["integer","null"],"format":"int64","readOnly":true,"description":"UTC timestamp (in milliseconds) when the currency exchange rate was received. `null` if the payout status is `UPCOMING` or if it is still pending FX conversion."},"exchangeRate":{"type":["number","null"],"readOnly":true,"description":"The currency exchange rate used for conversion. `null` if the payout status is `UPCOMING` or if it is still pending FX conversion."},"fxError":{"type":["string","null"],"readOnly":true,"description":"If there was an error with FX conversion, the specific details. `null` if the payout status is `UPCOMING` or if the FX conversion was successful."}}},"Error":{"type":"object","properties":{"name":{"description":"Error name returned for the failed request.","type":"string"},"code":{"description":"Stable machine-readable error code.","type":"string"},"message":{"description":"Human-readable error message.","type":"string"},"errors":{"description":"Optional validation details for specific request fields.","type":"array","items":{"type":"object","additionalProperties":true}},"status":{"description":"HTTP status code for the error.","type":"integer"},"supportUrl":{"description":"Support URL related to the error, when available.","type":"string","format":"uri"},"policyName":{"description":"Rate-limit policy name for `429` errors, when available.","type":"string"},"level":{"description":"Error severity level, when available.","type":"string"},"timestamp":{"description":"When the error response was created.","type":"string","format":"date-time"}}}},"responses":{"BadRequest":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The API key is missing, invalid, revoked, outside its scope, or not allowed to perform this action.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"UnprocessableEntity":{"description":"Request is not valid for the current program or participant state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Too many requests.","headers":{"GrowSurf-RateLimit-Second-Limit":{"description":"Number of API requests allowed per second policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Second-Remaining":{"description":"Number of API requests remaining in the second policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Second-Milliseconds":{"description":"Milliseconds until the second policy window resets.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Minute-Limit":{"description":"Number of API requests allowed per minute policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Minute-Remaining":{"description":"Number of API requests remaining in the minute policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Minute-Milliseconds":{"description":"Milliseconds until the minute policy window resets.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Hour-Limit":{"description":"Number of API requests allowed per hour policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Hour-Remaining":{"description":"Number of API requests remaining in the hour policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Hour-Milliseconds":{"description":"Milliseconds until the hour policy window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/campaign/{id}/payouts":{"get":{"tags":["Affiliate Programs"],"operationId":"listPayouts","summary":"List participant payouts","description":"**Affiliate programs only.** Retrieves a paged list of all participant payouts in an affiliate program.","parameters":[{"$ref":"#/components/parameters/CampaignId"},{"$ref":"#/components/parameters/NextId"},{"$ref":"#/components/parameters/Limit100"},{"$ref":"#/components/parameters/PayoutStatus"}],"responses":{"200":{"description":"Participant payouts returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ParticipantPayoutListResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"}}}}}} ``` ## List payouts for a participant > \*\*Affiliate programs only.\*\* Retrieves a paged list of payouts that belong to a participant. ```json {"openapi":"3.1.0","info":{"title":"GrowSurf REST API","version":"2.0.0"},"tags":[{"name":"Affiliate Programs","description":"Affiliate transaction, commission, and payout operations."}],"servers":[{"url":"https://api.growsurf.com/v2","description":"Production"}],"security":[{"apiKeyAuth":[]}],"components":{"securitySchemes":{"apiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"API key","description":"GrowSurf REST API key supplied as `Authorization: Bearer `."}},"parameters":{"CampaignId":{"name":"id","in":"path","required":true,"description":"GrowSurf program ID.","schema":{"type":"string"}},"ParticipantIdOrEmail":{"name":"participantIdOrEmail","in":"path","required":true,"description":"GrowSurf participant ID or URL-encoded participant email address.","schema":{"type":"string"}},"NextId":{"name":"nextId","in":"query","required":false,"description":"ID to start the next paged result set with.","schema":{"type":"string"}},"Limit100":{"name":"limit","in":"query","required":false,"description":"Number of results to return. Maximum 100.","schema":{"type":"integer","minimum":1,"maximum":100,"default":10}},"PayoutStatus":{"name":"status","in":"query","required":false,"description":"Participant payout status.","schema":{"$ref":"#/components/schemas/PayoutStatus"}}},"schemas":{"PayoutStatus":{"type":"string","enum":["UPCOMING","QUEUED","ISSUED","FAILED"]},"ParticipantPayoutListResponse":{"type":"object","required":["payouts","limit","nextId"],"properties":{"payouts":{"description":"Participant payouts returned for this page.","type":"array","items":{"$ref":"#/components/schemas/ParticipantPayout"}},"limit":{"description":"Maximum number of payouts requested for this page.","type":"integer"},"nextId":{"description":"Payout ID to pass as `nextId` for the next page, or `null` when there are no more results.","type":["string","null"]}}},"ParticipantPayout":{"type":"object","description":"**Affiliate programs only.** A payout generated for a participant in an affiliate program. All payouts start with a status of `UPCOMING`, which represents an aggregation of the participant's `ParticipantCommission` amounts, and is adjusted in real time as commissions change.","required":["id","participantId","commissionIds","amount","currencyISO","status","createdAt"],"properties":{"id":{"type":"string","readOnly":true,"description":"The unique identifier of the participant payout."},"participantId":{"type":"string","readOnly":true,"description":"The participant ID of the referrer who earned the payout."},"commissionIds":{"type":"array","readOnly":true,"items":{"type":"string"},"description":"The IDs of the associated `ParticipantCommission`s."},"amount":{"type":"integer","readOnly":true,"description":"Payout amount in the currency's smallest denomination (e.g., `100` cents equals $1.00 USD, and `100` equals ¥100 for a zero-decimal currency). Always non-negative."},"currencyISO":{"type":"string","readOnly":true,"description":"The [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code of the payout (e.g., `USD`, `GBP`)."},"status":{"$ref":"#/components/schemas/PayoutStatus","readOnly":true,"description":"Current lifecycle state of the payout."},"createdAt":{"type":"integer","format":"int64","readOnly":true,"description":"UTC timestamp (in milliseconds) when the payout record was created."},"queuedAt":{"type":["integer","null"],"format":"int64","readOnly":true,"description":"UTC timestamp (in milliseconds) when the payout was queued for processing (status `QUEUED`). `null` until the payout is queued."},"issuedAt":{"type":["integer","null"],"format":"int64","readOnly":true,"description":"UTC timestamp (in milliseconds) when the payout was issued. `null` if the payout was not successfully issued."},"failedAt":{"type":["integer","null"],"format":"int64","readOnly":true,"description":"UTC timestamp (in milliseconds) when the payout failed to be issued. `null` if the payout did not fail to be issued."},"provider":{"type":["string","null"],"readOnly":true,"description":"The payment provider used to issue the payout (e.g., `paypal`). `null` for payouts with a status of `UPCOMING`."},"amountInCampaignCurrency":{"type":["integer","null"],"readOnly":true,"description":"Payout amount converted to the program's currency, in the currency's smallest denomination. Always non-negative. `null` if the payout status is `UPCOMING` or if it is still pending FX conversion."},"campaignCurrencyISO":{"type":["string","null"],"readOnly":true,"description":"The [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code of the program used in currency conversion (e.g., `USD`, `GBP`). `null` if the payout status is `UPCOMING` or if it is still pending FX conversion."},"exchangeRateAt":{"type":["integer","null"],"format":"int64","readOnly":true,"description":"UTC timestamp (in milliseconds) when the currency exchange rate was received. `null` if the payout status is `UPCOMING` or if it is still pending FX conversion."},"exchangeRate":{"type":["number","null"],"readOnly":true,"description":"The currency exchange rate used for conversion. `null` if the payout status is `UPCOMING` or if it is still pending FX conversion."},"fxError":{"type":["string","null"],"readOnly":true,"description":"If there was an error with FX conversion, the specific details. `null` if the payout status is `UPCOMING` or if the FX conversion was successful."}}},"Error":{"type":"object","properties":{"name":{"description":"Error name returned for the failed request.","type":"string"},"code":{"description":"Stable machine-readable error code.","type":"string"},"message":{"description":"Human-readable error message.","type":"string"},"errors":{"description":"Optional validation details for specific request fields.","type":"array","items":{"type":"object","additionalProperties":true}},"status":{"description":"HTTP status code for the error.","type":"integer"},"supportUrl":{"description":"Support URL related to the error, when available.","type":"string","format":"uri"},"policyName":{"description":"Rate-limit policy name for `429` errors, when available.","type":"string"},"level":{"description":"Error severity level, when available.","type":"string"},"timestamp":{"description":"When the error response was created.","type":"string","format":"date-time"}}}},"responses":{"BadRequest":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The API key is missing, invalid, revoked, outside its scope, or not allowed to perform this action.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"UnprocessableEntity":{"description":"Request is not valid for the current program or participant state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Too many requests.","headers":{"GrowSurf-RateLimit-Second-Limit":{"description":"Number of API requests allowed per second policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Second-Remaining":{"description":"Number of API requests remaining in the second policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Second-Milliseconds":{"description":"Milliseconds until the second policy window resets.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Minute-Limit":{"description":"Number of API requests allowed per minute policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Minute-Remaining":{"description":"Number of API requests remaining in the minute policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Minute-Milliseconds":{"description":"Milliseconds until the minute policy window resets.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Hour-Limit":{"description":"Number of API requests allowed per hour policy.","schema":{"type":"integer"}},"GrowSurf-RateLimit-Hour-Remaining":{"description":"Number of API requests remaining in the hour policy.","schema":{"type":"integer"}},"GrowSurf-Retry-After-Hour-Milliseconds":{"description":"Milliseconds until the hour policy window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/campaign/{id}/participant/{participantIdOrEmail}/payouts":{"get":{"tags":["Affiliate Programs"],"operationId":"listParticipantPayouts","summary":"List payouts for a participant","description":"**Affiliate programs only.** Retrieves a paged list of payouts that belong to a participant.","parameters":[{"$ref":"#/components/parameters/CampaignId"},{"$ref":"#/components/parameters/ParticipantIdOrEmail"},{"$ref":"#/components/parameters/NextId"},{"$ref":"#/components/parameters/Limit100"},{"$ref":"#/components/parameters/PayoutStatus"}],"responses":{"200":{"description":"Participant payouts returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ParticipantPayoutListResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"}}}}}} ``` # API Guidelines Follow these standard guidelines when interacting with GrowSurf APIs. Requests * All requests should be made using HTTPS. * JSON objects are recommended for POST requests, but standard parameters are accepted. * All parameters are required unless otherwise specified. ## Responses * Data is returned in JSON. * Any non-`200` HTTP response code can be considered an error. {% hint style="info" %} **Tip:** Refer to [Response Codes](/developer-tools/rest-api/api-response-codes) for help in troubleshooting any errors. {% endhint %} ## Rate Limits All API requests made to GrowSurf (including client and server calls) are appropriately rate-limited to prevent excessive requests. If you exceed those limits, you will start receiving 429 error responses for any API calls that you make. Those 429 responses will have the following format. API keys and OAuth connections for the same team share the team's aggregate rate limits. Creating more credentials does not increase the team's total request capacity. ```javascript { "name": "RateLimit", "code": "RATE_LIMIT", "message": "You have reached your minute limit.", "status": 429, "supportUrl": "https://growsurf.com/settings#contact_support", "policyName": "MINUTE", "level": "error", "timestamp": "2019-12-08T00:05:45.478Z" } ``` The `message` and `policyName` will indicate which limit you hit (e.g. second, minute, or hour). ### Rate Headers {% hint style="info" %} **NOTE:** These headers are only included for requests made using an API key. {% endhint %} | Header | Description | | ---------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **`GrowSurf-RateLimit-Second-Limit`** | The number of API requests that are allowed per second. | | **`GrowSurf-RateLimit-Second-Remaining`** | The number of API requests remaining within the second policy. | | **`GrowSurf-Retry-After-Second-Milliseconds`** |

The window of time that the GrowSurf-RateLimit-Second-Limit and Growsurf-RateLimit-Second-Remaining headers apply to.

For example, a value of 1000 would be a window of 1 second.

This value is only provided if the second policy is hit or exceeded.

| | **`GrowSurf-RateLimit-Minute-Limit`** | The number of API requests that are allowed per minute. | | **`GrowSurf-RateLimit-Minute-Remaining`** | The number of API requests remaining within the minute policy. | | **`GrowSurf-Retry-After-Minute-Milliseconds`** |

The window of time that the GrowSurf-RateLimit-Minute-Limit and Growsurf-RateLimit-Minute-Remaining headers apply to.

For example, a value of 10000 would be a window of 10 seconds.

This value is only provided if the minute policy is hit or exceeded.

| | **`GrowSurf-RateLimit-Hour-Limit`** | The number of API requests that are allowed per hour. | | **`GrowSurf-RateLimit-Hour-Remaining`** | The number of API requests remaining within the hour policy. | | **`GrowSurf-Retry-After-Hour-Milliseconds`** |

The window of time that the GrowSurf-RateLimit-Hour-Limit and Growsurf-RateLimit-Hour-Remaining headers apply to.

For example, a value of 600000 would be a window of 10 minutes.

This value is only provided if the hour policy is hit or exceeded.

| ### Policies The following are the rate limits for all API requests made using an API key. | Policy | Limit | | ---------- | ----------------------- | | **Second** | 50 requests / 5 seconds | | **Minute** | 400 requests / minute | | **Hour** | 20,000 requests / hour | ### Slowdown Rate For operations which update a resource (`PUT`, `POST`, `DELETE`), if the cumulative rate of requests exceed 60 requests per minute, a slowdown delay will be added to each request thereafter. The delay is equal to the number of exceeded requests multiplied by 100 milliseconds (ms). **For example:** * 61st request: 100ms delay * 63rd request: 300ms delay * 70th request: 1000ms delay ### Max Connections In addition to the rate limits and slowdown rate, the number of concurrent connections to the REST API allowed per IP address is limited to three (3). Please note that if you hit a rate limit or max connection limit, you will see a [`429` error](https://docs.growsurf.com/api-response-codes#glossary). ### Suggestions Here are some suggestions for using the GrowSurf API within policy limits. #### 1. Cache data for repeat calls If your site or app uses data from GrowSurf on each page load, that data should be cached and loaded from that cache instead of being requested from the GrowSurf APIs each time. If you're making repeated requests to get participant information or program data for a custom implementation, the information from those calls should also be cached when possible. #### 2. Use Webhooks to get updated data from GrowSurf Webhooks are an excellent way for your application to receive updated information from GrowSurf without needing to call GrowSurf APIs. More details about using Webhooks can be found [here](/developer-tools/webhooks), with example data [here](https://docs.growsurf.com/developer-tools/webhooks/examples). ## Metadata Certain GrowSurf objects, such as [`Participants`](/developer-tools/rest-api/api-objects#participant) and [`Rewards`](/developer-tools/rest-api/api-objects#reward) can have a special `metadata`parameter, which is useful for storing any custom information. Learn more here: {% content-ref url="/pages/KdcA4HSS8K9pL0VdjLEP" %} [Metadata](/developer-tools/metadata) {% endcontent-ref %} # API Response Codes Refer to the below response code glossary to help you troubleshoot any errors. ## Glossary | **Response Code** | **Messages** | **Explanation** | | -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `200 OK` | The request was successful! | N/A | | `400 Bad Request` | Request validation failed on an input. |

Check that your inputs are entered correctly.

Note that participant lookups return a 400 (not a 404) when no participant exists for the given ID or email, and emailing a participant returns a 400 if they have unsubscribed.

| | `402 Usage Limit` | Usage limit exceeded. | You've reached a plan limit (such as your participant usage limit, or your plan's program limit when creating a program) and will need to upgrade to the next tier. | | `402 Payment Method Required` | You must add a payment method to your account to use the REST API for affiliate programs. | N/A | | `403 Not Authorized` |

You are not allowed to perform that action.

Or no valid participant access token provided.

Your API key may be missing, revoked, contain a typo, lack the required scope, or be limited to different programs. You may also be trying to access a program outside the team or program list assigned to the API key.

Verify that your API key has the required scope and program access. To create or change keys in Settings, use an owner, Admin, or teammate with Manage API access.

| | `403 Paid Plan Required` | A paid plan is required to use the GrowSurf REST API | A paid plan is required to use the REST API with referral programs. For affiliate programs, a payment method on file is required instead (see `402 Payment Method Required`). | | `403 Email Not Verified` | The team owner email address must be verified to use this endpoint. Check the owner inbox, or resend it via `POST /v2/team/owner/verification-email`. | Program and resource endpoints remain locked until the owner verifies the email address. Check the team's GrowSurf verification state with `GET /v2/team`. | | `403 Account Disabled` | This account has been disabled. | The team bound to the API key has been disabled. Please [contact support](https://app.growsurf.com/#contact_support) if you believe this is a mistake. | | `404 Resource Not Found` | The requested resource does not exist. | You may be trying to request a resource that does not exist or was deleted. | | `406 Invalid State` | The resource is not in a state that permits this operation. | The resource cannot be changed from its current state — for example, approving or fulfilling a participant reward that has already been fulfilled, or approving a commission that has already been paid out. | | `409 Conflict Duplicate Request` | Conflicting duplicate request. |

An identical request is already in progress — wait for it to complete before retrying.

When creating an account, a 409 means an account with this email already exists.

| | `422 Unprocessable Entity Error` | This endpoint is only available for referral programs. Your program is an affiliate program. | You may be trying to call an endpoint that is only valid to referral programs (or vice versa with affiliate programs). | | `422 Participant Blocked` | Participant was detected as a high-risk fraudster and was blocked from joining. |

The person may be a high-risk fraudster, and has been blocked from entering the program. Learn more about how GrowSurf's anti-fraud system works.

Please check that your program's anti-fraud settings are not set to Strict, or that you do not have the email or IP address blacklisted.

| | `429 Too Many Requests` | You have reached a rate limit. |

You have sent too many requests in a given time. Some operations (such as creating accounts or sending participant emails) have their own stricter limits.

See Rate Limits and Max Connections for more details on rate limits.

| | `5XX Internal Server Error` | The GrowSurf server is inaccessible or offline -- that's our fault! Check for updates on our [status page](https://growsurf.com/status). | N/A | # API Libraries Official GrowSurf API libraries for popular languages like TypeScript, Python, PHP, Ruby, and Java. The following official API libraries provide convenient access to the [GrowSurf REST API](https://docs.growsurf.com/developer-tools/rest-api). {% hint style="info" %} These libraries are for server-side REST API integrations. For native mobile apps, use the [iOS SDK](/developer-tools/ios-sdk) or [Android SDK](/developer-tools/android-sdk) instead. {% endhint %} Click on a library's *Installation* link to get started. | Language | Library | Get Started | | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------ | ---------------------------------------------------------------------------- | |

**TypeScript** | [`growsurf-typescript`](https://github.com/growsurf/growsurf-typescript) | [Installation](https://github.com/growsurf/growsurf-typescript#installation) | |

**Python** | [`growsurf-python`](https://github.com/growsurf/growsurf-python) | [Installation](https://github.com/growsurf/growsurf-python#installation) | |

**PHP** | [`growsurf-php`](https://github.com/growsurf/growsurf-php) | [Installation](https://github.com/growsurf/growsurf-php#installation) | |

**Ruby** | [`growsurf-ruby`](https://github.com/growsurf/growsurf-ruby) | [Installation](https://github.com/growsurf/growsurf-ruby#installation) | |

**Java** | [`growsurf-java`](https://github.com/growsurf/growsurf-java) | [Installation](https://github.com/growsurf/growsurf-java#installation) | # Webhooks Webhooks send data to your server when important events occur in your referral/affiliate program. This lets you automatically fulfill rewards or update users in your database. {% hint style="info" %} If you're using an AI tool such as Cursor, Codex, Claude Code, or Antigravity to help you implement GrowSurf, we recommend utilizing our [MCP server](https://docs.growsurf.com/build-with-ai). {% endhint %} ## Example scenarios Here are a few scenarios in which you would use webhooks: * If you have an internal points system, webhooks allow you to add credits to users in your database whenever a referral occurs. * When a new participant joins your referral or affiliate program, webhooks let you store their unique referral link (along with other participant details) in your database. ## Getting started ### Step 1: Add a webhook URL to your program 1. Go to the *Options* step in the *Program Editor*. 2. In the *Set up integrations* section*,* click the *Webhooks* card. Then enter your webhook endpoint URL. 3. Publish/save your changes.

Webhooks can be configured in the Options step in the Program Editor

{% hint style="info" %} **Tips:** * You can test your webhook URL to see if it is set up properly and/or to see the different types of data from each webhook event. Simply click the *Test* button right next to the webhook URL input field. * You can select the specific events to receive within the *advanced webhook settings* section. * A total of 5 webhooks can be added per program. {% endhint %} ## **Retry logic** If we are unable to deliver a webhook the first time, GrowSurf will attempt to redeliver your webhooks for several days with an exponential back off. After several days of failed attempts we will mark the webhook as undeliverable and it will no longer be retried. Webhook events are stored durably, so if delivery is ever interrupted, they will be retried once service is restored. You can always check our [System Status page](https://growsurf.com/status) for webhook health. ## **Next steps** View [Examples](/developer-tools/webhooks/examples) of implementing webhooks, or view what the request payloads for webhook events look like: * [When a participant reaches a reward goal](/developer-tools/webhooks/events-reference#participant_reached_a_goal) * [When a new participant is added to the program](https://docs.growsurf.com/developer-tools/webhooks/events-reference#new_participant_added) * [When the program ends](https://docs.growsurf.com/developer-tools/webhooks/events-reference#campaign_ended) # Securing Your Webhooks (optional) This is an optional step. For security purposes, you can add a webhook secret to limit requests sent to your webhook endpoint to those only coming from GrowSurf. ## Adding a secret 1. Go to the *Options* step in the *Program Editor*. 2. In the Webhooks integration, click *Show advanced webhook settings* and enter the secret (it can be any string of text). 3. Publish/save your changes. ![](/files/-M3vdyAlJ0GLVsKTKcLy) {% hint style="info" %} Once your program has a webhook secret, a signature `GrowSurf-Signature` will be included in the header of all outgoing requests to your webhook endpoint. {% endhint %} ## Validating payloads When your secret token has been set, GrowSurf uses it to create a hash signature to include in the header of each event notification payload.\ \ The signature hash is passed along with each request in the header as `GrowSurf-Signature`. You will need to compute a hash once the payload is received and compare it against the `GrowSurf-Signature` value provided by GrowSurf within the header. Those steps are outlined below. {% hint style="info" %} The `GrowSurf-Signature` header contains a timestamp and a signature hash value. The timestamp is prefixed by `ts=`, and the signature value is prefixed by `v=`. {% endhint %} ### **Step 1: Extract the timestamp and signature from the header** Split the header using the `,` character as the separator to get a list of elements. Then split each element using the `=` character as the separator to get a key/value pair.\ \ The value for key/prefix `ts` corresponds to the timestamp and the `v` key/prefix corresponds to the signature you will use to compare your generated hash against. {% hint style="info" %} NOTE: `ts` is a Unix timestamp in milliseconds {% endhint %} ### **Step 2: Prepare the signed payload string for comparison** Achieve this by concatenating: * The timestamp (as a string). AKA the value of `ts` * The character `.` * The actual JSON payload within the request body ### **Step 3: Determine the expected signature** Compute an *HMAC* with a `SHA256` hash function. Use the endpoint's signing secret token as the key (which you added in the *Options* step in the *Program Editor*), and use the signed payload string from **Step 2** as the message. ### **Step 4: Compare signatures** Compare the GrowSurf provided signature within the header to the expected signature. If they match then compute the difference between a current timestamp and the received timestamp `ts`. Then decide if the difference is within your tolerance. {% hint style="info" %} **Tip:** The timestamp comparison is completely optional but it will help to protect against timing attacks. {% endhint %} ## View an example [View an example here](/developer-tools/webhooks/examples#example-1-webhooks-with-secret) # Examples How to implement Webhooks for your GrowSurf program. ## Example 1: Webhooks Below is a **Node.js + Express** example of what the code for your webhook endpoint could look like: ```javascript //Your webhooks payload endpoint app.post("/your/webhook/payload-url", function(req, res) { const body = req.body; try { if (body.event === 'PARTICIPANT_REACHED_A_GOAL') { // Write code here to do something when a participant wins a reward console.log(`${body.data.participant.email} just won this reward: ${body.data.reward.description}`); // If the reward is approved if (body.data && body.data.reward && body.data.reward.approved) { // Do something } // If this is a double-sided reward, use body.data.reward.isReferrer to determine if this is for the referrer or referred person if (body.data && body.data.reward && body.data.reward.isReferrer) { // Do something // Optional: If you set metadata on the CampaignReward object, you can reference it: if (body.data.reward.metadata && body.data.reward.metadata["proRewardValue"]) { console.log(`${body.data.participant.email} earned an amount of ${body.data.reward.metadata["proRewardValue"]}.`); } } // Optional: If this is the referrer that unlocked the reward, you can get the details of the person that they referred if (body.data.reward.isReferrer && body.data.participant.referee) { console.log(`${body.data.participant.referee.email} was the person referred by ${body.data.participant.email}.`); } } else if (body.event === 'NEW_PARTICIPANT_ADDED') { // Write code here to do something when a new participant is added console.log(`${body.data.email} just joined via source: ${body.data.referralSource}.`); } else if (body.event === 'CAMPAIGN_ENDED') { // Write code here to do something when a program ends console.log(`${body.data.name} just ended with ${body.data.referralCount} total referrals!`); } } catch (err) { res.status(400).end(); } res.json({received: true}); }); ``` {% hint style="info" %} **Helpful tips:** * To see the different sample data from webhook request payloads, see [Events](/developer-tools/webhooks/events-reference) * If you reference [reward metadata](https://docs.growsurf.com/developer-tools/webhooks/events-reference#campaign_ended) in your *New Participant Reward* events, your marketing team can update these values anytime in the future from the Program Editor without getting developers involved. {% endhint %} ## Example 2: Webhooks (with secret) Below is a **Node.js + Express** example (using the [crypto-js](https://github.com/brix/crypto-js) library) of what the code for your webhook endpoint could look like: ```javascript //Your webhooks payload endpoint app.post("/your/webhook/payload-url", function(req, res) { const body = req.body; const signature = req.get("GrowSurf-Signature"); try { // Validate the signature validateSignature(body, signature); // Do work!..... // Write your code in here... } catch (err) { res.status(400).end(); } res.json({received: true}); }); /** * Compares the GrowSurf header provided signature against the expected * signature. * * @param {Object} body the request body provided by GrowSurf * @param {String} signature the signature hash value provided within the header of the request * @returns {Boolean} valid true if the expected matches the given * @throws {Exception} thrown if the expected signature value does not match the given */ const validateSignature = function(body, signature) { // Extract let parts = signature.split(","); // t value let timestamp = parts[0].split("=")[1]; // v value let hash = parts[1].split("=")[1]; // Generate hash let message = (timestamp + "." + JSON.stringify(body)); let expected = CryptoJS.HmacSHA256(message, "YOUR-SECRET-TOKEN").toString(); // Validate/Compare if(expected === hash) { return true; } else { throw new Error("Invalid Signature"); } } ``` # Events Reference Below are sample request payloads you will receive based on the webhook event types you have selected for your program. ## Overview * **`PARTICIPANT_REACHED_A_GOAL`** - Referral programs only. When a participant unlocks a new reward. * **`NEW_PARTICIPANT_ADDED`** - When a new participant is added to the program (includes direct signups, referrals, and participants added/imported via admin dashboard). * **`PARTICIPANT_FRAUD_STATUS_UPDATED`** - When an existing participant's fraud status changes. * **`NEW_COMMISSION_ADDED`** - Affiliate programs only. When a new commission is generated for an affiliate. * **`COMMISSION_ADJUSTED`** - Affiliate programs only. When an existing commission is adjusted (refunds, chargebacks, or refund cancellations). * **`NEW_PAYOUT_ISSUED`** - Affiliate programs only. When a payout is successfully issued to an affiliate. * **`CAMPAIGN_ENDED`** - When the program ends. *** ## `PARTICIPANT_REACHED_A_GOAL` Referral programs only **Description:** When a participant unlocks a new reward. {% hint style="info" %} **Important notes:** * **For double-sided rewards,** **two events will be sent for both referrer and referee**. To discern between the two, use the `data.reward.isReferrer` property (the referrer will have `isReferrer` as `true`). * You can confirm this by examining `data.reward.referrerId` and `data.reward.referredId` and comparing it with `data.participant.id`. * If the reward is for the referrer, you can view the person they referred by accessing `data.participant.referee`. * If the reward is for the referred friend, you can view the person who referred them by accessing `data.participant.referrer`. * **If you have manual reward approval enabled for your program, events will be sent twice: (1) when the reward is pending approval and (2) when the reward is approved.** To discern between unapproved/approved rewards, use the `data.reward.approved` property (approved rewards will have `approved` as `true`). * The `data.reward` object contains combined data from the [`CampaignReward`](https://docs.growsurf.com/developer-tools/rest-api/api-objects#reward) and [`ParticipantReward`](https://docs.growsurf.com/developer-tools/rest-api/api-objects#reward). * `data.reward.rewardId` represents the ID of the `CampaignReward` and will always be the same. You can find this ID from *Program Editor > 1. Rewards* and clicking the reward. * `data.reward.id` represents the ID of the `ParticipantReward` that was unlocked for the participant. This will be different for every new reward that the participant earns. You can find this ID by going to your admin dashboard and viewing the participant's rewards. {% endhint %} Here is an example event of a `PARTICIPANT_REACHED_A_GOAL` event where the reward is for the referrer because `data.reward.isReferrer` is `true`. The person they referred is reflected in `data.participant.referee`. If this reward was for the referred person, then `data.reward.isReferrer` would be `false`. And the person that referred them would be accessible from `data.participant.referrer`. ```json { "event": "PARTICIPANT_REACHED_A_GOAL", "createdAt": 1558345202613, "data": { "participant": { "id": "x9a7uu", "email": "richard@piedpiper.com", "firstName": "Richard", "lastName": "Hendricks", "notes": "", "isWinner": true, "referralCount": 11, "monthlyReferralCount": 8, "prevMonthlyReferralCount": 0, "vanityKeys": [], "shareUrl": "http://piedpiper.com?grsf=x9a7uu", "impressionCount": 309, "uniqueImpressionCount": 285, "shareCount": 163, "createdAt": 1554431962667, "referralSource": "DIRECT", "fraudRiskLevel": "LOW", "fraudReasonCode": "UNIQUE_IDENTITY", "metadata": { "piedPiperUserId": "12a39-8aajd-1dwiq", "companyName": "Pied Piper, Inc", "teamSize": "1-10" }, "unsubscribed": false, "referee": { "id": "uxjbxu", "createdAt": 1738485195346, "email": "i_was_referred@somesite.com", "firstName": "Billy", "lastName": "Smith", "notes": "", "isWinner": false, "referralCount": 0, "monthlyReferralCount": 0, "prevMonthlyReferralCount": 0, "vanityKeys": [], "shareUrl": "http://piedpiper.com?grsf=uxjbxu", "referralSource": "PARTICIPANT", "fraudRiskLevel": "LOW", "fraudReasonCode": "UNIQUE_IDENTITY", "impressionCount": 0, "uniqueImpressionCount": 0, "shareCount": 0, "metadata": {}, "unsubscribed": false } }, "reward": { "approved": true, "conversionsRequired": 1, "couponCode": "PROMO_20_OFF", "createdAt": 1542560101404, "approvedAt": 1659474941892, "fulfilledAt": null, "description": "Win a free t-shirt when you refer a friend to sign up to Pied Piper!", "imageUrl": "https://example.com/reward-image.png", "limit": 3, "title": "Early-Bird Reward", "isReferrer": true, "type": "SINGLE_SIDED", "rewardId": "crew_xlj123", "id": "prew_ccm2ue", "referredId": "ad3dfa", "referrerId": "x9a7uu", "metadata": { "foo": "bar", "amount": "$25", "points": 1000 } }, "campaign": { "id": "ct8f71", "name": "Middle Out Compression Campaign", "type": "REFERRAL", "currencyISO": "USD", "rewards": [ { "title": "Early-Bird Reward", "id": "crew_xlj123", "type": "SINGLE_SIDED", "description": "Win a free t-shirt when you refer a friend to sign up to Pied Piper!", "referralDescription": null, "isActive": true, "isVisible": true, "isUnlimited": true, "limit": 3, "limitDuration": "IN_TOTAL", "conversionsRequired": 1, "numberOfWinners": 3, "imageUrl": "https://example.com/reward-image.png", "order": null, "couponCode": "PROMO_20_OFF", "nextMilestonePrefix": "You are only", "nextMilestoneSuffix": "referrals away from receiving a nice reward!", "metadata": { "foo": "bar", "amount": "$25", "points": 1000 } } ] } } } ``` *** ## `NEW_PARTICIPANT_ADDED` **Description:** When a new participant is added to the program (includes direct signups, referrals, and participants added/imported via admin dashboard). Here is an example event of a `NEW_PARTICIPANT_ADDED` event where the newly added participant was referred. The person that referred them is reflected in `data.referrer`. If the participant was not referred, then `data.referrer` will not exist. ```json { "event": "NEW_PARTICIPANT_ADDED", "createdAt": 1558345215720, "data": { "id": "p88y0a", "email": "gavin.belson@hooli.com", "firstName": "Gavin", "lastName": "Belson", "notes": "This is obviously our competitor trying out our product!", "isWinner": false, "shareUrl": "http://piedpiper.com?grsf=p88y0a", "referralCount": 0, "monthlyReferralCount": 0, "prevMonthlyReferralCount": 0, "vanityKeys": [], "impressionCount": 0, "uniqueImpressionCount": 0, "shareCount": 3, "createdAt": 1554479231190, "referralSource": "PARTICIPANT", "fraudRiskLevel": "LOW", "fraudReasonCode": "UNIQUE_IDENTITY", "referredBy": "x9a7uu", "referrer": { "id": "x9a7uu", "email": "richard@piedpiper.com", "firstName": "Richard", "lastName": "Hendricks", "notes": "", "isWinner": true, "referralCount": 11, "monthlyReferralCount": 8, "prevMonthlyReferralCount": 0, "vanityKeys": [], "shareUrl": "http://piedpiper.com?grsf=x9a7uu", "impressionCount": 309, "uniqueImpressionCount": 285, "shareCount": 163, "createdAt": 1554431962667, "referralSource": "PARTICIPANT", "fraudRiskLevel": "LOW", "fraudReasonCode": "UNIQUE_IDENTITY", "metadata": { "piedPiperUserId": "12a39-8aajd-1dwiq", "companyName": "Pied Piper, Inc", "teamSize": "1-10" }, "unsubscribed": false }, "metadata": { "piedPiperUserId": "au71p-121x9-88faa", "companyName": "Hooli, Inc", "teamSize": "10,000+" }, "unsubscribed": false, "campaign": { "id": "ct8f71", "name": "Middle Out Compression Campaign", "type": "REFERRAL", "currencyISO": "USD", "rewards": [ { "title": "Early-Bird Reward", "id": "crew_xlj123", "type": "SINGLE_SIDED", "description": "Win a free t-shirt when you refer a friend to sign up to Pied Piper!", "referralDescription": null, "isActive": true, "isVisible": true, "isUnlimited": true, "limit": 3, "limitDuration": "IN_TOTAL", "conversionsRequired": 1, "numberOfWinners": 3, "imageUrl": "https://example.com/reward-image.png", "order": null, "couponCode": "PROMO_20_OFF", "nextMilestonePrefix": "You are only", "nextMilestoneSuffix": "referrals away from receiving a nice reward!", "metadata": { "foo": "bar", "amount": "$25", "points": 1000 } } ] } } } ``` *** ## `NEW_COMMISSION_ADDED` Affiliate programs only **Description:** When a new commission is generated for an affiliate. ```json { "event": "NEW_COMMISSION_ADDED", "createdAt": 1558345215720, "data": { "participant": { "id": "p88y0a", "email": "gavin.belson@hooli.com", "firstName": "Gavin", "lastName": "Belson", "notes": "", "isWinner": false, "shareUrl": "http://piedpiper.com?grsf=p88y0a", "referralCount": 1, "monthlyReferralCount": 0, "prevMonthlyReferralCount": 0, "vanityKeys": [], "impressionCount": 2, "uniqueImpressionCount": 2, "shareCount": 3, "createdAt": 1554479231190, "referralSource": "DIRECT", "fraudRiskLevel": "LOW", "metadata": {}, "unsubscribed": false }, "referredParticipant": { "id": "xh345d", "email": "dinesh@piedpiper.com", "firstName": "Dinesh", "lastName": "Chugtai", "notes": "", "isWinner": false, "shareUrl": "http://piedpiper.com?grsf=xh345d", "referralCount": 0, "monthlyReferralCount": 0, "prevMonthlyReferralCount": 0, "vanityKeys": [], "impressionCount": 0, "uniqueImpressionCount": 0, "shareCount": 0, "createdAt": 1554479231190, "referralSource": "PARTICIPANT", "fraudRiskLevel": "LOW", "metadata": {}, "unsubscribed": false }, "campaign": { "id": "ct8f71", "name": "Middle Out Compression Campaign", "type": "AFFILIATE", "currencyISO": "USD", "rewards": [] }, "commission": { "id": "comm_jp1ku7", "referrerId": "p88y0a", "referredId": "xh345d", "amount": 2500, "currencyISO": "USD", "saleAmount": 10000, "status": "APPROVED", "createdAt": 1731494175123, "approvedAt": 1731580575123, "paidAt": null, "reversedAt": null, "payoutQueuedAt": null, "holdDuration": 7, "provider": "stripe", "amountInCampaignCurrency": 2500, "saleAmountInCampaignCurrency": 10000, "campaignCurrencyISO": "USD", "exchangeRateAt": 1731494175123, "fxError": null } } } ``` *** ## `COMMISSION_ADJUSTED` Affiliate programs only **Description:** When an existing commission is adjusted (refunds, chargebacks, or refund cancellations). ```json { "event": "COMMISSION_ADJUSTED", "createdAt": 1558345215720, "data": { "participant": { "id": "p88y0a", "email": "gavin.belson@hooli.com", "firstName": "Gavin", "lastName": "Belson", "notes": "", "isWinner": false, "shareUrl": "http://piedpiper.com?grsf=p88y0a", "referralCount": 1, "monthlyReferralCount": 0, "prevMonthlyReferralCount": 0, "vanityKeys": [], "impressionCount": 2, "uniqueImpressionCount": 2, "shareCount": 3, "createdAt": 1554479231190, "referralSource": "DIRECT", "fraudRiskLevel": "LOW", "metadata": {}, "unsubscribed": false }, "referredParticipant": { "id": "xh345d", "email": "dinesh@piedpiper.com", "firstName": "Dinesh", "lastName": "Chugtai", "notes": "", "isWinner": false, "shareUrl": "http://piedpiper.com?grsf=xh345d", "referralCount": 0, "monthlyReferralCount": 0, "prevMonthlyReferralCount": 0, "vanityKeys": [], "impressionCount": 0, "uniqueImpressionCount": 0, "shareCount": 0, "createdAt": 1554479231190, "referralSource": "PARTICIPANT", "fraudRiskLevel": "LOW", "metadata": {}, "unsubscribed": false }, "campaign": { "id": "ct8f71", "name": "Middle Out Compression Campaign", "type": "AFFILIATE", "currencyISO": "USD", "rewards": [] }, "adjustment": { "currencyISO": "USD", "originalCommissionAmount": 9900, "newCommissionAmount": 0, "commissionAdjustedAmount": -9900, "reason": "FULL_REFUND", "adjustedAt": 1766393352171 }, "adjustedCommission": { "id": "comm_jp1ku7", "referrerId": "p88y0a", "referredId": "xh345d", "amount": 2500, "currencyISO": "USD", "saleAmount": 10000, "status": "PENDING", "createdAt": 1731494175123, "approvedAt": null, "paidAt": null, "reversedAt": null, "payoutQueuedAt": null, "holdDuration": 14, "provider": "stripe", "amountInCampaignCurrency": 2500, "saleAmountInCampaignCurrency": 10000, "campaignCurrencyISO": "USD", "exchangeRateAt": 1731494175123, "fxError": null } } } ``` *** ## `NEW_PAYOUT_ISSUED` Affiliate programs only **Description:** When a payout is successfully issued to an affiliate. ```json { "event": "NEW_PAYOUT_ISSUED", "createdAt": 1558345215720, "data": { "participant": { "id": "p88y0a", "email": "gavin.belson@hooli.com", "firstName": "Gavin", "lastName": "Belson", "notes": "", "isWinner": false, "shareUrl": "http://piedpiper.com?grsf=p88y0a", "referralCount": 1, "monthlyReferralCount": 0, "prevMonthlyReferralCount": 0, "vanityKeys": [], "impressionCount": 2, "uniqueImpressionCount": 2, "shareCount": 3, "createdAt": 1554479231190, "referralSource": "DIRECT", "fraudRiskLevel": "LOW", "metadata": {}, "unsubscribed": false }, "campaign": { "id": "ct8f71", "name": "Middle Out Compression Campaign", "type": "AFFILIATE", "currencyISO": "USD", "rewards": [] }, "payout": { "id": "po_k11ps9", "participantId": "p88y0a", "commissionIds": [ "comm_jp1ku7", "comm_a98s7z" ], "amount": 3600, "currencyISO": "USD", "status": "ISSUED", "createdAt": 1731494295334, "issuedAt": 1731580575123, "failedAt": null, "provider": "paypal", "amountInCampaignCurrency": 3600, "campaignCurrencyISO": "USD", "exchangeRateAt": 1731580575217, "exchangeRate": 1.0, "fxError": null } } } ``` *** ## `PARTICIPANT_FRAUD_STATUS_UPDATED` **Description:** When an existing participant's fraud status changes. This webhook event is emitted if either of the following happens: * If you manually mark a participant as a fraudster or non-fraudster from the GrowSurf admin dashboard. [Learn more here](https://support.growsurf.com/article/195-what-does-the-growsurf-anti-fraud-system-entail). * If GrowSurf's anti-fraud system automatically identifies a referrer as a fraudster after they tried referring someone. Here is an example of a `PARTICIPANT_FRAUD_STATUS_UPDATED` event where you can check the participant's fraud status via `data.participant.fraudRiskLevel` (it will be one of the following options: `"LOW"`, `"MEDIUM"`, or `"HIGH"`). You can also check the fraud reason code via `data.participant.fraudReasonCode` (see the [`Participant`](https://docs.growsurf.com/developer-tools/rest-api/api-objects#participant) object for all fraud reason code options). ```json { "event": "PARTICIPANT_FRAUD_STATUS_UPDATED", "createdAt": 1558345215720, "data": { "participant": { "id": "p88y0a", "email": "gavin.belson@hooli.com", "firstName": "Gavin", "lastName": "Belson", "notes": "This is obviously our competitor trying out our product!", "isWinner": false, "shareUrl": "http://piedpiper.com?grsf=p88y0a", "referralCount": 0, "monthlyReferralCount": 0, "prevMonthlyReferralCount": 0, "vanityKeys": [], "impressionCount": 0, "uniqueImpressionCount": 0, "shareCount": 3, "createdAt": 1554479231190, "referralSource": "PARTICIPANT", "fraudRiskLevel": "HIGH", "fraudReasonCode": "REFERRAL_CHAIN_FRAUD", "referredBy": "x9a7uu", "referrer": { "id": "x9a7uu", "email": "richard@piedpiper.com", "firstName": "Richard", "lastName": "Hendricks", "notes": "", "isWinner": true, "referralCount": 11, "monthlyReferralCount": 8, "prevMonthlyReferralCount": 0, "vanityKeys": [], "shareUrl": "http://piedpiper.com?grsf=x9a7uu", "impressionCount": 309, "uniqueImpressionCount": 285, "shareCount": 163, "createdAt": 1554431962667, "referralSource": "PARTICIPANT", "fraudRiskLevel": "LOW", "fraudReasonCode": "UNIQUE_IDENTITY", "metadata": { "piedPiperUserId": "12a39-8aajd-1dwiq", "companyName": "Pied Piper, Inc", "teamSize": "1-10" }, "unsubscribed": false }, "metadata": { "piedPiperUserId": "au71p-121x9-88faa", "companyName": "Hooli, Inc", "teamSize": "10,000+" }, "unsubscribed": false }, "campaign": { "id": "ct8f71", "name": "Middle Out Compression Campaign", "type": "REFERRAL", "currencyISO": "USD", "rewards": [ { "title": "Early-Bird Reward", "id": "crew_xlj123", "type": "SINGLE_SIDED", "description": "Win a free t-shirt when you refer a friend to sign up to Pied Piper!", "referralDescription": null, "isActive": true, "isVisible": true, "isUnlimited": true, "limit": 3, "limitDuration": "IN_TOTAL", "conversionsRequired": 1, "numberOfWinners": 3, "imageUrl": "https://example.com/reward-image.png", "order": null, "couponCode": "PROMO_20_OFF", "nextMilestonePrefix": "You are only", "nextMilestoneSuffix": "referrals away from receiving a nice reward!", "metadata": { "foo": "bar", "amount": "$25", "points": 1000 } } ] } } } ``` *** ## `CAMPAIGN_ENDED` **Description:** When the program ends. {% hint style="info" %} **Please note:** Only the first 1,000 will be returned in the `winners` Array. {% endhint %} ```json { "event": "CAMPAIGN_ENDED", "createdAt": 1558345152138, "data": { "id": "ct8f71", "name": "Middle-Out Compression Launch", "type": "REFERRAL", "participantCount": 5661, "startedAt": 1522432573250, "endedAt": 1533532422153, "status": "COMPLETE", "impressionCount": 11075, "referralCount": 1673, "winnerCount": 1673, "winners": [ { "id": "x9a7uu", "email": "richard@piedpiper.com", "firstName": "Richard", "lastName": "Hendricks", "notes": "", "isWinner": true, "referralCount": 11, "monthlyReferralCount": 8, "prevMonthlyReferralCount": 0, "vanityKeys": [], "shareUrl": "http://piedpiper.com?grsf=x9a7uu", "impressionCount": 309, "uniqueImpressionCount": 285, "shareCount": 163, "createdAt": 1554431962667, "referralSource": "PARTICIPANT", "fraudRiskLevel": "LOW", "fraudReasonCode": "UNIQUE_IDENTITY", "metadata": { "piedPiperUserId": "12a39-8aajd-1dwiq", "companyName": "Pied Piper, Inc", "teamSize": "1-10" }, "unsubscribed": false } ], "rewards": [ { "title": "Early-Bird Reward", "id": "crew_xlj123", "type": "SINGLE_SIDED", "description": "Win a free t-shirt when you refer a friend to sign up to Pied Piper!", "referralDescription": null, "isActive": true, "isVisible": true, "isUnlimited": true, "limit": 3, "limitDuration": "IN_TOTAL", "conversionsRequired": 1, "numberOfWinners": 3, "imageUrl": "https://example.com/reward-image.png", "order": null, "couponCode": "PROMO_20_OFF", "nextMilestonePrefix": "You are only", "nextMilestoneSuffix": "referrals away from receiving a nice reward!", "metadata": { "foo": "bar", "amount": "$25", "points": 1000 } } ] } } ``` # Metadata Use metadata to save any custom data to Participants and Rewards to make your referral program even more dynamic. Certain GrowSurf objects, such as [`Participants`](https://docs.growsurf.com/developer-tools/rest-api/api-objects#participant) and [`Rewards`](https://docs.growsurf.com/developer-tools/rest-api/api-objects#reward) can have a special `metadata` parameter, which is useful for storing any custom information. ## Use Cases Here are some examples of how you could use `metadata`: * Issue different reward values to participants based on their different `metadata` properties. [Learn more here](https://support.growsurf.com/article/357-how-to-set-up-dynamic-rewards). * If you need to save custom data to a participant to display or use later in your own application. * Attach custom key/value data to rewards in your program to retrieve later via the REST API when automating a reward via Webhooks or Zapier. *** ## Overview ### **Participant metadata** * Can be set via the program editor, admin dashboard, REST API, JavaScript Web API, and embeddable elements * Can be retrieved via REST API and is available via Webhooks * Can be viewed from your admin dashboard and when you download your participants list ### **Reward metadata** * Can be set via the program editor * Can be retrieved via JavaScript, REST API and is available via Webhooks * Can be used in pre-populated social share and invite messages, and within GrowSurf emails *** ## Participant metadata ### Setting participant metadata There are several different ways to save metadata to a participant. #### **Program Editor** **For referred participants**: From *Program Editor > 5. Installation*, navigate to the automagic form detection setup section (the page with the title "*Choose forms from your site or web app to automatically track.*"). This form is for tracking referred people who came to your website through their friend's unique referral link. Select a form and choose the input fields to save with each form submission. Any custom field that is not "Email", "First Name", or "Last Name" will be saved as metadata.

Choose the fields you want to save as metadata for referred participants

**For referrers (your users/customers):** From *Program Editor > 2. Design*, you can update the Signup Form with custom fields. This signup form is intended for your users/customers who sign up to your referral program in order to refer their friends. When a participant submits a new task from your referral portal, they will need to submit the custom fields as well, which will be saved as participant metadata.

Update the Signup Form in the campaign editor

When a participant signs up for the first time on your referral portal (or from the Embedded Signup Form), custom fields will be saved as metadata

#### **Admin Dashboard** When you are viewing a participant from the GrowSurf admin dashboard, you can add or update their metadata.

Update a participant in the admin dashboard

#### **REST API** You can use these REST API endpoints to add or update a participant's metadata: **For adding new participants:** * [`/POST Add Participant`](https://docs.growsurf.com/developer-tools/rest-api/api-reference#post-campaign-id-participant) **For updating existing participants:** * [`/POST Update Participant`](https://docs.growsurf.com/developer-tools/rest-api/api-reference#post-campaign-id-participant-participantidoremail) #### **JavaScript SDK** You can use the JavaScript method [`growsurf.addParticipant()`](https://docs.growsurf.com/developer-tools/javascript-sdk/api-reference#post-campaign-id-participant) to add metadata to a participant. Any keys other than `email`, `firstName`, and `lastName` will be saved as metadata. Metadata will only be set for new participants. **Example**: ```javascript growsurf.addParticipant({ email: 'gavin@hooli.com', company: 'Hooli', subscriptionPlan: 'businessPlan' }).then(participant => { // handle participant }); ``` {% hint style="warning" %} **Note**: Participant metadata cannot be updated using the JavaScript SDK. You must use the REST API to update metadata for existing participants. {% endhint %} #### **Embeddable Elements** You can pass in custom participant values into any [Embeddable Element](https://docs.growsurf.com/developer-tools/embeddable-elements) using the `data-grsf-metadata` attribute. Metadata will only be set for new participants. **Example**: ```html

``` {% hint style="warning" %} **Note**: Participant metadata cannot be updated using embeddable elements. You must use the REST API to update metadata for existing participants. {% endhint %} ### Using participant metadata #### REST API You can use these REST API endpoints to retrieve a participant's metadata: * [`/GET Participant`](https://docs.growsurf.com/developer-tools/rest-api/api-reference#get-campaign-id-participant-participantidoremail) #### Webhooks Participant metadata is returned on all participant payloads in [Webhook events](https://docs.growsurf.com/developer-tools/webhooks/events-reference). *** ## Reward metadata ### Setting reward metadata There is only one way to update reward metadata, from *Program Editor > 1. Rewards*.

Add/edit reward metadata from the program editor

### Using reward metadata You can then reference this reward metadata in different places of the Program Editor for UI purposes. For example, metadata will be available as an option by clicking the "+ Personalize" dropdown in social sharing, invites, and emails. #### JavaScript If you are using the JavaScript SDK, you can also retrieve reward metadata by calling [`growsurf.getCampaign()`](https://docs.growsurf.com/developer-tools/javascript-sdk/api-reference#get-campaign). This is useful for displaying any custom reward details in your UI. #### Webhooks Reward metadata is returned on all `campaign` payloads in [Webhook events](https://docs.growsurf.com/developer-tools/webhooks/events-reference). You can reference metadata when automating rewards using webhooks. This is useful so that your marketing team can make changes anytime to reward values in the future without getting developers involved. *** ### Tutorial View the following guide to help you add reward metadata and reference it throughout participant-facing elements of your GrowSurf program.

Guide to implementing reward metadata

#### 1. Add metadata to a reward * Go to *Campaign Editor > 1. Rewards* and click the Continue button. * Open the reward you want to edit. * Click "Advanced reward settings" and scroll to the Metadata section. * Click "Add Metadata", and enter `rewardForReferrer` for the key, and `50` for the value. * Click "Add Metadata" again, and enter `rewardForReferred` for the key, and `50` for the value.

*** #### 2. Update campaign design * Go to *Campaign Editor > 3. Design*. * Here are the sections you'll want to update with reward metadata: * **Header Content** * **Share (Social & Email Invites)** * **Referred Friend Motivators** **(Welcome Banner and Inline Welcome Message)** * For each element in the sections above, click the "+ Personalize" button underneath each input field, and from the dropdown select the reward metadata you added from step 1 above. See the images below as examples. **Header Content**

To explain this first example: The text `Sign up for Subank and receive ${{campaignReward['p6k82i']['rewardForReferrer']}}!` will be rendered as `Sign up for Subank and receive $50!`. **Share**

After you add reward metadata to a share message, see how it renders by clicking on the corresponding share button in the live preview section of the campaign editor. **Referred Friend Motivators**

To explain this example, the `{{referrerName}} invited you to join Subank! Sign up today and get ${{campaignReward['p6k82i']['rewardForReferred']}}!` will be rendered as `Gavin B invited you to join Subank! Sign up today and get $50!`. *** #### 3. Update campaign emails * Go to *Campaign Editor > 3. Emails*. * Open the "New Participant Reward" email. * In the Email Body section, type in the following: `{{isReferrer ? ("You've just earned a $" + campaignReward["p6k82i"]["rewardForReferrer"] + " gift card for referring a friend!") : ("You just got a $" + campaignReward["p6k82i"]["rewardForReferred"] + " gift card for activating your account and making your first purchase!") }}` * Preview the changes on the right-side section to make sure everything is rendering properly. * For referrers, the text would render like this: `You've just earned a $50 gift card for referring a friend!`. * For referred friends, the text would render like this: `You just got a $50 gift card for activating your account and making your first purchase!` * Repeat the above steps for all emails that you want to reference reward metadata in. * Note: For other emails, you can simply click the "+ Personalize" button to insert reward metadata. The "New Participant Reward" email is the only special email type to use the `{{isReferrer ? ... : ... }}` syntax for in order to account for when emails are sent to both referrers and referred friends (when the reward won is a double-sided reward).

*** #### 4. Final review and testing Make sure to thoroughly [test your campaign](https://support.growsurf.com/article/209-best-practices-for-testing-your-campaign) by signing up as both the referrer and a referred friend to ensure the reward metadata displays correctly in different elements.

## Policies The following are the policies when creating or updating metadata. | Policy | Limit | | ----------------------- | ---------------- | | **Metadata Key** | 40 characters | | **Metadata Value** | 500 characters | | **Total Metadata Keys** | 50 keys / object | | **Key Characters** | Alphanumeric | {% hint style="info" %} **Note the following:** * All metadata keys will be converted to camelCase. For example, if you provide a key "My Metadata Key" that key will be converted to `myMetadataKey`. * **Important:** Do not store any sensitive information (personally identifiable information, such as credit cards and social security numbers) as metadata within GrowSurf, as metadata rewards are accessible from the JavaScript SDK. {% endhint %} # ActiveCampaign Update ActiveCampaign contacts with their unique share link and referrer information. ## Sync with your ActiveCampaign List **Step 1:** In *Campaign Editor > 4. Options > Integrations*, open the ActiveCampaign integration card and enter your ActiveCampaign API URL and key ([click here to get your ActiveCampaign API URL and key](https://help.activecampaign.com/hc/en-us/articles/207317590-Getting-started-with-the-API#how-to-obtain-your-activecampaign-api-url-and-key)). {% hint style="info" %} IMPORTANT: Because the GrowSurf data sync to ActiveCampaign only occurs *after* you have connected with the integration, it is imperative to connect with the integration *BEFORE* importing participants.\ \ [Click here](https://support.growsurf.com/article/385-how-can-i-sync-my-growsurf-participants-to-my-esp) to see remedy options if you have already imported participants into your campaign but would like to sync their GrowSurf data to ActiveCampaign. {% endhint %} ![](/files/-MKcOKKEaAydJgcpXcgu) **Step 2:** Once connected, choose the ActiveCampaign list that you want to automatically sync to. GrowSurf will add/update your ActiveCampaign contacts every time a new participant is added or referred to your referral campaign. **Step 3:** Save changes. You should now see a screen that looks like the one below: ![](/files/-MKcOKKKYqZ7EKbLwPC7) **Step 4:** Open your ActiveCampaign account, and go to *Lists > Manage Fields.* For each GrowSurf custom field that you want available for ActiveCampaign contacts, you will need to manually click the edit icon next to each GrowSurf field (see screenshot below): ![](/files/-MUyRGjw2pamQ1XSnM8z) Then in the *Customize the Field Options* window, check the same ActiveCampaign list that you selected in the GrowSurf campaign editor. ![](/files/-MKetPi8z4pnjKu9H00E) For more help in editing custom contact fields, please see ActiveCampaign's help article [*How do I edit a custom contact field?*](https://help.activecampaign.com/hc/en-us/articles/115001623804-How-do-I-edit-a-custom-contact-field-)*.* ## Examples [View our ActiveCampaign tutorials](https://docs.growsurf.com/additional-integrations/activecampaign/tutorials) to see different kinds of examples that you can copy/paste into your email templates. ## **Contact Fields** GrowSurf will automatically create these new contact fields for your ActiveCampaign Contacts. To use them, you'll first need to [follow step #4 in the instructions above](https://docs.growsurf.com/integrations/activecampaign#sync-with-your-activecampaign-list). | **Field Name** | **Personalization Tag** | **Type** | **Description** | **Example** | | ---------------------------------------- | ---------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- | | **GrowSurf Share URL** | `%GROWSURF_SHARE_URL%` | TEXT | The participant's unique referral link | | | **GrowSurf Participant ID** | `%GROWSURF_PARTICIPANT_ID%` | TEXT | The participant's unique GrowSurf ID | abc123 | | **GrowSurf Referral Status** | `%GROWSURF_REFERRAL_STATUS_ID%` | TEXT | The referral status of the participant\* | CREDIT\_PENDING | | **GrowSurf Participant First Name** | `%GROWSURF_PARTICIPANT_FIRST_NAME%` | TEXT | The participant's first name | Bob | | **GrowSurf Participant Last Name** | `%GROWSURF_PARTICIPANT_LAST_NAME%` | TEXT | The participant's last name | Loblaw | | **GrowSurf Referrer First Name** | `%GROWSURF_REFERRER_FIRST_NAME%` | TEXT | The first name of the participant's referrer (if applicable) | Gavin | | **GrowSurf Referrer Last Name** | `%GROWSURF_REFERRER_LAST_NAME%` | TEXT | The last name of the participant's referrer (if applicable) | Belson | | **GrowSurf Referrer Email** | `%GROWSURF_REFERRER_EMAIL%` | TEXT | The email address of the participant's referrer (if applicable) | | | **GrowSurf Total Referral Count** | `%GROWSURF_TOTAL_REFERRAL_COUNT%` | NUMBER | The participant's all-time referral count | 0 | | **GrowSurf Monthly Referral Count** | `%GROWSURF_MONTHLY_REFERRAL_COUNT%` | NUMBER | The participant's current month referral count | 19 | | **GrowSurf Prev Monthly Referral Count** | `%GROWSURF_PREV_MONTHLY_REFERRAL_COUNT%` | NUMBER | The participant's previous month referral count | 200 | | **GrowSurf Next Milestone** | `%GROWSURF_NEXT_MILESTONE%` | TEXT | The text for the next/upcoming milestone reward (only applies to milestone rewards. [See](https://docs.growsurf.com/developer-tools/embeddable-elements#embedded-next-milestone) an example here) | You are only 2 referrals away from winning a free t-shirt! | | **GrowSurf Next Monthly Milestone** | `%GROWSURF_NEXT_MONTHLY_MILESTONE%` | TEXT | The text for the next/upcoming monthly milestone reward (only applies to milestone rewards. [See an example here](https://docs.growsurf.com/developer-tools/embeddable-elements#embedded-next-milestone)) | You are only 2 referrals away from winning a free t-shirt! | | **GrowSurf Total Invite Count** | `%GROWSURF_TOTAL_INVITE_COUNT%` | NUMBER | The participant's all-time invite count | 112 | | **GrowSurf Total Impression Count** | `%GROWSURF_TOTAL_IMPRESSION_COUNT%` | NUMBER | The participant's all-time impression count | 150 | \**GrowSurf Referral Status* can be the following: `CREDIT_PENDING` (This participant must still trigger a referral for their referrer to receive referral credit), `CREDIT_AWARDED` (This participant triggered a referral and their referrer received referral credit), `CREDIT_EXPIRED` (This participant did not trigger the referral credit within the referral credit expiration window so their referrer did not receive referral credit). You can use these personalization tags in your ActiveCampaign email templates. Whether you launch a new marketing campaign or have an automated drip campaign going on, make sure to always include `%GROWSURF_SHARE_URL%` in your emails to provoke your subscribers to make referrals! [Learn more about ActiveCampaign personalization tags here.](https://help.activecampaign.com/hc/en-us/articles/220709307-Personalization-Tags#how-personalization-tags-work) ## **Troubleshooting Tips** * **If the new participant isn't being added to ActiveCampaign, or if they are being added but their unique referral link isn't being synced to ActiveCampaign:** * Activity logs will denote if a participant was added to ActiveCampaign or if they were failed to be added. (In the case of failure, GrowSurf will re-attempt to add them for 7 days). * **If custom contact fields are not showing up for an ActiveCampaign contact:** * You will need to make sure to explicitly make them available for your ActiveCampaign list in order to show up. [Please reference step #4 in the instructions above](https://docs.growsurf.com/integrations/activecampaign#sync-with-your-activecampaign-list). * **If a GrowSurf custom field personalization tag is showing up as red when sending out an email**: * You will need to make sure to explicitly make the custom field available for your ActiveCampaign list in order to use it as a personalization tag in your emails. [Please reference step #4 in the instructions above](https://docs.growsurf.com/integrations/activecampaign#sync-with-your-activecampaign-list). [
](https://docs.growsurf.com/additional-integrations/mailchimp) # Tutorials We'll walk you through adding personalized referral program messaging to your ActiveCampaign emails. When you connect your GrowSurf campaign to ActiveCampaign, you can easily embed a referral program into your ActiveCampaign emails. Check out the examples below, each with ready-made code snippets that you can copy/paste and customize to your liking. ## Example 1 Display a static image in your email. ### What it looks like ![](/files/6rWCZf0i1y23UfO0zQIS) ### Copy/paste this HTML code into your ActiveCampaign email ```markup


Refer your friends, boost your savings Get $10 for every friend you refer to PrismJar with your personal referral link: %GROWSURF_SHARE_URL% Send to Email Post to Facebook Send by Twitter

Refer your friends, boost your savings

Get $10 for every friend you refer to PrismJar with your personal referral link: %GROWSURF_SHARE_URL%

Send to Email Post to Facebook Send by Twitter

``` ### **Customize the contents** 1. At line 4, replace [`https://growsurf-blog.s3.us-west-2.amazonaws.com/illustrations/GrowSurf-steps-2.png`](https://growsurf-blog.s3.us-west-2.amazonaws.com/illustrations/GrowSurf-steps-2.png) with your own image. 2. At line 11 replace `PrismJar` with your own brand name. 3. At line 12, replace `#1673df` with your own brand color. 4. At line 15, replace the text `%GROWSURF_SHARE_URL%%0AJoin%20PrismJar%20and%20we%20both%20get%20$10%20` with your own. 1. Make sure to encode the message using a tool like [https://www.url-encode-decode.com](https://www.url-encode-decode.com/) 2. Make sure to include `%GROWSURF_SHARE_URL%` only to the encoded message 5. At line 17, replace the text `Join%20PrismJar%20and%20we%20both%20get%20$5%20` with your own 1. Make sure to encode the message using a tool like [https://www.url-encode-decode.com](https://www.url-encode-decode.com/) ## Example 2 Display a static image in your email. ### What it looks like ![](/files/44NZyBJ9kXBfEgyXqQTW) ### Copy/paste this HTML code into your ActiveCampaign email ```markup

Get $10 in bonus credits when you refer a friend

The more friends you refer, the more money you make.

Get $10

``` ### **Customize the contents** 1. At line 4, replace [`https://growsurf-blog.s3.us-west-2.amazonaws.com/email-examples/Gift0002.png`](https://growsurf-blog.s3.us-west-2.amazonaws.com/email-examples/Gift0002.png) with your own image. 2. At line 15, replace `#e87b3c` with your own brand color. 3. At line 15, replace `YOUR_CAMPAIGN_ID` with your GrowSurf campaign ID (e.g, `p9josq`) 1. If you set up a custom domain for your GrowSurf Referral Portal, replace the entire `https://grow.surf/YOUR_CAMPAIGN_ID` instead with your Referral Portal URL (e.g, `https://refer.yourwebsite.com`). ## Example 3 Display static images in email. ### What it looks like ![](/files/gio8ujYq18DoA8cagDBc) ### Copy/paste this HTML code into your ActiveCampaign email ```markup

Get $10 when you refer a friend

Love Cointech? Spread the excitement by referring friends and you'll both get $10.

Refer Friends

It's easy to get rewarded

Refer friends to Cointech and we'll give you both $10 in account credits for every friend who makes their first deposit.

Spread the word

Go to your Cointech page to get your unique referral link and share it via text, email, or social media

You'll get $10

Receive $10 for each friend your refer that makes their first deposit

Your friends get $10

Each friend you refer also gets $10 in account credits. Everyone wins!

Refer Friends

``` ### **Customize the contents** 1. At line 5, replace all instances of `Cointech` with your own brand name. 2. At lines 6, 21, 30, 39, and 47, replace `#4f46e5` with your own brand color. 3. At lines 6 and 47, replace `YOUR_CAMPAIGN_ID` with your GrowSurf campaign ID (e.g, `p9josq`) 1. If you set up a custom domain for your GrowSurf Referral Portal, replace the entire `https://grow.surf/YOUR_CAMPAIGN_ID` instead with your Referral Portal URL (e.g, `https://refer.yourwebsite.com`). ## Example 4 Display a static image in your email. ### What it looks like ![](/files/Q40o1cOVt3Eecl09eRG6) ### Copy/paste this HTML code into your ActiveCampaign email ```markup

Give $200, Get $200

Did you know you can get $200 when you refer LearnEd to a friend?

Simply share your unique referral link with your friends/family and we'll give both of you a $200 gift card for everyone who enrolls into a LearnEd program! It's a win-win for all.

Refer Friends

``` ### **Customize the contents** 1. At line 5, replace `LearnEd` with your own brand name. 2. At line 10, replace [`https://d1pnnwteuly8z3.cloudfront.net/images/b90d3589-b2f5-4e75-bf91-c0fba9e89952/507b3cec-5435-499f-96d7-46c5a4d6d79f.svg`](https://d1pnnwteuly8z3.cloudfront.net/images/b90d3589-b2f5-4e75-bf91-c0fba9e89952/507b3cec-5435-499f-96d7-46c5a4d6d79f.svg) with your own image. 3. At line 19, replace `YOUR_CAMPAIGN_ID` with your GrowSurf campaign ID (e.g, `p9josq`) 1. If you set up a custom domain for your GrowSurf Referral Portal, replace the entire `https://grow.surf/YOUR_CAMPAIGN_ID` instead with your Referral Portal URL (e.g, `https://refer.yourwebsite.com`). 4. At line 19, replace `#ee1152` with your own brand color. ## Example 5 Display a static image in your email. ### What it looks like ![](/files/nJmQd7c0juiCajjubqAr) ### Copy/paste this HTML code into your ActiveCampaign email ```markup

Give $100, Get $100

Give $100, Get $100.

Did you know that you can get $100 for referrals?

Simply share your unique referral link: %GROWSURF_SHARE_URL% or click the button below to invite them from your personal referral portal. We'll give you and your friends both a $100 gift card when they activate an insurance policy with us.

Refer Friends

``` ### **Customize the contents** 1. At line 5, replace [`https://growsurf-blog.s3.us-west-2.amazonaws.com/email-examples/people.png`](https://growsurf-blog.s3.us-west-2.amazonaws.com/email-examples/people.png) with your own image. 2. At line 19, replace `#094a83` with your own brand color. 3. At line 19, replace `YOUR_CAMPAIGN_ID` with your GrowSurf campaign ID (e.g, `p9josq`) 1. If you set up a custom domain for your GrowSurf Referral Portal, replace the entire `https://grow.surf/YOUR_CAMPAIGN_ID` instead with your Referral Portal URL (e.g, `https://refer.yourwebsite.com`). ## Example 6 Display a static image in your email. ### What it looks like ![](/files/4tpeK411YYyHAvWEHVxg) ### Copy/paste this HTML code into your ActiveCampaign email ```markup

Invite your friends to Sips

Get a friend saving with Sips, and you'll both get $10 in accounts credits.

Copy & share your link:%GROWSURF_SHARE_URL%

Or spread the word on social media:

``` ### **Customize the contents** 1. At line 5, replace [`https://growsurf-blog.s3.us-west-2.amazonaws.com/email-examples/welcome.png`](https://growsurf-blog.s3.us-west-2.amazonaws.com/email-examples/welcome.png) with your own image. 2. At lines 7 and 12, replace `Sips` with your own brand name. 3. At line 27, replace the text `Hey!%20Do%20you%20love%20wine?%20So%20do%20I.` with your own. 1. Make sure to encode the message using a tool like [https://www.url-encode-decode.com](https://www.url-encode-decode.com/) 4. At line 33, replace the text `%GROWSURF_SHARE_URL%%0AHey!%20Do%20you%20love%20wine?%20So%20do%20I.` with your own 1. Make sure to encode the message using a tool like [https://www.url-encode-decode.com](https://www.url-encode-decode.com/) 2. Make sure to include `%GROWSURF_SHARE_URL%` only to the encoded message ## Example 7 Display a static image in your email. ### What it looks like ![](/files/YVoLRVmzmWm0ReoYoXAY) ### Copy/paste this HTML code into your ActiveCampaign email ```markup

Thanks for using PrismJar to manage your workforce. We hope your customer experience is amazing and one that's worth sharing. In fact, you can invite your friends and colleagues to try PrismJar, and you each get a $100 gift card when they sign up for an annual subscription.

Invite A Friend, Get $100

``` ### **Customize the contents** 1. At line 4, replace all instances of `PrismJar` with your own brand name. 2. At line 8, replace `#1673df` with your own brand color. 3. At line 8, replace `YOUR_CAMPAIGN_ID` with your GrowSurf campaign ID (e.g, `p9josq`) 1. If you set up a custom domain for your GrowSurf Referral Portal, replace the entire `https://grow.surf/YOUR_CAMPAIGN_ID` instead with your Referral Portal URL (e.g, `https://refer.yourwebsite.com`). 4. At line 12, replace `https://growsurf-blog.s3.us-west-2.amazonaws.com/email-examples/boy-and-girl-giving-high-five-to-each-other.png` with your own image. ## Example 8 Display static images in your email. ### What it looks like ![](/files/9gPvMvVQHapWIB72O0EF) ### Copy/paste this HTML code into your ActiveCampaign email ```markup

Get $10 when you refer a friend

Love Cointech? Spread the excitement by referring friends and we'll give you both get $10.

Refer Friends

Here's how to get $10

Spread the word

Go to your Cointech page to get your unique referral link and share it via text, email, or social media

You'll get $10

Receive $10 for each friend your refer that makes their first deposit

Your friends get $10

Each friend you refer also gets $10 in account credits. Everyone wins!

Refer Friends

``` ### **Customize the contents** 1. At lines 5 and 24, replace all instances of `Cointech` with your own brand name. 2. At lines 6 and 42, replace `YOUR_CAMPAIGN_ID` with your GrowSurf campaign ID (e.g, `p9josq`) 1. If you set up a custom domain for your GrowSurf Referral Portal, replace the entire `https://grow.surf/YOUR_CAMPAIGN_ID` instead with your Referral Portal URL (e.g, `https://refer.yourwebsite.com`). 3. At lines 6 and 42, replace `#4f46e5` with your own brand color. 4. At line 22, replace `https://growsurf-blog.s3.us-west-2.amazonaws.com/illustrations/GrowSurf-steps-1.png` with your own image. 5. At line 27, replace `https://growsurf-blog.s3.us-west-2.amazonaws.com/illustrations/GrowSurf-profiles-4.png` with your own image. 6. At line 32, replace `https://growsurf-blog.s3.us-west-2.amazonaws.com/illustrations/GrowSurf-steps-2.png` with your own image. ## Example 9 Display a static image in your email. ### What it looks like ![](/files/-MQW0SrO9bgdhrNa2DZB) ### Copy/paste this HTML code into your ActiveCampaign email ```markup

Get your swag

Become an Evening Stew ambassador. Invite your friends and coworkers to sign up to Evening Stew and get rewarded with exclusive swag.

Share with a friend

Or you can copy/paste your unique link here: %GROWSURF_SHARE_URL%

You currently have %GROWSURF_TOTAL_REFERRAL_COUNT% referrals. Check your status here. %GROWSURF_NEXT_MILESTONE%

``` ### **Customize the contents** 1. At line 20, replace all instances of `Evening Stew` with your own brand name. 2. At lines 25, 30, and 35, replace `#8E4CED` with your own brand color. 3. At line 25 and 35, replace `YOUR_CAMPAIGN_ID` with your GrowSurf campaign ID (e.g, `p9josq`) 1. If you setup a custom domain for your GrowSurf Referral Portal, replace the entire `https://grow.surf/YOUR_CAMPAIGN_ID` instead with your Referral Portal URL (e.g, `https://refer.yourwebsite.com`). 4. At line 15, replace [`https://growsurf-blog.s3-us-west-2.amazonaws.com/eveningstew/rewards-inline.png`](https://growsurf-blog.s3-us-west-2.amazonaws.com/eveningstew/rewards-inline.png) with your own image. 5. At line 35, because `%GROWSURF_NEXT_MILESTONE%` is used, make sure that any milestone rewards you have in your GrowSurf campaign have *Next Milestone* values set ([see image](https://growsurf-blog.s3-us-west-2.amazonaws.com/set-next-milestone-in-growsurf-campaign-editor.png). Note: This only applies to milestone rewards). ## Example 10 Display different reward images based on how many referrals the participant has made. ### What it looks like ![](/files/-MQU7NRt27EKKiY7csW3) ### Copy/paste this HTML code into your ActiveCampaign email ```markup

%GROWSURF_TOTAL_REFERRAL_COUNT% referrals

💯 Refer your friends, win stuff

1. Share your unique link with friends/coworkers

2. When they sign up you unlock a reward

3. Keep on sharing to unlock more rewards

Your unique link:

%GROWSURF_SHARE_URL%

View your referral progress

%GROWSURF_NEXT_MILESTONE%

``` ### **Customize the contents** 1. At lines 9, 41, and 46, replace `#8E4CED` with your own brand color. 2. At line 46, replace `YOUR_CAMPAIGN_ID` with your GrowSurf campaign ID (e.g, `p9josq`) 1. If you setup a custom domain for your GrowSurf Referral Portal, replace the entire `https://grow.surf/YOUR_CAMPAIGN_ID` instead with your Referral Portal URL (e.g, `https://refer.yourwebsite.com`). 3. At line 35, replace [`https://growsurf-blog.s3-us-west-2.amazonaws.com/eveningstew/0-won.png`](https://growsurf-blog.s3-us-west-2.amazonaws.com/eveningstew/0-won.png) with your own image based on `%GROWSURF_TOTAL_REFERRAL_COUNT%`. In this example, you would display any one of these five images at a given time: 1. If `%GROWSURF_TOTAL_REFERRAL_COUNT%` <3, then display [this image](https://growsurf-blog.s3-us-west-2.amazonaws.com/eveningstew/0-won.png). 2. If `%GROWSURF_TOTAL_REFERRAL_COUNT%` >=3 and <5, then display [this image](https://growsurf-blog.s3-us-west-2.amazonaws.com/eveningstew/1-won.png). 3. If `%GROWSURF_TOTAL_REFERRAL_COUNT%` >=5 and <10, then display [this image](https://growsurf-blog.s3-us-west-2.amazonaws.com/eveningstew/2-won.png). 4. If `%GROWSURF_TOTAL_REFERRAL_COUNT%` >=10 and <20, then display [this image](https://growsurf-blog.s3-us-west-2.amazonaws.com/eveningstew/3-won.png). 5. If `%GROWSURF_TOTAL_REFERRAL_COUNT%` >=20, then display [this image](https://growsurf-blog.s3-us-west-2.amazonaws.com/eveningstew/4-won.png). 4. At line 51, because `%GROWSURF_NEXT_MILESTONE%` is used, make sure that any milestone rewards you have in your GrowSurf campaign have *Next Milestone* values set ([see image](https://growsurf-blog.s3-us-west-2.amazonaws.com/set-next-milestone-in-growsurf-campaign-editor.png). Note: This only applies to milestone rewards). ## Example 11 Display a GIF image with rotating rewards in your email. ### What it looks like ![](/files/-MQU7F1fUbOPbKf9qhfl) ### Copy/paste this HTML code into your ActiveCampaign email ```markup

Share Evening Stew

🙌 Share Evening Stew with your friends/coworkers and earn free swag. Copy/paste your referral link: %GROWSURF_SHARE_URL% or click here to see your progress towards rewards.

``` ### **Customize the contents** 1. At lines 10 and 21, replace `Evening Stew` with your own brand name. 2. At line 21, replace all instances of`#8E4CED` with your own brand color. 3. At line 21, replace `YOUR_CAMPAIGN_ID` with your GrowSurf campaign ID (e.g, `p9josq`) 1. If you setup a custom domain for your GrowSurf Referral Portal, replace the entire `https://grow.surf/YOUR_CAMPAIGN_ID` instead with your Referral Portal URL (e.g, `https://refer.yourwebsite.com`). 4. At line 15, replace [`https://growsurf-blog.s3-us-west-2.amazonaws.com/eveningstew/rewards-inline.png`](https://growsurf-blog.s3-us-west-2.amazonaws.com/eveningstew/rotating-rewards.gif) with your own GIF image (you can use a tool like ). ## Example 12 Display a static image in your email. ### What it looks like ![](/files/-MSnaVa5w_qBtRSBreJl) ### Copy/paste this HTML code into your ActiveCampaign email ```markup

Love Husto? Refer a friend

You can earn a $200 gift card when your friend signs up for Husto.

Copy and share your unique link: %GROWSURF_SHARE_URL%

View your referral progress

``` ### **Customize the contents** 1. At lines 10 and 15, replace `Husto` with your own brand name. 2. At lines 20 and 30, replace `#F46A54` with your own brand color. 3. At line 30, replace `YOUR_CAMPAIGN_ID` with your GrowSurf campaign ID (e.g, `p9josq`) 1. If you setup a custom domain for your GrowSurf Referral Portal, replace the entire `https://grow.surf/YOUR_CAMPAIGN_ID` instead with your Referral Portal URL (e.g, `https://refer.yourwebsite.com`). 4. At line 25, replace [`https://growsurf-blog.s3-us-west-2.amazonaws.com/eveningstew/rewards-inline.png`](https://growsurf-blog.s3-us-west-2.amazonaws.com/eveningstew/rewards-inline.png) with your own image. ## Example 13 Display a static image with text next to it. ### What it looks like ![](/files/-MTHz3J_cRYB_xu9fjJP) ### Copy/paste this HTML code into your ActiveCampaign email ```markup

Love Husto? Earn a $200 gift card and a free month of Husto Premium for you and a friend! Copy and share your unique link: %GROWSURF_SHARE_URL%

**Step 2:** Staying within the same GrowSurf screen as the prior step, you need to append a `deep_link` query parameter to the Share URL. Depending on your Adjust link type, choose an option below. {% tabs %} {% tab title="Adjust Universal Link (branded domain)" %} If your Adjust link uses a branded Universal Link domain (e.g., `acecraft.go.link`, `zuscoffee.go.link`, `villamarket.go.link`): {% hint style="info" %} ## Get your app's deep link URL encoded 1. Get your app's deep link URL. For example, it looks something like `myapp://open`. 2. Use a [tool like this](https://meyerweb.com/eric/tools/dencoder/) to URL-encode it. Using the same example above, you should have something that looks like `myapp%3A%2F%2Fopen` . 3. Replace `myapp%3A%2F%2Fopen` in the examples below with your value from the previous step (leave `{{referralCode}}` as literal text — GrowSurf substitutes it for each participant's referral code at share time). {% endhint %} **If your Adjust link has no query parameters yet, prefix with `?`:** * Before: `https://zuscoffee.go.link/C0PHh` * After: `https://zuscoffee.go.link/C0PHh?deep_link=myapp%3A%2F%2Fopen%3Fgrsf%3D{{referralCode}}` **If your Adjust link already has query parameters (e.g., an `adj_t` token), prefix with `&`:** * Before: `https://villamarket.go.link/?adj_t=kzdgn86` * After: `https://villamarket.go.link/?adj_t=kzdgn86&deep_link=myapp%3A%2F%2Fopen%3Fgrsf%3D{{referralCode}}` {% endtab %} {% tab title="Adjust standard tracker URL" %} If your Adjust link uses the standard tracker URL format (e.g., `app.adjust.com`): {% hint style="info" %} ## Get your app's deep link URL encoded 1. Get your app's deep link URL. For example, it looks something like `myapp://open`. 2. Use a [tool like this](https://meyerweb.com/eric/tools/dencoder/) to URL-encode it. Using the same example above, you should have something that looks like `myapp%3A%2F%2Fopen` . 3. Replace `myapp%3A%2F%2Fopen` in the examples below with your value from the previous step (leave `{{referralCode}}` as literal text — GrowSurf substitutes it for each participant's referral code at share time). {% endhint %} **If your tracker URL has no query parameters yet, prefix with `?`:** * Before: `https://app.adjust.com/abc123` * After: `https://app.adjust.com/abc123?deep_link=myapp%3A%2F%2Fopen%3Fgrsf%3D{{referralCode}}` **If your tracker URL already has query parameters (e.g., a campaign tag), prefix with `&`:** * Before: `https://app.adjust.com/abc123?campaign=summer` * After: `https://app.adjust.com/abc123?campaign=summer&deep_link=myapp%3A%2F%2Fopen%3Fgrsf%3D{{referralCode}}` {% endtab %} {% endtabs %} {% hint style="info" %} There's no configuration necessary in Adjust. GrowSurf substitutes `{{referralCode}}` with each participant's referral code at share time (e.g., `abc123`). {% endhint %} **Step 3:** Pass the Adjust deferred deep link URL into the GrowSurf attribution adapter before calling `addReferredParticipant()`. {% tabs %} {% tab title="iOS" %} ```swift import GrowSurfAdjustAttribution try await GrowSurfAdjustAttribution.handle(adjustDeferredDeepLinkURL, sdk: growsurf) ``` {% endtab %} {% tab title="Android" %} ```kotlin import com.growsurf.sdk.attribution.adjust.GrowSurfAdjustAttribution GrowSurfAdjustAttribution.handle(adjustDeferredDeepLinkUri, growsurf) ``` {% endtab %} {% endtabs %} **Step 4:** Call `addReferredParticipant()` after the GrowSurf SDK has handled attribution. This method will validate pending attribution and creates a new referred participant record only when there is a valid referrer. *** ## iOS Deferred Deep Linking (New Installs) This is the primary path for an app referral program — a referral targets people who don't have your app yet, so most referred installs are cold installs. On iOS it's best-effort even when configured (see the troubleshooting tips below), so pair it with a fallback such as manual referral-code entry. For users who tap an Adjust link (and don't have your iOS app installed), the referral code only survives the install if Adjust **LinkMe** is enabled. iOS 14+ removed the IDFA/device matching (App Tracking Transparency), and iOS 15 Private Relay masks the click IP, which broke the probabilistic matching Adjust otherwise uses for cold-install deferred deep links. **LinkMe** is optional and off by default. Without it, an iOS user who installs from a referral link may open the app with no referral data, and `addReferredParticipant()` finds no referrer. To enable it: * **On your Adjust link:** add a LinkMe tag so the token is written at click time — `adj_linkme=1` for Universal/branded (`.go.link`) links, or `linkme=1` for standard tracker URLs. * **In your app:** enable LinkMe on the Adjust config **before** starting the Adjust SDK. The exact call depends on your Adjust SDK major version — `ADJConfig.enableLinkMe()` in Adjust iOS SDK v5, or `setLinkMeEnabled(true)` in v4 (confirm against [Adjust's current LinkMe docs](https://help.adjust.com/en/article/linkme) for your version). On iOS 16+, the user sees a one-time "Pasted from …" prompt on first launch when the SDK reads the LinkMe clipboard token. Without LinkMe, Adjust falls back to server-side, probabilistic matching, which is unreliable on modern iOS. The installed-app flow (an Adjust link that opens an app the user already has) does not need LinkMe. As with every provider, GrowSurf reads `grsf` out of whatever deep link Adjust delivers — so a deferred referral survives only when LinkMe is enabled and the delivered `deep_link` still carries `grsf`. *** ## Additional Tips * Test both flows before launching: * **Installed app flow:** Users who already have your app installed * **New install flow:** Users who don't have your app installed * If the referral code is missing after app install, confirm that the deep link URL passed to `GrowSurfAdjustAttribution.handle` contains `grsf`, `ref`, or `referredBy`. The most common cause is that the `deep_link` parameter in your Adjust Share URL was not URL-encoded correctly, or `{{referralCode}}` was accidentally URL-encoded to `%7B%7BreferralCode%7D%7D` and was not substituted by GrowSurf. * The `deep_link` value should URL-encode the `://`, `?`, and `=` characters of your app's deep link scheme, but `{{referralCode}}` itself must remain as literal text (not URL-encoded). For example, `myapp%3A%2F%2Fopen%3Fgrsf%3D{{referralCode}}` is correct; `myapp%3A%2F%2Fopen%3Fgrsf%3D%7B%7BreferralCode%7D%7D` is not. * **iOS deferred (cold install) is best-effort.** Even when LinkMe is enabled, a referral can be missing after a *new* iOS install if the user declined the iOS "Paste from …" prompt on first launch, copied something else before opening the app (overwriting the clipboard token), or tapped the link from an in-app / non-Safari browser. Provide a fallback such as manual referral-code entry, and don't assume the user always lands on a specific screen. (Android's Play Install Referrer is deterministic and isn't affected by these.) * See [iOS SDK Attribution Providers](/developer-tools/ios-sdk/attribution-providers), [Android SDK Attribution Providers](/developer-tools/android-sdk/attribution-providers), and [Getting Started for Native Mobile](/getting-started-for-native-mobile) for more details. # Amplitude Track and analyze referral program data alongside product analytics in Amplitude. ## How It Works After connecting, the Amplitude integration transmits data to your Amplitude account, enabling analysis and reporting on your referral program. For referrers, when they are added to your campaign (e.g., they get a referral link generated) or if they click a social share button (like Facebook or LinkedIn), GrowSurf sends an Amplitude event. For referred friends, if they sign up using your Share URL, GrowSurf also sends an event. {% hint style="success" %} Under the hood, GrowSurf will load the Amplitude JavaScript library, identify participants (both referrers and referred friends) by their email address, and track events. Rest assured, if Amplitude is already installed, GrowSurf ensures the library is not loaded twice and prevents duplicate identity calls. {% endhint %} ## Tracked Events The following events will be emitted with the `growsurf_` prefix. | Event | Description | Explanation | | --------------------------- | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `growsurf_referral` | \[Referred friend] New referral signup |

Records when a referred visitor signs up through a referral link.

This includes:

Those who submit the form on your website that has referral tracking enabled (via the campaign editor)
Adding a referred participant via growsurf.addParticipant()

| | `growsurf_referral_trigger` | \[Referred friend] Referral triggered | Records when a referred participant completes the desired qualifying action, which triggers a referral. Only applies when you are using [`growsurf.triggerReferral()`](https://docs.growsurf.com/developer-tools/javascript-sdk/api-reference#trigger-referral). | | `growsurf_signup` | \[Referrer] New referrer signup |

Records when someone generates a referral link and joins the campaign as a participant.

This includes:

Direct signups (someone entering in their email address on the GrowSurf form)
Passing in an email address via URL parameter ?grsf\_email
Passing in an email address via data-grsf-email attribute on an Embeddable Element
Adding a participant via growsurf.addParticipant()

| | `growsurf_share` | \[Referred] Social media share | Records when a referrer shares their link by clicking 'Copy Link' or clicking a social media button | | `growsurf_invite` | \[Referrer] Email invite(s) sent | Records when a referrer sends invitation(s) via email | ### Example Events Events correspond with the events listed in the [`growsurf.subscribe()`](https://docs.growsurf.com/developer-tools/javascript-sdk/api-reference#subscribe-to-event) method. To see examples of the raw `JSON` data, please see the [*Example Response*](https://docs.growsurf.com/developer-tools/javascript-sdk/api-reference#subscribe-to-event) section. *** ## How to Set Up **Step 1**: In *Campaign Editor > 4. Options > Integrations*, open the Amplitude integration card and enter your [Amplitude API key](https://amplitude.com/docs/apis/authentication). {% hint style="info" %} **Note:** If you are 100% certain that you already have Amplitude installed on your website, you do not need to enter in the Amplitude API key. Simply press *Connect* and the integration will be enabled. However, we recommend that you still enter it to account for URLs that do not have Amplitude installed. {% endhint %}

{% hint style="info" %} **Note:** Please allow up to 15 minutes of processing time for events to appear (in some cases where Amplitude is backed up, it can take longer). {% endhint %} Within Amplitude, if you click on a user, you'll be able to view specific details about the event.

{% hint style="info" %} For **new installs (deferred)** on iOS, the referral arrives through AppsFlyer Unified Deep Linking and `grsf` must ride in a `deep_link_value`/`deep_link_sub` field — see [iOS Deferred Deep Linking](#ios-deferred-deep-linking-new-installs) below. {% endhint %} **Step 2:** Pass the AppsFlyer callback payload into the GrowSurf attribution adapter before calling `addReferredParticipant()`. {% tabs %} {% tab title="iOS" %} ```swift import GrowSurfAppsFlyerAttribution try await GrowSurfAppsFlyerAttribution.handle(appsFlyerParams, sdk: growsurf) ``` {% endtab %} {% tab title="Android" %} ```kotlin import com.growsurf.sdk.attribution.appsflyer.GrowSurfAppsFlyerAttribution GrowSurfAppsFlyerAttribution.handle(appsFlyerConversionData, growsurf) ``` {% endtab %} {% endtabs %} **Step 3:** Call `addReferredParticipant()` after the GrowSurf SDK has handled attribution. This method will validate pending attribution and creates a new referred participant record only when there is a valid referrer. *** ## iOS Deferred Deep Linking (New Installs) This is the primary path for an app referral program — a referral targets people who don't have your app yet, so most referred installs are cold installs. On iOS it's best-effort even when configured (see the troubleshooting tips below), so pair it with a fallback such as manual referral-code entry. For users who tap an AppsFlyer OneLink (and don't have your iOS app installed), the referral code survives the install through AppsFlyer **Unified Deep Linking (UDL)**, which resolves the click server-side on first launch (typically within a \~15-minute click-to-install window). Unlike Branch, Adjust, and Singular, AppsFlyer does not read the clipboard for standard deferred attribution, so there is no "Pasted from …" prompt — but you must wire up its deep-link delegate, and the referral code must ride in a field UDL exposes to new installs. * **In your app:** set `AppsFlyerLib.shared().deepLinkDelegate` and implement the UDL callback (`didResolveDeepLink(_:)`). When AppsFlyer resolves the deferred link on first launch, forward the resolved deep-link values (a dictionary) into the GrowSurf adapter, then call `addReferredParticipant()`: {% tabs %} {% tab title="iOS" %} ```swift import GrowSurfAppsFlyerAttribution // Inside your AppsFlyer DeepLinkDelegate's didResolveDeepLink callback, // once the resolved result status is "found": try await GrowSurfAppsFlyerAttribution.handle(resolvedDeepLinkValues, sdk: growsurf) ``` {% endtab %} {% endtabs %} * **On your OneLink:** AppsFlyer UDL exposes only `deep_link_value` and `deep_link_sub1` through `deep_link_sub10` to a **new** install, so the GrowSurf referral code must ride in one of those fields — a query-string-only `grsf` is not guaranteed to survive a cold install. Map the GrowSurf code into `deep_link_value` or a `deep_link_sub` field in your OneLink template. (Confirm the exact delegate API against your installed AppsFlyer SDK version.) GrowSurf reads `grsf` out of whatever deep link AppsFlyer delivers — so a deferred referral is recovered only when UDL is configured, delivers the deep link on first launch, and the link carries `grsf` in a UDL-exposed field. The installed-app flow (a OneLink that opens an app the user already has) does not need UDL wiring. *** ## Additional Tips * Test both flows before launching: * **Installed app flow:** Users who already have your app installed * **New install flow:** Users who don't have your app installed — on iOS this requires the [iOS Deferred Deep Linking](#ios-deferred-deep-linking-new-installs) setup above * If the referral code is missing after a new install on iOS, confirm your OneLink carries the GrowSurf code in `deep_link_value` or `deep_link_sub1`–`deep_link_sub10` and that UDL is wired up — see [iOS Deferred Deep Linking](#ios-deferred-deep-linking-new-installs). * **iOS deferred (cold install) is best-effort.** AppsFlyer resolves deferred links server-side (no clipboard). A referral can be missing after a *new* iOS install if the install happened more than \~15 minutes after the click (outside the UDL window — use the `onConversionDataSuccess` / Extended DDL fallback for longer gaps), if `grsf` wasn't placed in `deep_link_value` or `deep_link_sub1`–`deep_link_sub10`, or if the UDL delegate (`didResolveDeepLink`) wasn't wired. Provide a fallback such as manual referral-code entry. (Android's Play Install Referrer is deterministic and isn't affected by these.) * See [iOS SDK Attribution Providers](/developer-tools/ios-sdk/attribution-providers), [Android SDK Attribution Providers](/developer-tools/android-sdk/attribution-providers), and [Getting Started for Native Mobile](/getting-started-for-native-mobile) for more details. # AWeber Update/add AWeber subscribers with their unique share link and referrer information. ## Sync with your AWeber List **Step 1:** In *Campaign Editor > 4. Options > Integrations*, click the *Connect to AWeber* button. {% hint style="info" %} IMPORTANT: Because the GrowSurf data sync to AWeber only occurs *after* you have connected with the integration, it is imperative to connect with the integration *BEFORE* importing participants.\ \ [Click here](https://support.growsurf.com/article/385-how-can-i-sync-my-growsurf-participants-to-my-esp) to see remedy options if you have already imported participants into your campaign but would like to sync their GrowSurf data to AWeber. {% endhint %} ![](/files/-MUw1EpTune7TN_j2l2h) **Step 2:** Log in to AWeber ![](/files/-MUw1sndmflUwh--hZU1) ![](/files/-MUxyTXvJ95MPKnhGnRb) **Step 3:** Once connected, select an AWeber account and then select an AWeber list that you want to automatically sync to. GrowSurf will add/update your AWeber subscribers every time a new participant is added or referred to your referral campaign. ## Examples [View our AWeber tutorials](https://docs.growsurf.com/additional-integrations/aweber/tutorials) to see different kinds of examples that you can copy/paste into your email templates. ## **Custom Fields** GrowSurf will automatically create these new subscriber fields for your AWeber lists. {% hint style="danger" %} AWeber has a max limit on the number of custom fields that are allowed per subscriber/list. You can add up to 25 custom fields per list. Please note that deleting a custom field will also delete any data already stored in that field for all of the subscribers on your list. {% endhint %} {% hint style="danger" %} AWeber does not allow custom fields with the word "name" or "email". Because of this restriction, GrowSurf has shortened "name" to "n" and "email" to "e" within various custom fields. See the list below for more details. {% endhint %} | **Field Name** | **Variables** | **Type** | **Description** | **Example** | | ---------------------------------------- | ---------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- | | **GrowSurf Share URL** | {!custom GrowSurf Share URL} | TEXT | The participant's unique referral link | | | **GrowSurf Participant ID** | {!custom GrowSurf Participant ID} | TEXT | The participant's unique GrowSurf ID | abc123 | | **GrowSurf Referral Status** | {!custom GrowSurf Referral Status} | TEXT | The referral status of the participant\* | CREDIT\_PENDING | | **GrowSurf Participant First N** | {!custom GrowSurf Participant First N} | TEXT | The participant's first name | Bob | | **GrowSurf Participant Last N** | {!custom GrowSurf Participant Last N} | TEXT | The participant's last name | Loblaw | | **GrowSurf Referrer First N** | {!custom GrowSurf Referrer First N} | TEXT | The first name of the participant's referrer (if applicable) | Gavin | | **GrowSurf Referrer Last N** | {!custom GrowSurf Referrer Last N} | TEXT | The last name of the participant's referrer (if applicable) | Belson | | **GrowSurf Referrer E** | {!custom GrowSurf Referrer E} | TEXT | The email address of the participant's referrer (if applicable) | | | **GrowSurf Total Referral Count** | {!custom GrowSurf Total Referral Count} | NUMBER | The participant's all-time referral count | 0 | | **GrowSurf Monthly Referral Count** | {!custom GrowSurf Monthly Referral Count} | NUMBER | The participant's current month referral count | 19 | | **GrowSurf Prev Monthly Referral Count** | {!custom GrowSurf Prev Monthly Referral Count} | NUMBER | The participant's previous month referral count | 200 | | **GrowSurf Next Milestone** | {!custom GrowSurf Next Milestone} | TEXT | The text for the next/upcoming milestone reward (only applies to milestone rewards. [See an example here](https://docs.growsurf.com/developer-tools/embeddable-elements#embedded-next-milestone)) | You are only 2 referrals away from winning a free t-shirt! | | **GrowSurf Next Monthly Milestone** | {!custom GrowSurf Next Monthly Milestone} | TEXT | The text for the next/upcoming monthly milestone reward (only applies to milestone rewards. [See an example here](https://docs.growsurf.com/developer-tools/embeddable-elements#embedded-next-milestone)) | You are only 2 referrals away from winning a free t-shirt! | | **GrowSurf Total Invite Count** | {!custom GrowSurf Total Invite Count} | NUMBER | The participant's all-time invite count | 112 | | **GrowSurf Total Impression Count** | {!custom GrowSurf Total Impression Count} | NUMBER | The participant's all-time impression count | 150 | \**GrowSurf Referral Status* can be the following: `CREDIT_PENDING` (This participant must still trigger a referral for their referrer to receive referral credit), `CREDIT_AWARDED` (This participant triggered a referral and their referrer received referral credit), `CREDIT_EXPIRED` (This participant did not trigger the referral credit within the referral credit expiration window so their referrer did not receive referral credit). You can use these new subscriber fields in your AWeber email templates. Whether you launch a new marketing campaign or have an automated drip campaign going on, make sure to always include `{{ subscriber.custom_field['growsurf_share_url'] }}` in your emails to provoke your subscribers to make referrals! ## **Troubleshooting Tips** * **If the new participant isn't being added to AWeber, or if they are being added but their unique referral link isn't being synced to AWeber:** * Activity logs will denote if a participant was added to AWeber or if they failed to be added. (In the case of failure, GrowSurf will re-attempt to add them for 7 days). # Tutorials We'll walk you through adding personalized referral program messaging to your AWeber emails. When you connect your GrowSurf campaign to AWeber, you can easily embed a referral program into your AWeber emails. Check out the examples below, each with ready-made code snippets that you can copy/paste and customize to your liking. ## Example 1 Display a static image in your email. ### What it looks like ![](/files/6rWCZf0i1y23UfO0zQIS) ### Copy/paste this HTML code into your AWeber email ```markup


Refer your friends, boost your savings Get $5 for every friend you refer to PrismJar with your personal referral link: {!custom GrowSurf Share URL} Send to Email Post to Facebook Send by Twitter

Refer your friends, boost your savings

Get $5 for every friend you refer to PrismJar with your personal referral link: {!custom GrowSurf Share URL}

Send to Email Post to Facebook Send by Twitter

``` ### **Customize the contents** 1. At line 4, replace [`https://growsurf-blog.s3.us-west-2.amazonaws.com/illustrations/GrowSurf-steps-2.png`](https://growsurf-blog.s3.us-west-2.amazonaws.com/illustrations/GrowSurf-steps-2.png) with your own image. 2. At line 11, replace `PrismJar` with your own brand name. 3. At line 12, replace `#1673df` with your own brand color 4. At line 15, replace the text `{!custom GrowSurf Share URL}%0AJoin%20PrismJar%20and%20we%20both%20get%20$10%20:)` with your own 1. Make sure to encode the message using a tool like [https://www.url-encode-decode.com](https://www.url-encode-decode.com/) 2. Make sure to include `{!custom GrowSurf Share URL}` only to the encoded message 5. At line 17, replace the text `Join%20PrismJar%20and%20we%20both%20get%20$10%20:)` with your own 1. Make sure to encode the message using a tool like [https://www.url-encode-decode.com](https://www.url-encode-decode.com/) ## Example 2 Display a static image in your email. ### What it looks like ![](/files/44NZyBJ9kXBfEgyXqQTW) ### Copy/paste this HTML code into your AWeber email ```markup

Get $10 in bonus credits when you refer a friend