GrowSurf MCP Server

Official

Overview Schema Source Related Servers Discussions Admin

growsurf_get_participant

Read-onlyIdempotent

Retrieve a single referral program participant's details by GrowSurf participant ID or email address, optionally targeting a specific campaign.

Instructions

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. Use growsurf_list_participants first if you need to find a participant ID. Targets campaignId if you pass it, otherwise GROWSURF_CAMPAIGN_ID.

Input Schema

TableJSON Schema

Name	Required	Description
`campaignId`	No	Target program (campaign) id for this call. Defaults to GROWSURF_CAMPAIGN_ID when omitted. Pass the `id` returned by growsurf_create_campaign to configure or operate a program you just created, without restarting the server.
`participantId`	No
`participantEmail`	No

Output Schema

TableJSON Schema

Name	Required	Description
`id`	No	The participant's unique id.
`rank`	No	All-time leaderboard rank.
`email`	No	The participant's email address.
`isNew`	No	`true` when the request created the participant. Returned by participant creation calls.
`notes`	No	Internal notes. Never shown to participants.
`rewards`	No	Rewards the participant has earned.
`isWinner`	No	`true` once the participant has earned at least one reward.
`lastName`	No	The participant's last name.
`metadata`	No	Custom key/value metadata (single level).
`referrer`	No	Summary of the participant's referrer (same core fields as a participant). Present only when the participant was referred.
`shareUrl`	No	The participant's unique referral link. Omitted for affiliate program participants who are not approved affiliates.
`createdAt`	No	When the participant joined, as a Unix timestamp in milliseconds.
`firstName`	No	The participant's first name.
`ipAddress`	No	IP address recorded for the participant, or `null`.
`referrals`	No	Ids of participants they successfully referred (100 most recent).
`referredBy`	No	Id of the referrer. Present only when the participant was referred.
`shareCount`	No	Share counts keyed by channel (e.g. `email`, `facebook`, `twitter`, `copyRefLink`, `iosNativeShare`).
`vanityKeys`	No	The participant's vanity keys.
`fingerprint`	No	Browser identifier recorded for the participant, or `null`.
`inviteCount`	No	Invites sent by the participant.
`isAffiliate`	No	Affiliate programs only. Whether this participant is an enrolled affiliate. A referred customer who has not joined the program is `false`.
`monthlyRank`	No	Current-month leaderboard rank (resets monthly).
`unsubscribed`	No	`true` if the participant unsubscribed from program emails.
`referralCount`	No	All-time referrals credited to the participant.
`fraudRiskLevel`	No	The participant's fraud risk level.
`payoutSettings`	No	Actions the participant must complete before a payout can be released. Always present.
`referralSource`	No	How the participant joined the program.
`referralStatus`	No	The referrer's credit status for this participant. Present only when the participant was referred.
`rewardEvidence`	No	What this response establishes about rewards. Combine with other reads; unknown here does not override evidence elsewhere.
`affiliateStatus`	No	Affiliate programs only. The enrolled affiliate's status (`APPROVED`, `SUSPENDED`, or `BANNED`). `null` for participants who are not affiliates.
`fraudReasonCode`	No	Reason code behind `fraudRiskLevel` (e.g. `UNIQUE_IDENTITY`, `DUPLICATE_EMAIL`, `MANUAL_UPDATE`).
`impressionCount`	No	Total views of the participant's referral link.
`prevMonthlyRank`	No	Previous-month leaderboard rank.
`mobileInstanceId`	No	App-install scoped identifier supplied by a native app, or `null`.
`monthlyReferrals`	No	Ids of participants they successfully referred this month (100 most recent).
`paypalEmailAddress`	No	PayPal email address on file, used for affiliate or PayPal reward payouts.
`unreadPayoutsCount`	No	Payouts the participant has not yet viewed. Affiliate programs only.
`monthlyReferralCount`	No	Referrals credited this month (resets monthly).
`allMatchingFraudsters`	No	Other participants flagged as matching this participant during anti-fraud checks.
`uniqueImpressionCount`	No	Unique views of the participant's referral link.
`unreadCommissionsCount`	No	Commissions the participant has not yet viewed. Affiliate programs only.
`prevMonthlyReferralCount`	No	Referrals credited the previous month.
`affiliateEnrollmentSource`	No	Affiliate programs only. How the affiliate enrolled (`OPEN_ENROLLMENT`, `APPLICATION`, `PARTICIPANT_AUTH`, `INVITE`, `REST_API`, `CSV`, or `DASHBOARD`). `null` when not recorded.

