GrowSurf

Add or fetch a participant by email. If the email already exists, the existing participant is returned unchanged. One exception: if that participant claimed an offer in the Claim Offer Popup and the signup is not complete yet, this call completes the signup with the original referrer and saves any non-blank `firstName`, `lastName`, and `metadata` you send. This is trusted direct enrollment and bypasses the public application review flow for affiliates. For affiliate programs, set `isAffiliate` to `true` to enroll a new participant as approved or `false` to create a non-affiliate. If you omit it, a valid `referredBy` creates a referred non-affiliate; without a valid referrer, the new participant is enrolled as approved. A valid `referredBy` can be combined with `isAffiliate: true`. Targets `campaignId` if you pass it, otherwise `GROWSURF_CAMPAIGN_ID`.

Generate Markdown prompts and acceptance checks for evaluating an agent's program-creation workflow: starter content, rewards, configuration, and frontend installation. Does not create a program or run the checks. Use `growsurf_program_design_advisor` to choose a program design, or `growsurf_integration_guide` to plan its web integration.

Generate Markdown code examples for the official backend REST API libraries in TypeScript, Python, PHP, Ruby, and Java. Select `language` and `workflow`; both default to `all`. Covers setup, program lookup, participant creation, referral credit, sales, and mobile participant tokens. Returns code without executing API calls. Use `growsurf_client_snippets` for browser JavaScript or `growsurf_mobile_sdk_guide` for native or React Native app setup.

Bulk delete participants from your GrowSurf program in one request. DESTRUCTIVE: deletion is permanent and cannot be undone. Successful rows lose participant access immediately; related record cleanup completes automatically, subject to required financial record retention. 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. Returns a `summary` (total, deletedCount, notFoundCount, duplicateCount, errorCount) plus per-row `results` in request order, each with `status` DELETED, NOT_FOUND, DUPLICATE (resolves to the same participant as an earlier entry), or ERROR — both `200` and `202` responses can include NOT_FOUND or ERROR rows, and the summary reports these outcomes. A `202` response includes `analyticsErasure` when analytics erasure is pending. `DELETED` means participant access was removed; reports can retain the participant until cleanup completes. Do not repeat successful rows to finish cleanup. Targets `campaignId` if you pass it, otherwise GROWSURF_CAMPAIGN_ID.

Cancel a pending delayed referral trigger for a participant before the delay elapses (e.g. on refund/cancellation). Returns { success, message }. Targets `campaignId` if you pass it, otherwise GROWSURF_CAMPAIGN_ID.

Capture temporary GrowSurf preview screenshots after a draft program is saved. Returns short-lived URLs for the controlled referrer Window and referred-friend experience, with an `expiresAt` timestamp in UTC. The screenshots reflect the saved program at capture time and do not verify installation on the customer's site. A failed inline image alone does not establish that the URL expired. This tool does not accept arbitrary URLs, HTML, JavaScript, or external screenshot targets. Targets `campaignId` if supplied, otherwise `GROWSURF_CAMPAIGN_ID`.

Generate Markdown browser JavaScript and CSS examples for referral tracking, embeddable elements, and the GrowSurf Window, with placement guidance. Does not install code or change a program. Use `growsurf_embeddable_element_snippet` for one HTML element, `growsurf_grsf_config_snippet` for `window.grsfConfig`, or `growsurf_api_library_snippets` for backend REST code.

Clone your GrowSurf program (campaign) into a new DRAFT program. Integrations and credentials are not copied; active rewards are cloned. Targets `campaignId` if you pass it, otherwise GROWSURF_CAMPAIGN_ID.

Create a new GrowSurf program (campaign) with type-appropriate starter content and optional inline rewards. Starter content includes Design, Emails, Options, Installation, and GrowSurf Window defaults. Only `type` is required. The program starts in `DRAFT` status and is owned by the credential's bound team. `currencyISO` defaults to `USD` and is immutable after creation. `goal` sets the sharing settings at creation and cannot be set later. Incentives require the customer's chosen amount or commission rate. Without `rewards`, GrowSurf's starter rewards are switched off and award nothing. Editor-tab configuration is not accepted here. Does not require `GROWSURF_CAMPAIGN_ID`. The response includes the new program `id`.

