canonical: https://jentic.com/apis/growsurf.com/growsurf

# GrowSurf REST API

The GrowSurf REST API manages referral and affiliate programs: campaigns, participants, referrals, rewards, affiliate commissions, payouts, and analytics. Every operation except account creation requires a GrowSurf API key, and each one lists the key scope it needs so access can be limited by team and program. It covers adding participants, triggering referrals, approving and fulfilling rewards, recording affiliate transactions, and reading campaign and participant analytics.

## For AI agents

Lets an AI agent run referral and affiliate programs: managing campaigns and participants, triggering referrals, approving rewards, and reading analytics.

## Scope

Does not handle email campaign design, ad buying, or payment processing. Use for referral and affiliate program management only.

## Capabilities

- Create and clone referral and affiliate campaigns
- Add participants and retrieve their referrals, rewards, and commissions
- Approve and fulfill participant rewards
- Record and refund affiliate transactions
- List participant payouts and request payout-destination confirmation
- Retrieve campaign and participant analytics

## Use cases

### Agent-run referral program

An AI agent can operate a referral program through GrowSurf by adding participants, triggering referrals, and approving and fulfilling rewards as milestones are met. Each API key carries scopes and program access limits, so an agent only reaches the campaigns its key allows. Connected through Jentic, the agent calls only the participant and reward operations it needs.

Example prompt: Add a participant to a campaign, trigger a referral, and approve the resulting reward once it is earned

### Affiliate commissions and payouts

Affiliate programs need transactions recorded, commissions approved, and payouts tracked. GrowSurf records an affiliate transaction, approves the commission it generates, and lists participant payouts and their destination status. An agent can run this loop and request a payout-destination confirmation where one is missing.

Example prompt: Record an affiliate transaction, approve the commission, and list the participant's payouts

### Program analytics

Growth teams measure referral performance per campaign and per participant. GrowSurf returns campaign analytics, activation analytics, and participant-level analytics, so an agent can pull the numbers that decide whether to adjust rewards. Leaderboard and activity-log endpoints add detail on who is driving referrals.

Example prompt: Retrieve a campaign's analytics and its activation analytics for a performance report

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/campaigns` | Create a campaign |
| POST | `/campaign/{id}/participant` | Add a participant |
| POST | `/campaign/{id}/participant/{participantIdOrEmail}/ref` | Trigger a referral |
| POST | `/campaign/{id}/reward/{rewardId}/approve` | Approve a participant reward |
| POST | `/campaign/{id}/participant/{participantIdOrEmail}/transaction` | Record an affiliate transaction |
| GET | `/campaign/{id}/payouts` | List participant payouts |
| GET | `/campaign/{id}/analytics` | Retrieve campaign analytics |

## Key resources

- **Campaigns** — Create, clone, and configure referral and affiliate campaigns
- **Participants** — Add participants and read their referrals, rewards, and commissions
- **Rewards** — Approve, fulfill, and delete participant rewards
- **Commissions and payouts** — Record transactions, approve commissions, and track payouts
- **Analytics** — Campaign, activation, and participant analytics

## AI readiness

This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use.

- **Score:** 68 / 100
- **Maturity:** AI-Aware
- **Dimensions:**
  - Foundational Compliance: 74 / 100
  - Developer Experience & Jentic Compatibility: 70 / 100
  - AI-Readiness & Agent Experience: 52 / 100
  - Agent Usability: 90 / 100
  - Security: 60 / 100
  - AI Discoverability: 82 / 100
- **View full report:** https://jentic.com/apis/growsurf.com/growsurf/scorecard
- **How the score is calculated:** https://docs.jentic.com/reference/api-readiness-framework/overview/
- **More about the dimensions:** https://docs.jentic.com/reference/api-readiness-framework/specification/#dimensional-model-overview

### Score it yourself

Every API in the directory is allowlisted, so you can re-score it with no key required.

- **Score your own API:** https://jentic.com/scorecard.md
- **Scoring CLI agent skill:** https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-scorecard/SKILL.md

```sh
npx @jentic/api-scorecard-cli score <openapi-url>
```

## Why Jentic

- **Setup:** Wiring GrowSurf by hand means handling its Bearer API key, matching each call to the scope it requires, and respecting per-key program access limits yourself. Through Jentic you install once, import GrowSurf from the API Directory, store the key once, and your agent calls it.
- **Permission scoping:** GrowSurf puts the campaign id in the URL path (`/campaign/{id}/...`), so a rule can pin your agent to one campaign and its participant and reward operations. You choose the operations it may call, so reward deletion and bulk participant deletion are not included unless you add them.
- **Credential handling:** Your GrowSurf key is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'add a referral participant' or 'approve a reward', and Jentic returns the matching GrowSurf operation with its input schema so the agent calls the right endpoint without reading the reference docs.

## Related APIs

- **ReferralCandy API** — A referral program platform versus GrowSurf's participant and reward surface.
- **Refersion Affiliate API** — Affiliate tracking and commissions versus GrowSurf's combined referral and affiliate model.
- **LoyaltyLion API** — Loyalty points and rewards to pair with GrowSurf's referral mechanics.

## FAQ

### What authentication does the GrowSurf REST API use?

GrowSurf authenticates with a REST API key supplied as a Bearer token in the Authorization header, per its OpenAPI spec, and each operation lists the key scope it requires. Account creation is the one operation that needs no key. Through Jentic the key is stored encrypted by your own Jentic One instance and injected at execution time.

### Can I trigger referrals and approve rewards with the GrowSurf REST API?

Yes. The participant operations add a participant and trigger a referral, and the reward operations approve and fulfill a participant's reward. You can also record affiliate transactions, approve the commissions they generate, and list payouts.

### What are the rate limits for the GrowSurf REST API?

The OpenAPI spec does not publish fixed rate limits, and access is instead bounded by the scopes and program-access limits on each API key. Check https://growsurf.com for current limits.

### How do I add a participant and trigger a referral with the GrowSurf REST API through Jentic?

Search Jentic for 'add a referral participant' and it returns the GrowSurf participant operation with its input schema, then search 'trigger a referral' for the referral operation. Install Jentic One with `curl -fsSL https://raw.githubusercontent.com/jentic/jentic-one/main/tools/install.sh | sh`, import GrowSurf from the API Directory, and store your key once. To run it on your own infrastructure, install Jentic One from its GitHub repo.

### Can I limit what my agent is allowed to do with GrowSurf?

Yes. Scope the agent to one campaign: GrowSurf puts the campaign id in the URL path (`/campaign/{id}/...`), so a rule can let the agent add participants and trigger referrals for that campaign and touch no other, and every call it makes is logged.

### Is there a GrowSurf MCP server?

You don't need an MCP server to connect your agent to GrowSurf. Jentic connects it directly from the API Directory: import it, store your credential once, and your agent discovers and calls the operations it needs on demand.