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
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
Authorizationwith the contentsBearer <YOUR_API_ACCESS_KEY>, where<YOUR_API_ACCESS_KEY>is your API key.
Example Authenticated Request
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:
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:
Next steps
Last updated
Was this helpful?