> 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/android-sdk/models-and-errors.md). # Models and Errors Models, callbacks, stores, interfaces, and errors exposed by the GrowSurf Android SDK. ## Core models ### GrowSurfConfiguration | Field | Type | Description | | ------------ | -------- | ------------------------ | | `campaignId` | `String` | GrowSurf program ID. | | `publicKey` | `String` | Mobile SDK public key. | | `baseUrl` | `String` | Mobile SDK API base URL. | ### GrowSurfAttribution | Field | Type | Description | | ------------ | --------------------------- | ------------------------------------------------------------ | | `referredBy` | `String?` | Referrer participant ID or vanity key. | | `ref` | `String?` | Referrer value mirrored for provider compatibility. | | `unique` | `Boolean?` | Whether the attribution provider marked the click as unique. | | `provider` | `String?` | Attribution provider name. | | `clickId` | `String?` | Provider click ID. | | `visit` | `GrowSurfVisitAttribution?` | Visit details the SDK recorded for this link. | ### GrowSurfVisitAttribution | Field | Type | Description | | ----------------- | ------------------------------ | ---------------------------------------------------------------------------------- | | `contractVersion` | `Int` | Contract version. The current value is `1`. | | `visitId` | `String` | Stable random visit ID used for idempotent retries. | | `occurredAt` | `Long` | Visit time as Unix milliseconds. | | `utm` | `GrowSurfAttributionUtm?` | The nine allowlisted UTM values. | | `referrer` | `GrowSurfAttributionUrl?` | Referrer origin and path only. | | `destination` | `GrowSurfAttributionUrl?` | Destination origin and path only. | | `trigger` | `GrowSurfAttributionTrigger` | `QR_CODE`, `DEEP_LINK`, `DEFERRED_DEEP_LINK`, `INSTALL_REFERRER`, or `MANUAL`. | | `provider` | `GrowSurfAttributionProvider?` | `BRANCH`, `APPSFLYER`, `ADJUST`, `SINGULAR`, `PLAY_INSTALL_REFERRER`, or `CUSTOM`. | | `clickId` | `String?` | Provider click ID when available. | `GrowSurfAttributionUtm` exposes `id`, `source`, `medium`, `campaign`, `sourcePlatform`, `term`, `content`, `creativeFormat`, and `marketingTactic`. `GrowSurfAttributionUrl` exposes `origin` and `path`. It never includes a query string or fragment. ### GrowSurfParticipantInput | Field | Type | Description | | --------------- | ---------------------- | --------------------------------------------------------------------------------------------------- | | `email` | `String` | Participant email address. | | `firstName` | `String?` | Participant first name. | | `lastName` | `String?` | Participant last name. | | `referredBy` | `String?` | Explicit referrer value. | | `attribution` | `GrowSurfAttribution?` | Explicit attribution payload. | | `metadata` | `Map?` | Custom JSON metadata to store on the participant. | | `termsAccepted` | `Boolean?` | Explicit Terms consent for direct signup to an open affiliate program. Omit for referred customers. | {% hint style="info" %} `mobileInstanceId` is generated and sent by the SDK automatically. It is not part of `GrowSurfParticipantInput`. {% endhint %} ### GrowSurfParticipantUpdateInput | Field | Type | Description | | ----------- | -------------------- | ---------------------- | | `firstName` | `String?` | Updated first name. | | `lastName` | `String?` | Updated last name. | | `metadata` | `Map?` | Updated JSON metadata. | ### GrowSurfCampaign | Field | Type | | ------------------ | ------------------------------ | | `id` | `String` | | `name` | `String?` | | `type` | `String?` | | `referralCount` | `Int?` | | `participantCount` | `Int?` | | `impressionCount` | `Int?` | | `inviteCount` | `Int?` | | `winnerCount` | `Int?` | | `currencyISO` | `String?` | | `status` | `String?` | | `rewards` | `List` | ### GrowSurfCampaignReward | Field | Type | | ----------------------- | ------------------------------------- | | `id` | `String?` | | `type` | `String?` | | `event` | `String?` | | `title` | `String?` | | `isVisible` | `Boolean?` | | `description` | `String?` | | `referralDescription` | `String?` | | `isUnlimited` | `Boolean?` | | `limit` | `Int?` | | `conversionsRequired` | `Int?` | | `numberOfWinners` | `Int?` | | `imageUrl` | `String?` | | `order` | `Int?` | | `limitDuration` | `String?` | | `nextMilestonePrefix` | `String?` | | `nextMilestoneSuffix` | `String?` | | `couponCode` | `String?` | | `referralCouponCode` | `String?` | | `metadata` | `Map` | | `commissionStructure` | `Map?` | | `value` | `GrowSurfCampaignRewardTaxValuation?` | | `referredValue` | `GrowSurfCampaignRewardTaxValuation?` | | `referredRewardUpfront` | `Boolean?` | ### GrowSurfCampaignRewardTaxValuation | Field | Type | | -------------------- | --------- | | `fairMarketValueUSD` | `Double?` | | `taxCharacter` | `String?` | ### GrowSurfParticipant | Field | Type | | -------------------------- | ------------------------- | | `id` | `String` | | `email` | `String?` | | `firstName` | `String?` | | `lastName` | `String?` | | `isAffiliate` | `Boolean?` | | `affiliateStatus` | `String?` | | `shareUrl` | `String?` | | `referredBy` | `String?` | | `paypalEmailAddress` | `String?` | | `referralCount` | `Int?` | | `leadCount` | `Int?` | | `inviteCount` | `Int?` | | `monthlyReferralCount` | `Int?` | | `prevMonthlyReferralCount` | `Int?` | | `rank` | `Int?` | | `monthlyRank` | `Int?` | | `prevMonthlyRank` | `Int?` | | `vanityKeys` | `List` | | `unreadCommissionsCount` | `Int?` | | `unreadPayoutsCount` | `Int?` | | `payoutSettings` | `GrowSurfPayoutSettings?` | | `taxInfo` | `GrowSurfTaxInfo?` | ### GrowSurfCreateParticipantResponse | Field | Type | | -------------------------- | ------------------------- | | `success` | `Boolean?` | | `participantToken` | `String?` | | `expiresIn` | `Int?` | | `participant` | `GrowSurfParticipant?` | | `isNew` | `Boolean?` | | `requiresParticipantToken` | `Boolean?` | | `window` | `GrowSurfWindowResponse?` | ### GrowSurfAddReferredParticipantResponse | Field | Type | | -------------------------- | ----------------------------------------------- | | `added` | `Boolean` | | `validReferral` | `Boolean` | | `referredBy` | `String?` | | `notAddedReason` | `GrowSurfAddReferredParticipantNotAddedReason?` | | `participantToken` | `String?` | | `expiresIn` | `Int?` | | `participant` | `GrowSurfParticipant?` | | `isNew` | `Boolean?` | | `requiresParticipantToken` | `Boolean?` | For referred customers in affiliate programs, `added` is `true` and `participantToken` can be `null`. ### GrowSurfAddReferredParticipantNotAddedReason | Case | Value | | ---------------------------- | ---------------------------- | | `NO_REFERRER` | `no_referrer` | | `INVALID_REFERRER` | `invalid_referrer` | | `PARTICIPANT_ALREADY_EXISTS` | `participant_already_exists` | ### Referral and reward models | Model | Fields | | ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `GrowSurfReferralsResponse` | `referrals`, `limit`, `nextOffset`, `more` | | `GrowSurfReferral` | `id`, `email`, `firstName`, `lastName`, `referralStatus`, `referredBy`, `createdAt`, `updatedAt`, `referrerEmail`, `referralTriggeredAt`, `referralCreditExpiredAt`, `isAwaitingSignup`, `canShowFollowUp`, `canFollowUp`, `followUpAvailableAt`, `displayStatus` | | `GrowSurfRewardsResponse` | `rewards`, `limit`, `nextId` | | `GrowSurfReward` | `id`, `status`, `unread`, `approved`, `rewardId`, `isReferrer`, `isFulfilled`, `isAvailable`, `approvedAt`, `fulfilledAt`, `referredId`, `referrerId`, `amount`, `currencyISO`, `commissionStructure` | | `GrowSurfSuccessResponse` | `success`, `message` | | `GrowSurfPayoutDestinationConfirmationResponse` | `success`, `status`, `provider`, `providerDisplayName`, `expiresAt` | | `GrowSurfAttributionResponse` | `success`, `valid`, `referredBy`, `accepted`, `duplicate`, `availability`, `reason`, `visitId`, `isUnique`, `receipt` | | `GrowSurfValidateReferrerResponse` | `success`, `valid`, `referredBy` | | `GrowSurfInviteResponse` | `success`, `message`, `messageType`, `invitesSent` | `displayStatus` is optional and does not change `referralStatus`. `OFFER_CLAIMED` means the contact claimed an offer but has not completed signup. The GrowSurf window uses the program’s editable **Claimed Offer** label. Completed signup takes precedence, including signup that still needs a qualifying purchase. `canShowFollowUp` allows the Follow up action only for a direct invitation from the current participant with Company as the Invite Email sender. A later offer claim preserves that invitation; a popup claim alone does not qualify. The Window shows the action when `canFollowUp` is also true. Confirmation sends the configured invitation email. The action is hidden while sending is unavailable, including the three-day cooldown. Opening the action never sends an email. `GrowSurfReward.status` is `PENDING`, `FULFILLED`, or `CANCELLED`. The native GrowSurf window keeps cancelled rows out of earned reward totals and unread badges. ## GrowSurf window models ### GrowSurfWindowIdentity | Case | Description | | --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Anonymous` | Loads the window without participant identity. | | `ParticipantFields(GrowSurfParticipantInput)` | Creates a new participant from fields before loading the window. Existing participants need a participant token; use `ExistingParticipantToken(String)`. | | `ExistingParticipantToken(String)` | Uses a participant token created by your backend or by the SDK. | ### GrowSurfWindowTheme | Field | Type | Description | | ------------------- | --------------------------------- | ----------------------------------------------------------- | | `primaryColor` | `Long?` | Optional ARGB primary color override, such as `0xFF13795B`. | | `colorScheme` | `GrowSurfWindowColorScheme` | `SYSTEM`, `LIGHT`, or `DARK`. | | `cornerRadiusDp` | `Float?` | Optional corner radius override in dp. | | `presentationStyle` | `GrowSurfWindowPresentationStyle` | `AUTOMATIC`, `FULL_SCREEN`, or `SHEET`. | ### GrowSurfWindowCallbacks | Callback | Type | | -------------------------- | ---------------------------------------- | | `onOpen` | `() -> Unit` | | `onClose` | `() -> Unit` | | `onParticipantCreated` | `(GrowSurfParticipant, String?) -> Unit` | | `onShareTracked` | `(String) -> Unit` | | `onInviteSent` | `() -> Unit` | | `onPayoutOrSettingsAction` | `(String) -> Unit` | | `onError` | `(Throwable) -> Unit` | ### GrowSurfWindowController | Method | Description | | --------- | ------------------------------------- | | `close()` | Closes the presented GrowSurf window. | ### GrowSurfWindowResponse | Field | Type | | ------------------ | --------------------------------- | | `version` | `String?` | | `campaign` | `GrowSurfWindowCampaign?` | | `signup` | `GrowSurfWindowSignup?` | | `visibleSections` | `Map` | | `share` | `GrowSurfWindowShareConfig?` | | `participant` | `GrowSurfParticipant?` | | `affiliateAccess` | `GrowSurfWindowAffiliateAccess?` | | `unreadCounts` | `GrowSurfWindowUnreadCounts?` | | `payoutSettings` | `GrowSurfPayoutSettings?` | | `content` | `Map` | | `resources` | `GrowSurfWindowResourcesContent?` | | `referrals` | `GrowSurfReferralsResponse?` | | `rewards` | `GrowSurfRewardsResponse?` | | `leaderboard` | `GrowSurfLeaderboardResponse?` | | `referralSummary` | `GrowSurfReferralSummary?` | | `affiliateSummary` | `GrowSurfAffiliateSummary?` | | `commissions` | `GrowSurfCommissionsResponse?` | | `payouts` | `GrowSurfPayoutsResponse?` | ### Additional window models | Model | Fields | | ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `GrowSurfWindowCampaign` | `id`, `type`, `status`, `companyName`, `companyLogoImageUrl`, `goal`, `currencyISO`, `shouldDisplayPoweredBy`, `rewardTypes`, `rewards`, `design`, `countryLabels` | | `GrowSurfWindowSignup` | `state`, `canCreateParticipant`, `affiliateEnrollment` | | `GrowSurfWindowAffiliateEnrollment` | `access`, `title`, `message`, `actionText`, `applicationUrl`, `terms` | | `GrowSurfWindowAffiliateEnrollmentTerms` | `isRequired`, `agreementPrefix`, `title`, `url` | | `GrowSurfWindowAffiliateAccess` | `status`, `title`, `message` | | `GrowSurfWindowShareConfig` | `preferredUrl`, `fallbackUrl`, `nativeShare`, `channels`, `invite` | | `GrowSurfWindowShareChannel` | `type`, `label`, `order`, `subject`, `message`, `nativePreferred` | | `GrowSurfWindowUnreadCounts` | `commissions`, `payouts` | | `GrowSurfWindowResourcesContent` | `isPublicDisplayed`, `title`, `viewResourcesLinkText`, `backLinkText`, `copyButtonText`, `copiedText`, `emptyState`, `icon`, `items` | | `GrowSurfWindowResourcesIcon` | `type`, `imageUrl` | | `GrowSurfWindowResource` | `id`, `type`, `title`, `description`, `category`, `url`, `text`, `file` | | `GrowSurfWindowResourceFile` | `fileName`, `mimeType`, `bytes` | | `GrowSurfWindowResourceDownloadResponse` | `url`, `expiresIn` | | `GrowSurfPayoutSettings` | `provider`, `paypalEmailAddress`, `canRequestPaypalConfirmEmail`, `hostedActions`, `requiredActions`, `payoutInstructionsMode`, `taxInfo`, `payoutDestinations` | | `GrowSurfPayoutDestinations` | `activeProvider`, `enabledProviders`, `requiresChoice`, `providers` | | `GrowSurfPayoutDestinationProvider` | `provider`, `providerDisplayName`, `status`, `claimEmail`, `needsRepairReason`, `canConfirm` | | `GrowSurfTaxInfo` | `status`, `formType`, `residencyCountryCode`, `vatNumber`, `statusReason`, `payoutSettings` | | `GrowSurfTaxInfoRefreshPayoutSettings` | `hostedActions`, `requiredActions` | | `GrowSurfTaxSessionResponse` | `hostedUrl`, `status` | | `GrowSurfTaxInfoSaveResponse` | `success`, `taxInfo` | | `GrowSurfLeaderboardResponse` | `participants`, `nextKey`, `page`, `hasMore` | | `GrowSurfLeaderboardParticipant` | `id`, `rank`, `monthlyRank`, `prevMonthlyRank`, `email`, `isWinner`, `referralCount`, `monthlyReferralCount`, `prevMonthlyReferralCount`, `pendingReferralCount`, `revenueAmount`, `commissionAmount` | | `GrowSurfReferralSummary` | `referrals`, `leads`, `expiredReferrals`, `clicks`, `rewardsEarned`, `pendingRewards`, `invitesSent`, `currencyISO` | | `GrowSurfAffiliateSummary` | `referralRevenue`, `totalPaidOut`, `upcomingPayout`, `referrals`, `leads`, `clicks`, `currencyISO` | | `GrowSurfCommissionsResponse` | `commissions`, `totalCount`, `totalAmount`, `summary`, `nextId` | | `GrowSurfCommission` | `id`, `amount`, `currencyISO`, `status`, `holdDuration`, `createdAt`, `amountInCampaignCurrency`, `saleAmountInCampaignCurrency`, `campaignCurrencyISO`, `unread` | | `GrowSurfPayoutsResponse` | `payouts`, `totalCount`, `totalAmount`, `summary`, `nextId` | | `GrowSurfPayout` | `id`, `amount`, `currencyISO`, `status`, `paymentMethod`, `queuedAt`, `reversedAt`, `createdAt`, `amountInCampaignCurrency`, `campaignCurrencyISO`, `unread` | `GrowSurfWindowResource.type` is `FILE`, `LINK`, or `TEXT`. Items keep the server-authorized order. `category` can be `null`. A FILE contains only safe display metadata; call `getParticipantResourceDownloadUrl(resourceId)` when the participant opens it. The response never includes private storage coordinates or a durable file URL. {% hint style="info" %} `GrowSurfWindowCampaign.design` carries the raw `participantAvatarStyle` value for custom screens. It is `CHARACTERS`, `INITIALS`, `ANIMALS`, or `GRADIENT`. The built-in window renders it automatically. Treat a missing or unknown value as `INITIALS`. {% endhint %} {% hint style="info" %} `payoutDestinations` is `null` when no payout provider applies to the participant. If you build your own settings UI, render `providerDisplayName` instead of hardcoding a provider name, show the payout method picker when `requiresChoice` is `true`, and show the confirm action only when that provider's `canConfirm` is `true`. The PayPal-specific `provider` and `paypalEmailAddress` fields still work as before. {% endhint %} ## Advanced interfaces and stores Use these APIs for tests or custom storage/transport integrations. | Type | Public methods | | ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | `GrowSurfCallback` | `onSuccess(result)`, `onError(error)` | | `GrowSurfTokenStore` | `getSessionToken()`, `getParticipantToken()`, `saveSessionToken(token)`, `saveParticipantToken(token)`, `clear()` | | `GrowSurfAttributionStore` | `getAttribution()`, `saveAttribution(attribution)`, `clearAttribution()`, `hasCheckedDeferredDeepLink()`, `markDeferredDeepLinkChecked()` | | `GrowSurfMobileInstanceIdStore` | `getMobileInstanceId()` | | `GrowSurfWindowCacheStore` | `getWindow(cacheKey, nowMillis)`, `saveWindow(cacheKey, windowJson, expiresAtMillis)`, `clear()` | | `GrowSurfInstallReferrerClient` | `getInstallReferrer()` | | `GrowSurfHttpTransport` | `execute(request)` | | `GrowSurfHttpRequest` | `method`, `url`, `headers`, `body`, `timeoutMillis` | | `GrowSurfHttpResponse` | `statusCode`, `body` | | `EncryptedPreferencesGrowSurfTokenStore` | Encrypted token store used by default. Clears only GrowSurf token data after confirmed unrecoverable crypto state. | | `PreferencesGrowSurfAttributionStore` | SharedPreferences-backed attribution store used by default. | | `PreferencesGrowSurfMobileInstanceIdStore` | SharedPreferences-backed mobile instance ID store used by default. | | `PreferencesGrowSurfWindowCacheStore` | SharedPreferences-backed window cache store. | | `EncryptedPreferencesGrowSurfWindowCacheStore` | Encrypted window cache store used by default. | | `UrlConnectionGrowSurfHttpTransport` | Default HTTP transport. | | `PlayStoreGrowSurfInstallReferrerClient` | Default Google Play Install Referrer client. | ## Android backup rules Android backs up `SharedPreferences`, but every GrowSurf preference file is device-scoped or regenerable, and a restored copy causes problems rather than preserving anything useful. Exclude all six from cloud backup and device transfer: | File | Why a restored copy is harmful | | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | `growsurf_tokens.xml` | Encrypted. Android does not back up the Keystore key, so the restored ciphertext is unreadable. | | `growsurf_window_cache_encrypted.xml` | Encrypted, same reason. | | `growsurf_attribution.xml` | A restored "already checked" flag makes the SDK skip the Install Referrer query, so a genuinely new referred install loses its referral with no error. | | `growsurf_identity.xml` | Holds the per-install id. Restoring it clones one install identity onto a second device. | | `growsurf_window_cache.xml` | Cleartext cache. Regenerable, and a restored copy is stale. | | `growsurf_participant_engagement.xml` | Holds pending participant engagement for this install. Restoring it can replay old portal or share activity on another device. | If your app does not have backup rules, point the `` element in your manifest to the rules included with the SDK: ```xml ``` Android supports one app-wide file for each rule type. If your app already has either file, keep your existing rules and add all six GrowSurf exclusions to it. Do not replace exclusions required by another SDK. ## Errors The SDK throws: * `GrowSurfException` for SDK state errors such as missing participant tokens. * `GrowSurfHttpException` for non-2xx HTTP responses. Exposes a `statusCode: Int` property and the response body as the exception message. --- # 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 by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.growsurf.com/developer-tools/android-sdk/models-and-errors.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. 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.