API Reference
This reference documents the GrowSurf REST API, including all available public methods and examples of each.
INDEX ↓
List participants · List leaderboard participants · Add participant · Retrieve participant · Update participant · Delete participant · Bulk delete participants · Trigger referral · Cancel delayed referral trigger · Create mobile participant token · Email participant · Retrieve participant analytics · List participant activity logs · Get a participant's payout destination status · Request a payout destination confirmation
List affiliate applications · Get affiliate application · Review affiliate application · List affiliate invites · Create affiliate invite · Revoke affiliate invite · Resend affiliate invite · Record affiliate transaction · Refund or amend affiliate transaction · List participant commissions · List commissions for a participant · Approve participant commission · Delete participant commission · List participant payouts · List payouts for a participant
ACCOUNTS ↓
Creates a new GrowSurf account. This is the only endpoint that does not require an API key. Before calling it, an authorized account owner must review and approve GrowSurf's Terms of Service and Privacy Policy. The account starts a 14-day Business trial without a credit card. The response includes an API key for the new account, shown once in the response. The key is a secret: store it in a secret manager and do not put it in logs, screenshots, URLs, model context, analytics, or generated output. A lost key cannot be recovered through this API, so do not create an account here unless you can store the key somewhere that outlives the current conversation. If you cannot, ask the account owner to connect GrowSurf's hosted MCP server at https://mcp.growsurf.com instead, which keeps the credential with your tool rather than in chat. The key is locked until the team owner's email address is verified: authenticated program and resource endpoints return a 403 with error code EMAIL_NOT_VERIFIED_ERROR until then (resend the email via POST /team/owner/verification-email, then retry). Verification unlocks this same key — keep it and retry rather than requesting a replacement. A welcome email is sent to the address with the verification link and a set-password link for dashboard access. Accounts whose email is never verified are deleted automatically after 7 days. Separately, for security, the API key is replaced the first time the account owner signs in to the GrowSurf dashboard; email verification does not trigger that, and the previous key then returns a 403 with error code NOT_AUTHORIZED_ERROR. Some actions (such as emailing participants) additionally require GrowSurf to verify the team first. Calling this endpoint accepts those policies on the account holder's behalf.
The email address for the new GrowSurf account. Personal emails and disposable email addresses are not accepted.
richard@piedpiper.comFirst name for the new account owner.
RichardLast name for the new account owner.
HendricksCompany name for the new account.
Pied PiperAccount created.
Email address for the new account.
richard@piedpiper.comAn API key for the new account. Use it as the Bearer token on subsequent requests. It is shown once and locked (403 EMAIL_NOT_VERIFIED_ERROR) until the account's email is verified; verification unlocks this same key, so keep it and retry. It is replaced only when the account owner first signs in to the GrowSurf dashboard.
sk_api_0123456789abcdef0123456789abcdef_u9v4m2q8n6r5s1t7w3x0y9z8a6b4c2d0e1f3g5h7GrowSurf team verification state. VERIFIED is required before a program can send participant emails.
NOT_REQUESTEDPossible values: Invalid request.
The account could not be created with the supplied details.
Too many requests.
POST /v2/accounts HTTP/1.1
Host: api.growsurf.com
Content-Type: application/json
Accept: */*
Content-Length: 101
{
"email": "richard@piedpiper.com",
"firstName": "Richard",
"lastName": "Hendricks",
"company": "Pied Piper"
}{
"email": "richard@piedpiper.com",
"apiKey": "<GROWSURF_API_KEY>",
"verificationStatus": "NOT_REQUESTED"
}TEAMS ↓
Retrieves the team bound to the API key or OAuth connection. verificationStatus is VERIFIED once GrowSurf has verified the team, which is required before a program can send participant emails.
GrowSurf REST API key supplied as Authorization: Bearer <api_key>.
Team returned.
The team bound to the API key or OAuth connection.
The team's display name.
Pied PiperGrowSurf team verification state. VERIFIED is required before a program can send participant emails.
VERIFIEDPossible values: When team verification was last requested, as a Unix timestamp in milliseconds.
1719792000000The API key is missing, invalid, revoked, outside its scope, or not allowed to perform this action.
Too many requests.
GET /v2/team HTTP/1.1
Host: api.growsurf.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"name": "Pied Piper",
"verificationStatus": "VERIFIED",
"verificationRequestedAt": 1719792000000
}Updates the name of the team bound to the API key or OAuth connection. Any other property is rejected with a 400. Personal profiles, billing, and team ownership are not editable here.
GrowSurf REST API key supplied as Authorization: Bearer <api_key>.
The Team fields you can update. Any property not listed here is rejected with a 400.
The team's display name.
Updated team returned.
The team bound to the API key or OAuth connection.
The team's display name.
Pied PiperGrowSurf team verification state. VERIFIED is required before a program can send participant emails.
VERIFIEDPossible values: When team verification was last requested, as a Unix timestamp in milliseconds.
1719792000000Invalid request.
The API key is missing, invalid, revoked, outside its scope, or not allowed to perform this action.
Too many requests.
PATCH /v2/team HTTP/1.1
Host: api.growsurf.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 26
{
"name": "Pied Piper Labs"
}{
"name": "Pied Piper",
"verificationStatus": "VERIFIED",
"verificationRequestedAt": 1719792000000
}Requests GrowSurf to verify the bound team (required before a program can email its participants). Idempotent — calling it again while a request is pending does not create a duplicate. Returns the team with its updated verificationStatus.
GrowSurf REST API key supplied as Authorization: Bearer <api_key>.
Verification request recorded.
The team bound to the API key or OAuth connection.
The team's display name.
Pied PiperGrowSurf team verification state. VERIFIED is required before a program can send participant emails.
VERIFIEDPossible values: When team verification was last requested, as a Unix timestamp in milliseconds.
1719792000000The API key is missing, invalid, revoked, outside its scope, or not allowed to perform this action.
Too many requests.
POST /v2/team/verification-request HTTP/1.1
Host: api.growsurf.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"name": "Pied Piper",
"verificationStatus": "VERIFIED",
"verificationRequestedAt": 1719792000000
}Resends the email-verification message to the owner of the account the API key belongs to. This is the recovery path for a 403 with error code EMAIL_NOT_VERIFIED_ERROR, so it stays callable with any GrowSurf API key while the rest of the API is locked. The response never reveals the owner's email address. A 200 with status: SENT is returned only when an email was actually dispatched. Returns 400 if the email is already verified, and 429 if a verification email was sent too recently — wait a moment, then retry.
GrowSurf REST API key supplied as Authorization: Bearer <api_key>.
Verification email sent.
Whether the verification email request was accepted.
Status of the verification email request.
Invalid request.
The API key is missing, invalid, revoked, outside its scope, or not allowed to perform this action.
Too many requests.
POST /v2/team/owner/verification-email HTTP/1.1
Host: api.growsurf.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"success": true,
"status": "SENT"
}Generates a new API key and makes the key used on this request stop working when rotation succeeds. Send a unique, random Idempotency-Key. If the response is interrupted, immediately retry with the original API key and the same Idempotency-Key to receive the same new key. Update every integration that used the old key. The team owner is notified by email whenever the key is rotated. GrowSurf SDKs generate the idempotency key automatically. This endpoint accepts an API key with api_key:rotate. If this scope is unavailable, rotate the key in the authenticated dashboard instead. This operation is available only through the REST API or a GrowSurf API SDK, not through MCP.
GrowSurf REST API key supplied as Authorization: Bearer <api_key>.
A unique, random value for this rotation request. Reuse this value only when retrying the same request with the original API key.
pied-piper-api-key-rotation-550e8400-e29b-41d4-a716-446655440000Pattern: ^[A-Za-z0-9._:-]+$The new API key.
The new API key. Store it now; the key used for rotation stops working immediately.
Invalid request.
The API key is missing, invalid, revoked, outside its scope, or not allowed to perform this action.
Too many requests.
POST /v2/api-key/rotate HTTP/1.1
Host: api.growsurf.com
Authorization: Bearer YOUR_SECRET_TOKEN
Idempotency-Key: pied-piper-api-key-rotation-550e8400-e29b-41d4-a716-446655440000
Accept: */*
{
"apiKey": "sk_api_0123456789abcdef0123456789abcdef_u9v4m2q8n6r5s1t7w3x0y9z8a6b4c2d0e1f3g5h7"
}CAMPAIGNS ↓
Retrieves a list of your programs. Deleted programs are not returned.
GrowSurf REST API key supplied as Authorization: Bearer <api_key>.
Campaigns returned.
The API key is missing, invalid, revoked, outside its scope, or not allowed to perform this action.
Too many requests.
GET /v2/campaigns HTTP/1.1
Host: api.growsurf.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"campaigns": [
{
"id": "abc123",
"name": "Middle Out Compression Campaign",
"type": "REFERRAL",
"referralCount": 20500,
"participantCount": 40000,
"impressionCount": 100000,
"winnerCount": 1500,
"inviteCount": 100,
"status": "IN_PROGRESS",
"currencyISO": "USD",
"rewards": [
{
"id": "crew_xyz789",
"type": "DOUBLE_SIDED",
"description": "Refer a friend and get a Pied Piper T-Shirt",
"referralDescription": "Join and receive middle out compression algorithm",
"isUnlimited": false,
"referredRewardUpfront": false,
"limit": 1,
"conversionsRequired": 1,
"numberOfWinners": 3,
"imageUrl": "https://piedpiper.com/reward-image.png",
"metadata": {}
}
]
}
]
}Retrieves a program for the given program ID.
GrowSurf REST API key supplied as Authorization: Bearer <api_key>.
GrowSurf program ID.
Campaign returned.
Detailed information about a GrowSurf program.
The unique identifier of the program.
abc123The program name (internal only, never exposed to participants).
Middle Out Compression CampaignThe program type.
REFERRALPossible values: The total referral count.
121The total participant count.
199The total number of impressions — the collective number of times participants' unique referral links have been viewed.
199The total number of invites sent by participants.
237The total number of winners — all participants with at least one approved reward (includes referrers and referred friends).
1The program currency as an ISO 4217 code (e.g., USD, GBP).
USDThe program status.
IN_PROGRESSPossible values: Invalid request.
The API key is missing, invalid, revoked, outside its scope, or not allowed to perform this action.
Resource not found.
Too many requests.
GET /v2/campaign/{id} HTTP/1.1
Host: api.growsurf.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"id": "abc123",
"name": "Middle Out Compression Campaign",
"type": "REFERRAL",
"referralCount": 121,
"participantCount": 199,
"impressionCount": 199,
"inviteCount": 237,
"winnerCount": 1,
"currencyISO": "USD",
"status": "IN_PROGRESS",
"rewards": [
{
"id": "crew_xyz789",
"type": "DOUBLE_SIDED",
"description": "Refer a friend and get a Pied Piper T-Shirt",
"referralDescription": "Join and receive middle out compression algorithm",
"isUnlimited": false,
"referredRewardUpfront": false,
"limit": 1,
"conversionsRequired": 1,
"numberOfWinners": 3,
"imageUrl": "https://piedpiper.com/reward-image.png",
"metadata": {}
}
]
}Creates a new program, plus any optional campaign rewards. The new program is created in DRAFT status and owned by the API key's bound team.
GrowSurf REST API key supplied as Authorization: Bearer <api_key>.
Request body for creating a program. Only type is required; everything else is server-defaulted. Editor-tab configuration (design, emails, options, installation) is NOT accepted here — configure it via the config sub-resources (e.g. PATCH /campaign/{id}/options) after the program is created.
The program type. Immutable after creation.
The program name (internal only, never exposed to participants). Defaults to a generated name (a friendly label plus the creation date) that you can rename at any time.
The company name shown to participants across the program's emails and referral or affiliate portal. When omitted, it defaults to the company name set when the account was created (see POST /accounts), with common legal suffixes removed.
URL of the company logo shown to participants. When omitted, it is auto-populated from your company's domain (and the program theme is seeded with your brand colors). Pass a value to override the logo; the returned campaign reflects a GrowSurf-hosted URL that may differ from the one you supplied.
ISO 4217 currency code. Defaults to USD. Chosen when the program is created and immutable afterward — it cannot be changed on update.
USDWhat the program is for, which seeds the share buttons and the starter rewards that suit that audience. Set it when you create the program; it is not accepted on update.
Programs whose participants refer other businesses (CUSTOMERS, USERS, B2B_SAAS_SELF_SERVICE, B2B_SAAS_ENTERPRISE, HEALTHCARE_PROVIDERS) start with the LinkedIn share button visible. Consumer, financial, education, insurance, telehealth, newsletter, and waitlist programs (B2C_SUBSCRIPTIONS, FINANCIAL_SERVICES, ONLINE_EDUCATION, INSURANCE, ONLINE_INSURANCE, TELEHEALTH, SUBSCRIBERS, WAITLIST) start with it hidden. On a referral program, each goal also sets the rest of its share buttons to suit that audience — a telehealth program keeps the public feeds off, a consumer subscription turns Pinterest and Reddit on. An affiliate program has its own share defaults, so only the LinkedIn default above applies to one. Omit goal and every share button keeps its standard default. Change any of it afterward with PATCH /campaign/{id}/design.
When you create a referral program without rewards, the goal also decides the starter rewards: most goals get one double-sided reward, HEALTHCARE_PROVIDERS gets a single-sided reward, SUBSCRIBERS gets a four-step milestone ladder, and WAITLIST gets a leaderboard. Every starter reward arrives switched off with a placeholder name, so the program awards nothing until you set the amount and turn one on.
TELEHEALTH is for consumer telehealth and wellness subscriptions, where patients refer friends. HEALTHCARE_PROVIDERS is for provider networks and clinician-facing products, where practices refer peer practices. INSURANCE replaces ONLINE_INSURANCE, which is still accepted and behaves identically.
B2B_SAAS_SELF_SERVICEPossible values: Campaign created.
Detailed information about a GrowSurf program.
The unique identifier of the program.
abc123The program name (internal only, never exposed to participants).
Middle Out Compression CampaignThe program type.
REFERRALPossible values: The total referral count.
121The total participant count.
199The total number of impressions — the collective number of times participants' unique referral links have been viewed.
199The total number of invites sent by participants.
237The total number of winners — all participants with at least one approved reward (includes referrers and referred friends).
1The program currency as an ISO 4217 code (e.g., USD, GBP).
USDThe program status.
IN_PROGRESSPossible values: Invalid request.
This action isn't available for your account yet (it needs an active subscription or a payment method on file), or the program limit was reached.
The API key is missing, invalid, revoked, outside its scope, or not allowed to perform this action.
Too many requests.
POST /v2/campaigns HTTP/1.1
Host: api.growsurf.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 103
{
"type": "REFERRAL",
"name": "Pied Piper Referral Program",
"companyName": "Pied Piper",
"currencyISO": "USD"
}{
"id": "abc123",
"name": "Pied Piper Referral Program",
"type": "REFERRAL",
"referralCount": 0,
"participantCount": 0,
"impressionCount": 0,
"inviteCount": 0,
"winnerCount": 0,
"currencyISO": "USD",
"status": "DRAFT",
"rewards": []
}Updates a program's identity and lifecycle. Only the fields you send are changed. type, urlId, and currencyISO are immutable. Editor-tab configuration (design, emails, options, installation) is edited via the dedicated config sub-resources, not here. The program cannot be deleted via this endpoint.
GrowSurf REST API key supplied as Authorization: Bearer <api_key>.
GrowSurf program ID.
Request body for updating a program's identity and lifecycle. Only the fields you send are changed. type, urlId, and currencyISO are immutable — currency is chosen once when the program is created and cannot be changed here (sending it returns a 400). Editor-tab configuration (design, emails, options, installation) is edited via the dedicated config sub-resources (e.g. PATCH /campaign/{id}/emails), not here.
The program name (internal only, never exposed to participants).
The company name shown to participants across the program's emails and referral or affiliate portal.
URL of the company logo shown to participants. The returned campaign reflects a GrowSurf-hosted URL that may differ from the one you supplied.
The requested program status. Only the dashboard's lifecycle moves are accepted: IN_PROGRESS publishes a DRAFT program or resumes a COMPLETE/CANCELLED one; COMPLETE ends an IN_PROGRESS program. Any other target (including DRAFT, PENDING, CANCELLED, and DELETED) returns a 400.
Campaign updated.
Detailed information about a GrowSurf program.
The unique identifier of the program.
abc123The program name (internal only, never exposed to participants).
Middle Out Compression CampaignThe program type.
REFERRALPossible values: The total referral count.
121The total participant count.
199The total number of impressions — the collective number of times participants' unique referral links have been viewed.
199The total number of invites sent by participants.
237The total number of winners — all participants with at least one approved reward (includes referrers and referred friends).
1The program currency as an ISO 4217 code (e.g., USD, GBP).
USDThe program status.
IN_PROGRESSPossible values: Invalid request.
The API key is missing, invalid, revoked, outside its scope, or not allowed to perform this action.
Resource not found.
Too many requests.
PATCH /v2/campaign/{id} HTTP/1.1
Host: api.growsurf.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 95
{
"name": "Pied Piper Launch Referral Program",
"companyName": "Pied Piper",
"status": "IN_PROGRESS"
}{
"id": "abc123",
"name": "Middle Out Compression Campaign",
"type": "REFERRAL",
"referralCount": 121,
"participantCount": 199,
"impressionCount": 199,
"inviteCount": 237,
"winnerCount": 1,
"currencyISO": "USD",
"status": "IN_PROGRESS",
"rewards": [
{
"id": "crew_xyz789",
"type": "DOUBLE_SIDED",
"event": "CONVERSION",
"title": "Pied Piper T-Shirt",
"isVisible": true,
"description": "Refer a friend and get a Pied Piper T-Shirt",
"referralDescription": "Join and receive middle out compression algorithm",
"referredRewardUpfront": false,
"isUnlimited": false,
"limit": 1,
"conversionsRequired": 1,
"numberOfWinners": 3,
"limitDuration": "IN_TOTAL",
"imageUrl": "https://piedpiper.com/reward-image.png",
"couponCode": "PROMO_20_OFF",
"order": 1,
"nextMilestonePrefix": "You are only",
"nextMilestoneSuffix": "referrals away from receiving a nice reward!",
"metadata": {
"company": "Hooli, Inc",
"companySize": 10000
},
"commissionStructure": {
"amount": null,
"amountISO": null,
"event": "SALE",
"type": "PERCENT",
"minPaidReferrals": 2,
"holdDuration": 30,
"duration": "FOREVER",
"durationInMonths": null,
"approvalRequired": false,
"percent": 25,
"hasMaxAmount": false,
"maxAmount": null,
"maxAmountISO": null,
"hasIntro": false,
"introType": null,
"introPercent": null,
"introAmount": null,
"introAmountISO": null,
"introDuration": null,
"introDurationInMonths": null
},
"referralCouponCode": "WELCOME_20_OFF",
"value": {
"fairMarketValueUSD": 25,
"taxCharacter": "PRIZE_OR_AWARD"
},
"referredValue": {
"fairMarketValueUSD": 25,
"taxCharacter": "PRIZE_OR_AWARD"
}
}
]
}Clones an existing program into a new DRAFT program. Integrations and credentials are not copied; active rewards are cloned.
GrowSurf REST API key supplied as Authorization: Bearer <api_key>.
GrowSurf program ID.
Campaign cloned.
Detailed information about a GrowSurf program.
The unique identifier of the program.
abc123The program name (internal only, never exposed to participants).
Middle Out Compression CampaignThe program type.
REFERRALPossible values: The total referral count.
121The total participant count.
199The total number of impressions — the collective number of times participants' unique referral links have been viewed.
199The total number of invites sent by participants.
237The total number of winners — all participants with at least one approved reward (includes referrers and referred friends).
1The program currency as an ISO 4217 code (e.g., USD, GBP).
USDThe program status.
IN_PROGRESSPossible values: Invalid request.
The API key is missing, invalid, revoked, outside its scope, or not allowed to perform this action.
Resource not found.
Too many requests.
POST /v2/campaign/{id}/clone HTTP/1.1
Host: api.growsurf.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"id": "abc123",
"name": "Middle Out Compression Campaign",
"type": "REFERRAL",
"referralCount": 121,
"participantCount": 199,
"impressionCount": 199,
"inviteCount": 237,
"winnerCount": 1,
"currencyISO": "USD",
"status": "IN_PROGRESS",
"rewards": [
{
"id": "crew_xyz789",
"type": "DOUBLE_SIDED",
"event": "CONVERSION",
"title": "Pied Piper T-Shirt",
"isVisible": true,
"description": "Refer a friend and get a Pied Piper T-Shirt",
"referralDescription": "Join and receive middle out compression algorithm",
"referredRewardUpfront": false,
"isUnlimited": false,
"limit": 1,
"conversionsRequired": 1,
"numberOfWinners": 3,
"limitDuration": "IN_TOTAL",
"imageUrl": "https://piedpiper.com/reward-image.png",
"couponCode": "PROMO_20_OFF",
"order": 1,
"nextMilestonePrefix": "You are only",
"nextMilestoneSuffix": "referrals away from receiving a nice reward!",
"metadata": {
"company": "Hooli, Inc",
"companySize": 10000
},
"commissionStructure": {
"amount": null,
"amountISO": null,
"event": "SALE",
"type": "PERCENT",
"minPaidReferrals": 2,
"holdDuration": 30,
"duration": "FOREVER",
"durationInMonths": null,
"approvalRequired": false,
"percent": 25,
"hasMaxAmount": false,
"maxAmount": null,
"maxAmountISO": null,
"hasIntro": false,
"introType": null,
"introPercent": null,
"introAmount": null,
"introAmountISO": null,
"introDuration": null,
"introDurationInMonths": null
},
"referralCouponCode": "WELCOME_20_OFF",
"value": {
"fairMarketValueUSD": 25,
"taxCharacter": "PRIZE_OR_AWARD"
},
"referredValue": {
"fairMarketValueUSD": 25,
"taxCharacter": "PRIZE_OR_AWARD"
}
}
]
}Renders the program's current saved configuration into two preview images: the referrer window a participant sees, and the referred-friend experience. Use them to show a person what the draft looks like before anything launches. The images render GrowSurf's own preview, not the program's installed website, so they do not prove an installation. Show each image inline when the client supports it, and include an Open preview link using the exact returned URL. Some clients cannot display remote images inline. Each URL is private and expires at expiresAt; compare that timestamp with the current UTC time before reporting it expired. Capture again after expiry. Only the account owner's credential can capture screenshots, and the endpoint takes no request body.
GrowSurf REST API key supplied as Authorization: Bearer <api_key>.
GrowSurf program ID.
Two preview images with expiring URLs.
ISO 8601 time the images were rendered.
2026-07-09T00:00:00.000ZISO 8601 time after which every url in screenshots stops working.
2026-07-09T00:15:00.000ZInvalid request.
The account's billing requirements for this action are not met.
The API key is missing, invalid, revoked, outside its scope, or not allowed to perform this action.
Resource not found.
Too many requests.
POST /v2/campaign/{id}/referral-flow-screenshots HTTP/1.1
Host: api.growsurf.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"generatedAt": "2026-07-09T00:00:00.000Z",
"expiresAt": "2026-07-09T00:15:00.000Z",
"screenshots": [
{
"view": "referrer",
"label": "Referrer window",
"url": "https://screenshots.growsurf.com/previews/richard-referrer.jpg?expires=1751932500",
"expiresAt": "2026-07-09T00:15:00.000Z",
"width": 1280,
"height": 800,
"contentType": "image/jpeg"
}
]
}CAMPAIGN RESOURCES ↓
Returns all draft and published FILE, LINK, and TEXT resources in their participant display order. Private file delivery coordinates are never returned.
GrowSurf REST API key supplied as Authorization: Bearer <api_key>.
GrowSurf program ID.
Program resources returned.
Invalid request.
The API key is missing, invalid, revoked, outside its scope, or not allowed to perform this action.
Resource not found.
Too many requests.
GET /v2/campaign/{id}/resources HTTP/1.1
Host: api.growsurf.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"resources": [
{
"id": "resource_abc123",
"type": "LINK",
"title": "Pied Piper product demo",
"description": "Watch the product walkthrough before your next introduction.",
"category": "Sales enablement",
"url": "https://piedpiper.com/product-demo",
"text": null,
"file": null,
"isPublished": true,
"position": 0,
"createdAt": 1788134400000,
"updatedAt": 1788134400000
},
{
"id": "resource_def456",
"type": "TEXT",
"title": "Product introduction",
"description": "Copy this introduction into an email or direct message.",
"category": "Sales enablement",
"url": null,
"text": "Pied Piper compresses data without sacrificing quality.",
"file": null,
"isPublished": true,
"position": 1,
"createdAt": 1788134460000,
"updatedAt": 1788134460000
},
{
"id": "resource_ghi789",
"type": "FILE",
"title": "Pied Piper media kit",
"description": "Approved logos and product screenshots.",
"category": "Brand assets",
"url": null,
"text": null,
"file": {
"fileName": "pied-piper-media-kit.pdf",
"mimeType": "application/pdf",
"bytes": 842315,
"format": "pdf",
"moderationStatus": "APPROVED"
},
"isPublished": false,
"position": 2,
"createdAt": 1788134520000,
"updatedAt": 1788134520000
}
]
}Creates one resource at the end of the program's order. LINK URLs must use HTTPS. TEXT content is plain text. To create a new FILE, first request an upload ticket, upload the bytes directly to the returned URL, then send the upload result as uploadResult with the one-time uploadTicket. A FILE is available to participants while its security review is pending; a rejected review blocks it.
GrowSurf REST API key supplied as Authorization: Bearer <api_key>.
GrowSurf program ID.
Program resource created.
One ordered program Resource. File delivery coordinates and internal database identifiers are never returned.
Stable public resource ID.
resource_abc123Resource content type.
Participant-visible resource title.
Optional participant-visible supporting text.
Optional category heading. Resources keep their explicit order across headings.
HTTPS destination for a LINK; otherwise null.
Plain copyable content for TEXT; otherwise null.
Whether eligible participants can receive the resource.
Zero-based dense participant display position.
Unix time in milliseconds when the resource was created.
Unix time in milliseconds when the resource was last updated.
Invalid request.
The API key is missing, invalid, revoked, outside its scope, or not allowed to perform this action.
Resource not found.
Too many requests.
POST /v2/campaign/{id}/resources HTTP/1.1
Host: api.growsurf.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 368
{
"type": null,
"title": "text",
"description": null,
"category": null,
"isPublished": false,
"url": "https://example.com",
"text": "text",
"uploadTicket": "text",
"uploadResult": {
"asset_id": "text",
"public_id": "text",
"version": 1,
"signature": "text",
"resource_type": "image",
"type": "text",
"bytes": 1,
"secure_url": "https://example.com",
"format": "text",
"ANY_ADDITIONAL_PROPERTY": "anything"
}
}{
"id": "resource_abc123",
"type": "LINK",
"title": "Pied Piper product demo",
"description": "Watch the product walkthrough before your next introduction.",
"category": "Sales enablement",
"url": "https://piedpiper.com/product-demo",
"text": null,
"file": null,
"isPublished": true,
"position": 0,
"createdAt": 1788134400000,
"updatedAt": 1788134400000
}Updates the supplied content or publication fields. Set position to move the resource; GrowSurf compacts the remaining positions. Changing type requires the complete fields for the new type. A FILE whose security review rejected it cannot be published or downloaded; a pending review does not block it.
GrowSurf REST API key supplied as Authorization: Bearer <api_key>.
GrowSurf program ID.
Program resource ID.
resource_abc123Partial Resource update. If type changes, include the complete content fields required by the new type.
Program resource updated.
One ordered program Resource. File delivery coordinates and internal database identifiers are never returned.
Stable public resource ID.
resource_abc123Resource content type.
Participant-visible resource title.
Optional participant-visible supporting text.
Optional category heading. Resources keep their explicit order across headings.
HTTPS destination for a LINK; otherwise null.
Plain copyable content for TEXT; otherwise null.
Whether eligible participants can receive the resource.
Zero-based dense participant display position.
Unix time in milliseconds when the resource was created.
Unix time in milliseconds when the resource was last updated.
Invalid request.
The API key is missing, invalid, revoked, outside its scope, or not allowed to perform this action.
Resource not found.
Too many requests.
PATCH /v2/campaign/{id}/resources/{resourceId} HTTP/1.1
Host: api.growsurf.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 382
{
"type": "FILE",
"title": "text",
"description": null,
"category": null,
"isPublished": true,
"position": 1,
"url": "https://example.com",
"text": "text",
"uploadTicket": "text",
"uploadResult": {
"asset_id": "text",
"public_id": "text",
"version": 1,
"signature": "text",
"resource_type": "image",
"type": "text",
"bytes": 1,
"secure_url": "https://example.com",
"format": "text",
"ANY_ADDITIONAL_PROPERTY": "anything"
}
}{
"id": "resource_abc123",
"type": "LINK",
"title": "Pied Piper product demo",
"description": "Watch the product walkthrough before your next introduction.",
"category": "Sales enablement",
"url": "https://piedpiper.com/product-demo",
"text": null,
"file": null,
"isPublished": true,
"position": 0,
"createdAt": 1788134400000,
"updatedAt": 1788134400000
}Deletes the program resource and compacts the remaining order. A referenced Media Center file is not deleted.
GrowSurf REST API key supplied as Authorization: Bearer <api_key>.
GrowSurf program ID.
Program resource ID.
resource_abc123Program resource deleted.
Deleted public resource ID.
Confirms that the resource was deleted.
Invalid request.
The API key is missing, invalid, revoked, outside its scope, or not allowed to perform this action.
Resource not found.
Too many requests.
DELETE /v2/campaign/{id}/resources/{resourceId} HTTP/1.1
Host: api.growsurf.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"id": "resource_abc123",
"success": true
}Creates a short-lived, one-time ticket and signed fields for an access-controlled FILE upload. The ticket is bound to this team, program, file name, MIME type, and byte size. Upload the exact bytes to uploadUrl with uploadParameters, then create or update a FILE resource with the returned upload result. This operation returns 503 until secure file review is configured.
GrowSurf REST API key supplied as Authorization: Bearer <api_key>.
GrowSurf program ID.
File name with an allowed extension.
Browser-declared MIME type. GrowSurf also verifies the file signature after upload.
Browser-reported file size in bytes.
One-time upload ticket created.
One-time bearer-like ticket. Do not log or persist it.
Ticket lifetime in seconds.
Endpoint that accepts the signed direct upload.
Invalid request.
The API key is missing, invalid, revoked, outside its scope, or not allowed to perform this action.
Resource not found.
Too many requests.
A required upstream service or account configuration is unavailable.
POST /v2/campaign/{id}/resource-upload-tickets HTTP/1.1
Host: api.growsurf.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 47
{
"fileName": "text",
"mimeType": "text",
"bytes": 1
}{
"ticket": "cGllZC1waXBlci1vbmUtdGltZS11cGxvYWQtdGlja2V0",
"expiresIn": 600,
"uploadUrl": "https://uploads.piedpiper.com/program-resources",
"uploadParameters": {
"timestamp": 1788134400,
"public_id": "program-resources/pied-piper/media-kit",
"type": "authenticated",
"signature": "pied-piper-example-signature"
}
}CAMPAIGN REWARDS ↓
Retrieves the program's configured Campaign Rewards, including rewards with isVisible: false and rewards whose group is not selected. Deleted rewards are excluded. Use this list to review and update switched-off starter rewards. isVisible: true alone does not mean a reward can be earned: a reward whose group is not selected can still be visible. A reward can be earned only when it also appears in the campaign response's embedded rewards array, which includes only enabled, visible rewards. Delete a reward with DELETE /campaign/{id}/reward-configs/{campaignRewardId}.
GrowSurf REST API key supplied as Authorization: Bearer <api_key>.
GrowSurf program ID.
Campaign rewards returned.
The list of a program's configured rewards.
Invalid request.
The API key is missing, invalid, revoked, outside its scope, or not allowed to perform this action.
Resource not found.
Too many requests.
GET /v2/campaign/{id}/reward-configs HTTP/1.1
Host: api.growsurf.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"rewards": [
{
"id": "crew_xyz789",
"type": "DOUBLE_SIDED",
"event": "CONVERSION",
"title": "Pied Piper T-Shirt",
"isVisible": true,
"description": "Refer a friend and get a Pied Piper T-Shirt",
"referralDescription": "Join and receive middle out compression algorithm",
"referredRewardUpfront": false,
"isUnlimited": false,
"limit": 1,
"conversionsRequired": 1,
"numberOfWinners": 3,
"limitDuration": "IN_TOTAL",
"imageUrl": "https://piedpiper.com/reward-image.png",
"couponCode": "PROMO_20_OFF",
"order": 1,
"nextMilestonePrefix": "You are only",
"nextMilestoneSuffix": "referrals away from receiving a nice reward!",
"metadata": {
"company": "Hooli, Inc",
"companySize": 10000
},
"commissionStructure": {
"amount": null,
"amountISO": null,
"event": "SALE",
"type": "PERCENT",
"minPaidReferrals": 2,
"holdDuration": 30,
"duration": "FOREVER",
"durationInMonths": null,
"approvalRequired": false,
"percent": 25,
"hasMaxAmount": false,
"maxAmount": null,
"maxAmountISO": null,
"hasIntro": false,
"introType": null,
"introPercent": null,
"introAmount": null,
"introAmountISO": null,
"introDuration": null,
"introDurationInMonths": null
},
"referralCouponCode": "WELCOME_20_OFF",
"value": {
"fairMarketValueUSD": 25,
"taxCharacter": "PRIZE_OR_AWARD"
},
"referredValue": {
"fairMarketValueUSD": 25,
"taxCharacter": "PRIZE_OR_AWARD"
}
}
]
}Creates a new campaign reward (CampaignReward) with a GrowSurf-assigned ID. The reward type must be compatible with the program type (affiliate programs support only AFFILIATE rewards; referral programs support all other types). Enabling an active reward of a type automatically enables that reward type on the program. For a referral reward, event: LEAD earns the reward on a referred signup and requires the program's referralTrigger to be CUSTOM; event: CONVERSION earns it on the later qualifying action. For an affiliate reward, commissionStructure.event: LEAD requires a FIXED commission with a positive amount; SALE can use FIXED or PERCENT.
GrowSurf REST API key supplied as Authorization: Bearer <api_key>.
GrowSurf program ID.
Request body for creating a campaign reward. type is required and must be compatible with the program type. AFFILIATE rewards additionally require commissionStructure (with amount for a FIXED commission or percent for a PERCENT commission).
Campaign reward created.
A single campaign reward (also known as a CampaignReward). This is different from a ParticipantReward, which is a reward earned by a participant.
The unique identifier of the campaign reward. You can find this ID from Program Editor > 1. Rewards and clicking the reward.
crew_xyz789The reward type.
DOUBLE_SIDEDPossible values: The event that earns this referral reward. Present for SINGLE_SIDED, DOUBLE_SIDED, and MILESTONE rewards. Legacy rewards return CONVERSION.
CONVERSIONPossible values: The reward title (internal only, never exposed to participants).
Pied Piper T-ShirtWhether 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.
trueThe reward description shown to the referrer.
Refer a friend and get a Pied Piper T-ShirtThe reward description shown to the referred friend (only applicable for double-sided reward types).
Join and receive middle out compression algorithmOnly 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.
falsetrue if this reward can be earned by a single participant an unlimited number of times.
falseThe number of times a participant can earn this reward (overridden when isUnlimited is true). -1 represents an unlimited reward in REST responses.
1The number of referrals a participant must make to earn this reward.
1The 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.
3Whether the reward can be earned in total, on a monthly basis, or on a yearly basis.
IN_TOTALPossible values: The reward image URL.
https://piedpiper.com/reward-image.pngA legacy 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.
PROMO_20_OFFIf 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.
1Text 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).
You are onlyText 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).
referrals away from receiving a nice reward!A legacy 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.
WELCOME_20_OFFInvalid request.
The API key is missing, invalid, revoked, outside its scope, or not allowed to perform this action.
Resource not found.
Too many requests.
POST /v2/campaign/{id}/reward-configs HTTP/1.1
Host: api.growsurf.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 185
{
"type": "DOUBLE_SIDED",
"description": "Refer a friend and get a Pied Piper T-Shirt",
"referralDescription": "Join and receive the middle-out compression algorithm",
"conversionsRequired": 1
}{
"id": "crew_xyz789",
"type": "DOUBLE_SIDED",
"event": "CONVERSION",
"title": "Pied Piper T-Shirt",
"isVisible": true,
"description": "Refer a friend and get a Pied Piper T-Shirt",
"referralDescription": "Join and receive middle out compression algorithm",
"referredRewardUpfront": false,
"isUnlimited": false,
"limit": 1,
"conversionsRequired": 1,
"numberOfWinners": 3,
"limitDuration": "IN_TOTAL",
"imageUrl": "https://piedpiper.com/reward-image.png",
"couponCode": "PROMO_20_OFF",
"order": 1,
"nextMilestonePrefix": "You are only",
"nextMilestoneSuffix": "referrals away from receiving a nice reward!",
"metadata": {
"company": "Hooli, Inc",
"companySize": 10000
},
"commissionStructure": {
"amount": null,
"amountISO": null,
"event": "SALE",
"type": "PERCENT",
"minPaidReferrals": 2,
"holdDuration": 30,
"duration": "FOREVER",
"durationInMonths": null,
"approvalRequired": false,
"percent": 25,
"hasMaxAmount": false,
"maxAmount": null,
"maxAmountISO": null,
"hasIntro": false,
"introType": null,
"introPercent": null,
"introAmount": null,
"introAmountISO": null,
"introDuration": null,
"introDurationInMonths": null
},
"referralCouponCode": "WELCOME_20_OFF",
"value": {
"fairMarketValueUSD": 25,
"taxCharacter": "PRIZE_OR_AWARD"
},
"referredValue": {
"fairMarketValueUSD": 25,
"taxCharacter": "PRIZE_OR_AWARD"
}
}Updates an existing campaign reward (CampaignReward). The reward type is immutable and cannot be changed. When the update replaces metadata, renamed keys automatically rewrite any {{campaignReward[…]}} references in campaign copy; removing a key that campaign copy still references returns a 409 listing the referencing fields. For a referral reward, event: LEAD earns the reward on a referred signup and requires the program's referralTrigger to be CUSTOM; event: CONVERSION earns it on the later qualifying action. For an affiliate reward, commissionStructure.event: LEAD requires a FIXED commission with a positive amount; SALE can use FIXED or PERCENT.
GrowSurf REST API key supplied as Authorization: Bearer <api_key>.
GrowSurf program ID.
Campaign reward (CampaignReward) ID.
The writable fields shared by the create and update campaign reward requests.
The reward title (internal only, never exposed to participants).
The reward description shown to the referrer.
The reward description shown to the referred friend (double-sided rewards only).
An image URL for the reward.
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.
trueWhether the reward can be earned an unlimited number of times. Defaults to true, except MILESTONE rewards, which can only be earned once.
trueFor double-sided rewards, deliver the referred friend's reward upfront as a discount.
falseThe event that earns a SINGLE_SIDED, DOUBLE_SIDED, or MILESTONE referral reward. Defaults to CONVERSION. LEAD requires the program's referralTrigger to be CUSTOM.
CONVERSIONPossible values: The number of times a participant can earn the reward (overridden by isUnlimited).
1The number of referrals required to earn the reward.
1The 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. A LEADERBOARD reward that omits it defaults to 3.
The display order of the reward.
The window over which limit applies.
IN_TOTALPossible values: Text shown before a participant's referral count in milestone progress copy (e.g. You are only). Applies to MILESTONE rewards.
Text shown after a participant's referral count in milestone progress copy (e.g. referrals away from your next reward!). Applies to MILESTONE rewards.
A legacy static coupon code shown to the referrer in the reward-won email and webhook when this reward is earned. 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.
A legacy static coupon code shown to the referred friend in the reward-won email and webhook (double-sided rewards). Same behavior and 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.
Campaign reward updated.
A single campaign reward (also known as a CampaignReward). This is different from a ParticipantReward, which is a reward earned by a participant.
The unique identifier of the campaign reward. You can find this ID from Program Editor > 1. Rewards and clicking the reward.
crew_xyz789The reward type.
DOUBLE_SIDEDPossible values: The event that earns this referral reward. Present for SINGLE_SIDED, DOUBLE_SIDED, and MILESTONE rewards. Legacy rewards return CONVERSION.
CONVERSIONPossible values: The reward title (internal only, never exposed to participants).
Pied Piper T-ShirtWhether 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.
trueThe reward description shown to the referrer.
Refer a friend and get a Pied Piper T-ShirtThe reward description shown to the referred friend (only applicable for double-sided reward types).
Join and receive middle out compression algorithmOnly 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.
falsetrue if this reward can be earned by a single participant an unlimited number of times.
falseThe number of times a participant can earn this reward (overridden when isUnlimited is true). -1 represents an unlimited reward in REST responses.
1The number of referrals a participant must make to earn this reward.
1The 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.
3Whether the reward can be earned in total, on a monthly basis, or on a yearly basis.
IN_TOTALPossible values: The reward image URL.
https://piedpiper.com/reward-image.pngA legacy 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.
PROMO_20_OFFIf 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.
1Text 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).
You are onlyText 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).
referrals away from receiving a nice reward!A legacy 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.
WELCOME_20_OFFInvalid request.
The API key is missing, invalid, revoked, outside its scope, or not allowed to perform this action.
Resource not found.
Conflicting duplicate request.
Too many requests.
PATCH /v2/campaign/{id}/reward-configs/{campaignRewardId} HTTP/1.1
Host: api.growsurf.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 60
{
"description": "Refer a friend and get a Pied Piper hoodie"
}{
"id": "crew_xyz789",
"type": "DOUBLE_SIDED",
"event": "CONVERSION",
"title": "Pied Piper T-Shirt",
"isVisible": true,
"description": "Refer a friend and get a Pied Piper T-Shirt",
"referralDescription": "Join and receive middle out compression algorithm",
"referredRewardUpfront": false,
"isUnlimited": false,
"limit": 1,
"conversionsRequired": 1,
"numberOfWinners": 3,
"limitDuration": "IN_TOTAL",
"imageUrl": "https://piedpiper.com/reward-image.png",
"couponCode": "PROMO_20_OFF",
"order": 1,
"nextMilestonePrefix": "You are only",
"nextMilestoneSuffix": "referrals away from receiving a nice reward!",
"metadata": {
"company": "Hooli, Inc",
"companySize": 10000
},
"commissionStructure": {
"amount": null,
"amountISO": null,
"event": "SALE",
"type": "PERCENT",
"minPaidReferrals": 2,
"holdDuration": 30,
"duration": "FOREVER",
"durationInMonths": null,
"approvalRequired": false,
"percent": 25,
"hasMaxAmount": false,
"maxAmount": null,
"maxAmountISO": null,
"hasIntro": false,
"introType": null,
"introPercent": null,
"introAmount": null,
"introAmountISO": null,
"introDuration": null,
"introDurationInMonths": null
},
"referralCouponCode": "WELCOME_20_OFF",
"value": {
"fairMarketValueUSD": 25,
"taxCharacter": "PRIZE_OR_AWARD"
},
"referredValue": {
"fairMarketValueUSD": 25,
"taxCharacter": "PRIZE_OR_AWARD"
}
}Deletes a campaign reward (CampaignReward). The reward is deactivated, removed from the program's reward set, and any connected upfront-discount coupons are cleaned up. If campaign copy still references any of the reward's metadata keys via {{campaignReward[…]}} tokens, the delete returns a 409 listing the referencing fields — update those fields first.
GrowSurf REST API key supplied as Authorization: Bearer <api_key>.
GrowSurf program ID.
Campaign reward (CampaignReward) ID.
Campaign reward deleted.
The deleted reward ID.
Whether the campaign reward was deleted.
Invalid request.
The API key is missing, invalid, revoked, outside its scope, or not allowed to perform this action.
Resource not found.
Conflicting duplicate request.
Too many requests.
DELETE /v2/campaign/{id}/reward-configs/{campaignRewardId} HTTP/1.1
Host: api.growsurf.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"id": "text",
"success": true
}CAMPAIGN DESIGN ↓
Retrieves a program's configured design fields: the dashboard Program Editor's Design tab plus the payout-destination confirmation page copy configured from payout integration cards. This includes the GrowSurf window layout, header, share channels and invites, signup form, portal and landing pages, theme styling, and referral or affiliate summary and status sections. The available fields depend on the program type. payoutDestinationConfirmation is omitted when no confirmation fields are stored. Stored null fields are returned as null; omitted and null fields use localized defaults.
GrowSurf REST API key supplied as Authorization: Bearer <api_key>.
GrowSurf program ID.
Campaign design returned.
A program's design configuration. It includes the dashboard Program Editor's Design tab and the payout-destination confirmation page copy configured from payout integration cards. The exact fields available depend on the program type (for example, referralSummary is referral-only, while affiliateSummary, commissions, and payouts are affiliate-only). participantSettings is available to both program types; its manual payout and Wise fields are affiliate-only. GET returns the fields configured for the program; payoutDestinationConfirmation is omitted when no confirmation fields are stored. Stored null fields are returned as null; omitted and null fields use localized defaults. PATCH back only the sections or fields you want to change (arrays such as signup.fields replace wholesale).
The participant avatar style. New programs start with CHARACTERS. Programs with a missing or unknown stored value return INITIALS for backward compatibility.
CHARACTERSPossible values: How the sections inside the GrowSurf window are laid out. navigationMode chooses between a tabbed layout (TABS) and a single scrolling list (LIST).
Header content for participants (postText) and non-participants (preText).
The stats panel a participant sees at the top of the GrowSurf window, summarizing their own referral progress. Only its heading text (title) is editable here.
Share channels (type.<channel>.{isVisible,buttonText,message,order}), invite settings, and share-button styling.
Signup form (fields[], GDPR consent, button and login text).
The Referral Status section, which lists the people a participant has invited and each one's progress (invite sent, pending, awarded, or expired). Controls its title, icon, column and status labels, empty-state text, and email masking. revealInviteEmails lets a signed-in participant see original invitation addresses when disclosure permission was recorded. Private invites and full email masking keep addresses hidden. Other referral addresses stay masked. revealInviteEmailText supplies the sign-in prompt; followUp supplies the invitation follow-up labels and messages.
The Leaderboard section that ranks participants against each other. Controls its title, icon, column labels, which time-period and ranking selectors appear, empty-state text, and how other participants' names are masked.
Referral programs only. The row of summary tiles a participant sees (clicks, leads, referrals, invites sent, rewards earned, and more). Controls each tile's label, tooltip, and visibility, plus the section's title and icon.
Affiliate programs only. The row of summary tiles an affiliate sees (clicks, leads, referrals, referral revenue, upcoming payout, and total paid out). Controls each tile's label, tooltip, and visibility, plus the section's title and icon.
Affiliate programs only. The Commissions section of the participant portal, which lists an affiliate's earned commissions and their status (pending, approved, paid, or reversed). Controls its title, icon, column labels, status labels and tooltips, and empty-state text.
Affiliate programs only. The Payouts section of the participant portal, which lists an affiliate's payouts and their status (upcoming, queued, issued, failed, or reversed). Controls its title, icon, column labels, status labels and tooltips, and empty-state text.
The heading, icon, and empty-state text of the rewards panel shown to participants. Which rewards appear, and the order they appear in, are managed through the campaign rewards endpoints, not here.
The participant's account settings area in the portal. Controls the labels and messages for logging out, managing PayPal and Wise payout emails (including confirmation, connected, expired, and repair states), and completing tax details (country of residency, VAT, and tax-form status). Wise payout copy applies to affiliate programs; the other fields also apply to eligible referral programs.
Portal and landing pages — company info, content (FAQ/terms/labels), styles (fonts), third-party script IDs (GA/GTM/Facebook/HubSpot), and SEO meta tags. Custom code, CSS, and JS are not editable via the API.
Invalid request.
The API key is missing, invalid, revoked, outside its scope, or not allowed to perform this action.
Resource not found.
Too many requests.
GET /v2/campaign/{id}/design HTTP/1.1
Host: api.growsurf.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"participantAvatarStyle": "CHARACTERS",
"window": {
"navigationMode": "TABS"
},
"header": {
"preText": "Refer friends and earn rewards",
"postText": "Thanks for joining! Share your link below."
},
"referredExperience": {
"bannerText": "You were referred by a friend",
"bannerPlacement": "BOTTOM"
},
"login": {
"heading": "Sign in",
"description": "Enter your email and we’ll send you a secure sign-in link.",
"fieldLabel": "Email",
"fieldPlaceholder": "you@example.com",
"buttonText": "Send sign-in link",
"successHeading": "Check your email",
"successBody": "If that email belongs to an account, we just sent a secure sign-in link. Open it on this device to finish signing in.",
"resendPrompt": "Didn't get it?",
"resend": "Resend link",
"resent": "Sign-in link sent again. Check your inbox.",
"invalidEmail": "Please enter a valid email address.",
"cooldown": "You've requested a few links already. Please wait a moment before trying again.",
"serverError": "Something went wrong on our end. Please try again in a moment.",
"invalidLink": "This sign-in link is invalid or has expired. Enter your email to get a new one.",
"verificationHeading": "Verify your email",
"verificationDescription": "For your security, we’ll send a sign-in link to the email address on your account.",
"verificationSuccessBody": "Open the sign-in link in your email on this device to continue."
},
"trafficInsights": {
"isPublicDisplayed": true,
"title": "Your traffic",
"defaultDateRange": "LAST_30_DAYS",
"breakdowns": {
"geo": {
"isVisible": false
}
}
}
}Updates a program's design configuration, including the payout-destination confirmation page copy configured from payout integration cards. Only the fields you send are changed; anything you leave out is untouched (arrays such as signup.fields replace wholesale). Unknown fields, fields not available for the program type, and invalid values return a 400. Landing-page custom code and JavaScript are not editable via the API.
GrowSurf REST API key supplied as Authorization: Bearer <api_key>.
GrowSurf program ID.
A program's design configuration. It includes the dashboard Program Editor's Design tab and the payout-destination confirmation page copy configured from payout integration cards. The exact fields available depend on the program type (for example, referralSummary is referral-only, while affiliateSummary, commissions, and payouts are affiliate-only). participantSettings is available to both program types; its manual payout and Wise fields are affiliate-only. GET returns the fields configured for the program; payoutDestinationConfirmation is omitted when no confirmation fields are stored. Stored null fields are returned as null; omitted and null fields use localized defaults. PATCH back only the sections or fields you want to change (arrays such as signup.fields replace wholesale).
The participant avatar style. New programs start with CHARACTERS. Programs with a missing or unknown stored value return INITIALS for backward compatibility.
CHARACTERSPossible values: How the sections inside the GrowSurf window are laid out. navigationMode chooses between a tabbed layout (TABS) and a single scrolling list (LIST).
Header content for participants (postText) and non-participants (preText).
The stats panel a participant sees at the top of the GrowSurf window, summarizing their own referral progress. Only its heading text (title) is editable here.
Share channels (type.<channel>.{isVisible,buttonText,message,order}), invite settings, and share-button styling.
Signup form (fields[], GDPR consent, button and login text).
The Referral Status section, which lists the people a participant has invited and each one's progress (invite sent, pending, awarded, or expired). Controls its title, icon, column and status labels, empty-state text, and email masking. revealInviteEmails lets a signed-in participant see original invitation addresses when disclosure permission was recorded. Private invites and full email masking keep addresses hidden. Other referral addresses stay masked. revealInviteEmailText supplies the sign-in prompt; followUp supplies the invitation follow-up labels and messages.
The Leaderboard section that ranks participants against each other. Controls its title, icon, column labels, which time-period and ranking selectors appear, empty-state text, and how other participants' names are masked.
Referral programs only. The row of summary tiles a participant sees (clicks, leads, referrals, invites sent, rewards earned, and more). Controls each tile's label, tooltip, and visibility, plus the section's title and icon.
Affiliate programs only. The row of summary tiles an affiliate sees (clicks, leads, referrals, referral revenue, upcoming payout, and total paid out). Controls each tile's label, tooltip, and visibility, plus the section's title and icon.
Affiliate programs only. The Commissions section of the participant portal, which lists an affiliate's earned commissions and their status (pending, approved, paid, or reversed). Controls its title, icon, column labels, status labels and tooltips, and empty-state text.
Affiliate programs only. The Payouts section of the participant portal, which lists an affiliate's payouts and their status (upcoming, queued, issued, failed, or reversed). Controls its title, icon, column labels, status labels and tooltips, and empty-state text.
The heading, icon, and empty-state text of the rewards panel shown to participants. Which rewards appear, and the order they appear in, are managed through the campaign rewards endpoints, not here.
The participant's account settings area in the portal. Controls the labels and messages for logging out, managing PayPal and Wise payout emails (including confirmation, connected, expired, and repair states), and completing tax details (country of residency, VAT, and tax-form status). Wise payout copy applies to affiliate programs; the other fields also apply to eligible referral programs.
Portal and landing pages — company info, content (FAQ/terms/labels), styles (fonts), third-party script IDs (GA/GTM/Facebook/HubSpot), and SEO meta tags. Custom code, CSS, and JS are not editable via the API.
Campaign design updated.
A program's design configuration. It includes the dashboard Program Editor's Design tab and the payout-destination confirmation page copy configured from payout integration cards. The exact fields available depend on the program type (for example, referralSummary is referral-only, while affiliateSummary, commissions, and payouts are affiliate-only). participantSettings is available to both program types; its manual payout and Wise fields are affiliate-only. GET returns the fields configured for the program; payoutDestinationConfirmation is omitted when no confirmation fields are stored. Stored null fields are returned as null; omitted and null fields use localized defaults. PATCH back only the sections or fields you want to change (arrays such as signup.fields replace wholesale).
The participant avatar style. New programs start with CHARACTERS. Programs with a missing or unknown stored value return INITIALS for backward compatibility.
CHARACTERSPossible values: How the sections inside the GrowSurf window are laid out. navigationMode chooses between a tabbed layout (TABS) and a single scrolling list (LIST).
Header content for participants (postText) and non-participants (preText).
The stats panel a participant sees at the top of the GrowSurf window, summarizing their own referral progress. Only its heading text (title) is editable here.
Share channels (type.<channel>.{isVisible,buttonText,message,order}), invite settings, and share-button styling.
Signup form (fields[], GDPR consent, button and login text).
The Referral Status section, which lists the people a participant has invited and each one's progress (invite sent, pending, awarded, or expired). Controls its title, icon, column and status labels, empty-state text, and email masking. revealInviteEmails lets a signed-in participant see original invitation addresses when disclosure permission was recorded. Private invites and full email masking keep addresses hidden. Other referral addresses stay masked. revealInviteEmailText supplies the sign-in prompt; followUp supplies the invitation follow-up labels and messages.
The Leaderboard section that ranks participants against each other. Controls its title, icon, column labels, which time-period and ranking selectors appear, empty-state text, and how other participants' names are masked.
Referral programs only. The row of summary tiles a participant sees (clicks, leads, referrals, invites sent, rewards earned, and more). Controls each tile's label, tooltip, and visibility, plus the section's title and icon.
Affiliate programs only. The row of summary tiles an affiliate sees (clicks, leads, referrals, referral revenue, upcoming payout, and total paid out). Controls each tile's label, tooltip, and visibility, plus the section's title and icon.
Affiliate programs only. The Commissions section of the participant portal, which lists an affiliate's earned commissions and their status (pending, approved, paid, or reversed). Controls its title, icon, column labels, status labels and tooltips, and empty-state text.
Affiliate programs only. The Payouts section of the participant portal, which lists an affiliate's payouts and their status (upcoming, queued, issued, failed, or reversed). Controls its title, icon, column labels, status labels and tooltips, and empty-state text.
The heading, icon, and empty-state text of the rewards panel shown to participants. Which rewards appear, and the order they appear in, are managed through the campaign rewards endpoints, not here.
The participant's account settings area in the portal. Controls the labels and messages for logging out, managing PayPal and Wise payout emails (including confirmation, connected, expired, and repair states), and completing tax details (country of residency, VAT, and tax-form status). Wise payout copy applies to affiliate programs; the other fields also apply to eligible referral programs.
Portal and landing pages — company info, content (FAQ/terms/labels), styles (fonts), third-party script IDs (GA/GTM/Facebook/HubSpot), and SEO meta tags. Custom code, CSS, and JS are not editable via the API.
Invalid request.
The API key is missing, invalid, revoked, outside its scope, or not allowed to perform this action.
Resource not found.
Too many requests.
PATCH /v2/campaign/{id}/design HTTP/1.1
Host: api.growsurf.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 1467
{
"participantAvatarStyle": "CHARACTERS",
"window": {
"navigationMode": "TABS"
},
"header": {
"preText": "Refer friends and earn rewards",
"postText": "Thanks for joining! Share your link below."
},
"referredExperience": {
"bannerText": "You were referred by a friend",
"bannerPlacement": "BOTTOM"
},
"login": {
"heading": "Sign in",
"description": "Enter your email and we’ll send you a secure sign-in link.",
"fieldLabel": "Email",
"fieldPlaceholder": "you@example.com",
"buttonText": "Send sign-in link",
"successHeading": "Check your email",
"successBody": "If that email belongs to an account, we just sent a secure sign-in link. Open it on this device to finish signing in.",
"resendPrompt": "Didn't get it?",
"resend": "Resend link",
"resent": "Sign-in link sent again. Check your inbox.",
"invalidEmail": "Please enter a valid email address.",
"cooldown": "You've requested a few links already. Please wait a moment before trying again.",
"serverError": "Something went wrong on our end. Please try again in a moment.",
"invalidLink": "This sign-in link is invalid or has expired. Enter your email to get a new one.",
"verificationHeading": "Verify your email",
"verificationDescription": "For your security, we’ll send a sign-in link to the email address on your account.",
"verificationSuccessBody": "Open the sign-in link in your email on this device to continue."
},
"trafficInsights": {
"isPublicDisplayed": true,
"title": "Your traffic",
"defaultDateRange": "LAST_30_DAYS",
"breakdowns": {
"geo": {
"isVisible": false
}
}
}
}{
"participantAvatarStyle": "CHARACTERS",
"window": {
"navigationMode": "TABS"
},
"header": {
"preText": "Refer friends and earn rewards",
"postText": "Thanks for joining! Share your link below."
},
"referredExperience": {
"bannerText": "You were referred by a friend",
"bannerPlacement": "BOTTOM"
},
"login": {
"heading": "Sign in",
"description": "Enter your email and we’ll send you a secure sign-in link.",
"fieldLabel": "Email",
"fieldPlaceholder": "you@example.com",
"buttonText": "Send sign-in link",
"successHeading": "Check your email",
"successBody": "If that email belongs to an account, we just sent a secure sign-in link. Open it on this device to finish signing in.",
"resendPrompt": "Didn't get it?",
"resend": "Resend link",
"resent": "Sign-in link sent again. Check your inbox.",
"invalidEmail": "Please enter a valid email address.",
"cooldown": "You've requested a few links already. Please wait a moment before trying again.",
"serverError": "Something went wrong on our end. Please try again in a moment.",
"invalidLink": "This sign-in link is invalid or has expired. Enter your email to get a new one.",
"verificationHeading": "Verify your email",
"verificationDescription": "For your security, we’ll send a sign-in link to the email address on your account.",
"verificationSuccessBody": "Open the sign-in link in your email on this device to continue."
},
"trafficInsights": {
"isPublicDisplayed": true,
"title": "Your traffic",
"defaultDateRange": "LAST_30_DAYS",
"breakdowns": {
"geo": {
"isVisible": false
}
}
}
}CAMPAIGN EMAILS ↓
Retrieves a program's email configuration — the same surface as the dashboard Program Editor's Emails tab. Returns each editable email template (subject, preheader, body, isEnabled) plus the settings block (sender, contact, and design). The set of email templates returned depends on the program type (referral vs affiliate).
GrowSurf REST API key supplied as Authorization: Bearer <api_key>.
GrowSurf program ID.
Campaign emails configuration returned.
A program's email configuration (the dashboard Program Editor's Emails tab). Each property is an editable email template; the set of templates available depends on the program type (referral vs affiliate), and writing a template that is not available for the program type returns a 400. The settings object holds sender, contact, and design settings. To see the full object with every template and its current values, GET this resource, then PATCH back only the fields you want to change.
Invalid request.
The API key is missing, invalid, revoked, outside its scope, or not allowed to perform this action.
Resource not found.
Too many requests.
GET /v2/campaign/{id}/emails HTTP/1.1
Host: api.growsurf.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"welcomeNonReferred": {
"subject": "Welcome to the Pied Piper referral program",
"preheader": "Share your referral link and earn rewards",
"body": "<p>Thanks for joining! Share your link: {{shareUrl}}</p>{{emailFooter}}",
"isEnabled": true
},
"settings": {
"sender": {
"fromName": "Pied Piper",
"replyToEmail": "rewards@piedpiper.com"
}
}
}Updates a program's email configuration. Only the fields you send are changed; omitted fields are left untouched. You may only write the email templates the dashboard exposes for the program type — writing a template that is not available for the program type returns a 400. Some fields are read-only (settings.sender.fromEmail, whose custom value requires dashboard domain verification).
GrowSurf REST API key supplied as Authorization: Bearer <api_key>.
GrowSurf program ID.
A program's email configuration (the dashboard Program Editor's Emails tab). Each property is an editable email template; the set of templates available depends on the program type (referral vs affiliate), and writing a template that is not available for the program type returns a 400. The settings object holds sender, contact, and design settings. To see the full object with every template and its current values, GET this resource, then PATCH back only the fields you want to change.
Campaign emails configuration updated.
A program's email configuration (the dashboard Program Editor's Emails tab). Each property is an editable email template; the set of templates available depends on the program type (referral vs affiliate), and writing a template that is not available for the program type returns a 400. The settings object holds sender, contact, and design settings. To see the full object with every template and its current values, GET this resource, then PATCH back only the fields you want to change.
Invalid request.
The API key is missing, invalid, revoked, outside its scope, or not allowed to perform this action.
Resource not found.
Too many requests.
PATCH /v2/campaign/{id}/emails HTTP/1.1
Host: api.growsurf.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 320
{
"welcomeNonReferred": {
"subject": "Welcome to the Pied Piper referral program",
"preheader": "Share your referral link and earn rewards",
"body": "<p>Thanks for joining! Share your link: {{shareUrl}}</p>{{emailFooter}}",
"isEnabled": true
},
"settings": {
"sender": {
"fromName": "Pied Piper",
"replyToEmail": "rewards@piedpiper.com"
}
}
}{
"welcomeNonReferred": {
"subject": "Welcome to the Pied Piper referral program",
"preheader": "Share your referral link and earn rewards",
"body": "<p>Thanks for joining! Share your link: {{shareUrl}}</p>{{emailFooter}}",
"isEnabled": true
},
"settings": {
"sender": {
"fromName": "Pied Piper",
"replyToEmail": "rewards@piedpiper.com"
}
}
}CAMPAIGN OPTIONS ↓
Retrieves a program's options — the same surface as the dashboard Program Editor's Options tab. Includes the attribution model, reward/fraud approval, anti-fraud lists + toggles, referral cookie/credit windows, reCAPTCHA, affiliate enrollment + application review, payout threshold + tax settings (affiliate only), and notification-email settings. fraud.recaptcha.secretKey is never returned.
GrowSurf REST API key supplied as Authorization: Bearer <api_key>.
GrowSurf program ID.
Campaign options returned.
A program's options (the dashboard Program Editor's Options tab). To see the full object with every field and its current value, GET this resource, then PATCH back only the fields you want to change. Some fields are program-type specific (see the per-field notes).
Affiliate programs only. How public signups join the program. OPEN_ENROLLMENT enrolls signups directly (the default for programs created before applications existed). MANUAL_REVIEW collects an application you approve or deny. AUTO_APPROVE collects the full application and approves it immediately. Switching to a reviewed mode requires a saved Program Page. Trusted enrollment through the API, CSV import, dashboard, or invites is never blocked by this setting.
Affiliate programs only. Whether a denied applicant may apply again. AFTER_COOLDOWN (the default) allows a new application once affiliateReapplicationCooldownDays has passed; DISABLED never allows one.
Affiliate programs only. How many days a denied applicant waits before they can apply again (1-365, default 30). Only used when affiliateReapplicationPolicy is AFTER_COOLDOWN.
Affiliate programs only. Optional review-time expectation (in business days, 1-60) shown to pending applicants. Send null to clear it; when unset, applicants see neutral "we'll email you" copy instead.
Referral programs only. When true, each reward a participant earns is held for you to manually approve before it unlocks (and before the reward-won email is sent); when false, earned rewards are approved automatically. Cannot be true together with autoFulfillRewards.
Referral programs only. When true, rewards a participant earns are automatically marked as sent instead of you marking each one by hand, usually paired with an automated reward-delivery integration. Cannot be true together with requireManualRewardApproval.
When true, no signup is automatically blocked for fraud. Every participant is allowed to join, and any suspected fraud is flagged in your dashboard for you to review. Cannot be true together with autoBlockFraud.
When true, signups flagged as high fraud risk are automatically blocked from joining; when false, they are allowed in and flagged in your dashboard for review. Cannot be true together with requireManualFraudApproval.
Require returning participants to authenticate. Affiliate programs require this to be true.
When true, GrowSurf stores only the minimum participant data needed to help you meet GDPR/CCPA requirements. Some participant fields are omitted and fraud screening is limited while this is on.
When true, referrals from visitors who arrived through paid ads (for example Google or Facebook ads) are not attributed, so the referring participant is not credited for them. Recommended so participants don't compete with you for your own paid keywords.
Selects which server-verified visit receives conversion credit within referralCookieWindowDays. LAST_CLICK is used when this field is missing, including for programs created before attribution models were configurable.
LAST_CLICKPossible values: How long, in days, a referral-link click is remembered in the visitor's browser. If the visitor signs up within this window, the referral is credited to the participant whose link they clicked.
How long, in days, a referred friend has to complete a qualifying action for their referrer to earn credit and unlock a reward. After this window the referral no longer counts toward rewards. null = never expires.
Affiliate programs only. Minimum payout in the program's currency minor units (0 or null = no minimum). Requires currencyISO to be set.
Invalid request.
The API key is missing, invalid, revoked, outside its scope, or not allowed to perform this action.
Resource not found.
Too many requests.
GET /v2/campaign/{id}/options HTTP/1.1
Host: api.growsurf.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"blockPaidAdsTraffic": true,
"attributionModel": "LAST_CLICK",
"referralCookieWindowDays": 90,
"fraud": {
"blockBurnerEmails": true,
"maxSignupsPerIp2Min": 5
}
}Updates a program's options. Only the fields you send are changed. Some fields are program-type specific (requireManualRewardApproval/autoFulfillRewards are referral-only; affiliateApplicationMode/affiliateReapplicationPolicy and payoutThreshold/taxDocumentation are affiliate-only, and affiliate programs require requireParticipantAuth: true). fraud.recaptcha.secretKey is write-only. referralCreditWindowDays: null means "never expires".
GrowSurf REST API key supplied as Authorization: Bearer <api_key>.
GrowSurf program ID.
A program's options (the dashboard Program Editor's Options tab). To see the full object with every field and its current value, GET this resource, then PATCH back only the fields you want to change. Some fields are program-type specific (see the per-field notes).
Affiliate programs only. How public signups join the program. OPEN_ENROLLMENT enrolls signups directly (the default for programs created before applications existed). MANUAL_REVIEW collects an application you approve or deny. AUTO_APPROVE collects the full application and approves it immediately. Switching to a reviewed mode requires a saved Program Page. Trusted enrollment through the API, CSV import, dashboard, or invites is never blocked by this setting.
Affiliate programs only. Whether a denied applicant may apply again. AFTER_COOLDOWN (the default) allows a new application once affiliateReapplicationCooldownDays has passed; DISABLED never allows one.
Affiliate programs only. How many days a denied applicant waits before they can apply again (1-365, default 30). Only used when affiliateReapplicationPolicy is AFTER_COOLDOWN.
Affiliate programs only. Optional review-time expectation (in business days, 1-60) shown to pending applicants. Send null to clear it; when unset, applicants see neutral "we'll email you" copy instead.
Referral programs only. When true, each reward a participant earns is held for you to manually approve before it unlocks (and before the reward-won email is sent); when false, earned rewards are approved automatically. Cannot be true together with autoFulfillRewards.
Referral programs only. When true, rewards a participant earns are automatically marked as sent instead of you marking each one by hand, usually paired with an automated reward-delivery integration. Cannot be true together with requireManualRewardApproval.
When true, no signup is automatically blocked for fraud. Every participant is allowed to join, and any suspected fraud is flagged in your dashboard for you to review. Cannot be true together with autoBlockFraud.
When true, signups flagged as high fraud risk are automatically blocked from joining; when false, they are allowed in and flagged in your dashboard for review. Cannot be true together with requireManualFraudApproval.
Require returning participants to authenticate. Affiliate programs require this to be true.
When true, GrowSurf stores only the minimum participant data needed to help you meet GDPR/CCPA requirements. Some participant fields are omitted and fraud screening is limited while this is on.
When true, referrals from visitors who arrived through paid ads (for example Google or Facebook ads) are not attributed, so the referring participant is not credited for them. Recommended so participants don't compete with you for your own paid keywords.
Selects which server-verified visit receives conversion credit within referralCookieWindowDays. LAST_CLICK is used when this field is missing, including for programs created before attribution models were configurable.
LAST_CLICKPossible values: How long, in days, a referral-link click is remembered in the visitor's browser. If the visitor signs up within this window, the referral is credited to the participant whose link they clicked.
How long, in days, a referred friend has to complete a qualifying action for their referrer to earn credit and unlock a reward. After this window the referral no longer counts toward rewards. null = never expires.
Affiliate programs only. Minimum payout in the program's currency minor units (0 or null = no minimum). Requires currencyISO to be set.
Campaign options updated.
A program's options (the dashboard Program Editor's Options tab). To see the full object with every field and its current value, GET this resource, then PATCH back only the fields you want to change. Some fields are program-type specific (see the per-field notes).
Affiliate programs only. How public signups join the program. OPEN_ENROLLMENT enrolls signups directly (the default for programs created before applications existed). MANUAL_REVIEW collects an application you approve or deny. AUTO_APPROVE collects the full application and approves it immediately. Switching to a reviewed mode requires a saved Program Page. Trusted enrollment through the API, CSV import, dashboard, or invites is never blocked by this setting.
Affiliate programs only. Whether a denied applicant may apply again. AFTER_COOLDOWN (the default) allows a new application once affiliateReapplicationCooldownDays has passed; DISABLED never allows one.
Affiliate programs only. How many days a denied applicant waits before they can apply again (1-365, default 30). Only used when affiliateReapplicationPolicy is AFTER_COOLDOWN.
Affiliate programs only. Optional review-time expectation (in business days, 1-60) shown to pending applicants. Send null to clear it; when unset, applicants see neutral "we'll email you" copy instead.
Referral programs only. When true, each reward a participant earns is held for you to manually approve before it unlocks (and before the reward-won email is sent); when false, earned rewards are approved automatically. Cannot be true together with autoFulfillRewards.
Referral programs only. When true, rewards a participant earns are automatically marked as sent instead of you marking each one by hand, usually paired with an automated reward-delivery integration. Cannot be true together with requireManualRewardApproval.
When true, no signup is automatically blocked for fraud. Every participant is allowed to join, and any suspected fraud is flagged in your dashboard for you to review. Cannot be true together with autoBlockFraud.
When true, signups flagged as high fraud risk are automatically blocked from joining; when false, they are allowed in and flagged in your dashboard for review. Cannot be true together with requireManualFraudApproval.
Require returning participants to authenticate. Affiliate programs require this to be true.
When true, GrowSurf stores only the minimum participant data needed to help you meet GDPR/CCPA requirements. Some participant fields are omitted and fraud screening is limited while this is on.
When true, referrals from visitors who arrived through paid ads (for example Google or Facebook ads) are not attributed, so the referring participant is not credited for them. Recommended so participants don't compete with you for your own paid keywords.
Selects which server-verified visit receives conversion credit within referralCookieWindowDays. LAST_CLICK is used when this field is missing, including for programs created before attribution models were configurable.
LAST_CLICKPossible values: How long, in days, a referral-link click is remembered in the visitor's browser. If the visitor signs up within this window, the referral is credited to the participant whose link they clicked.
How long, in days, a referred friend has to complete a qualifying action for their referrer to earn credit and unlock a reward. After this window the referral no longer counts toward rewards. null = never expires.
Affiliate programs only. Minimum payout in the program's currency minor units (0 or null = no minimum). Requires currencyISO to be set.
Invalid request.
The API key is missing, invalid, revoked, outside its scope, or not allowed to perform this action.
Resource not found.
Too many requests.
PATCH /v2/campaign/{id}/options HTTP/1.1
Host: api.growsurf.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 149
{
"blockPaidAdsTraffic": true,
"attributionModel": "LAST_CLICK",
"referralCookieWindowDays": 90,
"fraud": {
"blockBurnerEmails": true,
"maxSignupsPerIp2Min": 5
}
}{
"blockPaidAdsTraffic": true,
"attributionModel": "LAST_CLICK",
"referralCookieWindowDays": 90,
"fraud": {
"blockBurnerEmails": true,
"maxSignupsPerIp2Min": 5
}
}CAMPAIGN INSTALLATION ↓
Retrieves a program's installation configuration — the same surface as the dashboard Program Editor's Installation tab (plus the Mobile SDK settings). Includes the referral trigger (referral programs only), signup tracking method, share URL and whitelist, custom-form signup settings, and mobile SDK settings.
GrowSurf REST API key supplied as Authorization: Bearer <api_key>.
GrowSurf program ID.
Campaign installation configuration returned.
A program's installation configuration (the dashboard Program Editor's Installation tab). To see the full object with every field and its current value, GET this resource, then PATCH back only the fields you want to change. referralTrigger is only present and writable for referral programs.
Referral programs only. Sets what a referred friend must do before a referral counts. ON_SIGNUP ("Sign Up") counts the referral as soon as they sign up. CUSTOM ("Sign Up + Qualifying Action") counts it only after they sign up and also complete a qualifying action you define, such as a first payment.
CUSTOMPossible values: The signup tracking method. FORM_DETECTION = GrowSurf automatically detects submissions of an existing form on your site; PROGRAMMATIC = you add participants via the JavaScript/mobile SDKs or this API.
PROGRAMMATICPossible values: The landing page referred friends are taken to when they click a participant's referral link — usually your homepage or a marketing page. Required; must include an http(s):// scheme and contain no #, #!, or ??.
https://piedpiper.comWhen true, each participant's referral link becomes a GrowSurf-hosted link instead of a link to your own share URL, and clicks are routed by the visitor's device (Android to Google Play, iOS to your iOS attribution or App Store URL, desktop to your share URL). Mainly used by mobile apps. Applies to referral links everywhere they appear, including the SDKs, integrations, webhooks, the GrowSurf window, and participant exports.
Extra domains, beyond your share URL, where the GrowSurf window and SDK are allowed to run — handy for testing on local or staging URLs. Adding an apex domain (e.g. https://piedpiper.com) also allows its subdomains. Known shared-platform root domains, such as github.io, do not grant access. Add your site's hostname, such as https://piedpiper.github.io, or a domain you own. Path-based shared hosts, such as unbouncepages.com, require a domain you own. Each entry must include an http(s):// scheme. Sending this array replaces the entire list.
["https://piedpiper.com","https://staging.piedpiper.com"]Invalid request.
The API key is missing, invalid, revoked, outside its scope, or not allowed to perform this action.
Resource not found.
Too many requests.
GET /v2/campaign/{id}/installation HTTP/1.1
Host: api.growsurf.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"shareUrl": "https://piedpiper.com",
"signupEvent": "PROGRAMMATIC",
"referralTrigger": "CUSTOM"
}Updates a program's installation configuration. Only the fields you send are changed; omitted fields are left untouched. referralTrigger is only available for referral programs. mobile.publicKey is read-only; if no key exists yet, enabling mobile.isEnabled creates one. Changing shareUrl re-resolves its redirect destinations, which may take a moment to complete. URLs must include an explicit http:// or https:// scheme.
GrowSurf REST API key supplied as Authorization: Bearer <api_key>.
GrowSurf program ID.
A program's installation configuration (the dashboard Program Editor's Installation tab). To see the full object with every field and its current value, GET this resource, then PATCH back only the fields you want to change. referralTrigger is only present and writable for referral programs.
Referral programs only. Sets what a referred friend must do before a referral counts. ON_SIGNUP ("Sign Up") counts the referral as soon as they sign up. CUSTOM ("Sign Up + Qualifying Action") counts it only after they sign up and also complete a qualifying action you define, such as a first payment.
CUSTOMPossible values: The signup tracking method. FORM_DETECTION = GrowSurf automatically detects submissions of an existing form on your site; PROGRAMMATIC = you add participants via the JavaScript/mobile SDKs or this API.
PROGRAMMATICPossible values: The landing page referred friends are taken to when they click a participant's referral link — usually your homepage or a marketing page. Required; must include an http(s):// scheme and contain no #, #!, or ??.
https://piedpiper.comWhen true, each participant's referral link becomes a GrowSurf-hosted link instead of a link to your own share URL, and clicks are routed by the visitor's device (Android to Google Play, iOS to your iOS attribution or App Store URL, desktop to your share URL). Mainly used by mobile apps. Applies to referral links everywhere they appear, including the SDKs, integrations, webhooks, the GrowSurf window, and participant exports.
Extra domains, beyond your share URL, where the GrowSurf window and SDK are allowed to run — handy for testing on local or staging URLs. Adding an apex domain (e.g. https://piedpiper.com) also allows its subdomains. Known shared-platform root domains, such as github.io, do not grant access. Add your site's hostname, such as https://piedpiper.github.io, or a domain you own. Path-based shared hosts, such as unbouncepages.com, require a domain you own. Each entry must include an http(s):// scheme. Sending this array replaces the entire list.
["https://piedpiper.com","https://staging.piedpiper.com"]Campaign installation configuration updated.
A program's installation configuration (the dashboard Program Editor's Installation tab). To see the full object with every field and its current value, GET this resource, then PATCH back only the fields you want to change. referralTrigger is only present and writable for referral programs.
Referral programs only. Sets what a referred friend must do before a referral counts. ON_SIGNUP ("Sign Up") counts the referral as soon as they sign up. CUSTOM ("Sign Up + Qualifying Action") counts it only after they sign up and also complete a qualifying action you define, such as a first payment.
CUSTOMPossible values: The signup tracking method. FORM_DETECTION = GrowSurf automatically detects submissions of an existing form on your site; PROGRAMMATIC = you add participants via the JavaScript/mobile SDKs or this API.
PROGRAMMATICPossible values: The landing page referred friends are taken to when they click a participant's referral link — usually your homepage or a marketing page. Required; must include an http(s):// scheme and contain no #, #!, or ??.
https://piedpiper.comWhen true, each participant's referral link becomes a GrowSurf-hosted link instead of a link to your own share URL, and clicks are routed by the visitor's device (Android to Google Play, iOS to your iOS attribution or App Store URL, desktop to your share URL). Mainly used by mobile apps. Applies to referral links everywhere they appear, including the SDKs, integrations, webhooks, the GrowSurf window, and participant exports.
Extra domains, beyond your share URL, where the GrowSurf window and SDK are allowed to run — handy for testing on local or staging URLs. Adding an apex domain (e.g. https://piedpiper.com) also allows its subdomains. Known shared-platform root domains, such as github.io, do not grant access. Add your site's hostname, such as https://piedpiper.github.io, or a domain you own. Path-based shared hosts, such as unbouncepages.com, require a domain you own. Each entry must include an http(s):// scheme. Sending this array replaces the entire list.
["https://piedpiper.com","https://staging.piedpiper.com"]Invalid request.
The API key is missing, invalid, revoked, outside its scope, or not allowed to perform this action.
Resource not found.
Too many requests.
PATCH /v2/campaign/{id}/installation HTTP/1.1
Host: api.growsurf.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 92
{
"shareUrl": "https://piedpiper.com",
"signupEvent": "PROGRAMMATIC",
"referralTrigger": "CUSTOM"
}{
"shareUrl": "https://piedpiper.com",
"signupEvent": "PROGRAMMATIC",
"referralTrigger": "CUSTOM"
}CAMPAIGN INTEGRATIONS ↓
Lists every integration this program can connect, each with its current state. Integrations that do not apply to the program type are omitted (for example, Wise on a referral program). Read-only: connecting an integration is an OAuth or credential handshake completed in the GrowSurf dashboard, so it cannot be done over the API. connected means credentials are stored, enabled means the integration is switched on and working, and autoDisabled means GrowSurf switched it off after repeated delivery failures — its credentials are still stored, but it delivers nothing until it is reconnected in the dashboard. connectUrl is the dashboard link to hand the person running the program when they want to connect one.
GrowSurf REST API key supplied as Authorization: Bearer <api_key>.
GrowSurf program ID.
Integrations returned.
The API key is missing, invalid, revoked, outside its scope, or not allowed to perform this action.
Resource not found.
Too many requests.
GET /v2/campaign/{id}/integrations HTTP/1.1
Host: api.growsurf.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"integrations": [
{
"id": "mailchimp",
"name": "Mailchimp",
"connected": true,
"enabled": true,
"autoDisabled": false,
"connectUrl": "https://app.growsurf.com/editor/aq2ln3/options/integrations?integration=mailchimp"
},
{
"id": "stripe",
"name": "Stripe",
"connected": true,
"enabled": false,
"autoDisabled": false,
"connectUrl": "https://app.growsurf.com/editor/aq2ln3/options/integrations?integration=stripe"
},
{
"id": "slack",
"name": "Slack",
"connected": false,
"enabled": false,
"autoDisabled": false,
"connectUrl": "https://app.growsurf.com/editor/aq2ln3/options/integrations?integration=slack"
}
]
}CAMPAIGN WEBHOOKS ↓
Lists a program's webhooks (secrets are never returned).
GrowSurf REST API key supplied as Authorization: Bearer <api_key>.
GrowSurf program ID.
Webhooks returned.
The API key is missing, invalid, revoked, outside its scope, or not allowed to perform this action.
Resource not found.
Too many requests.
GET /v2/campaign/{id}/webhooks HTTP/1.1
Host: api.growsurf.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"webhooks": [
{
"id": "primary",
"payloadUrl": "https://piedpiper.com/growsurf/webhook",
"events": [
"NEW_PARTICIPANT_ADDED",
"PARTICIPANT_REACHED_A_GOAL"
],
"isEnabled": true,
"autoDisabledDueToFailures": false,
"failureCount": 0,
"lastFailureAt": null
}
]
}Adds a webhook to the program.
GrowSurf REST API key supplied as Authorization: Bearer <api_key>.
GrowSurf program ID.
The URL that receives webhook deliveries.
https://piedpiper.com/growsurf/webhookWrite-only. Used to sign deliveries (the GrowSurf-Signature HMAC header). Never returned.
whsec_piedpiper_webhook_secretWhether the webhook should start enabled. Defaults to true.
trueWebhook created.
A program webhook's configuration (payload URL, subscribed events, enabled state) plus read-only delivery-health fields.
The webhook id (primary for the program's primary webhook).
primaryThe URL that receives webhook deliveries.
https://piedpiper.com/growsurf/webhookWhether deliveries to this webhook are enabled.
trueRead-only. Whether GrowSurf auto-disabled this webhook after repeated delivery failures.
falseRead-only. Consecutive delivery failures.
0Read-only. When the last delivery failure occurred, as a Unix timestamp in milliseconds.
Invalid request.
The API key is missing, invalid, revoked, outside its scope, or not allowed to perform this action.
Resource not found.
Too many requests.
POST /v2/campaign/{id}/webhooks HTTP/1.1
Host: api.growsurf.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 163
{
"payloadUrl": "https://piedpiper.com/growsurf/webhook",
"events": [
"NEW_PARTICIPANT_ADDED",
"PARTICIPANT_REACHED_A_GOAL"
],
"secret": "whsec_middleout",
"isEnabled": true
}{
"id": "primary",
"payloadUrl": "https://piedpiper.com/growsurf/webhook",
"events": [
"NEW_PARTICIPANT_ADDED",
"PARTICIPANT_REACHED_A_GOAL"
],
"isEnabled": true,
"autoDisabledDueToFailures": false,
"failureCount": 0,
"lastFailureAt": null
}Updates a webhook by id.
GrowSurf REST API key supplied as Authorization: Bearer <api_key>.
GrowSurf program ID.
Webhook ID (primary for the program's primary webhook, or the id of an additional webhook).
New URL that receives webhook deliveries.
https://piedpiper.com/growsurf/webhookWrite-only.
whsec_rotated_piedpiper_secretWhether deliveries to this webhook are enabled.
Webhook updated.
A program webhook's configuration (payload URL, subscribed events, enabled state) plus read-only delivery-health fields.
The webhook id (primary for the program's primary webhook).
primaryThe URL that receives webhook deliveries.
https://piedpiper.com/growsurf/webhookWhether deliveries to this webhook are enabled.
trueRead-only. Whether GrowSurf auto-disabled this webhook after repeated delivery failures.
falseRead-only. Consecutive delivery failures.
0Read-only. When the last delivery failure occurred, as a Unix timestamp in milliseconds.
Invalid request.
The API key is missing, invalid, revoked, outside its scope, or not allowed to perform this action.
Resource not found.
Too many requests.
PATCH /v2/campaign/{id}/webhooks/{webhookId} HTTP/1.1
Host: api.growsurf.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 54
{
"events": [
"NEW_PARTICIPANT_ADDED"
],
"isEnabled": false
}{
"id": "primary",
"payloadUrl": "https://piedpiper.com/growsurf/webhook",
"events": [
"NEW_PARTICIPANT_ADDED",
"PARTICIPANT_REACHED_A_GOAL"
],
"isEnabled": true,
"autoDisabledDueToFailures": false,
"failureCount": 0,
"lastFailureAt": null
}Removes a webhook by id.
GrowSurf REST API key supplied as Authorization: Bearer <api_key>.
GrowSurf program ID.
Webhook ID (primary for the program's primary webhook, or the id of an additional webhook).
Webhook deleted.
ID of the webhook that was deleted.
Whether the webhook was deleted.
The API key is missing, invalid, revoked, outside its scope, or not allowed to perform this action.
Resource not found.
Too many requests.
DELETE /v2/campaign/{id}/webhooks/{webhookId} HTTP/1.1
Host: api.growsurf.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"id": "primary",
"success": true
}Sends a live test event to a webhook using its stored URL and secret.
GrowSurf REST API key supplied as Authorization: Bearer <api_key>.
GrowSurf program ID.
Webhook ID (primary for the program's primary webhook, or the id of an additional webhook).
The event to simulate. When omitted, the webhook's first enabled event is used, and the request returns 400 if the webhook has no enabled events.
NEW_PARTICIPANT_ADDEDPossible values: Test result.
Whether the test webhook request completed.
Invalid request.
The API key is missing, invalid, revoked, outside its scope, or not allowed to perform this action.
Resource not found.
Too many requests.
POST /v2/campaign/{id}/webhooks/{webhookId}/test HTTP/1.1
Host: api.growsurf.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 33
{
"event": "NEW_PARTICIPANT_ADDED"
}{
"success": true,
"payload": {
"event": "NEW_PARTICIPANT_ADDED",
"participant": {
"id": "f8g9nl",
"email": "gavin@hooli.com"
}
},
"response": {
"msg": "OK",
"statusCode": 200
}
}PARTICIPANTS ↓
Retrieves a paged list of participants in a program.
Pass metadata[key]=value to return only participants whose stored metadata matches every given key and value exactly, for example metadata[customerId]=12345. Up to 3 keys per request. Filtered results are ordered by participant id and page with the same nextId and limit parameters. Filtered requests are rate limited separately from unfiltered ones and return 429 when that limit is reached.
GrowSurf REST API key supplied as Authorization: Bearer <api_key>.
GrowSurf program ID.
ID to start the next paged result set with.
Number of results to return. Maximum 100.
10Participants returned.
Maximum number of participants requested for this page.
Participant ID to pass as nextId for the next page, or null when there are no more results.
Invalid request.
The API key is missing, invalid, revoked, outside its scope, or not allowed to perform this action.
Resource not found.
Too many requests.
GET /v2/campaign/{id}/participants HTTP/1.1
Host: api.growsurf.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"participants": [
{
"id": "3vxff9",
"firstName": "Gavin",
"lastName": "Belson",
"referralCount": 0,
"monthlyReferralCount": 0,
"prevMonthlyReferralCount": 0,
"leadCount": 0,
"rank": 10001,
"monthlyRank": 50,
"shareUrl": "https://hooli.com?grsf=gavin-3vxff9",
"rewards": [],
"email": "gavin@hooli.com",
"createdAt": 1558665537426,
"referralSource": "DIRECT",
"isWinner": false,
"shareCount": {
"email": 0,
"facebook": 0,
"linkedin": 0,
"pinterest": 0,
"twitter": 0
},
"impressionCount": 0,
"uniqueImpressionCount": 0,
"inviteCount": 3,
"referrals": [],
"referrer": null,
"metadata": {},
"vanityKeys": [
"gavin-3vxff9"
],
"unsubscribed": false
}
],
"limit": 10,
"nextId": "1u7v0q"
}Retrieves participants in leaderboard order for the specified leaderboard type.
GrowSurf REST API key supplied as Authorization: Bearer <api_key>.
GrowSurf program ID.
ID to start the next paged result set with.
Number of results to return. Maximum 100.
10Deprecated. Use leaderboardType=CURRENT_MONTH instead.
falseLeaderboard ordering mode.
ALL_TIMEExample: ALL_TIMEPossible values: Leaderboard participants returned.
Maximum number of participants requested for this page.
Participant ID to pass as nextId for the next page, or null when there are no more results.
Invalid request.
The API key is missing, invalid, revoked, outside its scope, or not allowed to perform this action.
Resource not found.
Request is not valid for the current program or participant state.
Too many requests.
GET /v2/campaign/{id}/leaderboard HTTP/1.1
Host: api.growsurf.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"participants": [
{
"id": "3vxff9",
"firstName": "Gavin",
"lastName": "Belson",
"referralCount": 0,
"monthlyReferralCount": 0,
"prevMonthlyReferralCount": 0,
"leadCount": 0,
"rank": 10001,
"monthlyRank": 50,
"shareUrl": "https://hooli.com?grsf=gavin-3vxff9",
"rewards": [],
"email": "gavin@hooli.com",
"createdAt": 1558665537426,
"referralSource": "DIRECT",
"isWinner": false,
"shareCount": {
"email": 0,
"facebook": 0,
"linkedin": 0,
"pinterest": 0,
"twitter": 0
},
"impressionCount": 0,
"uniqueImpressionCount": 0,
"inviteCount": 3,
"referrals": [],
"referrer": null,
"metadata": {},
"vanityKeys": [
"gavin-3vxff9"
],
"unsubscribed": false
}
],
"limit": 10,
"nextId": "1u7v0q"
}Adds a new participant to the program. If the email already exists, the existing participant is returned unchanged. For affiliate programs, set isAffiliate to true to enroll a new participant as an approved affiliate or false to create a non-affiliate. If you omit isAffiliate, a valid referredBy creates a referred non-affiliate; without a valid referrer, the new participant is enrolled as an approved affiliate. You can send a valid referredBy with isAffiliate: true to keep the referral attribution and enroll the participant as an affiliate. A new participant with a valid referredBy counts as a referred signup. When the program's referralTrigger is CUSTOM, that signup can earn Lead-event rewards and commissions for the referrer, the same as a signup through the public client or mobile flow.
GrowSurf REST API key supplied as Authorization: Bearer <api_key>.
GrowSurf program ID.
Participant email address.
gavin@hooli.comReferrer participant ID or email address.
richard@piedpiper.comAffiliate programs only. Controls affiliate enrollment for a new participant. true enrolls the participant with affiliateStatus: APPROVED; false creates a non-affiliate without affiliateStatus. Existing participants are returned unchanged.
The referral credit status, only meaningful when referredBy resolves to a referrer. When omitted, it is derived from the program's referral trigger: CREDIT_AWARDED, CREDIT_PENDING (manual or custom trigger), or CREDIT_EXPIRED (past the credit window). Left unset when no referrer resolves.
CREDIT_AWARDEDPossible values: Participant first name.
GavinParticipant last name.
BelsonParticipant IP address, when available.
203.0.113.10Browser identifier, when available.
9d4c1f2ab8e35d7c6a1b0e9f8d7c6b5aOptional app-install scoped identifier supplied by a native app. Recommended for mobile participant creation and mobile participant token flows. The official mobile SDKs generate a lowercase UUID.
5f7d0f4c-3e7c-4aa9-8c41-d81d998f0bb1Participant returned.
Detailed information about a program participant.
The unique identifier of the participant.
f8g9nlAffiliate programs only. Whether this participant is an enrolled affiliate. A referred customer who has not joined the program is false.
Affiliate programs only. The enrolled affiliate's status (APPROVED, SUSPENDED, or BANNED). null for participants who are not affiliates.
Affiliate programs only. How the affiliate enrolled (OPEN_ENROLLMENT, APPLICATION, PARTICIPANT_AUTH, INVITE, REST_API, CSV, or DASHBOARD). null when not recorded.
The first name of the participant.
GavinThe last name of the participant.
BelsonThe email of the participant.
gavin@hooli.comThe PayPal email address on file for the participant, used for affiliate or PayPal reward payouts.
gavin@hooli.comThe total number of referrals made by the participant.
2The total number of referrals made this month by the participant (resets at the end of the month).
2The total number of referrals made the previous month by the participant.
0The number of pending referrals the participant made that have not converted into successful referrals yet. Not cumulative: it goes down when a lead converts.
1The rank of the participant.
10001The monthly rank of the participant. This rank resets to 0 at the end of each month.
20001The previous monthly rank of the participant. Not returned if the participant did not exist in your program during the previous month.
24000The unique share URL of the participant. Omitted for affiliate program participants who are not approved affiliates.
https://piedpiper.com?grsf=gavin-f8g9nlThe date the participant was added to the program (UTC milliseconds).
1552404738928The source of how the participant joined the program.
PARTICIPANTPossible values: If the participant was referred, the referrer's status in receiving the referral credit. Only applicable if the participant was referred into the program.
CREDIT_AWARDEDPossible values: The ID of the referrer. Only applicable if the participant was referred into the program.
h8kp6lA value that represents the integrity of the participant.
LOWPossible values: Machine-readable label for the participant's fraudRiskLevel. The label identifies broad
outcomes such as unique or duplicate participant data, suspicious referral activity,
configured access rules, or a manual update.
Current labels include UNIQUE_IDENTITY, DUPLICATE_EMAIL, DUPLICATE_IDENTITY,
DUPLICATE_IDENTITY_EXCESSIVE, EMAIL_FRAUD, SIMILAR_EMAIL, SIMILAR_FIRST_NAME,
SIMILAR_LAST_NAME, REFERRAL_EMAIL_PATTERN, REFERRAL_CHAIN_FRAUD,
REFERRAL_VELOCITY_FRAUD, DOMAIN_CLUSTERING_FRAUD, MANUAL_UPDATE, WHITELISTED,
BLACKLIST_MATCH, BLOCKED_IP, and REFERRER_HIGH_RISK. Treat this as a diagnostic
label because GrowSurf can add labels without notice.
UNIQUE_IDENTITYtrue if the participant has earned one or more rewards.
trueThe total number of impressions the participant has made.
2The total number of unique impressions the participant has made.
2The total number of invites the participant has sent.
3A list of Participant IDs who were successfully referred by the participant. Limited to the 100 most recently referred friends.
["i9g2bh","xua4sq"]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.
["i9g2bh","xua4sq"]The IP address recorded for the participant, or null when unavailable.
127.0.0.1The browser identifier recorded for the participant, or null when unavailable.
cfb163bd47ba666c52cb932c521e47f4App-install scoped identifier supplied by a native app, or null when unavailable. The official mobile SDKs generate a lowercase UUID. Not stored when strict GDPR/CCPA mode is enabled.
5f7d0f4c-3e7c-4aa9-8c41-d81d998f0bb1Internal notes about the participant, added via the GrowSurf Dashboard.
This is obviously our competitor trying out our product!true if the participant has unsubscribed from program emails.
falseThe list of vanity keys that the participant has.
["gavin-f8g9nl"]Affiliate programs only. The number of commissions the participant has not yet viewed.
1Affiliate programs only. The number of payouts the participant has not yet viewed.
0Whether this participant was newly created by the request. Returned by participant creation calls; false when the participant already existed.
falseInvalid request.
The API key is missing, invalid, revoked, outside its scope, or not allowed to perform this action.
Conflicting duplicate request.
Participant was blocked or the endpoint is not available for this program type.
Too many requests.
POST /v2/campaign/{id}/participant HTTP/1.1
Host: api.growsurf.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 258
{
"email": "gavin@hooli.com",
"firstName": "Gavin",
"lastName": "Belson",
"ipAddress": "203.0.113.10",
"mobileInstanceId": "5f7d0f4c-3e7c-4aa9-8c41-d81d998f0bb1",
"referredBy": "richard-h8kp6l",
"isAffiliate": true,
"metadata": {
"companyName": "Hooli",
"industry": "Software"
}
}{
"id": "f8g9nl",
"firstName": "Gavin",
"lastName": "Belson",
"referralCount": 2,
"monthlyReferralCount": 2,
"prevMonthlyReferralCount": 0,
"leadCount": 1,
"rank": 10001,
"monthlyRank": 20001,
"shareUrl": "https://piedpiper.com?grsf=gavin-f8g9nl",
"email": "gavin@hooli.com",
"createdAt": 1552404738928,
"fraudRiskLevel": "LOW",
"fraudReasonCode": "UNIQUE_IDENTITY",
"isWinner": true,
"shareCount": {
"email": 10,
"facebook": 1,
"pinterest": 1,
"twitter": 11
},
"impressionCount": 2,
"uniqueImpressionCount": 2,
"inviteCount": 3,
"referrals": [
"i9g2bh",
"xua4sq"
],
"monthlyReferrals": [
"i9g2bh",
"xua4sq"
],
"referralSource": "PARTICIPANT",
"referralStatus": "CREDIT_AWARDED",
"referrer": null,
"ipAddress": "127.0.0.1",
"fingerprint": "cfb163bd47ba666c52cb932c521e47f4",
"mobileInstanceId": "5f7d0f4c-3e7c-4aa9-8c41-d81d998f0bb1",
"metadata": {
"company": "Hooli, Inc",
"companySize": 10000
},
"unsubscribed": false,
"rewards": [],
"vanityKeys": [
"gavin-f8g9nl"
]
}Retrieves a single participant by GrowSurf participant ID or email address.
GrowSurf REST API key supplied as Authorization: Bearer <api_key>.
GrowSurf program ID.
GrowSurf participant ID or URL-encoded participant email address.
Participant returned.
Detailed information about a program participant.
The unique identifier of the participant.
f8g9nlAffiliate programs only. Whether this participant is an enrolled affiliate. A referred customer who has not joined the program is false.
Affiliate programs only. The enrolled affiliate's status (APPROVED, SUSPENDED, or BANNED). null for participants who are not affiliates.
Affiliate programs only. How the affiliate enrolled (OPEN_ENROLLMENT, APPLICATION, PARTICIPANT_AUTH, INVITE, REST_API, CSV, or DASHBOARD). null when not recorded.
The first name of the participant.
GavinThe last name of the participant.
BelsonThe email of the participant.
gavin@hooli.comThe PayPal email address on file for the participant, used for affiliate or PayPal reward payouts.
gavin@hooli.comThe total number of referrals made by the participant.
2The total number of referrals made this month by the participant (resets at the end of the month).
2The total number of referrals made the previous month by the participant.
0The number of pending referrals the participant made that have not converted into successful referrals yet. Not cumulative: it goes down when a lead converts.
1The rank of the participant.
10001The monthly rank of the participant. This rank resets to 0 at the end of each month.
20001The previous monthly rank of the participant. Not returned if the participant did not exist in your program during the previous month.
24000The unique share URL of the participant. Omitted for affiliate program participants who are not approved affiliates.
https://piedpiper.com?grsf=gavin-f8g9nlThe date the participant was added to the program (UTC milliseconds).
1552404738928The source of how the participant joined the program.
PARTICIPANTPossible values: If the participant was referred, the referrer's status in receiving the referral credit. Only applicable if the participant was referred into the program.
CREDIT_AWARDEDPossible values: The ID of the referrer. Only applicable if the participant was referred into the program.
h8kp6lA value that represents the integrity of the participant.
LOWPossible values: Machine-readable label for the participant's fraudRiskLevel. The label identifies broad
outcomes such as unique or duplicate participant data, suspicious referral activity,
configured access rules, or a manual update.
Current labels include UNIQUE_IDENTITY, DUPLICATE_EMAIL, DUPLICATE_IDENTITY,
DUPLICATE_IDENTITY_EXCESSIVE, EMAIL_FRAUD, SIMILAR_EMAIL, SIMILAR_FIRST_NAME,
SIMILAR_LAST_NAME, REFERRAL_EMAIL_PATTERN, REFERRAL_CHAIN_FRAUD,
REFERRAL_VELOCITY_FRAUD, DOMAIN_CLUSTERING_FRAUD, MANUAL_UPDATE, WHITELISTED,
BLACKLIST_MATCH, BLOCKED_IP, and REFERRER_HIGH_RISK. Treat this as a diagnostic
label because GrowSurf can add labels without notice.
UNIQUE_IDENTITYtrue if the participant has earned one or more rewards.
trueThe total number of impressions the participant has made.
2The total number of unique impressions the participant has made.
2The total number of invites the participant has sent.
3A list of Participant IDs who were successfully referred by the participant. Limited to the 100 most recently referred friends.
["i9g2bh","xua4sq"]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.
["i9g2bh","xua4sq"]The IP address recorded for the participant, or null when unavailable.
127.0.0.1The browser identifier recorded for the participant, or null when unavailable.
cfb163bd47ba666c52cb932c521e47f4App-install scoped identifier supplied by a native app, or null when unavailable. The official mobile SDKs generate a lowercase UUID. Not stored when strict GDPR/CCPA mode is enabled.
5f7d0f4c-3e7c-4aa9-8c41-d81d998f0bb1Internal notes about the participant, added via the GrowSurf Dashboard.
This is obviously our competitor trying out our product!true if the participant has unsubscribed from program emails.
falseThe list of vanity keys that the participant has.
["gavin-f8g9nl"]Affiliate programs only. The number of commissions the participant has not yet viewed.
1Affiliate programs only. The number of payouts the participant has not yet viewed.
0Whether this participant was newly created by the request. Returned by participant creation calls; false when the participant already existed.
falseInvalid request.
The API key is missing, invalid, revoked, outside its scope, or not allowed to perform this action.
Resource not found.
Too many requests.
GET /v2/campaign/{id}/participant/{participantIdOrEmail} HTTP/1.1
Host: api.growsurf.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"id": "f8g9nl",
"firstName": "Gavin",
"lastName": "Belson",
"referralCount": 2,
"monthlyReferralCount": 2,
"prevMonthlyReferralCount": 0,
"leadCount": 1,
"rank": 10001,
"monthlyRank": 20001,
"shareUrl": "https://piedpiper.com?grsf=gavin-f8g9nl",
"email": "gavin@hooli.com",
"createdAt": 1552404738928,
"fraudRiskLevel": "LOW",
"fraudReasonCode": "UNIQUE_IDENTITY",
"isWinner": true,
"shareCount": {
"email": 10,
"facebook": 1,
"pinterest": 1,
"twitter": 11
},
"impressionCount": 2,
"uniqueImpressionCount": 2,
"inviteCount": 3,
"referrals": [
"i9g2bh",
"xua4sq"
],
"monthlyReferrals": [
"i9g2bh",
"xua4sq"
],
"referralSource": "PARTICIPANT",
"referralStatus": "CREDIT_AWARDED",
"referrer": null,
"ipAddress": "127.0.0.1",
"fingerprint": "cfb163bd47ba666c52cb932c521e47f4",
"mobileInstanceId": "5f7d0f4c-3e7c-4aa9-8c41-d81d998f0bb1",
"metadata": {
"company": "Hooli, Inc",
"companySize": 10000
},
"unsubscribed": false,
"rewards": [],
"vanityKeys": [
"gavin-f8g9nl"
]
}Updates a participant by GrowSurf participant ID or email address. For affiliate programs, set affiliateStatus to APPROVED, SUSPENDED, or BANNED. APPROVED enrolls the participant as an affiliate. SUSPENDED and BANNED require an existing affiliate. This endpoint does not accept isAffiliate, and affiliate enrollment cannot be removed through REST. Setting referredBy on a participant without a referrer counts as a referred signup: when the program's referralTrigger is CUSTOM and the referral is CREDIT_PENDING, it can earn Lead-event rewards and commissions for the referrer once. A referrer assigned with referralStatus: CREDIT_AWARDED does not earn Lead value.
GrowSurf REST API key supplied as Authorization: Bearer <api_key>.
GrowSurf program ID.
GrowSurf participant ID or URL-encoded participant email address.
The participant fields you can update. Any property not listed here is rejected with a 400 (you cannot update read-only fields such as counters, isAffiliate, origin, or fraud state).
Referrer participant ID or email address to assign to this participant.
richard@piedpiper.comParticipant email address.
gavin@hooli.comParticipant first name.
GavinParticipant last name.
BelsonReferral credit status for this participant.
CREDIT_AWARDEDPossible values: Affiliate programs only. Sets the affiliate status. APPROVED also enrolls a participant who is not yet an affiliate. SUSPENDED and BANNED are rejected for non-affiliates.
Custom referral-code aliases for this participant. Sending this array replaces the existing aliases.
["gavin-belson","hooli"]Whether the participant is unsubscribed from program emails.
Freeform internal notes about the participant (internal only, never exposed to participants).
VIP prospect from the Hooli partner program.Updated participant returned.
Detailed information about a program participant.
The unique identifier of the participant.
f8g9nlAffiliate programs only. Whether this participant is an enrolled affiliate. A referred customer who has not joined the program is false.
Affiliate programs only. The enrolled affiliate's status (APPROVED, SUSPENDED, or BANNED). null for participants who are not affiliates.
Affiliate programs only. How the affiliate enrolled (OPEN_ENROLLMENT, APPLICATION, PARTICIPANT_AUTH, INVITE, REST_API, CSV, or DASHBOARD). null when not recorded.
The first name of the participant.
GavinThe last name of the participant.
BelsonThe email of the participant.
gavin@hooli.comThe PayPal email address on file for the participant, used for affiliate or PayPal reward payouts.
gavin@hooli.comThe total number of referrals made by the participant.
2The total number of referrals made this month by the participant (resets at the end of the month).
2The total number of referrals made the previous month by the participant.
0The number of pending referrals the participant made that have not converted into successful referrals yet. Not cumulative: it goes down when a lead converts.
1The rank of the participant.
10001The monthly rank of the participant. This rank resets to 0 at the end of each month.
20001The previous monthly rank of the participant. Not returned if the participant did not exist in your program during the previous month.
24000The unique share URL of the participant. Omitted for affiliate program participants who are not approved affiliates.
https://piedpiper.com?grsf=gavin-f8g9nlThe date the participant was added to the program (UTC milliseconds).
1552404738928The source of how the participant joined the program.
PARTICIPANTPossible values: If the participant was referred, the referrer's status in receiving the referral credit. Only applicable if the participant was referred into the program.
CREDIT_AWARDEDPossible values: The ID of the referrer. Only applicable if the participant was referred into the program.
h8kp6lA value that represents the integrity of the participant.
LOWPossible values: Machine-readable label for the participant's fraudRiskLevel. The label identifies broad
outcomes such as unique or duplicate participant data, suspicious referral activity,
configured access rules, or a manual update.
Current labels include UNIQUE_IDENTITY, DUPLICATE_EMAIL, DUPLICATE_IDENTITY,
DUPLICATE_IDENTITY_EXCESSIVE, EMAIL_FRAUD, SIMILAR_EMAIL, SIMILAR_FIRST_NAME,
SIMILAR_LAST_NAME, REFERRAL_EMAIL_PATTERN, REFERRAL_CHAIN_FRAUD,
REFERRAL_VELOCITY_FRAUD, DOMAIN_CLUSTERING_FRAUD, MANUAL_UPDATE, WHITELISTED,
BLACKLIST_MATCH, BLOCKED_IP, and REFERRER_HIGH_RISK. Treat this as a diagnostic
label because GrowSurf can add labels without notice.
UNIQUE_IDENTITYtrue if the participant has earned one or more rewards.
trueThe total number of impressions the participant has made.
2The total number of unique impressions the participant has made.
2The total number of invites the participant has sent.
3A list of Participant IDs who were successfully referred by the participant. Limited to the 100 most recently referred friends.
["i9g2bh","xua4sq"]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.
["i9g2bh","xua4sq"]The IP address recorded for the participant, or null when unavailable.
127.0.0.1The browser identifier recorded for the participant, or null when unavailable.
cfb163bd47ba666c52cb932c521e47f4App-install scoped identifier supplied by a native app, or null when unavailable. The official mobile SDKs generate a lowercase UUID. Not stored when strict GDPR/CCPA mode is enabled.
5f7d0f4c-3e7c-4aa9-8c41-d81d998f0bb1Internal notes about the participant, added via the GrowSurf Dashboard.
This is obviously our competitor trying out our product!true if the participant has unsubscribed from program emails.
falseThe list of vanity keys that the participant has.
["gavin-f8g9nl"]Affiliate programs only. The number of commissions the participant has not yet viewed.
1Affiliate programs only. The number of payouts the participant has not yet viewed.
0Whether this participant was newly created by the request. Returned by participant creation calls; false when the participant already existed.
falseInvalid request.
The API key is missing, invalid, revoked, outside its scope, or not allowed to perform this action.
Resource not found.
Conflicting duplicate request.
Too many requests.
POST /v2/campaign/{id}/participant/{participantIdOrEmail} HTTP/1.1
Host: api.growsurf.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 127
{
"firstName": "Gavin",
"lastName": "Belson",
"metadata": {
"company": "Hooli, Inc"
},
"unsubscribed": false,
"affiliateStatus": "APPROVED"
}{
"id": "f8g9nl",
"firstName": "Gavin",
"lastName": "Belson",
"referralCount": 2,
"monthlyReferralCount": 2,
"prevMonthlyReferralCount": 0,
"leadCount": 1,
"rank": 10001,
"monthlyRank": 20001,
"shareUrl": "https://piedpiper.com?grsf=gavin-f8g9nl",
"email": "gavin@hooli.com",
"createdAt": 1552404738928,
"fraudRiskLevel": "LOW",
"fraudReasonCode": "UNIQUE_IDENTITY",
"isWinner": true,
"shareCount": {
"email": 10,
"facebook": 1,
"pinterest": 1,
"twitter": 11
},
"impressionCount": 2,
"uniqueImpressionCount": 2,
"inviteCount": 3,
"referrals": [
"i9g2bh",
"xua4sq"
],
"monthlyReferrals": [
"i9g2bh",
"xua4sq"
],
"referralSource": "PARTICIPANT",
"referralStatus": "CREDIT_AWARDED",
"referrer": null,
"ipAddress": "127.0.0.1",
"fingerprint": "cfb163bd47ba666c52cb932c521e47f4",
"mobileInstanceId": "5f7d0f4c-3e7c-4aa9-8c41-d81d998f0bb1",
"metadata": {
"company": "Hooli, Inc",
"companySize": 10000
},
"unsubscribed": false,
"rewards": [],
"vanityKeys": [
"gavin-f8g9nl"
]
}Removes a participant by GrowSurf participant ID or email address. A 202 response means participant cleanup completed and analytics erasure is pending. Analytics reports can retain the removed participant until erasure completes. Do not repeat the deletion to finish analytics erasure; GrowSurf processes it automatically.
GrowSurf REST API key supplied as Authorization: Bearer <api_key>.
GrowSurf program ID.
GrowSurf participant ID or URL-encoded participant email address.
Success response.
Whether the request succeeded.
Participant cleanup completed; analytics erasure is pending.
Invalid request.
The API key is missing, invalid, revoked, outside its scope, or not allowed to perform this action.
Resource not found.
The resource is temporarily locked for this operation. Retry the request in a few minutes.
Too many requests.
DELETE /v2/campaign/{id}/participant/{participantIdOrEmail} HTTP/1.1
Host: api.growsurf.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"success": true
}Deletes a list of participants from a program in one request. Each entry in participants is a GrowSurf participant ID or an email address (mixed lists are allowed). Up to 200 entries per request — chunk larger lists across multiple calls. The response reports a per-row status for every submitted entry, so a 200 can include rows that were NOT_FOUND or failed. Deletion is permanent and removes the participants' referrals, rewards, commissions, and payout records. A 202 response also includes analyticsErasure when analytics erasure is pending. A DELETED row means participant cleanup completed; analytics reports can retain that participant until erasure completes. Do not repeat successful rows to finish analytics erasure.
GrowSurf REST API key supplied as Authorization: Bearer <api_key>.
GrowSurf program ID.
GrowSurf participant IDs and/or email addresses to delete. Mixed entries are allowed.
["gavin@hooli.com","f8g9nl"]Per-row outcomes returned (individual rows may still be NOT_FOUND, DUPLICATE, or ERROR).
Per-row outcomes returned; analytics erasure is pending. Individual rows may still be NOT_FOUND, DUPLICATE, or ERROR.
Invalid request.
The API key is missing, invalid, revoked, outside its scope, or not allowed to perform this action.
Resource not found.
Too many requests.
POST /v2/campaign/{id}/participants/bulk-delete HTTP/1.1
Host: api.growsurf.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 65
{
"participants": [
"gavin@hooli.com",
"erlich@aviato.com",
"f8g9nl"
]
}{
"summary": {
"total": 3,
"deletedCount": 2,
"notFoundCount": 1,
"duplicateCount": 0,
"errorCount": 0
},
"results": [
{
"index": 0,
"identifier": "gavin@hooli.com",
"status": "DELETED",
"participantId": "f8g9nl",
"email": "gavin@hooli.com"
},
{
"index": 1,
"identifier": "erlich@aviato.com",
"status": "NOT_FOUND",
"message": "No participant matches this id or email."
},
{
"index": 2,
"identifier": "f8g9nl",
"status": "DUPLICATE",
"participantId": "f8g9nl",
"message": "Resolves to the same participant as an earlier entry in this request."
}
]
}Triggers referral credit for an existing referred participant by GrowSurf participant ID or email address. Optionally pass delayInDays to hold the credit for a number of days before it is awarded (for example, to cover your own refund window). A delayed trigger can be cancelled before it is awarded with the Cancel delayed referral trigger request (DELETE on this same path).
GrowSurf REST API key supplied as Authorization: Bearer <api_key>.
GrowSurf program ID.
GrowSurf participant ID or URL-encoded participant email address.
Optional body for a referral trigger. Omit it (or send an empty object) to award credit immediately.
Number of whole days to hold referral credit before it is awarded. Useful for honoring a refund window before crediting a referrer. Omit this field to award credit immediately. The credit is awarded automatically once the delay elapses, and can be cancelled before then with the Cancel delayed referral trigger request.
14Referral trigger result returned.
Whether referral credit was awarded or scheduled.
Human-readable result message, present when credit was not awarded immediately or when a delayed trigger was scheduled.
Invalid request.
The API key is missing, invalid, revoked, outside its scope, or not allowed to perform this action.
Resource not found.
Request is not valid for the current program or participant state.
Too many requests.
POST /v2/campaign/{id}/participant/{participantIdOrEmail}/ref HTTP/1.1
Host: api.growsurf.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 2
{}{
"success": true,
"message": "Successfully awarded referral credit."
}Cancels a pending delayed referral trigger for a participant (the companion to a delayed Trigger referral request). Use this to undo a scheduled referral credit before it is awarded, for example when a refund occurs inside your refund window. If the participant has no pending delayed trigger, success is returned as false.
GrowSurf REST API key supplied as Authorization: Bearer <api_key>.
GrowSurf program ID.
GrowSurf participant ID or URL-encoded participant email address.
Delayed referral trigger cancellation result returned.
Whether referral credit was awarded or scheduled.
Human-readable result message, present when credit was not awarded immediately or when a delayed trigger was scheduled.
Invalid request.
The API key is missing, invalid, revoked, outside its scope, or not allowed to perform this action.
Resource not found.
Request is not valid for the current program or participant state.
Too many requests.
DELETE /v2/campaign/{id}/participant/{participantIdOrEmail}/ref HTTP/1.1
Host: api.growsurf.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"success": true,
"message": "Successfully cancelled the delayed referral trigger."
}Creates or returns a participant using the same input behavior as Add Participant, then returns a participant-scoped token for GrowSurf mobile SDK participant endpoints. Use this endpoint from your backend after your mobile app authenticates a signed-in user. The program must have mobile SDK access enabled.
GrowSurf REST API key supplied as Authorization: Bearer <api_key>.
GrowSurf program ID.
Participant email address.
gavin@hooli.comReferrer participant ID or email address.
richard@piedpiper.comAffiliate programs only. Controls affiliate enrollment for a new participant. true enrolls the participant with affiliateStatus: APPROVED; false creates a non-affiliate without affiliateStatus. Existing participants are returned unchanged.
The referral credit status, only meaningful when referredBy resolves to a referrer. When omitted, it is derived from the program's referral trigger: CREDIT_AWARDED, CREDIT_PENDING (manual or custom trigger), or CREDIT_EXPIRED (past the credit window). Left unset when no referrer resolves.
CREDIT_AWARDEDPossible values: Participant first name.
GavinParticipant last name.
BelsonParticipant IP address, when available.
203.0.113.10Browser identifier, when available.
9d4c1f2ab8e35d7c6a1b0e9f8d7c6b5aOptional app-install scoped identifier supplied by a native app. Recommended for mobile participant creation and mobile participant token flows. The official mobile SDKs generate a lowercase UUID.
5f7d0f4c-3e7c-4aa9-8c41-d81d998f0bb1Participant and mobile participant token returned.
Participant-scoped bearer token for GrowSurf mobile SDK participant endpoints.
Token lifetime in seconds.
Whether this request created a new participant. Returns false when the participant already existed.
Invalid request.
The API key is missing, invalid, revoked, outside its scope, or not allowed to perform this action.
Resource not found.
Conflicting duplicate request.
Participant was blocked or the endpoint is not available for this program type.
Too many requests.
POST /v2/campaign/{id}/mobile-participant-token HTTP/1.1
Host: api.growsurf.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 258
{
"email": "gavin@hooli.com",
"firstName": "Gavin",
"lastName": "Belson",
"ipAddress": "203.0.113.10",
"mobileInstanceId": "5f7d0f4c-3e7c-4aa9-8c41-d81d998f0bb1",
"referredBy": "richard-h8kp6l",
"isAffiliate": true,
"metadata": {
"companyName": "Hooli",
"industry": "Software"
}
}{
"participantToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"expiresIn": 31536000,
"isNew": true,
"participant": {
"id": "gavin-f8g9nl",
"email": "gavin@hooli.com",
"firstName": "Gavin",
"lastName": "Belson",
"referralCount": 0,
"monthlyReferralCount": 0,
"rank": 12,
"monthlyRank": 4,
"shareUrl": "https://piedpiper.com?rfsn=gavin-f8g9nl",
"rewards": []
}
}Sends an email to a participant. Provide EITHER emailType to trigger one of the program's configured email templates, OR subject + body for a free-form email. Free-form emails are sent with the same compliance handling (company name, postal address, and an unsubscribe link are added automatically, and unsubscribed participants are suppressed). Sending requires the team to be verified by GrowSurf. Requires a verified custom email domain on the program (which can be completed in Campaign Editor > 3. Emails > Email Settings). Returns 400 until one is verified. The email is accepted for delivery. welcomeNonReferred can only be sent to advocates or approved, enrolled affiliates in a program that has not ended. Returns 400 for other recipients.
GrowSurf REST API key supplied as Authorization: Bearer <api_key>.
GrowSurf program ID.
GrowSurf participant ID or URL-encoded participant email address.
Provide EITHER emailType (template mode) OR subject + body (free-form mode), not both.
The program email template to trigger (template mode). Send the camelCase email-type key. The available types depend on the program type; the template's isEnabled setting controls automatic sends only. This endpoint can trigger any sendable template. System and transactional types (login link, payout destination confirmation, tax notifications) and the invite email cannot be sent. Referral programs: welcomeNonReferred, referralLinkViewedFirstTime, referralLinkUsed, referredSignup, welcomeReferred, goalAchieved, campaignEndedWinners, campaignEndedNonWinners, progressUpdateMonthly. Affiliate programs: welcomeNonReferred, referralLinkViewedFirstTime, referredSignup, commissionGenerated, commissionAdjusted, payoutPending, payoutSentSuccess, progressUpdateMonthly.
Subject line for a free-form email. Supports dynamic text ({{...}} tokens), the same as the body.
HTML body for a free-form email. When settings.design.layoutMode is INLINE, include {{emailFooter}} in the body; {{emailHeader}} is optional. You can personalize it with dynamic text, inserting {{...}} tokens like {{firstName}} or {{shareUrl}}. See Guide to using dynamic text in GrowSurf emails.
Optional preheader text for a free-form email.
Email accepted for delivery.
Whether the email request was accepted.
The email was accepted for delivery.
Invalid request.
The API key is missing, invalid, revoked, outside its scope, or not allowed to perform this action.
Resource not found.
Too many requests.
POST /v2/campaign/{id}/participant/{participantIdOrEmail}/email HTTP/1.1
Host: api.growsurf.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 28
{
"emailType": "goalAchieved"
}{
"success": true,
"status": "queued"
}Retrieves analytics for a single participant — all-time engagement counters, leaderboard ranks, and per-channel share counts (plus affiliate revenue, commission, and payout metrics for affiliate programs). Pass include=email for sent (accepted for delivery), delivered, opened, clicked, bounced, and spamComplaints metrics attributed to this participant, including invitations they sent. Use include=email,series to include the same counts in each UTC series bucket. Pass include=activation for covered participant enrollment, cohort anchor, and first milestones. Request both activation and series to add covered portalViews and shareActions to each series bucket. days, startDate, and endDate filter only the optional series and email data. They do not filter the top-level analytics, ranks, shareCount, or activation values.
GrowSurf REST API key supplied as Authorization: Bearer <api_key>.
GrowSurf program ID.
GrowSurf participant ID or URL-encoded participant email address.
Comma-separated optional data. series returns this participant's own activity per period; email returns sent, delivered, opened, clicked, bounced, spamComplaints, and per-email-type metrics attributed to the participant for the requested analytics window (including invitations they sent). Request both in either order to add email counts to every series item for emails sent during that period. activation returns covered enrollment, cohort-anchor, and first-milestone values. Request activation,series to add portalViews and shareActions; those values are null outside known coverage. Only documented tokens are accepted; an unknown token returns 400.
email,seriesLast number of days for optional series and email analytics. Defaults to 365. Maximum 1825. Does not filter the top-level all-time totals.
365Start of a custom series and email analytics window as a Unix timestamp in milliseconds. Set it together with endDate. Does not filter the top-level all-time totals.
End of a custom series and email analytics window as a Unix timestamp in milliseconds. Set it together with startDate. Does not filter the top-level all-time totals.
Bucket size for the series (only used when include contains series). Defaults to day.
dayPossible values: Participant analytics returned.
Present only when include contains series or email. Window start (Unix ms).
1704067200000Present only when include contains series or email. Window end (Unix ms).
1706745600000Invalid request.
The API key is missing, invalid, revoked, outside its scope, or not allowed to perform this action.
Resource not found.
Too many requests.
GET /v2/campaign/{id}/participant/{participantIdOrEmail}/analytics HTTP/1.1
Host: api.growsurf.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"analytics": {
"referrals": 12,
"monthlyReferrals": 3,
"leads": 2,
"expiredReferrals": 1,
"impressions": 340,
"uniqueImpressions": 210,
"invitesSent": 8,
"rewardStatus": {
"unapproved": 1,
"unfulfilled": 3,
"completed": 1
},
"currencyISO": "USD"
},
"ranks": {
"rank": 5,
"monthlyRank": 2,
"prevMonthlyRank": 4
},
"shareCount": {
"email": 3,
"facebook": 5,
"twitter": 2,
"copyRefLink": 7
}
}Returns a participant's activity logs, most recent first (offset/limit paginated).
GrowSurf REST API key supplied as Authorization: Bearer <api_key>.
GrowSurf program ID.
GrowSurf participant ID or URL-encoded participant email address.
Number of logs to return (1–100, default 20).
20Number of logs to skip.
0Activity logs returned.
The offset for the next page, or null when there are no more logs.
Number of activity logs returned per page.
The API key is missing, invalid, revoked, outside its scope, or not allowed to perform this action.
Resource not found.
Too many requests.
GET /v2/campaign/{id}/participant/{participantIdOrEmail}/activity-logs HTTP/1.1
Host: api.growsurf.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"activityLogs": [
{
"type": "REFERRAL",
"text": "Referral credit awarded",
"createdAt": 1719792000000
}
],
"offset": null,
"limit": 20
}Returns a participant's payout-destination status across every payout provider enabled for the program (PayPal and/or Wise). For each provider it reports the current status, the confirmed claim email, the legal recipient type, and — when a delivery bounced or a recipient was invalidated — the repair reason. activeProvider is the provider that currently gets paid, or null until the participant confirms one.
GrowSurf REST API key supplied as Authorization: Bearer <api_key>.
GrowSurf program ID.
GrowSurf participant ID or URL-encoded participant email address.
Payout destination status returned.
A participant's payout-destination status across every enabled payout provider.
The provider that currently gets paid, or null until the participant confirms one.
Invalid request.
The account's billing requirements for this action are not met.
The API key is missing, invalid, revoked, outside its scope, or not allowed to perform this action.
Resource not found.
Too many requests.
GET /v2/campaign/{id}/participant/{participantIdOrEmail}/payout-destination HTTP/1.1
Host: api.growsurf.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"activeProvider": "WISECOM",
"enabledProviders": [
"PAYPAL",
"WISECOM"
],
"destinations": [
{
"provider": "PAYPAL",
"providerDisplayName": "PayPal",
"status": "NONE",
"claimEmail": null,
"legalEntityType": null,
"confirmedAt": null,
"needsRepairReason": null
},
{
"provider": "WISECOM",
"providerDisplayName": "Wise",
"status": "ACTIVE",
"claimEmail": "richard@piedpiper.com",
"legalEntityType": "INDIVIDUAL",
"confirmedAt": 1752000000000,
"needsRepairReason": null
}
]
}Sends the participant a one-time link to confirm their payout destination for the chosen provider. Only the participant can open the link and confirm — this endpoint just triggers the message. The provider must be enabled for the program.
GrowSurf REST API key supplied as Authorization: Bearer <api_key>.
GrowSurf program ID.
GrowSurf participant ID or URL-encoded participant email address.
The payout provider the participant should confirm a destination for. VENMO uses a confirmed email and is available only when connected PayPal Payouts and payout-email confirmation are enabled in a USD program; Venmo recipients must be in the United States.
Confirmation message requested.
Confirms the message was requested.
The provider the participant was asked to confirm.
The customer-facing provider name (e.g. "PayPal", "Wise").
When the confirmation link expires, in epoch milliseconds.
Invalid request.
The account's billing requirements for this action are not met.
The API key is missing, invalid, revoked, outside its scope, or not allowed to perform this action.
Resource not found.
Too many requests.
POST /v2/campaign/{id}/participant/{participantIdOrEmail}/payout-destination/request-confirmation HTTP/1.1
Host: api.growsurf.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 21
{
"provider": "PAYPAL"
}{
"status": "CONFIRMATION_REQUESTED",
"provider": "WISECOM",
"providerDisplayName": "Wise",
"expiresAt": 1752604800000
}PARTICIPANT REWARDS ↓
Retrieves a paged list of rewards earned by a participant.
GrowSurf REST API key supplied as Authorization: Bearer <api_key>.
GrowSurf program ID.
GrowSurf participant ID or URL-encoded participant email address.
ID to start the next paged result set with.
Number of results to return. Maximum 100.
10Participant rewards returned.
Maximum number of rewards requested for this page.
Reward ID to pass as nextId for the next page, or null when there are no more results.
Invalid request.
The API key is missing, invalid, revoked, outside its scope, or not allowed to perform this action.
Resource not found.
Request is not valid for the current program or participant state.
Too many requests.
GET /v2/campaign/{id}/participant/{participantIdOrEmail}/rewards HTTP/1.1
Host: api.growsurf.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"limit": 2,
"nextId": "prew_v2qtfq",
"rewards": [
{
"id": "prew_rr35mg",
"rewardId": "crew_c6w1qo",
"status": "PENDING",
"unread": true,
"approved": false,
"approvedAt": null,
"fulfilledAt": null,
"isReferrer": true,
"isAvailable": false,
"isFulfilled": false,
"referredId": "xh345d",
"referrerId": "f8g9nl"
},
{
"id": "prew_oltj0s",
"rewardId": "crew_c6w1qo",
"status": "FULFILLED",
"unread": false,
"approved": true,
"approvedAt": 1659453091744,
"fulfilledAt": 1659453418901,
"isReferrer": false,
"isAvailable": true,
"isFulfilled": true,
"referredId": "zyx765",
"referrerId": "f8g9nl"
}
]
}Approves a manually approved reward earned by a participant. This requires reward:write. When the request also sets fulfill to true, it additionally requires reward:fulfill.
GrowSurf REST API key supplied as Authorization: Bearer <api_key>.
GrowSurf program ID.
Participant reward ID.
Set true to mark the reward as sent after approval.
falseSuccess response.
Whether the request succeeded.
Invalid request.
The API key is missing, invalid, revoked, outside its scope, or not allowed to perform this action.
Resource not found.
Resource is not in a state that permits this operation.
Request is not valid for the current program or participant state.
Too many requests.
POST /v2/campaign/{id}/reward/{rewardId}/approve HTTP/1.1
Host: api.growsurf.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 17
{
"fulfill": false
}{
"success": true
}Marks an approved participant reward as sent. This status does not confirm delivery.
GrowSurf REST API key supplied as Authorization: Bearer <api_key>.
GrowSurf program ID.
Participant reward ID.
Success response.
Whether the request succeeded.
Invalid request.
The API key is missing, invalid, revoked, outside its scope, or not allowed to perform this action.
Resource not found.
Resource is not in a state that permits this operation.
Request is not valid for the current program or participant state.
Too many requests.
POST /v2/campaign/{id}/reward/{rewardId}/fulfill HTTP/1.1
Host: api.growsurf.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"success": true
}Removes a manually approved participant reward that has not already been approved.
GrowSurf REST API key supplied as Authorization: Bearer <api_key>.
GrowSurf program ID.
Participant reward ID.
Success response.
Whether the request succeeded.
Invalid request.
The API key is missing, invalid, revoked, outside its scope, or not allowed to perform this action.
Resource not found.
Resource is not in a state that permits this operation.
Request is not valid for the current program or participant state.
Too many requests.
DELETE /v2/campaign/{id}/reward/{rewardId} HTTP/1.1
Host: api.growsurf.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"success": true
}REFERRALS AND INVITES ↓
Retrieves a list of all referrals and email invites made by participants in a program.
GrowSurf REST API key supplied as Authorization: Bearer <api_key>.
GrowSurf program ID.
Field used to sort referral results.
updatedAtPossible values: Return results in descending order when true.
trueNumber of results to return. Maximum 100.
10Offset number used to skip through a result set.
0URL-encoded email value to filter referral results.
First name value to filter results.
Last name value to filter results.
Referral status to filter results.
CREDIT_AWARDEDPossible values: ID to start the next paged result set with.
Referrals and invites returned.
Maximum number of referrals requested for this page.
Offset to pass as offset for the next page, or null when offset pagination is not used.
Referral ID to pass as nextId for the next page, or null when there are no more results.
Whether another page of referrals is available.
Invalid request.
The API key is missing, invalid, revoked, outside its scope, or not allowed to perform this action.
Resource not found.
Too many requests.
GET /v2/campaign/{id}/referrals HTTP/1.1
Host: api.growsurf.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"referrals": [
{
"id": "f2bukr",
"email": "gavin@hooli.com",
"firstName": "Gavin",
"lastName": "Belson",
"referralStatus": "CREDIT_AWARDED",
"referredBy": "2khaha",
"createdAt": 1591546112223,
"updatedAt": 1591546285013
},
{
"id": "ugqeq9",
"email": "***************",
"firstName": null,
"lastName": null,
"referralStatus": "INVITE_SENT",
"referredBy": "xde212",
"createdAt": 1591469527740,
"updatedAt": 1591469527740
}
],
"limit": 4,
"nextOffset": 4,
"nextId": "g19s1b",
"more": true
}Retrieves referrals and email invites made by a participant.
GrowSurf REST API key supplied as Authorization: Bearer <api_key>.
GrowSurf program ID.
GrowSurf participant ID or URL-encoded participant email address.
Field used to sort referral results.
updatedAtPossible values: Return results in descending order when true.
trueNumber of results to return. Maximum 100.
10Offset number used to skip through a result set.
0URL-encoded email value to filter referral results.
First name value to filter results.
Last name value to filter results.
Referral status to filter results.
CREDIT_AWARDEDPossible values: ID to start the next paged result set with.
Participant referrals and invites returned.
Maximum number of referrals requested for this page.
Offset to pass as offset for the next page, or null when offset pagination is not used.
Referral ID to pass as nextId for the next page, or null when there are no more results.
Whether another page of referrals is available.
Invalid request.
The API key is missing, invalid, revoked, outside its scope, or not allowed to perform this action.
Resource not found.
Too many requests.
GET /v2/campaign/{id}/participant/{participantIdOrEmail}/referrals HTTP/1.1
Host: api.growsurf.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"referrals": [
{
"id": "f2bukr",
"email": "gavin@hooli.com",
"firstName": "Gavin",
"lastName": "Belson",
"referralStatus": "CREDIT_AWARDED",
"referredBy": "2khaha",
"createdAt": 1591546112223,
"updatedAt": 1591546285013
},
{
"id": "ugqeq9",
"email": "***************",
"firstName": null,
"lastName": null,
"referralStatus": "INVITE_SENT",
"referredBy": "xde212",
"createdAt": 1591469527740,
"updatedAt": 1591469527740
}
],
"limit": 4,
"nextOffset": 4,
"nextId": "g19s1b",
"more": true
}Sends email invites on behalf of a participant to a list of email addresses. Sending invites via the API requires a verified custom email domain on the program; the request fails until one is verified.
GrowSurf REST API key supplied as Authorization: Bearer <api_key>.
GrowSurf program ID.
GrowSurf participant ID or URL-encoded participant email address.
Email addresses to invite.
["erlich@aviato.com"]Message body for the invite email.
Try Pied Piper. I think you'll like the new compression workflow.Subject line for the invite email.
Richard invited you to Pied PiperInvite send result returned.
Whether the invites request succeeded.
Result category for the invites request.
sentNumber of invite emails sent.
1Invalid request.
The API key is missing, invalid, revoked, outside its scope, or not allowed to perform this action.
Resource not found.
Too many requests.
POST /v2/campaign/{id}/participant/{participantIdOrEmail}/invites HTTP/1.1
Host: api.growsurf.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 155
{
"emailAddresses": [
"erlich@aviato.com"
],
"subjectText": "Join me on Pied Piper",
"messageText": "{{referrerFirstName}} invited you with {{referrerShareUrl}}."
}{
"success": true,
"messageType": "sent",
"invitesSent": 1
}ANALYTICS ↓
Retrieves analytics for a program. Pass interval to also get a time-series (series) alongside the totals, and include to add previous-period totals, status breakdowns, derived rates, email performance, or participant engagement. Add email to include for sent (accepted for delivery), delivered, opened, clicked, bounced, and spamComplaints metrics plus per-email-type breakdowns. Add engagement for unique active, sharing, repeat, and retained participants plus portal-view and share-action totals. Email rates and engagement comparisons are ratios from 0 to 1. Email isPartial and engagement coverage states distinguish unavailable or partial data from measured zeroes.
GrowSurf REST API key supplied as Authorization: Bearer <api_key>.
GrowSurf program ID.
Last number of days to retrieve analytics for. Defaults to 365. Maximum 1825.
365Start date of the analytics timeframe as a Unix timestamp in milliseconds. Required if days is not set.
End date of the analytics timeframe as a Unix timestamp in milliseconds. Required if days is not set.
When set to day, week, or month, the response also includes a series array with per-period totals and uses the same bucket size for engagement.series. Defaults to total (no legacy series); engagement.series uses daily buckets when interval is total or omitted.
totalPossible values: Comma-separated list of optional data to include: previousPeriod adds totals for the equal-length window immediately before the requested one; statusCounts adds reward (and, for affiliate programs, affiliate/commission/payout) status breakdowns; rates adds derived referral rates; email adds sent, delivered, opened, clicked, bounced, spamComplaints, and per-email-type metrics; engagement adds unique participant engagement, action totals, comparisons, and platform/source/channel breakdowns. When email and an interval are both requested, each series item also contains counts for emails sent during that period. Combine email with previousPeriod to include the same email metrics in both windows.
previousPeriod,statusCounts,rates,email,engagementIANA timezone used for engagement interval boundaries and distinct-day calculations. Used only when include contains engagement.
UTCExample: America/Los_AngelesLimits engagement events to one client platform. Used only when include contains engagement.
ALLPossible values: Campaign analytics returned.
Start of the analytics timeframe, as a Unix timestamp in milliseconds.
1704067200000End of the analytics timeframe, as a Unix timestamp in milliseconds.
1706745600000Invalid request.
The account's billing requirements for this action are not met.
The API key is missing, invalid, revoked, outside its scope, or not allowed to perform this action.
Resource not found.
Too many requests.
GET /v2/campaign/{id}/analytics HTTP/1.1
Host: api.growsurf.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"analytics": {
"invites": 13,
"impressions": 213,
"uniqueImpressions": 34,
"participants": 400,
"referrals": 113,
"referralCreditPendings": 298,
"referralCreditExpireds": 15,
"emailShares": 1,
"facebookShares": 8,
"twitterShares": 53,
"threadsShares": 7,
"blueskyShares": 10,
"pinterestShares": 9,
"linkedInShares": 0,
"smsShares": 4,
"messengerShares": 5,
"whatsAppShares": 1,
"wechatShares": 4,
"telegramShares": 5,
"qrcodeShares": 49,
"redditShares": 4,
"tumblrShares": 0,
"copyRefLinkShares": 12,
"iosNativeShares": 3,
"androidNativeShares": 2,
"totalRevenue": 982151,
"totalCommissions": 314231,
"totalCommissionCount": 49,
"uniqueCommissionReferrals": 31
},
"startDate": 1592359793538,
"endDate": 1747879793538
}Retrieves activation for eligible participants in one exact half-open enrollment cohort. aggregate covers the complete selected cohort, while cohorts splits that same range by cohortInterval. Each participant has the selected observationWindowDays after their eligibility date to reach each ordered stage. If cohortFrom and cohortTo are omitted, GrowSurf selects the latest fully matured rolling cohort. Unavailable and partial states preserve unknown pre-coverage data instead of reporting false zeroes. One request can return at most 100 cohort buckets.
GrowSurf REST API key supplied as Authorization: Bearer <api_key>.
GrowSurf program ID.
Inclusive cohort start as a Unix timestamp in milliseconds. Provide it together with cohortTo, or omit both for the latest fully matured cohort.
1767225600000Exclusive cohort end as a Unix timestamp in milliseconds. Provide it together with cohortFrom, or omit both for the latest fully matured cohort.
1767830400000Bucket size for the cohorts array.
dayPossible values: Days after each participant's eligibility date in which stages can count.
30Possible values: IANA timezone used to advance cohort bucket boundaries.
UTCExample: America/Los_AngelesCampaign activation analytics returned.
One selected activation aggregate and its exact cohort-interval buckets.
Earliest date from which activation capture is expected to be complete, or null until coverage begins.
Version of the shared activation and engagement metric definitions.
1Program type that determines eligibility and display labels.
REFERRALPossible values: IANA timezone used to advance cohort bucket boundaries.
America/Los_AngelesBucket size used for cohorts.
Days after each participant's eligibility date in which stages can count.
Program-specific display label for the stable PORTAL_VIEWED stage.
Referral portal viewedPossible values: Display helper that defines a qualifying portal view.
Signed-in participant view.Invalid request.
The account's billing requirements for this action are not met.
The API key is missing, invalid, revoked, outside its scope, or not allowed to perform this action.
Resource not found.
Too many requests.
GET /v2/campaign/{id}/analytics/activation HTTP/1.1
Host: api.growsurf.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"coverageStartAt": null,
"metricContractVersion": 1,
"programType": "REFERRAL",
"timezone": "UTC",
"cohortInterval": "week",
"observationWindowDays": 7,
"portalViewedLabel": "Referral portal viewed",
"portalViewedHelperText": "Signed-in participant view.",
"aggregate": {
"state": "UNAVAILABLE",
"reason": "COVERAGE_UNAVAILABLE",
"cohort": {
"from": 1767225600000,
"to": 1767830400000,
"effectiveFrom": null,
"maturedAt": 1768435200000,
"asOf": 1768521600000,
"anchorField": "enrolledAsAdvocateAt"
},
"strictStages": null,
"rawStageCounts": null,
"stalledSegments": null,
"outcomes": null,
"largestDrop": null
},
"cohorts": [
{
"state": "UNAVAILABLE",
"reason": "COVERAGE_UNAVAILABLE",
"cohort": {
"from": 1767225600000,
"to": 1767830400000,
"effectiveFrom": null,
"maturedAt": 1768435200000,
"asOf": 1768521600000,
"anchorField": "enrolledAsAdvocateAt"
},
"strictStages": null,
"rawStageCounts": null,
"stalledSegments": null,
"outcomes": null,
"largestDrop": null
}
]
}AFFILIATE PROGRAMS ↓
Lists an affiliate program's applications, newest first. Applications exist on programs that review public signups (an affiliateApplicationMode of MANUAL_REVIEW or AUTO_APPROVE). A pending applicant is not a participant until their application is approved.
GrowSurf REST API key supplied as Authorization: Bearer <api_key>.
GrowSurf program ID.
Only return applications with this status.
How many applications to return per page (1-100).
10Offset number used to skip through a result set.
0Applications returned.
Total number of applications matching the filter.
1The offset this page started at.
0The page size used.
10Invalid request.
The account's billing requirements for this action are not met.
The API key is missing, invalid, revoked, outside its scope, or not allowed to perform this action.
Resource not found.
Too many requests.
GET /v2/campaign/{id}/affiliate-applications HTTP/1.1
Host: api.growsurf.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"applications": [
{
"id": "k1v2x3",
"status": "PENDING",
"email": "erlich@aviato.com",
"firstName": "Erlich",
"lastName": "Bachman",
"answers": [
{
"fieldId": "primaryChannelUrl",
"label": "Website or social media channel",
"type": "url",
"value": "https://aviato.com"
},
{
"fieldId": "countryCode",
"label": "Country",
"type": "country",
"value": "US"
},
{
"fieldId": "audience",
"label": "Tell us about your target audience",
"type": "textarea",
"value": "Startup founders and engineering teams"
},
{
"fieldId": "promotionPlan",
"label": "How do you plan to promote us?",
"type": "textarea",
"value": "Tutorials and product comparisons"
},
{
"fieldId": "additionalInformation",
"label": "Anything else you’d like us to know?",
"type": "textarea",
"value": "I have used Pied Piper since the beta."
}
],
"termsAcceptedAt": 1752710400000,
"riskLevel": "LOW",
"rejectionReason": null,
"reviewedAt": null,
"decidedAt": null,
"reapplyAllowedAt": null,
"participantId": null,
"createdAt": 1752710400000
}
],
"total": 1,
"offset": 0,
"limit": 10
}Returns one affiliate application, including its submitted form answers.
GrowSurf REST API key supplied as Authorization: Bearer <api_key>.
GrowSurf program ID.
Affiliate application ID.
k1v2x3Application returned.
Public application ID.
k1v2x3Where the application is in review. Only PENDING applications can be decided.
PENDINGPossible values: Required applicant email address, or null after applicant data is removed under the Program's retention policy.
erlich@aviato.comRequired applicant first name, or null after applicant data is removed under the Program's retention policy.
ErlichRequired applicant last name, or null after applicant data is removed under the Program's retention policy.
BachmanWhen the applicant accepted the Program Terms, in Unix milliseconds, or null when acceptance was not required.
1752710400000GrowSurf risk assessment. Applications that are not LOW risk are held for manual review; null means no assessment was recorded.
LOWPossible values: Reason recorded when the application was denied, or null before denial.
When the application was reviewed, in Unix milliseconds, or null while pending.
When the decision was made, in Unix milliseconds, or null while pending.
When a denied applicant may apply again, in Unix milliseconds, or null when not applicable.
Public participant ID created or upgraded by approval, or null before approval.
tnn0ssWhen the application was submitted, as a Unix timestamp in milliseconds.
1752710400000Invalid request.
The account's billing requirements for this action are not met.
The API key is missing, invalid, revoked, outside its scope, or not allowed to perform this action.
Resource not found.
Too many requests.
GET /v2/campaign/{id}/affiliate-applications/{applicationId} HTTP/1.1
Host: api.growsurf.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"id": "k1v2x3",
"status": "PENDING",
"email": "erlich@aviato.com",
"firstName": "Erlich",
"lastName": "Bachman",
"answers": [
{
"fieldId": "primaryChannelUrl",
"label": "Website or social media channel",
"type": "url",
"value": "https://aviato.com"
},
{
"fieldId": "countryCode",
"label": "Country",
"type": "country",
"value": "US"
},
{
"fieldId": "audience",
"label": "Tell us about your target audience",
"type": "textarea",
"value": "Startup founders and engineering teams"
},
{
"fieldId": "promotionPlan",
"label": "How do you plan to promote us?",
"type": "textarea",
"value": "Tutorials and product comparisons"
},
{
"fieldId": "additionalInformation",
"label": "Anything else you’d like us to know?",
"type": "textarea",
"value": "I have used Pied Piper since the beta."
}
],
"termsAcceptedAt": 1752710400000,
"riskLevel": "LOW",
"rejectionReason": null,
"reviewedAt": null,
"decidedAt": null,
"reapplyAllowedAt": null,
"participantId": null,
"createdAt": 1752710400000
}Decides a pending application. Set status to APPROVED to enroll the applicant (this creates the participant, or upgrades an existing participant with the same email), or to DENIED with an optional rejectionReason. A denied applicant may reapply after the program's reapplication cooldown; send an earlier reapplyAllowedAt (without status) to shorten that wait for one applicant. Approval is idempotent: repeating it returns the same participant.
GrowSurf REST API key supplied as Authorization: Bearer <api_key>.
GrowSurf program ID.
Affiliate application ID.
k1v2x3Either decide a pending application with status, or move a denied application's reapplication window with reapplyAllowedAt. These actions cannot be combined.
Updated application returned.
Public application ID.
k1v2x3Where the application is in review. Only PENDING applications can be decided.
PENDINGPossible values: Required applicant email address, or null after applicant data is removed under the Program's retention policy.
erlich@aviato.comRequired applicant first name, or null after applicant data is removed under the Program's retention policy.
ErlichRequired applicant last name, or null after applicant data is removed under the Program's retention policy.
BachmanWhen the applicant accepted the Program Terms, in Unix milliseconds, or null when acceptance was not required.
1752710400000GrowSurf risk assessment. Applications that are not LOW risk are held for manual review; null means no assessment was recorded.
LOWPossible values: Reason recorded when the application was denied, or null before denial.
When the application was reviewed, in Unix milliseconds, or null while pending.
When the decision was made, in Unix milliseconds, or null while pending.
When a denied applicant may apply again, in Unix milliseconds, or null when not applicable.
Public participant ID created or upgraded by approval, or null before approval.
tnn0ssWhen the application was submitted, as a Unix timestamp in milliseconds.
1752710400000Invalid request.
The account's billing requirements for this action are not met.
The API key is missing, invalid, revoked, outside its scope, or not allowed to perform this action.
Resource not found.
The application was already decided (approve/deny can only run once), or reapplyAllowedAt was sent for an application that is not denied.
Too many requests.
PATCH /v2/campaign/{id}/affiliate-applications/{applicationId} HTTP/1.1
Host: api.growsurf.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 21
{
"status": "APPROVED"
}{
"id": "k1v2x3",
"status": "PENDING",
"email": "erlich@aviato.com",
"firstName": "Erlich",
"lastName": "Bachman",
"answers": [
{
"fieldId": "primaryChannelUrl",
"label": "Website or social media channel",
"type": "url",
"value": "https://aviato.com"
}
],
"termsAcceptedAt": 1752710400000,
"riskLevel": "LOW",
"rejectionReason": null,
"reviewedAt": null,
"decidedAt": null,
"reapplyAllowedAt": null,
"participantId": "tnn0ss",
"createdAt": 1752710400000
}Lists an affiliate program's enrollment invites, newest first.
GrowSurf REST API key supplied as Authorization: Bearer <api_key>.
GrowSurf program ID.
Only return invites with this status.
How many invites to return per page (1-100).
10Offset number used to skip through a result set.
0Invites returned.
Total number of invites matching the filter.
1The offset this page started at.
0The page size used.
10Invalid request.
The account's billing requirements for this action are not met.
The API key is missing, invalid, revoked, outside its scope, or not allowed to perform this action.
Resource not found.
Too many requests.
GET /v2/campaign/{id}/affiliate-invites HTTP/1.1
Host: api.growsurf.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"invites": [
{
"id": "m4n5p6",
"status": "PENDING",
"email": "erlich@aviato.com",
"firstName": "Erlich",
"lastName": "Bachman",
"expiresAt": 1,
"lastSentAt": 1,
"acceptedAt": null,
"revokedAt": null,
"createdAt": 1752710400000
}
],
"total": 1,
"offset": 0,
"limit": 10
}Invites someone to join the affiliate program. GrowSurf emails them a single-use accept link; accepting it enrolls them as an approved affiliate without going through the public application. One active invite can exist per email address.
GrowSurf REST API key supplied as Authorization: Bearer <api_key>.
GrowSurf program ID.
Email address to invite.
erlich@aviato.comInvitee first name, used in the invite email.
ErlichInvitee last name.
BachmanInvite created and emailed.
Invite ID.
m4n5p6The invite's lifecycle state. Accepting a pending invite enrolls the invitee as an approved affiliate.
Invitee email address.
erlich@aviato.comInvitee first name, when provided.
ErlichInvitee last name, when provided.
BachmanWhen the emailed accept link stops working, in Unix milliseconds.
When the invite email was last sent, in Unix milliseconds.
When the invite was accepted, in Unix milliseconds. null until accepted.
When the invite was revoked, in Unix milliseconds. null unless revoked.
When the invite was created, in Unix milliseconds.
1752710400000Invalid request.
The account's billing requirements for this action are not met.
The API key is missing, invalid, revoked, outside its scope, or not allowed to perform this action.
Resource not found.
An active invite already exists for this email, or the email already belongs to an affiliate.
Too many requests.
POST /v2/campaign/{id}/affiliate-invites HTTP/1.1
Host: api.growsurf.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 50
{
"email": "erlich@aviato.com",
"firstName": "Erlich"
}{
"id": "m4n5p6",
"status": "PENDING",
"email": "erlich@aviato.com",
"firstName": "Erlich",
"lastName": null,
"expiresAt": 1753920000000,
"lastSentAt": 1752710400000,
"acceptedAt": null,
"revokedAt": null,
"createdAt": 1752710400000
}Revokes a pending invite. Its emailed accept link stops working immediately.
GrowSurf REST API key supplied as Authorization: Bearer <api_key>.
GrowSurf program ID.
Affiliate invite ID.
m4n5p6Revoked invite returned.
Invite ID.
m4n5p6The invite's lifecycle state. Accepting a pending invite enrolls the invitee as an approved affiliate.
Invitee email address.
erlich@aviato.comInvitee first name, when provided.
ErlichInvitee last name, when provided.
BachmanWhen the emailed accept link stops working, in Unix milliseconds.
When the invite email was last sent, in Unix milliseconds.
When the invite was accepted, in Unix milliseconds. null until accepted.
When the invite was revoked, in Unix milliseconds. null unless revoked.
When the invite was created, in Unix milliseconds.
1752710400000Invalid request.
The account's billing requirements for this action are not met.
The API key is missing, invalid, revoked, outside its scope, or not allowed to perform this action.
Resource not found.
Only a pending invite can be revoked.
Too many requests.
DELETE /v2/campaign/{id}/affiliate-invites/{inviteId} HTTP/1.1
Host: api.growsurf.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"id": "m4n5p6",
"status": "PENDING",
"email": "erlich@aviato.com",
"firstName": "Erlich",
"lastName": "Bachman",
"expiresAt": 1,
"lastSentAt": 1,
"acceptedAt": null,
"revokedAt": null,
"createdAt": 1752710400000
}Re-sends a pending invite with a fresh accept link (the previous link stops working). Resends are rate limited per invite; retry after a few minutes if a resend was just sent.
GrowSurf REST API key supplied as Authorization: Bearer <api_key>.
GrowSurf program ID.
Affiliate invite ID.
m4n5p6Updated invite returned.
Invite ID.
m4n5p6The invite's lifecycle state. Accepting a pending invite enrolls the invitee as an approved affiliate.
Invitee email address.
erlich@aviato.comInvitee first name, when provided.
ErlichInvitee last name, when provided.
BachmanWhen the emailed accept link stops working, in Unix milliseconds.
When the invite email was last sent, in Unix milliseconds.
When the invite was accepted, in Unix milliseconds. null until accepted.
When the invite was revoked, in Unix milliseconds. null unless revoked.
When the invite was created, in Unix milliseconds.
1752710400000Invalid request.
The account's billing requirements for this action are not met.
The API key is missing, invalid, revoked, outside its scope, or not allowed to perform this action.
Resource not found.
The invite is not pending, or its resend cooldown has not elapsed yet.
Too many requests.
POST /v2/campaign/{id}/affiliate-invites/{inviteId}/resend HTTP/1.1
Host: api.growsurf.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"id": "m4n5p6",
"status": "PENDING",
"email": "erlich@aviato.com",
"firstName": "Erlich",
"lastName": "Bachman",
"expiresAt": 1,
"lastSentAt": 1,
"acceptedAt": null,
"revokedAt": null,
"createdAt": 1752710400000
}Affiliate programs only. Records a sale made by a referred customer and generates affiliate commissions for their referrer when applicable. Requires at least one transaction identifier (externalId, transactionId, orderId, paymentId, invoiceId, paymentIntentId, or chargeId) so repeated requests can be de-duplicated — without one, a resent sale would create a second commission. Reuse the same identifier(s) when refunding.
GrowSurf REST API key supplied as Authorization: Bearer <api_key>.
GrowSurf program ID.
GrowSurf participant ID or URL-encoded participant email address.
To record a Stripe, Chargebee or Recurly payment, supply paymentProvider, testMode, and the provider's payment transactionId. For Stripe, use a Charge ID (ch_...) or PaymentIntent ID (pi_...); both identify the same captured payment. The integration must be enabled in that mode. grossAmount, currency, and any supplied paidAt must match the provider payment. Other payment identifiers and tax or net-amount overrides are not accepted for provider payments. GrowSurf reads those payment details from the connected account. The provider customer must match the participant's email or stored provider identity. Webhook, API, and manual submissions for the same provider payment are treated as duplicates. Omit paymentProvider and testMode to record a sale using your own transaction details.
Connected payment provider. Requires transactionId and an explicit testMode.
true for the provider's test account or false for its live account. Required when paymentProvider is supplied; otherwise omit this field.
3-letter ISO 4217 currency code for the sale. Must match the program currency.
USDPattern: ^[A-Za-z]{3}$Total sale amount in the currency's minor unit. Must be a positive integer.
10000Net-of-tax sale amount in the currency's minor unit. Used as the commissionable base when supplied.
9000Tax collected in the currency's minor unit. Used to derive the commissionable base when netAmount is absent.
1000Explicit post-tax cash amount in the currency's minor unit. Overrides derived net amounts.
9000Amount actually paid in the currency's minor unit, when reported by your payment processor.
10000When the payment was captured or settled, as a Unix timestamp in milliseconds.
1719792000000Primary transaction identifier from your billing system. Used to detect duplicate submissions.
txn_piedpiper_1001Transaction identifier to store for this sale. Used to detect duplicate submissions.
txn_piedpiper_1001Customer record identifier, such as a payment-provider customer ID.
cust_gavin_belsonOrder identifier. Used to detect duplicate submissions when supplied.
order_piedpiper_1001Payment identifier. Used to detect duplicate submissions when supplied.
pay_piedpiper_1001Invoice identifier. Used to detect duplicate submissions when supplied.
inv_piedpiper_1001Subscription identifier for recurring payments.
sub_piedpiper_001Payment intent identifier. Used to detect duplicate submissions when supplied.
pi_piedpiper_1001Charge identifier. Used to detect duplicate submissions when supplied.
ch_piedpiper_1001Freeform sale description shown in dashboard context and reports.
Gavin Belson first month subscriptionInvoice total including tax, in the currency's minor unit.
10000Invoice total excluding tax, in the currency's minor unit.
9000Invoice subtotal excluding tax, in the currency's minor unit.
9000Aggregate tax amount in the currency's minor unit.
1000Transaction result returned.
Invalid request.
The API key is missing, invalid, revoked, outside its scope, or not allowed to perform this action.
Resource not found.
Request is not valid for the current program or participant state.
Too many requests.
POST /v2/campaign/{id}/participant/{participantIdOrEmail}/transaction HTTP/1.1
Host: api.growsurf.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 151
{
"currency": "USD",
"grossAmount": 9900,
"amountCashNet": 7900,
"invoiceId": "invoice_54",
"paidAt": 1733702400000,
"description": "Renewal for Pro subscription"
}{
"success": true,
"firstSale": false,
"duplicate": false,
"message": "Sale was successfully recorded. Commission(s) for the referrer will be generated, if applicable."
}Affiliate programs only. Records an amendment (refund, partial refund, refund cancellation, or chargeback) against a previously recorded transaction and reverses or adjusts the referrer's commission. The inverse of Record Affiliate Transaction. Identify the original transaction with the same identifier(s) you sent when recording it. Commissions already paid out to the affiliate are not clawed back. The amendment still updates the sale revenue used in program reporting; full refunds and chargebacks also update tax reporting.
GrowSurf REST API key supplied as Authorization: Bearer <api_key>.
GrowSurf program ID.
GrowSurf participant ID or URL-encoded participant email address.
To amend a Stripe, Chargebee or Recurly payment, supply paymentProvider, testMode, and the original provider payment's transactionId (a Charge or PaymentIntent ID for Stripe). These values must identify the same connected account and mode used for the sale. This records an amendment in GrowSurf; it does not send a refund through the payment provider. Omit paymentProvider and testMode for other transactions recorded through the API or dashboard. At least one transaction identifier is required. Use the same identifier you supplied when recording the sale.
Connected payment provider for the original sale. Requires transactionId and testMode.
true for the original payment's test account or false for its live account. Required when paymentProvider is supplied; otherwise omit this field.
REFUND covers full refunds, partial refunds, and refund cancellations; CHARGEBACK is always a full reversal.
REFUNDExample: REFUNDPossible values: Cumulative amount refunded so far, in the currency's minor unit. Omit for a full refund. For a partial refund send the running total, not the per-refund delta.
2500Original sale gross (minor units). Optional — the value stored when the transaction was recorded is used when available; only needed for partial refunds of older records.
10000Stable per-refund identifier. Required when canceling a refund or changing the refunded total after a cancellation. Reuse the original refund's identifier for its cancellation. An amendment without enough refund identity returns 409 without applying the cancellation. Newly observed higher cumulative refunds and incomplete coverage are retained for reconciliation.
re_piedpiper_1001Refund status. Send canceled with the original refundId to cancel that refund. Record each original refund with refundId and refundAmount first. Missing or conflicting refund history returns 409 without applying the cancellation. Newly observed higher cumulative refunds and incomplete coverage are retained for reconciliation.
succeededPositive amount for this individual refund, no greater than the sale amount, in the sale currency's minor unit. Send it with refundId on each original refund to support cancellations and out-of-order amendments. The amount for a given refundId cannot change. A cancellation can omit it when the original amount is already recorded. Incomplete refund history returns 409 without applying the cancellation. Newly observed higher cumulative refunds and incomplete coverage are retained for reconciliation.
2500Set true only after reconciling and recording every original refund's refundId and refundAmount, including refunds later canceled. This confirmation resolves previously incomplete refund history. Omit it during ordinary delivery. Cancellations remain 409 while history is incomplete. Replaying an old confirmation cannot reconcile a later gap; confirm a newly reconciled refund or complete provider list.
true3-letter ISO currency. Optional — resolved from the original commission when available.
USDPattern: ^[A-Za-z]{3}$Original transaction identifier from your billing system.
txn_piedpiper_1001Original transaction identifier to match against.
txn_piedpiper_1001Original order identifier to match against.
order_piedpiper_1001Original payment identifier to match against.
pay_piedpiper_1001Original invoice identifier to match against.
inv_piedpiper_1001Original payment intent identifier to match against.
pi_piedpiper_1001Original charge identifier to match against.
ch_piedpiper_1001Freeform amendment description shown in dashboard context and reports.
Partial refund for Gavin BelsonAmendment result returned.
true when the amendment was processed (including the tax-only case for already-paid commissions); false when no matching transaction was found.
Present and true when no commission matched the provided identifiers.
Amendment type that was processed.
REFUNDPossible values: Number of commissions found for the provided identifiers.
1Number of commissions reversed (set to zero amount).
0Number of commissions partially adjusted.
1Number of pending commissions deleted by the amendment.
0Commission IDs that matched the submitted identifiers.
["comm_abc123"]Human-readable result message for the amendment.
Refund processed.Invalid request.
The API key is missing, invalid, revoked, outside its scope, or not allowed to perform this action.
Resource not found.
The refund amendment has missing or conflicting per-refund history. Record each original refund with its stable refundId and positive refundAmount. After reconciling all original refunds, set refundHistoryComplete to true to resolve incomplete history. The cancellation is not applied on conflict. Newly observed higher cumulative refunds and incomplete coverage are retained for reconciliation.
Request is not valid for the current program or participant state.
Too many requests.
POST /v2/campaign/{id}/participant/{participantIdOrEmail}/transaction/refund HTTP/1.1
Host: api.growsurf.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 128
{
"amendmentType": "REFUND",
"invoiceId": "invoice_54",
"amountRefunded": 9900,
"description": "Customer refunded the Pro subscription"
}{
"success": true,
"amendmentType": "REFUND",
"matched": 1,
"reversed": 1,
"adjusted": 0,
"deleted": 0,
"matchingCommissionIds": [
"comm_jy6kl1"
],
"message": "Amendment recorded: 1 commission(s) reversed."
}Affiliate programs only. Retrieves a paged list of all participant commissions in an affiliate program.
GrowSurf REST API key supplied as Authorization: Bearer <api_key>.
GrowSurf program ID.
ID to start the next paged result set with.
Number of results to return. Maximum 100.
10Participant commission status.
PENDINGPossible values: Participant commissions returned.
Maximum number of commissions requested for this page.
Commission ID to pass as nextId for the next page, or null when there are no more results.
Invalid request.
The API key is missing, invalid, revoked, outside its scope, or not allowed to perform this action.
Resource not found.
Request is not valid for the current program or participant state.
Too many requests.
GET /v2/campaign/{id}/commissions HTTP/1.1
Host: api.growsurf.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"commissions": [
{
"id": "comm_abc123",
"referrerId": "f8g9nl",
"referredId": "h8kp6l",
"event": "SALE",
"amount": 1000,
"saleAmount": 10000,
"currencyISO": "USD",
"status": "PENDING",
"approvedAt": null,
"paidAt": null,
"reversedAt": null,
"holdDuration": 30,
"payoutQueuedAt": null,
"provider": "stripe",
"createdAt": 1591546112223,
"amountInCampaignCurrency": 1000,
"saleAmountInCampaignCurrency": 10000,
"exchangeRate": null,
"campaignCurrencyISO": "USD",
"exchangeRateAt": null,
"fxError": null
}
],
"limit": 10,
"nextId": null
}Affiliate programs only. Retrieves a paged list of commissions earned by a participant.
GrowSurf REST API key supplied as Authorization: Bearer <api_key>.
GrowSurf program ID.
GrowSurf participant ID or URL-encoded participant email address.
ID to start the next paged result set with.
Number of results to return. Maximum 100.
10Participant commission status.
PENDINGPossible values: Participant commissions returned.
Maximum number of commissions requested for this page.
Commission ID to pass as nextId for the next page, or null when there are no more results.
Invalid request.
The API key is missing, invalid, revoked, outside its scope, or not allowed to perform this action.
Resource not found.
Request is not valid for the current program or participant state.
Too many requests.
GET /v2/campaign/{id}/participant/{participantIdOrEmail}/commissions HTTP/1.1
Host: api.growsurf.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"commissions": [
{
"id": "comm_abc123",
"referrerId": "f8g9nl",
"referredId": "h8kp6l",
"event": "SALE",
"amount": 1000,
"saleAmount": 10000,
"currencyISO": "USD",
"status": "PENDING",
"approvedAt": null,
"paidAt": null,
"reversedAt": null,
"holdDuration": 30,
"payoutQueuedAt": null,
"provider": "stripe",
"createdAt": 1591546112223,
"amountInCampaignCurrency": 1000,
"saleAmountInCampaignCurrency": 10000,
"exchangeRate": null,
"campaignCurrencyISO": "USD",
"exchangeRateAt": null,
"fxError": null
}
],
"limit": 10,
"nextId": null
}Affiliate programs only. Approves a pending participant commission so it can become eligible for payout.
GrowSurf REST API key supplied as Authorization: Bearer <api_key>.
GrowSurf program ID.
Participant commission ID.
Success response.
Whether the request succeeded.
Invalid request.
The API key is missing, invalid, revoked, outside its scope, or not allowed to perform this action.
Resource not found.
Resource is not in a state that permits this operation.
Request is not valid for the current program or participant state.
Too many requests.
POST /v2/campaign/{id}/commission/{commissionId}/approve HTTP/1.1
Host: api.growsurf.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"success": true
}Affiliate programs only. Removes a pending participant commission.
GrowSurf REST API key supplied as Authorization: Bearer <api_key>.
GrowSurf program ID.
Participant commission ID.
Success response.
Whether the request succeeded.
Invalid request.
The API key is missing, invalid, revoked, outside its scope, or not allowed to perform this action.
Resource not found.
Resource is not in a state that permits this operation.
Request is not valid for the current program or participant state.
Too many requests.
DELETE /v2/campaign/{id}/commission/{commissionId} HTTP/1.1
Host: api.growsurf.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"success": true
}Affiliate programs only. Retrieves a paged list of all participant payouts in an affiliate program.
GrowSurf REST API key supplied as Authorization: Bearer <api_key>.
GrowSurf program ID.
ID to start the next paged result set with.
Number of results to return. Maximum 100.
10Participant payout status.
ISSUEDPossible values: Participant payouts returned.
Maximum number of payouts requested for this page.
Payout ID to pass as nextId for the next page, or null when there are no more results.
Invalid request.
The API key is missing, invalid, revoked, outside its scope, or not allowed to perform this action.
Resource not found.
Request is not valid for the current program or participant state.
Too many requests.
GET /v2/campaign/{id}/payouts HTTP/1.1
Host: api.growsurf.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"payouts": [
{
"id": "po_k11ps9",
"participantId": "f8g9nl",
"commissionIds": [
"comm_jp1ku7",
"comm_a98s7z"
],
"amount": 3600,
"currencyISO": "USD",
"status": "ISSUED",
"createdAt": 1635638400000,
"issuedAt": 1635724800000,
"failedAt": null,
"reversedAt": null,
"provider": "paypal",
"amountInCampaignCurrency": 3600,
"campaignCurrencyISO": "USD",
"exchangeRateAt": 1635638400000,
"exchangeRate": 1,
"fxError": null
}
],
"limit": 10,
"nextId": null
}Affiliate programs only. Retrieves a paged list of payouts that belong to a participant.
GrowSurf REST API key supplied as Authorization: Bearer <api_key>.
GrowSurf program ID.
GrowSurf participant ID or URL-encoded participant email address.
ID to start the next paged result set with.
Number of results to return. Maximum 100.
10Participant payout status.
ISSUEDPossible values: Participant payouts returned.
Maximum number of payouts requested for this page.
Payout ID to pass as nextId for the next page, or null when there are no more results.
Invalid request.
The API key is missing, invalid, revoked, outside its scope, or not allowed to perform this action.
Resource not found.
Request is not valid for the current program or participant state.
Too many requests.
GET /v2/campaign/{id}/participant/{participantIdOrEmail}/payouts HTTP/1.1
Host: api.growsurf.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"payouts": [
{
"id": "po_k11ps9",
"participantId": "f8g9nl",
"commissionIds": [
"comm_jp1ku7",
"comm_a98s7z"
],
"amount": 3600,
"currencyISO": "USD",
"status": "ISSUED",
"createdAt": 1635638400000,
"issuedAt": 1635724800000,
"failedAt": null,
"reversedAt": null,
"provider": "paypal",
"amountInCampaignCurrency": 3600,
"campaignCurrencyISO": "USD",
"exchangeRateAt": 1635638400000,
"exchangeRate": 1,
"fxError": null
}
],
"limit": 10,
"nextId": null
}Last updated
Was this helpful?