> For the complete documentation index, see [llms.txt](https://docs.growsurf.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.growsurf.com/developer-tools/rest-api/api-objects.md).

# Objects

## Team

```json
{"openapi":"3.1.0","info":{"title":"GrowSurf REST API","version":"2.0.0"},"components":{"schemas":{"Team":{"type":"object","description":"The team bound to the API key or OAuth connection.","required":["name","verificationStatus","verificationRequestedAt"],"properties":{"name":{"description":"The team's display name.","type":"string"},"verificationStatus":{"type":"string","enum":["NOT_REQUESTED","REQUESTED","VERIFIED"],"readOnly":true,"description":"GrowSurf team verification state. `VERIFIED` is required before a program can send participant emails."},"verificationRequestedAt":{"type":"integer","format":"int64","nullable":true,"readOnly":true,"description":"When team verification was last requested, as a Unix timestamp in milliseconds."}}}}}}
```

***

## Campaign

```json
{"openapi":"3.1.0","info":{"title":"GrowSurf REST API","version":"2.0.0"},"components":{"schemas":{"Campaign":{"type":"object","description":"Detailed information about a GrowSurf program.","required":["id","name","type","referralCount","participantCount","impressionCount","inviteCount","winnerCount","status","rewards"],"properties":{"id":{"type":"string","readOnly":true,"description":"The unique identifier of the program."},"name":{"type":"string","description":"The program name (internal only, never exposed to participants)."},"type":{"$ref":"#/components/schemas/CampaignType","description":"The program type."},"referralCount":{"type":"integer","readOnly":true,"description":"The total referral count."},"participantCount":{"type":"integer","readOnly":true,"description":"The total participant count."},"impressionCount":{"type":"integer","readOnly":true,"description":"The total number of impressions — the collective number of times participants' unique referral links have been viewed."},"inviteCount":{"type":"integer","readOnly":true,"description":"The total number of invites sent by participants."},"winnerCount":{"type":"integer","readOnly":true,"description":"The total number of winners — all participants with at least one approved reward (includes referrers and referred friends)."},"currencyISO":{"type":["string","null"],"minLength":3,"maxLength":3,"description":"The program currency as an [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) code (e.g., `USD`, `GBP`)."},"status":{"$ref":"#/components/schemas/CampaignStatus","description":"The program status."},"rewards":{"type":"array","items":{"$ref":"#/components/schemas/Reward"},"description":"The list of rewards associated with the program."}}},"CampaignType":{"type":"string","enum":["REFERRAL","AFFILIATE"]},"CampaignStatus":{"type":"string","enum":["DRAFT","IN_PROGRESS","COMPLETE","DELETED"]},"Reward":{"type":"object","description":"A single campaign reward (also known as a `CampaignReward`). This is different from a `ParticipantReward`, which is a reward earned by a participant.","required":["id","type","isUnlimited","metadata"],"properties":{"id":{"type":"string","readOnly":true,"description":"The unique identifier of the campaign reward. You can find this ID from *Program Editor > 1. Rewards* and clicking the reward."},"type":{"$ref":"#/components/schemas/RewardType","description":"The reward type."},"title":{"type":["string","null"],"description":"The reward title (internal only, never exposed to participants)."},"isVisible":{"type":"boolean","description":"Whether the reward is enabled. When `false`, the reward is disabled: it is no longer awarded, and it is hidden from participants, including those who already earned it. Set `true` for the reward to be visible and awardable."},"description":{"type":["string","null"],"description":"The reward description shown to the referrer."},"referralDescription":{"type":["string","null"],"description":"The reward description shown to the referred friend (only applicable for double-sided reward types)."},"referredRewardUpfront":{"type":"boolean","description":"Only applies to double-sided rewards. When `true`, the referred friend's reward is delivered upfront as a discount and no `ParticipantReward` is created for them when the referral triggers."},"isUnlimited":{"type":"boolean","description":"`true` if this reward can be earned by a single participant an unlimited number of times."},"limit":{"type":["integer","null"],"description":"The number of times a participant can earn this reward (overridden when `isUnlimited` is `true`). `-1` represents an unlimited reward in REST responses."},"conversionsRequired":{"type":["integer","null"],"description":"The number of referrals a participant must make to earn this reward."},"numberOfWinners":{"type":["integer","null"],"description":"The maximum number of winners. Only applies to `LEADERBOARD` rewards. When `limitDuration` is `PER_MONTH`, this many top referrers win each month; otherwise this many win in total."},"limitDuration":{"type":["string","null"],"enum":["IN_TOTAL","PER_MONTH","PER_YEAR",null],"description":"Whether the reward can be earned in total, on a monthly basis, or on a yearly basis."},"imageUrl":{"type":["string","null"],"description":"The reward image URL."},"couponCode":{"type":["string","null"],"description":"A static coupon code shown to the referrer in the reward-won email and webhook. Display text only; GrowSurf does not create or validate it in any billing system. If the program has a connected billing integration (Stripe, Chargebee, or Recurly) that issues a coupon for the referral, that issued code is shown instead."},"order":{"type":["integer","null"],"description":"If there are multiple rewards, the order in which the reward should be displayed. `null` by default until set within the Design step of the program editor."},"nextMilestonePrefix":{"type":["string","null"],"description":"Text displayed in front of a participant's referral count for UI purposes (e.g., \"You are only\"). Applicable for milestone rewards (when `type` is `MILESTONE`)."},"nextMilestoneSuffix":{"type":["string","null"],"description":"Text displayed after a participant's referral count for UI purposes (e.g., \"referrals away from receiving a nice reward!\"). Applicable for milestone rewards (when `type` is `MILESTONE`)."},"metadata":{"$ref":"#/components/schemas/Metadata","description":"The reward metadata."},"commissionStructure":{"oneOf":[{"$ref":"#/components/schemas/CommissionStructure"},{"type":"null"}],"description":"The reward commission structure. Present only for affiliate programs."},"referralCouponCode":{"type":["string","null"],"description":"A static coupon code shown to the referred friend in the reward-won email and webhook (double-sided rewards). Same caveats as `couponCode`: display text only, not created or validated in any billing system, and superseded by a connected billing integration's issued coupon when one exists."},"value":{"oneOf":[{"$ref":"#/components/schemas/RewardTaxValuation"},{"type":"null"}],"description":"Tax valuation for the reward (the referrer's side of a double-sided reward). `null` when no valuation is set."},"referredValue":{"oneOf":[{"$ref":"#/components/schemas/RewardTaxValuation"},{"type":"null"}],"description":"Tax valuation for the referred friend's side of a double-sided reward. `null` when no valuation is set."}}},"RewardType":{"type":"string","enum":["SINGLE_SIDED","DOUBLE_SIDED","MILESTONE","LEADERBOARD","AFFILIATE"]},"Metadata":{"type":"object","description":"Shallow custom metadata object.","additionalProperties":true},"CommissionStructure":{"type":"object","description":"The commission configuration for an affiliate reward. Present only for affiliate programs.","properties":{"amount":{"type":["integer","null"],"description":"Fixed commission amount in the currency's smallest denomination, used when `type` is `FIXED`. `null` for percentage-based commissions."},"amountISO":{"type":["string","null"],"description":"ISO 4217 currency code for the fixed `amount`. Defaults to the program's currency when omitted. Must match the campaign `currencyISO` when provided. `null` for percentage-based commissions."},"event":{"type":["string","null"],"description":"The event that generates a commission (e.g., `SALE`)."},"type":{"type":["string","null"],"enum":["PERCENT","FIXED",null],"description":"How the commission is calculated: `PERCENT` (a percentage of the sale) or `FIXED` (a fixed `amount`)."},"minPaidReferrals":{"type":["integer","null"],"description":"The minimum number of paid referrals required before commissions are earned."},"holdDuration":{"type":["integer","null"],"description":"Number of days a commission is held before it can be paid out."},"duration":{"type":["string","null"],"description":"How long commissions continue to be earned for a referred customer."},"durationInMonths":{"type":["integer","null"],"description":"When `duration` is repeating, the number of months over which commissions are earned."},"approvalRequired":{"type":["boolean","null"],"description":"`true` if commissions require manual approval before they can be paid out."},"percent":{"type":["number","null"],"description":"The commission percentage, used when `type` is `PERCENT`."},"hasMaxAmount":{"type":["boolean","null"],"description":"`true` if a maximum commission amount cap is configured."},"maxAmount":{"type":["integer","null"],"description":"The maximum commission amount cap in the currency's smallest denomination. `null` if no cap is set."},"maxAmountISO":{"type":["string","null"],"description":"The [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code for `maxAmount`. Must match the campaign `currencyISO` when provided."},"hasIntro":{"type":["boolean","null"],"description":"`true` if an introductory commission rate is configured."},"introType":{"type":["string","null"],"description":"How the introductory commission is calculated: `PERCENT` or `FIXED`."},"introPercent":{"type":["number","null"],"description":"The introductory commission percentage, used when `introType` is `PERCENT`."},"introAmount":{"type":["integer","null"],"description":"The introductory commission amount in the currency's smallest denomination, used when `introType` is `FIXED`."},"introAmountISO":{"type":["string","null"],"description":"The [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code for `introAmount`. Must match the campaign `currencyISO` when provided."},"introDuration":{"type":["string","null"],"description":"How long the introductory rate applies."},"introDurationInMonths":{"type":["integer","null"],"description":"When `introDuration` is repeating, the number of months the introductory rate applies."}},"additionalProperties":false},"RewardTaxValuation":{"type":"object","description":"Tax valuation settings for a reward. Only relevant when the program collects tax documentation.","properties":{"fairMarketValueUSD":{"type":["number","null"],"minimum":0,"description":"Manual fair-market value in USD (major units) used as the fallback when the reward value cannot be resolved automatically. `null` = no manual value."},"isTaxReportable":{"type":["boolean","null"],"description":"Whether the reward's value counts toward 1099 thresholds/totals. `null` = use the smart default for the reward's source."}}}}}}
```

***

## Reward

```json
{"openapi":"3.1.0","info":{"title":"GrowSurf REST API","version":"2.0.0"},"components":{"schemas":{"Reward":{"type":"object","description":"A single campaign reward (also known as a `CampaignReward`). This is different from a `ParticipantReward`, which is a reward earned by a participant.","required":["id","type","isUnlimited","metadata"],"properties":{"id":{"type":"string","readOnly":true,"description":"The unique identifier of the campaign reward. You can find this ID from *Program Editor > 1. Rewards* and clicking the reward."},"type":{"$ref":"#/components/schemas/RewardType","description":"The reward type."},"title":{"type":["string","null"],"description":"The reward title (internal only, never exposed to participants)."},"isVisible":{"type":"boolean","description":"Whether the reward is enabled. When `false`, the reward is disabled: it is no longer awarded, and it is hidden from participants, including those who already earned it. Set `true` for the reward to be visible and awardable."},"description":{"type":["string","null"],"description":"The reward description shown to the referrer."},"referralDescription":{"type":["string","null"],"description":"The reward description shown to the referred friend (only applicable for double-sided reward types)."},"referredRewardUpfront":{"type":"boolean","description":"Only applies to double-sided rewards. When `true`, the referred friend's reward is delivered upfront as a discount and no `ParticipantReward` is created for them when the referral triggers."},"isUnlimited":{"type":"boolean","description":"`true` if this reward can be earned by a single participant an unlimited number of times."},"limit":{"type":["integer","null"],"description":"The number of times a participant can earn this reward (overridden when `isUnlimited` is `true`). `-1` represents an unlimited reward in REST responses."},"conversionsRequired":{"type":["integer","null"],"description":"The number of referrals a participant must make to earn this reward."},"numberOfWinners":{"type":["integer","null"],"description":"The maximum number of winners. Only applies to `LEADERBOARD` rewards. When `limitDuration` is `PER_MONTH`, this many top referrers win each month; otherwise this many win in total."},"limitDuration":{"type":["string","null"],"enum":["IN_TOTAL","PER_MONTH","PER_YEAR",null],"description":"Whether the reward can be earned in total, on a monthly basis, or on a yearly basis."},"imageUrl":{"type":["string","null"],"description":"The reward image URL."},"couponCode":{"type":["string","null"],"description":"A static coupon code shown to the referrer in the reward-won email and webhook. Display text only; GrowSurf does not create or validate it in any billing system. If the program has a connected billing integration (Stripe, Chargebee, or Recurly) that issues a coupon for the referral, that issued code is shown instead."},"order":{"type":["integer","null"],"description":"If there are multiple rewards, the order in which the reward should be displayed. `null` by default until set within the Design step of the program editor."},"nextMilestonePrefix":{"type":["string","null"],"description":"Text displayed in front of a participant's referral count for UI purposes (e.g., \"You are only\"). Applicable for milestone rewards (when `type` is `MILESTONE`)."},"nextMilestoneSuffix":{"type":["string","null"],"description":"Text displayed after a participant's referral count for UI purposes (e.g., \"referrals away from receiving a nice reward!\"). Applicable for milestone rewards (when `type` is `MILESTONE`)."},"metadata":{"$ref":"#/components/schemas/Metadata","description":"The reward metadata."},"commissionStructure":{"oneOf":[{"$ref":"#/components/schemas/CommissionStructure"},{"type":"null"}],"description":"The reward commission structure. Present only for affiliate programs."},"referralCouponCode":{"type":["string","null"],"description":"A static coupon code shown to the referred friend in the reward-won email and webhook (double-sided rewards). Same caveats as `couponCode`: display text only, not created or validated in any billing system, and superseded by a connected billing integration's issued coupon when one exists."},"value":{"oneOf":[{"$ref":"#/components/schemas/RewardTaxValuation"},{"type":"null"}],"description":"Tax valuation for the reward (the referrer's side of a double-sided reward). `null` when no valuation is set."},"referredValue":{"oneOf":[{"$ref":"#/components/schemas/RewardTaxValuation"},{"type":"null"}],"description":"Tax valuation for the referred friend's side of a double-sided reward. `null` when no valuation is set."}}},"RewardType":{"type":"string","enum":["SINGLE_SIDED","DOUBLE_SIDED","MILESTONE","LEADERBOARD","AFFILIATE"]},"Metadata":{"type":"object","description":"Shallow custom metadata object.","additionalProperties":true},"CommissionStructure":{"type":"object","description":"The commission configuration for an affiliate reward. Present only for affiliate programs.","properties":{"amount":{"type":["integer","null"],"description":"Fixed commission amount in the currency's smallest denomination, used when `type` is `FIXED`. `null` for percentage-based commissions."},"amountISO":{"type":["string","null"],"description":"ISO 4217 currency code for the fixed `amount`. Defaults to the program's currency when omitted. Must match the campaign `currencyISO` when provided. `null` for percentage-based commissions."},"event":{"type":["string","null"],"description":"The event that generates a commission (e.g., `SALE`)."},"type":{"type":["string","null"],"enum":["PERCENT","FIXED",null],"description":"How the commission is calculated: `PERCENT` (a percentage of the sale) or `FIXED` (a fixed `amount`)."},"minPaidReferrals":{"type":["integer","null"],"description":"The minimum number of paid referrals required before commissions are earned."},"holdDuration":{"type":["integer","null"],"description":"Number of days a commission is held before it can be paid out."},"duration":{"type":["string","null"],"description":"How long commissions continue to be earned for a referred customer."},"durationInMonths":{"type":["integer","null"],"description":"When `duration` is repeating, the number of months over which commissions are earned."},"approvalRequired":{"type":["boolean","null"],"description":"`true` if commissions require manual approval before they can be paid out."},"percent":{"type":["number","null"],"description":"The commission percentage, used when `type` is `PERCENT`."},"hasMaxAmount":{"type":["boolean","null"],"description":"`true` if a maximum commission amount cap is configured."},"maxAmount":{"type":["integer","null"],"description":"The maximum commission amount cap in the currency's smallest denomination. `null` if no cap is set."},"maxAmountISO":{"type":["string","null"],"description":"The [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code for `maxAmount`. Must match the campaign `currencyISO` when provided."},"hasIntro":{"type":["boolean","null"],"description":"`true` if an introductory commission rate is configured."},"introType":{"type":["string","null"],"description":"How the introductory commission is calculated: `PERCENT` or `FIXED`."},"introPercent":{"type":["number","null"],"description":"The introductory commission percentage, used when `introType` is `PERCENT`."},"introAmount":{"type":["integer","null"],"description":"The introductory commission amount in the currency's smallest denomination, used when `introType` is `FIXED`."},"introAmountISO":{"type":["string","null"],"description":"The [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code for `introAmount`. Must match the campaign `currencyISO` when provided."},"introDuration":{"type":["string","null"],"description":"How long the introductory rate applies."},"introDurationInMonths":{"type":["integer","null"],"description":"When `introDuration` is repeating, the number of months the introductory rate applies."}},"additionalProperties":false},"RewardTaxValuation":{"type":"object","description":"Tax valuation settings for a reward. Only relevant when the program collects tax documentation.","properties":{"fairMarketValueUSD":{"type":["number","null"],"minimum":0,"description":"Manual fair-market value in USD (major units) used as the fallback when the reward value cannot be resolved automatically. `null` = no manual value."},"isTaxReportable":{"type":["boolean","null"],"description":"Whether the reward's value counts toward 1099 thresholds/totals. `null` = use the smart default for the reward's source."}}}}}}
```

***

## Webhook

```json
{"openapi":"3.1.0","info":{"title":"GrowSurf REST API","version":"2.0.0"},"components":{"schemas":{"Webhook":{"type":"object","description":"A program webhook's configuration (payload URL, subscribed events, enabled state) plus read-only delivery-health fields.","required":["id","events","isEnabled","autoDisabledDueToFailures","failureCount"],"properties":{"id":{"type":"string","readOnly":true,"description":"The webhook id (`primary` for the program's primary webhook)."},"payloadUrl":{"type":"string","nullable":true,"description":"The URL that receives webhook deliveries."},"events":{"description":"Webhook events this endpoint is subscribed to.","type":"array","items":{"$ref":"#/components/schemas/WebhookEvent"}},"isEnabled":{"description":"Whether deliveries to this webhook are enabled.","type":"boolean"},"autoDisabledDueToFailures":{"type":"boolean","readOnly":true,"description":"Read-only. Whether GrowSurf auto-disabled this webhook after repeated delivery failures."},"failureCount":{"type":"integer","readOnly":true,"description":"Read-only. Consecutive delivery failures."},"lastFailureAt":{"type":"integer","format":"int64","nullable":true,"readOnly":true,"description":"Read-only. When the last delivery failure occurred, as a Unix timestamp in milliseconds."}}},"WebhookEvent":{"type":"string","description":"A webhook event name (the events GrowSurf delivers to subscribed webhooks).","enum":["PARTICIPANT_REACHED_A_GOAL","NEW_PARTICIPANT_ADDED","CAMPAIGN_ENDED","PARTICIPANT_FRAUD_STATUS_UPDATED","NEW_COMMISSION_ADDED","COMMISSION_ADJUSTED","NEW_PAYOUT_ISSUED"]}}}}
```

***

## Participant

```json
{"openapi":"3.1.0","info":{"title":"GrowSurf REST API","version":"2.0.0"},"components":{"schemas":{"Participant":{"type":"object","description":"Detailed information about a program participant.","required":["id","referralCount","monthlyReferralCount","rank","monthlyRank","shareUrl","rewards","email"],"properties":{"id":{"type":"string","readOnly":true,"description":"The unique identifier of the participant."},"firstName":{"type":["string","null"],"description":"The first name of the participant."},"lastName":{"type":["string","null"],"description":"The last name of the participant."},"email":{"type":"string","description":"The email of the participant."},"paypalEmailAddress":{"type":"string","format":"email","description":"The PayPal email address on file for the participant, used for affiliate or PayPal reward payouts."},"referralCount":{"type":"integer","readOnly":true,"description":"The total number of referrals made by the participant."},"monthlyReferralCount":{"type":"integer","readOnly":true,"description":"The total number of referrals made this month by the participant (resets at the end of the month)."},"prevMonthlyReferralCount":{"type":"integer","readOnly":true,"description":"The total number of referrals made the previous month by the participant."},"rank":{"type":"integer","readOnly":true,"description":"The rank of the participant."},"monthlyRank":{"type":"integer","readOnly":true,"description":"The monthly rank of the participant. This rank resets to 0 at the end of each month."},"prevMonthlyRank":{"type":"integer","readOnly":true,"description":"The previous monthly rank of the participant. Not returned if the participant did not exist in your program during the previous month."},"shareUrl":{"type":"string","readOnly":true,"description":"The unique share URL of the participant."},"createdAt":{"type":"integer","format":"int64","readOnly":true,"description":"The date the participant was added to the program (UTC milliseconds)."},"referralSource":{"$ref":"#/components/schemas/ReferralSource","readOnly":true,"description":"The source of how the participant joined the program."},"referralStatus":{"$ref":"#/components/schemas/ReferralStatus","description":"If the participant was referred, the referrer's status in receiving the referral credit. Only applicable if the participant was referred into the program."},"referredBy":{"type":"string","description":"The ID of the referrer. Only applicable if the participant was referred into the program."},"fraudRiskLevel":{"$ref":"#/components/schemas/FraudRiskLevel","readOnly":true,"description":"A value that represents the integrity of the participant."},"fraudReasonCode":{"type":"string","readOnly":true,"description":"The reason for the participant's `fraudRiskLevel`:\n\n- `UNIQUE_IDENTITY` — They have a unique identity (no other participant has the same identity).\n- `DUPLICATE_EMAIL` — Their email is not unique and is identical to another participant's email (e.g., gavin@hooli.com = gavin+1@hooli.com).\n- `DUPLICATE_IDENTITY` — Their identity (fingerprint or mobile instance ID) is not unique and matches another participant's.\n- `DUPLICATE_IDENTITY_EXCESSIVE` — Within a small window of time, they had an excessive number of referred participants who also shared the same IP address.\n- `EMAIL_FRAUD` — Their email was found to match another participant's when updated in a connected billing or payment integration.\n- `SIMILAR_EMAIL` — Their browser fingerprint matches another participant's and their email looks suspiciously similar.\n- `SIMILAR_FIRST_NAME` — Their browser fingerprint matches another participant's and their first name looks suspiciously similar.\n- `SIMILAR_LAST_NAME` — Their browser fingerprint matches another participant's and their last name looks suspiciously similar.\n- `REFERRAL_EMAIL_PATTERN` — (Status for a referred person) Their email matched a similar pattern to their referrer's email.\n- `REFERRAL_CHAIN_FRAUD` — (Status for a referrer or referred person) Their characteristics matched a pattern with other referrals the referrer made, indicating a fraud ring.\n- `REFERRAL_VELOCITY_FRAUD` — (Status for a referrer or referred person) The referrer made an excessive number of referrals in a short period of time.\n- `DOMAIN_CLUSTERING_FRAUD` — (Status for a referrer or referred person) The referrer made an excessive number of referrals sharing the same suspicious domain in a short period of time.\n- `MANUAL_UPDATE` — They were manually marked as a fraudster from the GrowSurf dashboard.\n- `WHITELISTED` — They were allowed to join the program because one of their properties matched an allowed value.\n- `BLACKLIST_MATCH` — They were not allowed to join the program because one of their properties matched a blocked value.\n- `BLOCKED_IP` — They were not allowed to join the program because their IP address was recently blocked by antifraud IP throttling.\n- `REFERRER_HIGH_RISK` — They were not allowed to join the program because their referrer was a high-risk fraudster."},"isWinner":{"type":"boolean","readOnly":true,"description":"`true` if the participant has earned one or more rewards."},"shareCount":{"type":"object","readOnly":true,"additionalProperties":{"type":"integer"},"description":"An object containing counts of how many times the participant has shared their referral link, keyed by channel. Standard web channels include `email`, `facebook`, and `twitter`; SDK/native-share channels include `iosNativeShare` and `androidNativeShare`."},"impressionCount":{"type":"integer","readOnly":true,"description":"The total number of impressions the participant has made."},"uniqueImpressionCount":{"type":"integer","readOnly":true,"description":"The total number of unique impressions the participant has made."},"inviteCount":{"type":"integer","readOnly":true,"description":"The total number of invites the participant has sent."},"referrals":{"type":"array","readOnly":true,"items":{"type":"string"},"description":"A list of `Participant` IDs who were successfully referred by the participant. Limited to the 100 most recently referred friends."},"monthlyReferrals":{"type":"array","readOnly":true,"items":{"type":"string"},"description":"A list of `Participant` IDs successfully referred by the participant this month (resets at the end of the month). Limited to the 100 most recent."},"referrer":{"readOnly":true,"oneOf":[{"$ref":"#/components/schemas/ParticipantReferrer"},{"type":"null"}],"description":"An object containing the participant's referrer information. Only applicable if the participant was referred into the program."},"ipAddress":{"type":["string","null"],"description":"The IP address associated with the participant, used for anti-fraud matching."},"fingerprint":{"type":["string","null"],"description":"The browser fingerprint associated with the participant, used for anti-fraud matching."},"mobileInstanceId":{"type":["string","null"],"description":"App-install scoped mobile identifier used for anti-fraud matching when provided by native mobile apps. The official mobile SDKs generate this as a lowercase UUID. Not stored when strict GDPR/CCPA mode is enabled."},"metadata":{"$ref":"#/components/schemas/Metadata","description":"An object containing any custom key-value data, useful for saving additional data for the participant (e.g., `company`, `companySize`). Metadata is never used by GrowSurf and usage is optional. Metadata is returned only in REST API calls, and never in JavaScript Web API calls. See [API Guidelines](https://docs.growsurf.com/developer-tools/rest-api/api-guidelines)."},"notes":{"type":["string","null"],"description":"Internal notes about the participant, added via the [GrowSurf Dashboard](https://growsurf.com/dashboard)."},"unsubscribed":{"type":"boolean","description":"`true` if the participant has unsubscribed from program emails."},"rewards":{"type":"array","readOnly":true,"items":{"$ref":"#/components/schemas/ParticipantReward"},"description":"A list of the rewards the participant has earned."},"vanityKeys":{"type":"array","items":{"type":"string"},"description":"The list of vanity keys that the participant has."},"unreadCommissionsCount":{"type":"integer","readOnly":true,"description":"Affiliate programs only. The number of commissions the participant has not yet viewed."},"unreadPayoutsCount":{"type":"integer","readOnly":true,"description":"Affiliate programs only. The number of payouts the participant has not yet viewed."},"isNew":{"type":"boolean","readOnly":true,"description":"Whether this participant was newly created by the request. Returned by participant creation calls; `false` when the participant already existed."},"allMatchingFraudsters":{"type":"array","readOnly":true,"items":{"type":"object","additionalProperties":true},"description":"A list of other participants flagged as matching this participant during anti-fraud checks."},"payoutSettings":{"type":"object","readOnly":true,"description":"Payout-related actions the participant must complete before a payout can be released (e.g. confirming a PayPal email or submitting a W-9/W-8 tax form). Always present; the requiredActions array is empty when no action is required.","properties":{"requiredActions":{"description":"Actions the participant must complete before payouts can be sent.","type":"array","readOnly":true,"items":{"type":"string","enum":["PAYPAL_EMAIL","TAX_INFO"]}}}}}},"ReferralSource":{"type":"string","enum":["DIRECT","PARTICIPANT"]},"ReferralStatus":{"type":"string","enum":["CREDIT_PENDING","CREDIT_AWARDED","CREDIT_EXPIRED","INVITE_SENT"]},"FraudRiskLevel":{"type":"string","enum":["LOW","MEDIUM","HIGH"]},"ParticipantReferrer":{"type":"object","description":"Summary information about a participant's referrer, returned within the `referrer` field of a `Participant`.","properties":{"id":{"type":"string","description":"The unique identifier of the referrer."},"firstName":{"type":["string","null"],"description":"The first name of the referrer."},"lastName":{"type":["string","null"],"description":"The last name of the referrer."},"email":{"type":"string","description":"The email of the referrer."},"referralCount":{"type":"integer","description":"The total number of referrals made by the referrer."},"monthlyReferralCount":{"type":"integer","description":"The total number of referrals made this month by the referrer (resets at the end of the month)."},"prevMonthlyReferralCount":{"type":"integer","description":"The total number of referrals made the previous month by the referrer."},"rank":{"type":"integer","description":"The rank of the referrer."},"monthlyRank":{"type":"integer","description":"The monthly rank of the referrer. This rank resets to 0 at the end of each month."},"prevMonthlyRank":{"type":"integer","description":"The previous monthly rank of the referrer."},"shareUrl":{"type":"string","description":"The unique share URL of the referrer."},"createdAt":{"type":"integer","format":"int64","description":"The date the referrer was added to the program (UTC milliseconds)."},"referralSource":{"$ref":"#/components/schemas/ReferralSource","description":"The source of how the referrer joined the program."},"referralStatus":{"$ref":"#/components/schemas/ReferralStatus","description":"If the referrer was themselves referred, their referrer's status in receiving the referral credit."},"fraudRiskLevel":{"$ref":"#/components/schemas/FraudRiskLevel","description":"A value that represents the integrity of the referrer."},"fraudReasonCode":{"type":"string","description":"The reason for the referrer's `fraudRiskLevel`. See `Participant.fraudReasonCode` for the list of possible values."},"isWinner":{"type":"boolean","description":"`true` if the referrer has earned one or more rewards."},"shareCount":{"type":"object","additionalProperties":{"type":"integer"},"description":"An object containing counts of how many times the referrer has shared their referral link, keyed by channel."},"impressionCount":{"type":"integer","description":"The total number of impressions the referrer has made."},"uniqueImpressionCount":{"type":"integer","description":"The total number of unique impressions the referrer has made."},"inviteCount":{"type":"integer","description":"The total number of invites the referrer has sent."},"referrals":{"type":"array","items":{"type":"string"},"description":"A list of `Participant` IDs who were successfully referred by the referrer. Limited to the 100 most recent."},"monthlyReferrals":{"type":"array","items":{"type":"string"},"description":"A list of `Participant` IDs successfully referred by the referrer this month (resets at the end of the month). Limited to the 100 most recent."},"ipAddress":{"type":["string","null"],"description":"The IP address associated with the referrer, used for anti-fraud matching."},"fingerprint":{"type":["string","null"],"description":"The browser fingerprint associated with the referrer, used for anti-fraud matching."},"metadata":{"$ref":"#/components/schemas/Metadata","description":"An object containing any custom key-value data for the referrer."},"unsubscribed":{"type":"boolean","description":"`true` if the referrer has unsubscribed from program emails."}}},"Metadata":{"type":"object","description":"Shallow custom metadata object.","additionalProperties":true},"ParticipantReward":{"type":"object","description":"A reward that a participant has earned. This is different from a program `Reward` Object and contains information pertinent only to the participant that earned the reward.","required":["id","rewardId","status"],"properties":{"id":{"type":"string","readOnly":true,"description":"The unique identifier of the participant's reward. This is different for every new reward the participant earns."},"rewardId":{"type":"string","readOnly":true,"description":"The ID of the program `Reward` (`CampaignReward`) that this participant has earned."},"status":{"$ref":"#/components/schemas/RewardStatus","readOnly":true,"description":"The status of the participant's reward."},"unread":{"type":"boolean","readOnly":true,"description":"`true` if the participant has not yet seen the reward in a GrowSurf window."},"approved":{"type":"boolean","readOnly":true,"description":"`true` if the participant's reward has been approved."},"approvedAt":{"type":["integer","null"],"format":"int64","readOnly":true,"description":"The date and time the reward was approved for this participant (UTC milliseconds). `null` for unapproved rewards."},"fulfilledAt":{"type":["integer","null"],"format":"int64","readOnly":true,"description":"The date and time the reward was fulfilled for this participant (UTC milliseconds). `null` for unapproved or unfulfilled rewards."},"isReferrer":{"type":"boolean","readOnly":true,"description":"`true` if the participant earned the reward as the referrer; `false` if they earned it as the referred friend (only applicable for double-sided reward types)."},"isAvailable":{"type":"boolean","readOnly":true,"description":"`true` if the reward is available for the participant to claim or redeem."},"isFulfilled":{"type":"boolean","readOnly":true,"description":"`true` if the participant's reward has been fulfilled."},"referredId":{"type":"string","readOnly":true,"description":"The ID of the friend that was referred."},"referrerId":{"type":"string","readOnly":true,"description":"The ID of the participant that made the referral."},"commissionStructure":{"readOnly":true,"oneOf":[{"$ref":"#/components/schemas/CommissionStructure"},{"type":"null"}],"description":"The commission structure associated with this reward. Present only for affiliate programs."}}},"RewardStatus":{"type":"string","enum":["PENDING","FULFILLED"]},"CommissionStructure":{"type":"object","description":"The commission configuration for an affiliate reward. Present only for affiliate programs.","properties":{"amount":{"type":["integer","null"],"description":"Fixed commission amount in the currency's smallest denomination, used when `type` is `FIXED`. `null` for percentage-based commissions."},"amountISO":{"type":["string","null"],"description":"ISO 4217 currency code for the fixed `amount`. Defaults to the program's currency when omitted. Must match the campaign `currencyISO` when provided. `null` for percentage-based commissions."},"event":{"type":["string","null"],"description":"The event that generates a commission (e.g., `SALE`)."},"type":{"type":["string","null"],"enum":["PERCENT","FIXED",null],"description":"How the commission is calculated: `PERCENT` (a percentage of the sale) or `FIXED` (a fixed `amount`)."},"minPaidReferrals":{"type":["integer","null"],"description":"The minimum number of paid referrals required before commissions are earned."},"holdDuration":{"type":["integer","null"],"description":"Number of days a commission is held before it can be paid out."},"duration":{"type":["string","null"],"description":"How long commissions continue to be earned for a referred customer."},"durationInMonths":{"type":["integer","null"],"description":"When `duration` is repeating, the number of months over which commissions are earned."},"approvalRequired":{"type":["boolean","null"],"description":"`true` if commissions require manual approval before they can be paid out."},"percent":{"type":["number","null"],"description":"The commission percentage, used when `type` is `PERCENT`."},"hasMaxAmount":{"type":["boolean","null"],"description":"`true` if a maximum commission amount cap is configured."},"maxAmount":{"type":["integer","null"],"description":"The maximum commission amount cap in the currency's smallest denomination. `null` if no cap is set."},"maxAmountISO":{"type":["string","null"],"description":"The [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code for `maxAmount`. Must match the campaign `currencyISO` when provided."},"hasIntro":{"type":["boolean","null"],"description":"`true` if an introductory commission rate is configured."},"introType":{"type":["string","null"],"description":"How the introductory commission is calculated: `PERCENT` or `FIXED`."},"introPercent":{"type":["number","null"],"description":"The introductory commission percentage, used when `introType` is `PERCENT`."},"introAmount":{"type":["integer","null"],"description":"The introductory commission amount in the currency's smallest denomination, used when `introType` is `FIXED`."},"introAmountISO":{"type":["string","null"],"description":"The [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code for `introAmount`. Must match the campaign `currencyISO` when provided."},"introDuration":{"type":["string","null"],"description":"How long the introductory rate applies."},"introDurationInMonths":{"type":["integer","null"],"description":"When `introDuration` is repeating, the number of months the introductory rate applies."}},"additionalProperties":false}}}}
```

***

## ParticipantCommission

```json
{"openapi":"3.1.0","info":{"title":"GrowSurf REST API","version":"2.0.0"},"components":{"schemas":{"ParticipantCommission":{"type":"object","description":"**Affiliate programs only.** A commission generated for a (referrer) participant in an affiliate program.","required":["id","referrerId","referredId","amount","saleAmount","currencyISO","status","createdAt"],"properties":{"id":{"type":"string","readOnly":true,"description":"The unique identifier of the participant commission."},"referrerId":{"type":"string","readOnly":true,"description":"The participant ID of the referrer who earned the commission."},"referredId":{"type":"string","readOnly":true,"description":"The participant ID of the referred friend (the conversion that triggered the commission)."},"amount":{"type":["integer","null"],"readOnly":true,"description":"Commission amount (what the affiliate earned) in the currency's smallest denomination (e.g., `100` cents equals $1.00 USD, and `100` equals ¥100 for a zero-decimal currency). Always non-negative when present; `null` if it could not be computed."},"saleAmount":{"type":["integer","null"],"readOnly":true,"description":"The sale amount from the transaction the referral paid, in the currency's smallest denomination. Always non-negative when present; `null` for commissions whose provider does not report a sale amount."},"currencyISO":{"type":"string","readOnly":true,"description":"The [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code of the commission (e.g., `USD`, `GBP`)."},"status":{"$ref":"#/components/schemas/CommissionStatus","readOnly":true,"description":"Current lifecycle state of the commission."},"approvedAt":{"type":["integer","null"],"format":"int64","readOnly":true,"description":"UTC timestamp (in milliseconds) when the commission was approved. `null` until the commission transitions to `APPROVED`."},"paidAt":{"type":["integer","null"],"format":"int64","readOnly":true,"description":"UTC timestamp (in milliseconds) when the commission was sent in a payout. `null` until the commission transitions to `PAID`."},"reversedAt":{"type":["integer","null"],"format":"int64","readOnly":true,"description":"UTC timestamp (in milliseconds) when the commission was reversed (for example, due to a refund or chargeback). `null` unless the commission transitions to `REVERSED`."},"holdDuration":{"type":["integer","null"],"readOnly":true,"description":"Number of days the commission must age before it can be processed for payout. Defaults to `0` (no hold)."},"payoutQueuedAt":{"type":["integer","null"],"format":"int64","readOnly":true,"description":"UTC timestamp (in milliseconds) when the commission was queued for payout. `null` if it has not been scheduled."},"provider":{"type":["string","null"],"readOnly":true,"description":"Origin of the commission event. For example, `stripe` or `api`."},"createdAt":{"type":"integer","format":"int64","readOnly":true,"description":"UTC timestamp (in milliseconds) when the commission record was created."},"amountInCampaignCurrency":{"type":["integer","null"],"readOnly":true,"description":"Commission amount converted to the program's currency, in the currency's smallest denomination. Always non-negative. `null` if the commission is still pending FX conversion."},"saleAmountInCampaignCurrency":{"type":["integer","null"],"readOnly":true,"description":"The sale amount converted to the program's currency, in the currency's smallest denomination. Always non-negative. `null` if the commission is still pending FX conversion."},"exchangeRate":{"type":["number","null"],"readOnly":true,"description":"The currency exchange rate used for conversion. `null` if the commission is still pending FX conversion."},"campaignCurrencyISO":{"type":["string","null"],"readOnly":true,"description":"The [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code of the program used in currency conversion (e.g., `USD`, `GBP`). `null` if the commission is still pending FX conversion."},"exchangeRateAt":{"type":["integer","null"],"format":"int64","readOnly":true,"description":"UTC timestamp (in milliseconds) when the currency exchange rate was received. `null` if the commission is still pending FX conversion."},"fxError":{"type":["string","null"],"readOnly":true,"description":"If there was an error with FX conversion, the specific details. `null` if conversion was successful."}}},"CommissionStatus":{"type":"string","enum":["PENDING","APPROVED","PAID","REVERSED","DELETED"]}}}}
```

{% hint style="success" %}
**Currency Exchange Note:**

If the referral makes a payment in a currency different from your program's currency (`Campaign.currencyISO`), the following foreign currency exchange-related fields can be used to normalize commission data for accounting/reporting purposes: `amountInCampaignCurrency`, `saleAmountInCampaignCurrency`, `exchangeRate`, `campaignCurrencyISO`, and `exchangeRateAt`.\
\
For example, if your campaign's currency is set to `USD` but a referral makes a payment in `CAD`, the generated commission will have `amountInCampaignCurrency` as the `USD` equivalent of the `CAD` payment.
{% endhint %}

***

## ParticipantPayout

```json
{"openapi":"3.1.0","info":{"title":"GrowSurf REST API","version":"2.0.0"},"components":{"schemas":{"ParticipantPayout":{"type":"object","description":"**Affiliate programs only.** A payout generated for a participant in an affiliate program. All payouts start with a status of `UPCOMING`, which represents an aggregation of the participant's `ParticipantCommission` amounts, and is adjusted in real time as commissions change.","required":["id","participantId","commissionIds","amount","currencyISO","status","createdAt"],"properties":{"id":{"type":"string","readOnly":true,"description":"The unique identifier of the participant payout."},"participantId":{"type":"string","readOnly":true,"description":"The participant ID of the referrer who earned the payout."},"commissionIds":{"type":"array","readOnly":true,"items":{"type":"string"},"description":"The IDs of the associated `ParticipantCommission`s."},"amount":{"type":"integer","readOnly":true,"description":"Payout amount in the currency's smallest denomination (e.g., `100` cents equals $1.00 USD, and `100` equals ¥100 for a zero-decimal currency). Always non-negative."},"currencyISO":{"type":"string","readOnly":true,"description":"The [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code of the payout (e.g., `USD`, `GBP`)."},"status":{"$ref":"#/components/schemas/PayoutStatus","readOnly":true,"description":"Current lifecycle state of the payout."},"createdAt":{"type":"integer","format":"int64","readOnly":true,"description":"UTC timestamp (in milliseconds) when the payout record was created."},"queuedAt":{"type":["integer","null"],"format":"int64","readOnly":true,"description":"UTC timestamp (in milliseconds) when the payout was queued for processing (status `QUEUED`). `null` until the payout is queued."},"issuedAt":{"type":["integer","null"],"format":"int64","readOnly":true,"description":"UTC timestamp (in milliseconds) when the payout was issued. `null` if the payout was not successfully issued."},"failedAt":{"type":["integer","null"],"format":"int64","readOnly":true,"description":"UTC timestamp (in milliseconds) when the payout failed to be issued. `null` if the payout did not fail to be issued."},"provider":{"type":["string","null"],"readOnly":true,"description":"The payment provider used to issue the payout (e.g., `paypal`). `null` for payouts with a status of `UPCOMING`."},"amountInCampaignCurrency":{"type":["integer","null"],"readOnly":true,"description":"Payout amount converted to the program's currency, in the currency's smallest denomination. Always non-negative. `null` if the payout status is `UPCOMING` or if it is still pending FX conversion."},"campaignCurrencyISO":{"type":["string","null"],"readOnly":true,"description":"The [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code of the program used in currency conversion (e.g., `USD`, `GBP`). `null` if the payout status is `UPCOMING` or if it is still pending FX conversion."},"exchangeRateAt":{"type":["integer","null"],"format":"int64","readOnly":true,"description":"UTC timestamp (in milliseconds) when the currency exchange rate was received. `null` if the payout status is `UPCOMING` or if it is still pending FX conversion."},"exchangeRate":{"type":["number","null"],"readOnly":true,"description":"The currency exchange rate used for conversion. `null` if the payout status is `UPCOMING` or if it is still pending FX conversion."},"fxError":{"type":["string","null"],"readOnly":true,"description":"If there was an error with FX conversion, the specific details. `null` if the payout status is `UPCOMING` or if the FX conversion was successful."}}},"PayoutStatus":{"type":"string","enum":["UPCOMING","QUEUED","ISSUED","FAILED"]}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.growsurf.com/developer-tools/rest-api/api-objects.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.