Create a new campaign reward (reward config) on your GrowSurf program. `type` must be compatible with the program type (affiliate programs support only AFFILIATE rewards; referral programs support the other types). Targets `campaignId` if you pass it, otherwise GROWSURF_CAMPAIGN_ID.

Add a webhook to your GrowSurf program. `payloadUrl` is required. `events` is the list of events this webhook is subscribed to. Omit it to subscribe the webhook to every event its program type offers, or send `[]` for none. An event the program type does not offer returns `400`. A program can have up to 5 webhooks, counting the primary webhook, so you can create up to 4. Creating another returns `400`. `secret` is write-only — GrowSurf uses it to sign deliveries (the GrowSurf-Signature HMAC header) and never returns it. A program can have only one saved Bask Health webhook across all `bask.ninja` hosts and paths, including disabled webhooks. A second Bask Health webhook returns `400`. A concurrent change to webhook settings can return `409`; reload the webhooks before retrying. Targets `campaignId` if you pass it, otherwise GROWSURF_CAMPAIGN_ID.

Create or fetch a participant, then create a participant-scoped mobile SDK token via GrowSurf REST. Participant creation is trusted direct enrollment and bypasses the public application review flow for affiliates. Targets `campaignId` if you pass it, otherwise `GROWSURF_CAMPAIGN_ID`.

Create a `FILE`, `LINK`, or `TEXT` resource for participants. `LINK` requires an HTTPS `url`. `TEXT` requires plain `text`. A `FILE` up to 10 MB requires a one-time `uploadTicket` and the unmodified `uploadResult` from GrowSurf's secure upload flow. New resources default to draft unless `isPublished` is set. API reference: https://growsurf.com/openapi.json. Targets `campaignId` if supplied, otherwise `GROWSURF_CAMPAIGN_ID`.

Delete a campaign reward (reward config) from your GrowSurf program. The reward is deactivated, removed from the program's reward set, and any connected upfront-discount coupons are cleaned up. `campaignRewardId` is the reward key. Returns { id, success }. Targets `campaignId` if you pass it, otherwise GROWSURF_CAMPAIGN_ID.

Remove a webhook from your GrowSurf program by id. Returns { id, success }. Targets `campaignId` if you pass it, otherwise GROWSURF_CAMPAIGN_ID.

Delete a participant resource from your GrowSurf program. This does not remove its reusable Media Center asset. Targets `campaignId` if you pass it, otherwise GROWSURF_CAMPAIGN_ID.

Send an email to a participant (by GrowSurf participant ID or email). Provide EITHER `emailType` to trigger one of the program's configured email templates, OR `subject` + `body` for a free-form email (optionally `preheader`). For programs with `settings.design.layoutMode` set to `INLINE`, `body` must include `{{emailFooter}}`; `{{emailHeader}}` is optional. 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 and a verified custom email domain on the program (set up in *Program Editor > 3. Emails > Email Settings*). Returns 400 until one is verified. The email is accepted for delivery. Targets `campaignId` if you pass it, otherwise GROWSURF_CAMPAIGN_ID.

Generate one embeddable element's HTML as Markdown. Choose `element`; optionally include participant authentication attributes. Does not install the element or change a program. Use `growsurf_client_snippets` for a broader browser integration or `growsurf_grsf_config_snippet` for page-level participant auto authentication.

Fetch your GrowSurf campaign (program) details via REST. Embedded reward settings do not establish that an individual reward was earned, approved, or delivered. Earned reward records belong to the individual participant. Targets `campaignId` if supplied, otherwise `GROWSURF_CAMPAIGN_ID`.

