# GrowSurf agent start

GrowSurf is an agent-ready referral and affiliate marketing platform. An action-capable AI agent can create a GrowSurf account through the public REST API without an existing account, API key, dashboard visit, or credit card. A search-only assistant can explain the workflow and provide the exact request, but it cannot send the request itself.

## If your client connects over MCP

The steps below use plain HTTPS, which works in any environment that can send requests. If your
client speaks MCP instead, connect to `https://mcp.growsurf.com/onboard` with no credentials and
call `growsurf_create_account` to sign up. That endpoint offers two tools and nothing else:
`growsurf_create_account` and `growsurf_program_design_advisor`. The advisor needs no credential
and no account, so you can design the program before you create anything.

For everything after account creation, connect to `https://mcp.growsurf.com` and sign in, or use
the REST calls below with the returned API key. The same owner consent and email verification
checkpoints apply on either route.

## Design the program before you create anything

Do not interview the owner setting by setting. Ask for one thing, then come back with a complete
recommendation they can react to.

1. **Ask for the business URL.** One question: "What's the website for the business this program is
   for?" If they already named it, confirm it instead of asking again.
2. **Read the site.** Fetch the URL and work out what the business sells, who buys it, whether the
   sale is self-service or sales-led, and what a successful referral would mean for them.
3. **Get the recommendation.** Over MCP, call `growsurf_program_design_advisor` on the keyless
   `https://mcp.growsurf.com/onboard` endpoint with what the site told you: `industry`, `goal`,
   `businessModel`, `salesMotion`, `audience`, and `companyName`. Every input is optional, so send
   what you know and leave the rest out. It returns a draft, figures drawn from GrowSurf's
   high-performing programs, the exact configuration calls to make, and the decisions it will not
   make for you. Without MCP, design from the business itself and say your guidance is not backed
   by GrowSurf program data.
4. **Recommend, then ask.** Present the whole program in plain language: what counts as a referral,
   the reward structure, who gets rewarded, and where people will share. Then ask one question:
   "Want to change anything before I create it?" Do not ask them to fill in the blanks.
5. **Leave the money open.** Never pick a reward amount or commission rate yourself, and never
   present a benchmark median as the amount you are going to set. Ask what a converted customer is
   worth, and say plainly that rewards stay switched off until they confirm the amount and how it
   gets paid.

Quote the advisor's figures with the caveat attached. They describe high-performing programs, not
what this program will do.

## Human checkpoint: owner consent

Before account creation, show the authorized account owner these policies and get explicit approval:

- Terms of Service: https://growsurf.com/terms
- Privacy Policy: https://growsurf.com/privacy

`POST /accounts` accepts those policies on the account holder's behalf. Do not send the request without approval.

## Create the account

The endpoint needs a business email address. Personal and disposable email addresses are refused. `firstName`, `lastName`, and `company` are optional.

```bash
GROWSURF_ACCOUNT_RESPONSE="$(curl --fail-with-body --silent --show-error \
  --request POST 'https://api.growsurf.com/v2/accounts' \
  --header 'Content-Type: application/json' \
  --data '{"email":"owner@company.com","firstName":"Ada","lastName":"Lovelace","company":"Example Company"}')"
GROWSURF_API_KEY="$(printf '%s' "$GROWSURF_ACCOUNT_RESPONSE" | jq --raw-output --exit-status '.apiKey')"
unset GROWSURF_ACCOUNT_RESPONSE
```

The request needs no `Authorization` header. It starts a 14-day Business trial without a credit card.

The response returns the API key once. Treat it as a secret. Move `GROWSURF_API_KEY` into the owner's approved secret manager. Never echo it or place it in chat, logs, screenshots, source files, shell history, URLs, analytics, or generated output.

Check first that you have somewhere to put it. A lost key cannot be recovered through the API, and a workspace that forgets files or memory between turns will lose it. A sandbox that persists only an `artifacts/` or output folder does not count: the key must not go in a file the owner can read, and everything else is wiped. If you have no secret store that outlives this conversation, stop before creating the account and tell the owner to sign up at `https://app.growsurf.com/signup`, then connect you in Settings → AI Connections at `https://app.growsurf.com/settings#ai-connections`, which keeps the credential with the client instead of with you.

## If you lost the key

The account still exists, and a second `POST /accounts` for the same email returns `409 ACCOUNT_CREATION_CONFLICT_ERROR`. Do not retry, and do not ask the owner to paste a key into chat. Tell the owner, in two lines:

