Skip to main content
Glama
GrowSurf MCP Server

GrowSurf MCP Server

Official

Get Participant

growsurf_get_participant
Read-onlyIdempotent

Fetch a single GrowSurf participant by ID or email to review referral status, referral count, and reward approval or fulfillment details for a 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. Targets campaignId if you pass it, otherwise GROWSURF_CAMPAIGN_ID.

Input Schema

NameRequiredDescriptionDefault
campaignIdYesTarget program (campaign) id for this call. Defaults to GROWSURF_CAMPAIGN_ID when omitted. Program IDs also identify newly created programs without restarting the server.
participantIdNo
participantEmailNo

Output Schema

NameRequiredDescriptionDefault
idNoThe participant's unique id.
rankNoAll-time leaderboard rank.
emailNoThe participant's email address.
isNewNo`true` when the request created the participant. Returned by participant creation calls.
notesNoInternal notes. Never shown to participants.
groupIdNoThe participant's group (`grp_…`), or `null` for Default. Their new referrals earn this group's rewards.
rewardsNoRewards the participant has earned.
isWinnerNo`true` once the participant has earned at least one reward.
languageNoThe language code of the participant's portal and program emails, such as `es`. The program's base language unless the participant (or you) picked another of the program's languages.
lastNameNoThe participant's last name.
metadataNoCustom key/value metadata (single level).
referrerNoThe participant's referrer. It has the same fields as a participant, and its own `referrer` is always `null`. Present only when the participant was referred.
shareUrlNoThe participant's unique referral link. Omitted for affiliate program participants who are not approved affiliates.
createdAtNoWhen the participant joined, as a Unix timestamp in milliseconds.
firstNameNoThe participant's first name.
ipAddressNoIP address recorded for the participant, or `null`.
leadCountNoPending referrals that have not converted yet.
referralsNoIds of participants they successfully referred (100 most recent).
referredByNoId of the referrer. Present only when the participant was referred.
shareCountNoShare counts keyed by channel (e.g. `email`, `facebook`, `twitter`, `copyRefLink`, `iosNativeShare`).
vanityKeysNoThe participant's vanity keys.
fingerprintNoBrowser identifier recorded for the participant, or `null`.
groupSourceNoHow the participant got into their group: `MANUAL` (a move, including a move to Default), `LINK` (the group's signup link), `EMAIL`, or `DOMAIN` (a group rule). `null` when no group placement was ever made.
inviteCountNoInvites sent by the participant.
isAffiliateNoAffiliate programs only. Whether this participant is an enrolled affiliate. A referred customer who has not joined the program is `false`.
monthlyRankNoCurrent-month leaderboard rank (resets monthly).
unsubscribedNo`true` if the participant unsubscribed from program emails.
referralCountNoAll-time referrals credited to the participant.
fraudRiskLevelNoThe participant's fraud risk level.
payoutSettingsNoActions the participant must complete before a payout can be released. Always present.
referralSourceNoHow the participant joined the program. `DIRECT` means without a referrer, `PARTICIPANT` means through a participant referral, `IMPORT` means through a CSV import, `MANUAL` means through the dashboard, and `DELETED_PARTICIPANT` means the original referrer was later deleted.
referralStatusNoThe referrer's credit status for this participant. Present only when the participant was referred.
rewardEvidenceNoWhat this response establishes about rewards. Combine with other reads; unknown here does not override evidence elsewhere.
affiliateStatusNoAffiliate programs only. The enrolled affiliate's status (`APPROVED`, `SUSPENDED`, or `BANNED`). `null` for participants who are not affiliates.
fraudReasonCodeNoReason code behind `fraudRiskLevel` (e.g. `UNIQUE_IDENTITY`, `DUPLICATE_EMAIL`, `MANUAL_UPDATE`).
impressionCountNoTotal views of the participant's referral link.
prevMonthlyRankNoPrevious-month leaderboard rank.
mobileInstanceIdNoApp-install scoped identifier supplied by a native app, or `null`.
monthlyReferralsNoIds of participants they successfully referred this month (100 most recent).
paypalEmailAddressNoPayPal email address on file, used for affiliate or PayPal reward payouts.
unreadPayoutsCountNoPayouts the participant has not yet viewed. Affiliate programs only.
monthlyReferralCountNoReferrals credited this month (resets monthly).
allMatchingFraudstersNoOther participants flagged as matching this participant during anti-fraud checks.
uniqueImpressionCountNoUnique views of the participant's referral link.
unreadCommissionsCountNoCommissions the participant has not yet viewed. Affiliate programs only.
referralLeadQualifiedAtNoWhen this referred signup counted as a lead for the referrer, in Unix milliseconds. Set only when the program's `referralTrigger` is `CUSTOM`. Lead-event Campaign Rewards and commissions use it.
prevMonthlyReferralCountNoReferrals credited the previous month.
affiliateEnrollmentSourceNoAffiliate 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.

  1. Changed3 schema fields changedv0.19.32
    • addedOutput schema / properties / groupId
      Added value: +{
      +  "description": "The participant's group (`grp_…`), or `null` for Default. Their new referrals earn this group's rewards.",
      +  "type": [
      +    "string",
      +    "null"
      +  ]
      +}
    • addedOutput schema / properties / groupSource
      Added value: +{
      +  "description": "How the participant got into their group: `MANUAL` (a move, including a move to Default), `LINK` (the group's signup link), `EMAIL`, or `DOMAIN` (a group rule). `null` when no group placement was ever made.",
      +  "enum": [
      +    "MANUAL",
      +    "LINK",
      +    "EMAIL",
      +    "DOMAIN",
      +    null
      +  ],
      +  "type": [
      +    "string",
      +    "null"
      +  ]
      +}
    • addedOutput schema / properties / rewards / items / properties / groupId
      Added value: +{
      +  "description": "The group whose reward this is (`grp_…`), saved when it was earned. `null` for Default and for rewards earned before groups existed.",
      +  "type": [
      +    "string",
      +    "null"
      +  ]
      +}
  2. Changed3 schema fields changedv0.19.28
    • changedOutput schema / properties / rewards / items / properties / amount / description
      Previous value: -"What this reward delivered, in major units, when the reward records a delivered amount (such as a gift card). Read from this reward, not from the Campaign Reward's configured amount. `null` for every other reward."New value: +"What this reward is worth, in major units of `currencyISO`: the coupon, account credit, payout, or gift card the provider confirmed, or else the amount saved on the reward when it was earned. Later Campaign Reward or integration changes do not change it. `null` for a percent-off coupon (see `percentOff`) or when no amount is available."
    • addedOutput schema / properties / rewards / items / properties / amountSource
      Added value: +{
      +  "description": "Where `amount` or `percentOff` comes from. `METADATA` means the amount saved on the reward when it was earned; any other value names the provider. `null` when both are `null`.",
      +  "enum": [
      +    "STRIPE",
      +    "CHARGEBEE",
      +    "RECURLY",
      +    "CHARGIFY",
      +    "PAYPAL",
      +    "VENMO",
      +    "TANGO_CARD",
      +    "TREMENDOUS",
      +    "XTRM",
      +    "METADATA",
      +    null
      +  ],
      +  "type": [
      +    "string",
      +    "null"
      +  ]
      +}
    • addedOutput schema / properties / rewards / items / properties / percentOff
      Added value: +{
      +  "description": "Discount of a percent-off coupon (`20` = 20% off). `null` for every other reward. Never add it to money amounts.",
      +  "type": [
      +    "number",
      +    "null"
      +  ]
      +}
  3. Changed4 schema fields changedv0.19.27
    • addedOutput schema / properties / referralLeadQualifiedAt
      Added value: +{
      +  "description": "When this referred signup counted as a lead for the referrer, in Unix milliseconds. Set only when the program's `referralTrigger` is `CUSTOM`. Lead-event Campaign Rewards and commissions use it.",
      +  "type": [
      +    "integer",
      +    "null"
      +  ]
      +}
    • changedOutput schema / properties / referrer / description
      Previous value: -"Summary of the participant's referrer (same core fields as a participant). Present only when the participant was referred."New value: +"The participant's referrer. It has the same fields as a participant, and its own `referrer` is always `null`. Present only when the participant was referred."
    • addedOutput schema / properties / rewards / items / properties / amount
      Added value: +{
      +  "description": "What this reward delivered, in major units, when the reward records a delivered amount (such as a gift card). Read from this reward, not from the Campaign Reward's configured amount. `null` for every other reward.",
      +  "type": [
      +    "number",
      +    "null"
      +  ]
      +}
    • addedOutput schema / properties / rewards / items / properties / currencyISO
      Added value: +{
      +  "description": "The ISO 4217 currency code for `amount`. `null` whenever `amount` is `null`.",
      +  "type": [
      +    "string",
      +    "null"
      +  ]
      +}
  4. Changed2 schema fields changedv0.19.23
    • changedOutput schema / properties / referralSource / description
      Previous value: -"How the participant joined the program."New value: +"How the participant joined the program. `DIRECT` means without a referrer, `PARTICIPANT` means through a participant referral, `IMPORT` means through a CSV import, `MANUAL` means through the dashboard, and `DELETED_PARTICIPANT` means the original referrer was later deleted."
    • changedOutput schema / properties / referralSource / enum
      Previous value: -[
      -  "DIRECT",
      -  "PARTICIPANT"
      -]New value: +[
      +  "DIRECT",
      +  "PARTICIPANT",
      +  "DELETED_PARTICIPANT",
      +  "IMPORT",
      +  "MANUAL"
      +]
  5. Changed3 schema fields changedv0.19.15
    • addedInput schema / properties / campaignId / minLength
      Added value: +1
    • addedInput schema / required
      Added value: +[
      +  "campaignId"
      +]
    • addedOutput schema / properties / language
      Added value: +{
      +  "description": "The language code of the participant's portal and program emails, such as `es`. The program's base language unless the participant (or you) picked another of the program's languages.",
      +  "type": "string"
      +}
  6. Changed1 schema field changedv0.19.9
    • changedInput schema / properties / campaignId / description
      Previous value: -"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."New value: +"Target program (campaign) id for this call. Defaults to GROWSURF_CAMPAIGN_ID when omitted. Program IDs also identify newly created programs without restarting the server."
  7. Changed1 schema field changedv0.18.1
    • addedOutput schema / properties / leadCount
      Added value: +{
      +  "description": "Pending referrals that have not converted yet.",
      +  "type": "integer"
      +}
  8. Changed5 schema fields changedv0.14.0
    • 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"
      +]
  9. First observedv0.12.2