Fetch strict activation for eligible participants in one enrollment cohort. Referral programs group by `enrolledAsAdvocateAt`; affiliate programs group by `approvedAsAffiliateAt`. The ordered stages are `ELIGIBLE`, `PORTAL_VIEWED`, `SHARE_ACTION`, `UNIQUE_REFERRAL_VISIT`, `LEAD`, and `CREDITED_REFERRAL`. Each participant gets the selected 7- or 30-day observation window. Omit both cohort bounds for the latest fully matured cohort. Read `coverageStartAt`, `state`, and `reason` before interpreting a null or zero; unavailable history does not mean an action never happened. Targets `campaignId` if passed, otherwise `GROWSURF_CAMPAIGN_ID`.

Fetch analytics for your GrowSurf program: participants, referrals, impressions, per-channel shares, and affiliate revenue, commission, and payout metrics when applicable. Pass `interval` (`day`, `week`, or `month`) for a per-period `series`. Pass comma-separated `include` values for `previousPeriod`, `statusCounts`, `rates`, `email`, or `engagement`. `engagement` groups unique active, sharing, repeat, and retained participants by when portal views and share actions occurred. Its `coverageStartAt`, `state`, and `reason` distinguish measured zeroes from partial or unavailable history. Scope the timeframe with `days` (default 365, max 1825) or an explicit `startDate`/`endDate` window. Explicit dates must both be positive Unix timestamps in milliseconds, with `endDate` >= `startDate` and a maximum span of 1825 days. `timezone` and `platform` apply to engagement only. Targets `campaignId` if passed, otherwise `GROWSURF_CAMPAIGN_ID`.

Fetch the custom domain that serves your GrowSurf program's landing pages, such as `https://refer.example.com`. Returns `domain` (`null` when none is set), `isVerified`, `verifiedAt`, and `dnsRecord`, the `CNAME` record to add at the DNS provider. This read does not check DNS; use `growsurf_verify_campaign_custom_domain` for a live check. Targets `campaignId` if supplied, otherwise `GROWSURF_CAMPAIGN_ID`.

Fetch the configured design fields for your GrowSurf program, including GrowSurf Window content, colors, sharing sections, participant avatars under `participantAvatarStyle`, referred-visitor content such as the Claim Offer Popup, the website widget under `widget`, the participant Traffic report under `trafficInsights` (it starts on for new affiliate programs and hidden for referral programs, and every setting is returned with its default copy), participant sign-in copy under `login`, payout-destination confirmation page copy under `payoutDestinationConfirmation`, country-name overrides under `countryLabels`, and the participant Settings panel under `participantSettings` (its `languageSectionTitle` and `languageSectionInstructionsText` label the language picker shown when the program has more than one language). `participantAvatarStyle` is `CHARACTERS`, `INITIALS`, `ANIMALS`, or `GRADIENT`; missing or unknown values mean `INITIALS`. `visualStyle` is the program Style (`GLOW`, `CLEAN`, `FLAT`, `ROUND`, `TINT`, or `GLASS`) and is omitted when the program has no saved Style. The confirmation section is omitted when no confirmation fields are stored. Stored `null` fields are returned as `null`; omitted and `null` fields use localized defaults. Targets `campaignId` if you pass it, otherwise GROWSURF_CAMPAIGN_ID.

Fetch the Emails tab configuration for your GrowSurf program, including participant and admin email templates, settings, and read-only fields. `settings.sender.fromEmail` is read-only and can be changed in the dashboard after domain verification. When updating, omit unchanged sender fields; `fromName` and `replyToEmail` cannot be cleared with `null`. Targets `campaignId` if supplied, otherwise `GROWSURF_CAMPAIGN_ID`.

Fetch the Installation tab configuration for your GrowSurf program (embed/installation and tracking setup). Returns the full object with every field and its current value — the same shape you send back on update. Targets `campaignId` if you pass it, otherwise GROWSURF_CAMPAIGN_ID.

