> 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

This reference documents the models, callbacks, advanced interfaces, stores, 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.                                           |

### 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<String, String>?` | Custom metadata to store on the participant. |

{% 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<String, String>?` | Updated 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>` |

### GrowSurfCampaignReward

| Field                   | Type       |
| ----------------------- | ---------- |
| `id`                    | `String?`  |
| `type`                  | `String?`  |
| `title`                 | `String?`  |
| `description`           | `String?`  |
| `referralDescription`   | `String?`  |
| `isUnlimited`           | `Boolean?` |
| `limit`                 | `Int?`     |
| `conversionsRequired`   | `Int?`     |
| `numberOfWinners`       | `Int?`     |
| `imageUrl`              | `String?`  |
| `order`                 | `Int?`     |
| `limitDuration`         | `String?`  |
| `nextMilestonePrefix`   | `String?`  |
| `nextMilestoneSuffix`   | `String?`  |
| `couponCode`            | `String?`  |
| `referredRewardUpfront` | `Boolean?` |

### GrowSurfParticipant

| Field                      | Type           |
| -------------------------- | -------------- |
| `id`                       | `String`       |
| `email`                    | `String?`      |
| `firstName`                | `String?`      |
| `lastName`                 | `String?`      |
| `shareUrl`                 | `String?`      |
| `paypalEmailAddress`       | `String?`      |
| `referralCount`            | `Int?`         |
| `inviteCount`              | `Int?`         |
| `monthlyReferralCount`     | `Int?`         |
| `prevMonthlyReferralCount` | `Int?`         |
| `rank`                     | `Int?`         |
| `monthlyRank`              | `Int?`         |
| `prevMonthlyRank`          | `Int?`         |
| `vanityKeys`               | `List<String>` |
| `unreadCommissionsCount`   | `Int?`         |
| `unreadPayoutsCount`       | `Int?`         |

### GrowSurfCreateParticipantResponse

| Field                      | Type                      |
| -------------------------- | ------------------------- |
| `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?`                                      |

### 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`, `referralStatus`, `createdAt`, `updatedAt`, `referralTriggeredAt`, `referralCreditExpiredAt` |
| `GrowSurfRewardsResponse`          | `rewards`, `limit`, `nextId`                                                                                |
| `GrowSurfReward`                   | `id`, `status`, `unread`, `approved`, `rewardId`, `title`, `description`, `isReferrer`                      |
| `GrowSurfSuccessResponse`          | `success`, `message`                                                                                        |
| `GrowSurfAttributionResponse`      | `success`, `valid`, `referredBy`                                                                            |
| `GrowSurfValidateReferrerResponse` | `success`, `valid`, `referredBy`                                                                            |
| `GrowSurfInviteResponse`           | `success`, `message`, `messageType`                                                                         |

## 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)` with a token created by your backend or returned by the SDK. |
| `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<String, Boolean>`         |
| `share`            | `GrowSurfWindowShareConfig?`   |
| `participant`      | `GrowSurfParticipant?`         |
| `unreadCounts`     | `GrowSurfWindowUnreadCounts?`  |
| `payoutSettings`   | `GrowSurfPayoutSettings?`      |
| `content`          | `Map<String, Any?>`            |
| `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`                                                     |
| `GrowSurfWindowSignup`           | `state`, `canCreateParticipant`                                                                                                                                                                       |
| `GrowSurfWindowShareConfig`      | `preferredUrl`, `fallbackUrl`, `nativeShare`, `channels`, `invite`                                                                                                                                    |
| `GrowSurfWindowShareChannel`     | `type`, `label`, `order`, `subject`, `message`, `nativePreferred`                                                                                                                                     |
| `GrowSurfWindowUnreadCounts`     | `commissions`, `payouts`                                                                                                                                                                              |
| `GrowSurfPayoutSettings`         | `provider`, `paypalEmailAddress`, `canRequestPaypalConfirmEmail`, `hostedActions`, `requiredActions`, `taxInfo`                                                                                       |
| `GrowSurfTaxInfo`                | `status`, `formType`                                                                                                                                                                                  |
| `GrowSurfTaxSessionResponse`     | `hostedUrl`, `status`                                                                                                                                                                                 |
| `GrowSurfLeaderboardResponse`    | `participants`, `offsetKey`, `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`, `saleAmountAmountInCampaignCurrency`, `campaignCurrencyISO`, `unread`                               |
| `GrowSurfPayoutsResponse`        | `payouts`, `totalCount`, `totalAmount`, `summary`, `nextId`                                                                                                                                           |
| `GrowSurfPayout`                 | `id`, `amount`, `currencyISO`, `status`, `queuedAt`, `createdAt`, `amountInCampaignCurrency`, `campaignCurrencyISO`, `unread`                                                                         |

## Advanced interfaces and stores

Use these APIs for tests or custom storage/transport integrations.

| Type                                           | Public methods                                                                                                                            |
| ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `GrowSurfCallback<T>`                          | `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`       | EncryptedSharedPreferences-backed token store used by default.                                                                            |
| `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` | EncryptedSharedPreferences-backed window cache store used by default.                                                                     |
| `UrlConnectionGrowSurfHttpTransport`           | Default HTTP transport.                                                                                                                   |
| `PlayStoreGrowSurfInstallReferrerClient`       | Default Google Play Install Referrer client.                                                                                              |

## 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 dynamically by asking a question.

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

```
GET https://docs.growsurf.com/developer-tools/android-sdk/models-and-errors.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.