TDQS

A3.9/5.0
Behavior4/5

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is fully covered. The description goes beyond them by interpreting domain fields: referralStatus vs referralCount semantics (including that zero referrals is consistent with CREDIT_AWARDED) and the distinction between reward approval and fulfillment marking. It omits auth requirements, error behavior for unknown IDs/emails, and rate limits, which keeps it below 5.

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

Conciseness4/5

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

Purpose and lookup keys are front-loaded in the opening sentence, followed by tightly packed field semantics. Every sentence carries information, though the referral/reward explanations are dense and would read better as discrete points rather than a continuous paragraph.

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

Completeness4/5

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

For a low-complexity read-only lookup with an output schema present, the definition covers what the agent needs to call it and how to interpret the more confusing response fields. Remaining gaps are minor: no statement of behavior when the participant is not found, and no clarification of the ID-vs-email precedence.

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

Parameters3/5

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

Schema coverage is only 33%: participantId and participantEmail have no schema descriptions, so the description must compensate, and it does explain that either identifier can be used to fetch the participant. The campaignId sentence largely restates the schema's own default-to-GROWSURF_CAMPAIGN_ID wording, and it never says whether the two identifiers are mutually exclusive or what happens if both are supplied, which the anyOf in the schema implies but the prose does not clarify.

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 first sentence states a specific verb and resource ('Fetch a single participant') and names the two lookup keys (GrowSurf participant ID or email address), which cleanly separates it from sibling list/analytics/update tools. An agent can identify the operation without opening the schema.

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

Usage Guidelines3/5

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

The description implies usage by stating the accepted identifiers and by explaining that campaignId is used when passed, otherwise the GROWSURF_CAMPAIGN_ID default. However, it never says when to prefer this tool over siblings such as growsurf_get_participant_analytics or growsurf_update_participant, and gives no exclusions or prerequisites. Guidance is implied rather than explicit.

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

Deploy Server

Other Tools