Models and Errors

Models, callbacks, stores, and errors exposed by the GrowSurf iOS SDK.

Core models

GrowSurfConfiguration

Field	Type	Description
campaignId	String	GrowSurf program ID.
publicKey	String	Mobile SDK public key.
baseURL	URL	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	Bool?	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	Int64	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	[String: GrowSurfJSONValue]?	Custom JSON metadata to store on the participant.
termsAccepted	Bool?	Explicit Terms consent for direct signup to an open affiliate program. Omit for referred customers.

mobileInstanceId is generated and sent by the SDK automatically. It is not part of GrowSurfParticipantInput.

GrowSurfParticipantUpdateInput

Field	Type	Description
firstName	String?	Updated first name.
lastName	String?	Updated last name.
metadata	[String: GrowSurfJSONValue]?	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	[GrowSurfCampaignReward]

GrowSurfCampaignReward

Field	Type
id	String?
type	String?
event	String?
title	String?
isVisible	Bool?
description	String?
referralDescription	String?
isUnlimited	Bool?
limit	Int?
conversionsRequired	Int?
numberOfWinners	Int?
imageUrl	String?
order	Int?
limitDuration	String?
nextMilestonePrefix	String?
nextMilestoneSuffix	String?
couponCode	String?
referralCouponCode	String?
metadata	[String: GrowSurfJSONValue]?
commissionStructure	[String: GrowSurfJSONValue]?
value	GrowSurfCampaignRewardTaxValuation?
referredValue	GrowSurfCampaignRewardTaxValuation?
referredRewardUpfront	Bool?

GrowSurfCampaignRewardTaxValuation

Field	Type
fairMarketValueUSD	Double?
taxCharacter	String?

GrowSurfParticipant

Field	Type
id	String
email	String?
firstName	String?
lastName	String?
isAffiliate	Bool?
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	[String]?
unreadCommissionsCount	Int?
unreadPayoutsCount	Int?
payoutSettings	GrowSurfPayoutSettings?
taxInfo	GrowSurfTaxInfo?

GrowSurfCreateParticipantResponse

Field	Type
success	Bool?
participantToken	String?
expiresIn	Int?
participant	GrowSurfParticipant?
isNew	Bool?
requiresParticipantToken	Bool?
window	GrowSurfWindowResponse?

GrowSurfAddReferredParticipantResponse

Field	Type
added	Bool
validReferral	Bool
referredBy	String?
notAddedReason	GrowSurfAddReferredParticipantNotAddedReason?
participantToken	String?
expiresIn	Int?
participant	GrowSurfParticipant?
isNew	Bool?
requiresParticipantToken	Bool?

For referred customers in affiliate programs, added is true and participantToken can be nil.

GrowSurfAddReferredParticipantNotAddedReason

Case	Raw value
.noReferrer	no_referrer
.invalidReferrer	invalid_referrer
.participantAlreadyExists	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
primaryColorHex	String?	Optional primary color override, such as #13795B.
colorScheme	GrowSurfWindowTheme.ColorScheme	.system, .light, or .dark.
cornerRadius	Double?	Optional corner radius override.
presentationStyle	GrowSurfWindowTheme.PresentationStyle	.automatic, .fullScreen, or .sheet.

GrowSurfWindowCallbacks

Callback	Type
onOpen	() -> Void
onClose	() -> Void
onParticipantCreated	(GrowSurfParticipant, String?) -> Void
onShareTracked	(String) -> Void
onInviteSent	() -> Void
onPayoutOrSettingsAction	(String) -> Void
onError	(Error) -> Void

GrowSurfWindowController

Method	Description
close()	Closes the presented GrowSurf window.

GrowSurfWindowResponse

Field	Type
version	String?
campaign	GrowSurfWindowCampaign?
signup	GrowSurfWindowSignup?
visibleSections	[String: Bool]
share	GrowSurfWindowShareConfig?
participant	GrowSurfParticipant?
affiliateAccess	GrowSurfWindowAffiliateAccess?
unreadCounts	GrowSurfWindowUnreadCounts?
payoutSettings	GrowSurfPayoutSettings?
content	[String: GrowSurfJSONValue]?
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
GrowSurfJSONValue	.string, .number, .bool, .object, .array, .null

GrowSurfWindowResource.type is .file, .link, or .text. Items keep the server-authorized order. category can be nil. 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.

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.

payoutDestinations is nil 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.

Advanced protocols and stores

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

Type	Public methods
GrowSurfHTTPClient	data(for:)
GrowSurfTokenStore	sessionToken(), participantToken(), saveSessionToken(_:), saveParticipantToken(_:), clear()
GrowSurfAttributionStore	attribution(), saveAttribution(_:), clearAttribution()
GrowSurfMobileInstanceIdStore	mobileInstanceId()
GrowSurfWindowCacheStore	windowData(cacheKey:now:), saveWindowData(_:cacheKey:expiresAt:), clear()
GrowSurfUserDefaultsAttributionStore	UserDefaults-backed attribution store.
GrowSurfUserDefaultsMobileInstanceIdStore	UserDefaults-backed mobile instance ID store.
GrowSurfUserDefaultsWindowCacheStore	UserDefaults-backed window cache store.
GrowSurfFileWindowCacheStore	File-backed window cache store used by default.
GrowSurfKeychainTokenStore	Keychain-backed token store used by default.

Errors

GrowSurfError can be:

• invalidURL

• missingSessionToken

• missingParticipantToken

• invalidResponse

• httpStatus(Int, String?)