Schema Changelog

Changes observed during successful MCP inspections.

Changed5 schema fields changedv0.14.0Sep 10, 2026

addedOutput schema / properties / rewardEvidence

Added value: +{
+  "description": "What this response establishes about rewards. Combine with other reads; unknown here does not override evidence elsewhere.",
+  "properties": {
+    "approvalPolicy": {
+      "description": "Referral reward approval policy from requireManualRewardApproval, not affiliate commission approval or an individual reward state.",
+      "enum": [
+        "manual",
+        "automatic",
+        "unknown"
+      ],
+      "type": "string"
+    },
+    "automaticFulfillmentMarking": {
+      "description": "The autoFulfillRewards setting, when returned by an options read. Null means unknown; this controls marking, not delivery.",
+      "type": [
+        "boolean",
+        "null"
+      ]
+    },
+    "basis": {
+      "enum": [
+        "this_response_only"
+      ],
+      "type": "string"
+    },
+    "conclusion": {
+      "type": "string"
+    },
+    "deliveryStatus": {
+      "enum": [
+        "unknown"
+      ],
+      "type": "string"
+    },
+    "integrationConnection": {
+      "enum": [
+        "not_established"
+      ],
+      "type": "string"
+    },
+    "nextStep": {
+      "type": "string"
+    },
+    "programReferralTrigger": {
+      "enum": [
+        "not_established"
+      ],
+      "type": "string"
+    }
+  },
+  "type": "object"
+}

changedOutput schema / properties / rewards / items / properties / fulfilledAt / description

Previous value: -"When the reward was fulfilled, as a Unix timestamp in milliseconds. `null` until fulfilled."New value: +"When the reward was marked fulfilled, as a Unix timestamp in milliseconds. `null` until marked fulfilled; this is not a delivery receipt."

changedOutput schema / properties / rewards / items / properties / isFulfilled / description

Previous value: -"`true` once the reward has been fulfilled."New value: +"`true` once the reward is marked fulfilled. Confirm actual delivery through fulfillment records."

changedOutput schema / properties / rewards / items / properties / status / description

Previous value: -"Fulfillment status of the earned reward."New value: +"Fulfillment marking of the earned reward. `FULFILLED` records that it was marked fulfilled, not proof of delivery. `CANCELLED` means an unpaid Lead reward was reversed before fulfillment."

changedOutput schema / properties / rewards / items / properties / status / enum

Previous value: -[
-  "PENDING",
-  "FULFILLED"
-]New value: +[
+  "PENDING",
+  "FULFILLED",
+  "CANCELLED"
+]

First observedv0.12.2Aug 25, 2026

TDQS

A4.9/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already mark this as read-only, idempotent, and non-destructive, and the description adds valuable interpretive context beyond that: referralStatus vs referralCount semantics, why zero referrals can align with CREDIT_AWARDED, and the distinction between fulfillment marking and actual delivery confirmation. This prevents misinterpretation of returned fields.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The core action is front-loaded, and the subsequent sentences each add necessary disambiguation about field meanings and campaign targeting. There is little to no filler, and the density is justified by the need to prevent interpretation errors.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given that the annotations cover safety and the output schema describes return structure, the description supplies the missing decision info: how to find a participant ID, what the fields mean semantically, and how campaign targeting behaves. An agent has enough clarity to invoke this tool correctly without further investigation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is only 33% since participantId and participantEmail lack descriptions, but the description compensates by explaining that either a GrowSurf participant ID or an email address is used to fetch the participant. It also gives campaignId practical meaning by noting the default GROWSURF_CAMPAIGN_ID behavior. Full field-level detail is still somewhat light, but the essential semantics are present.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The opening phrase 'Fetch a single participant by GrowSurf participant ID or email address' states a specific verb, resource, and lookup method. It clearly distinguishes this tool from growsurf_list_participants by emphasizing 'single participant' and even names the sibling explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly says 'Use growsurf_list_participants first if you need to find a participant ID,' giving concrete guidance on when to use an alternative tool. It also explains the campaignId targeting behavior and fallback to GROWSURF_CAMPAIGN_ID, so an agent knows exactly how to route the call.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server