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.

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.
Using TypeScript, Python, PHP, Ruby, or Java? Use an official GrowSurf API library. Learn more.
Building a native iOS or Android app? Use the iOS SDK or Android SDK for mobile attribution, participant creation, sharing, and referral portal data. Use the REST API from your backend for secure server-side actions.

Getting started

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

Step 1: Get your API key

Go to API Keys in GrowSurf Settings.
Create an API key.
Copy the new key when GrowSurf shows it. For security, the full key is shown only once.

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.

Step 2: Set up authentication

The GrowSurf REST API uses your API key to authenticate requests:

Set a plain text header named Authorization with the contents Bearer <YOUR_API_ACCESS_KEY>, where <YOUR_API_ACCESS_KEY> is your API key.

Example Authenticated Request

curl -X "GET" "https://api.growsurf.com/v2/campaign/4pdlhb" -H "Authorization: Bearer <YOUR_API_ACCESS_KEY>"

OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://api.growsurf.com/v2/campaign/4pdlhb")
  .get()
  .addHeader("Authorization", "Bearer <YOUR_API_ACCESS_KEY>")
  .build();

Response response = client.newCall(request).execute();

const request = require("request");

const options = {
  method: 'GET',
  url: 'https://api.growsurf.com/v2/campaign/4pdlhb',
  headers: {
    Authorization: 'Bearer <YOUR_API_ACCESS_KEY>'
  }
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);
  console.log(body);
});

import requests

url = "https://api.growsurf.com/v2/campaign/4pdlhb"
headers = {
    'Authorization': "Bearer <YOUR_API_ACCESS_KEY>"
    }
response = requests.request("GET", url, headers=headers)

print(response.text)

<?php

$request = new HttpRequest();
$request->setUrl('https://api.growsurf.com/v2/campaign/4pdlhb');
$request->setMethod(HTTP_METH_GET);
$request->setHeaders(array(
  'Authorization' => 'Bearer <YOUR_API_ACCESS_KEY>'
));

try {
  $response = $request->send();
  echo $response->getBody();
} catch (HttpException $ex) {
  echo $ex;
}

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 <YOUR_API_ACCESS_KEY>")
	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	body, _ := ioutil.ReadAll(res.Body)
	fmt.Println(res)
	fmt.Println(string(body))

}

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

Last updated 7 days ago

Was this helpful?