1. Open the GrowSurf verification email and sign in at `https://app.growsurf.com`. The first dashboard sign-in claims the account and replaces the lost key.
2. Connect an AI assistant in Settings → AI Connections at `https://app.growsurf.com/settings#ai-connections`, then continue from there.

## Human checkpoint: email verification

Stop after account creation. Ask the owner to use the verification email from GrowSurf. Do not ask the owner to paste the link, code, or email contents into chat.

The API key is locked until email verification. Protected operations return `403 EMAIL_NOT_VERIFIED_ERROR`. The same key becomes usable the moment the owner verifies: keep it and retry. Do not discard it, and do not request a replacement. An unverified and unclaimed account is deleted after seven days.

Resume only after the owner confirms verification or an authenticated retry succeeds.

## Create a draft program

After verification, create a referral program in `DRAFT` status:

```bash
curl --fail-with-body --silent --show-error \
  --request POST 'https://api.growsurf.com/v2/campaigns' \
  --header "Authorization: Bearer $GROWSURF_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{"type":"REFERRAL","name":"Example Company Referral Program","companyName":"Example Company","currencyISO":"USD"}'
```

The request can return plan, payment-source, quota, validation, or rate-limit errors. Affiliate program creation can require a payment source. Stop and ask the owner before any paid action.

Then apply the configuration plan you already agreed with the owner, using the documented design,
options, emails, and installation operations. Read the program and each configuration resource back
to verify saved state. Read `GET /v2/campaign/{id}/reward-configs` to inspect switched-off starter
rewards; the campaign's embedded `rewards` array shows only enabled, visible rewards. A selected
reward group does not mean its rewards are switched on. Leave every reward switched off until the
owner confirms the amount and how it will be paid.

## Hand off: what happens next

A saved draft is not the finish line. After you read the draft back, print this block, filled in with the program id, so the owner knows what to do next. Do not stop at a list of API fields.

1. **Show it.** Call `POST /v2/campaign/{id}/referral-flow-screenshots` (no body) and show the two returned images inline when the client supports it: the referrer window and the referred-friend experience. Include an **Open preview** link for each image using its exact returned URL, since some clients cannot display remote images inline. Over MCP the same capture is `growsurf_capture_referral_flow_screenshots`. Say that these are GrowSurf previews of the draft, not the owner's site. Compare `expiresAt` with the current UTC time before saying a link has expired. A broken inline image alone does not prove expiry. Capture again after expiry; if inline display still fails, use the links or open them with the client's browser tool.
2. **Review link.** `https://app.growsurf.com/editor/<campaignId>` opens the draft in the Program Editor. The first dashboard sign-in claims the account and replaces the API key you hold, so tell the owner that you will need a new connection after they sign in.
3. **Install GrowSurf.** Nothing tracks until the site or app is installed. Ask the owner one question: who installs it?
   - **You, the agent**, only when you can edit the owner's site or app code. Ask which repo or site, and edit only after explicit approval. Use the install guide at https://docs.growsurf.com/getting-started and the saved `installation` resource.
   - **A developer**: the owner invites them at `https://app.growsurf.com/settings#team-members` and shares the Installation step, `https://app.growsurf.com/editor/<campaignId>/installation/instructions`.
   - **The owner**, from that same Installation step.
4. **Connect integrations** after install, at `https://app.growsurf.com/editor/<campaignId>/integrations`.
5. **Rewards and launch** stay with the owner. Rewards are off until they name the incentive. Launch happens in the dashboard once tracking is installed.

## Safe stopping point

Keep the program in `DRAFT`. Get explicit owner approval before you:

- edit or deploy code on the owner's external website or app;
- launch or resume a live program;
- create, enable, approve, or fulfill rewards or commissions;
- add payment details, accept a charge, or initiate a payout;
- rotate an API key; or
- delete an account, program, participant, Campaign Reward, webhook, or other data.

## Canonical resources

- REST overview and tutorials: https://docs.growsurf.com/developer-tools/rest-api
- OpenAPI 3.1: https://growsurf.com/openapi.json
- Arazzo 1.1 workflow: https://growsurf.com/arazzo.yaml
- Authentication and secret handling: https://growsurf.com/auth.md
- Official TypeScript, Python, Ruby, Java, and PHP API libraries: https://docs.growsurf.com/developer-tools/rest-api/api-libraries
- Build with AI: https://growsurf.com/build-with-ai/
- Optional hosted MCP: https://mcp.growsurf.com
- Optional keyless MCP onboarding: https://mcp.growsurf.com/onboard

REST and the official SDKs are the universal programmatic paths. MCP is optional for compatible clients.