Fetch the Options tab configuration for your GrowSurf program (referral triggers, anti-fraud lists and toggles, affiliate enrollment and application review, notifications, the program's languages under `languages`, and other behavior options). Returns the full object with every field and its current value, the same shape you send back on update. `autoFulfillRewards: false` permits manual fulfillment and does not prove that any reward went undelivered. Targets `campaignId` if you pass it, otherwise GROWSURF_CAMPAIGN_ID.

Return a dashboard link to an integration's connect panel in the GrowSurf Program Editor (Options > Integrations). Connecting Stripe, PayPal, Wise, or another account requires the user to complete the dashboard flow; the API cannot connect an account on their behalf. `integration` accepts supported keys, including camelCase keys such as `constantContact` and `helpScout`. The result reports whether the integration is `connected`, `enabled`, or `autoDisabled`. If the program check cannot run, `programVerified` is `false` and the result still includes a production dashboard link. Tango Card, Tremendous, Bask Health, CareValidate, MD Integrations, Lithos, and Telegra apply only to referral programs. Wise applies only to affiliate programs. Targets `campaignId` if supplied, otherwise `GROWSURF_CAMPAIGN_ID`.

Fetch a single participant by GrowSurf participant ID or email address. `referralStatus` describes credit to their referrer; `referralCount` counts referrals this participant generated, so zero is consistent with `CREDIT_AWARDED`. In `rewards`, `approved` records approval; `status`, `isFulfilled`, and `fulfilledAt` record fulfillment marking, not confirmation of delivery. Targets `campaignId` if you pass it, otherwise GROWSURF_CAMPAIGN_ID.

List a participant's activity logs (by GrowSurf participant ID or email), most recent first, offset/limit paginated. `limit` is 1-100 (default 20); `offset` skips logs. The response `offset` is the cursor for the next page (null when there are no more). Targets `campaignId` if you pass it, otherwise GROWSURF_CAMPAIGN_ID.

Fetch analytics for one participant by GrowSurf participant ID or email. The base response includes all-time engagement, rank, share, and applicable affiliate revenue, commission, and payout metrics. Add `activation` to `include` for the program-specific eligibility anchor and covered first milestones, including `firstPortalViewedAt` and `firstShareChannel`. A null milestone with a partial or unavailable `state` is unknown, not proof that the action never happened. Request both `activation` and `series` for covered `portalViews` and `shareActions` buckets. Filter optional series and email data with `days` (up to 1825) or both `startDate` and `endDate` as positive Unix timestamps in milliseconds. `endDate` must be at or after `startDate`, and the range can span at most 1825 days. These date parameters do not filter the base response or activation milestones. Targets `campaignId` if passed, otherwise `GROWSURF_CAMPAIGN_ID`.

Get a participant's payout-destination status (by GrowSurf participant ID or email) across every payout provider enabled for the program (PayPal, Venmo, or Wise). For each provider it reports the current `status`, the confirmed payout email, the legal recipient type, and — when a delivery bounced or a recipient was invalidated — the repair reason. `activeProvider` is the provider that currently gets paid, or null until the participant confirms one. Targets `campaignId` if you pass it, otherwise GROWSURF_CAMPAIGN_ID.

Fetch 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 email participants. Personal profiles and internal identifiers are not returned. Requires `GROWSURF_API_KEY`; does not require `GROWSURF_CAMPAIGN_ID`.

Generate the HTML code for GrowSurf Participant Auto Authentication using `window.grsfConfig`. The generated code belongs in `<head>`, before the GrowSurf Universal Code.

Plan a web integration for a referral or affiliate program. Returns Markdown steps for installing the Universal Code, identifying participants, tracking referrals or sales, and verifying webhooks. Does not inspect or change a program. Use `growsurf_client_snippets` for browser JavaScript examples, `growsurf_api_library_snippets` for backend code, or `growsurf_mobile_sdk_guide` for native or React Native apps.

List your GrowSurf program's configured Campaign Rewards, including switched-off rewards and rewards whose group is not selected. Deleted rewards are excluded. A reward can be earned only when it also appears in the campaign response's embedded `rewards` array. These settings do not establish that a participant earned or received a reward; earned reward records belong to the individual participant. Targets `campaignId` if supplied, otherwise `GROWSURF_CAMPAIGN_ID`.

List your GrowSurf program's webhooks (secrets are never returned). Targets `campaignId` if you pass it, otherwise GROWSURF_CAMPAIGN_ID.