KickoffLabs platform help — viral marketing for pre-launch waitlists, bonus-entry giveaways, milestone-reward referral programs, and leaderboard giveaways with REST API v1 + v2, server-side webhooks (`__fraudulent`/`__referral`), AnyForm + KOL.js, and native ESP/Shopify/Zapier integrations. Use when viral campaigns aren't tracking referrers, deciding between Hobby (lead-capped, no A/B, no reward emails) vs Premium (A/B + reward emails) vs Business vs Enterprise tiers, the API key is rejected for being embedded client-side, webhook `__fraudulent` codes (`duplidate_email`/`duplicate_ip`/`bounced`) need a triage workflow, choosing v1 vs v2 endpoints, leaderboard capped at 50, lead-cap auto-upgrade inflating bills, or comparing to Viral Loops/UpViral/Prefinery. Do NOT use for newsletter audience growth (use /sales-audience-growth), merge-tag referrals (use /sales-referralkit), SparkLoop paid recommendations (use /sales-sparkloop), or multi-level Level 1/2/3 referrals (use /sales-referralhero).
Instrucciones de origen · Vista previa de solo lectura
name
sales-kickofflabs
description
KickoffLabs platform help — viral marketing for pre-launch waitlists, bonus-entry giveaways, milestone-reward referral programs, and leaderboard giveaways with REST API v1 + v2, server-side webhooks (`__fraudulent`/`__referral`), AnyForm + KOL.js, and native ESP/Shopify/Zapier integrations. Use when viral campaigns aren't tracking referrers, deciding between Hobby (lead-capped, no A/B, no reward emails) vs Premium (A/B + reward emails) vs Business vs Enterprise tiers, the API key is rejected for being embedded client-side, webhook `__fraudulent` codes (`duplidate_email`/`duplicate_ip`/`bounced`) need a triage workflow, choosing v1 vs v2 endpoints, leaderboard capped at 50, lead-cap auto-upgrade inflating bills, or comparing to Viral Loops/UpViral/Prefinery. Do NOT use for newsletter audience growth (use /sales-audience-growth), merge-tag referrals (use /sales-referralkit), SparkLoop paid recommendations (use /sales-sparkloop), or multi-level Level 1/2/3 referrals (use /sales-referralhero).
If the question is KickoffLabs-specific, continue to Step 3.
Step 3 — KickoffLabs platform reference
Read references/platform-guide.md for the full reference — feature gating per tier, campaign type selection (waitlist / giveaway / milestone / leaderboard / opt-in), AnyForm vs direct-API, fraud detection signals, SMS verification, ESP integrations, and comparisons with Viral Loops / UpViral / Prefinery / ReferralCandy / Voucherify.
Read references/kickofflabs-api-reference.md for the REST API documentation — v1 (/subscribe, /info) + v2 (/v2/{CAMPAIGN_ID}/... for tags, leads, actions, leaderboard, approve, block, waitlist, verify, SMS, bulk-tags), authentication via api_key + CAMPAIGN_ID, webhook payload schemas (including __fraudulent, __referral, __reward_level, __score_change, __tagged), and rate limits by tier.
Answer the user's question using only the relevant section. Don't dump the full reference.
Step 4 — Actionable guidance
Focus on the user's specific situation:
Hobby tier excludes A/B testing, reward level emails, tracking pixels, and custom email templates — for any campaign that needs milestone rewards (the main referral mechanic), start at Premium ($48/mo annual).
API key must be server-side only. Don't embed in client-side JavaScript — KickoffLabs explicitly warns about this. Use AnyForm + KOL.js for browser-side, then have your backend call the API with the key.
v1 vs v2: v1 (/subscribe, /info) is form-encoded and still active for simple adds. v2 (/v2/{CAMPAIGN_ID}/...) is JSON and covers tags, approve/block, bulk operations, leaderboard, waitlist, SMS verification. Use v2 for new integrations.
AnyForm vs direct API: KickoffLabs' own guidance is "in most cases, use AnyForm for custom pages instead of adding leads directly via the API." AnyForm handles attribution (?kid= parsing), referrer cookies, and lead deduplication automatically. Reserve direct API for server-to-server flows your AnyForm can't capture.
SMS verification is Premium+ as a $50/mo add-on; Enterprise includes it. If your fraud risk requires SMS verification, budget Premium + add-on ($98/mo annual) or Enterprise ($202/mo annual).
Lead-cap auto-upgrade at $8 per 1,000 overage — if your campaign spikes (Product Hunt launch, press feature), expect auto-upgrade billing to kick in. Set a campaign-level cap if you want hard ceilings.
Fraud-detection flags in webhook: duplicate_ip (same IP signing up multiple times), bounced (email bounced on verify), duplidate_email (their typo — duplicate email). Treat them as advisory; combine with approve / block endpoints for manual review.
Leaderboard endpoint caps at 50 results — for larger top-N lists, paginate via leads endpoint and sort client-side.
If you discover a gotcha, workaround, or tip not covered in references/learnings.md, append it there.
Gotchas
Best-effort from research — review these, especially items about plan-gated features that may shift.
API key must be server-side. "Your API Key should never be used in client side JavaScript." Browser-embedded keys leak to any attacker who reads page source. Use AnyForm + KOL.js for browser-side; reserve the API key for backend.
duplidate_email is spelled with a typo in KickoffLabs's own webhook payload docs. When parsing the __fraudulent array, match against the literal string duplidate_email as well as duplicate_email if KickoffLabs ever fixes it. Don't "correct" the typo client-side.
v1 and v2 endpoints coexist. v1 /subscribe is form-encoded; v2 /v2/... is JSON-first. Mixing them in one integration confuses parameter parsing. Pick one path per campaign workflow.
Reward-level emails are Premium+. Hobby tier ($13/mo) supports the autoresponder but NOT reward-level emails — so milestone-reward programs need Premium minimum.
A/B testing is Premium+. Hobby cannot A/B test campaign variants. Limits iteration on signup conversion early.
Custom email templates + custom domains require Business+ ($99/mo). Premium ($48/mo) gives one custom domain but uses default email templates.
SMS Contests are Premium+ add-on at $50/mo extra (Enterprise includes). Don't promise SMS verification on Hobby.
Lead-cap auto-upgrade at $8 per 1,000 overage — viral campaigns spike, billing follows. Capterra reviews flag pricing concerns; set a campaign-level cap and configure billing alerts.
Leaderboard endpoint capped at 50 leads. No pagination on /leaderboard itself — pull more via the leads endpoints and rank client-side.
Rate limits scale with plan: ~10/min on Hobby up to ~100/min on Enterprise. Use bulk endpoints (Bulk Tags, bulk Approve up to 200 emails) for batch operations.
Webhook signing is undocumented in public material. No HMAC/signature scheme published. Verify caller IP or use a shared-secret query param if signing matters; or contact support to confirm current behavior.
AnyForm is preferred over direct API for custom pages. KickoffLabs's own docs say so. Direct API is for server-to-server attribution flows AnyForm can't reach.
Capterra reviewers complain about design customization limits ("section mechanic requires more options") and a learning curve. If pixel-perfect landing pages matter, pair KickoffLabs with a standalone landing-page tool (Unbounce, Leadpages, Framer) and post results via AnyForm.
Related skills
/sales-audience-growth — Newsletter audience growth strategy (referrals + cross-promotion + lead magnets across all platforms)
/sales-newsletter — Newsletter monetization (paid subs, sponsorships, ad networks)
/sales-referralkit — ReferralKit (no-code merge-tag-driven newsletter referrals, free up to 10K leads)
/sales-referralhero — ReferralHero (full-stack referral/affiliate/waitlist/contest with multi-level Level 1/2/3 + coupon groups + REST API + webhooks + Zapier)
/sales-affiliate-program — General affiliate program strategy and platform selection
/sales-klaviyo — Klaviyo platform help (native ESP integration)
/sales-mailchimp — Mailchimp platform help (native ESP integration)
/sales-activecampaign — ActiveCampaign platform help (native ESP integration)
/sales-brevo — Brevo platform help (native ESP integration)
/sales-do — Not sure which skill to use? The router matches any sales objective to the right skill. Install: npx skills add sales-skills/sales --skill sales-do -a claude-code
Examples
Example 1: Tier picking for a Product Hunt launch waitlist
User says: "I'm launching on Product Hunt next month and want a viral waitlist with milestone rewards. Hobby or Premium?"
Skill does: Recommends Premium ($48/mo annual, 2,500 leads/mo) because reward-level emails are Premium+, A/B testing is Premium+, and a Product Hunt feature can spike well past Hobby's 500-leads cap. Warns about $8-per-1,000 auto-upgrade billing on spike and suggests setting a campaign cap if budget is tight. Mentions SMS Verification add-on ($50/mo extra) if fraud risk is high. Recommends Business ($99/mo) only if custom email templates/domains matter from day one.
Result: User picks Premium with annual billing, sets a 10K-lead campaign cap, plans SMS verification only if first 1K signups show fraud signals.
Example 2: Webhook payload __fraudulent interpretation
User says: "I'm getting webhooks with __fraudulent arrays containing duplidate_email and bounced — what do these mean and what should I do?"
Skill does: Confirms duplidate_email is verbatim from KickoffLabs docs (yes, with the typo — match the literal string). duplicate_ip means another lead signed up from the same IP recently. bounced means the verification email bounced. Suggests a triage workflow: auto-block on bounced, manual-review on duplicate_ip/duplidate_email, and use POST /v2/{CAMPAIGN_ID}/approve (supports up to 200 emails per bulk call) to override after review.
Result: User builds a webhook handler that routes by fraud reason and queues borderline cases for human review with batch approve.
Example 3: v1 cURL to add a lead with referrer attribution
User says: "Give me a cURL example to add a subscriber via the API with referrer attribution. I'm on Premium."
Skill does: Provides POST https://api.kickofflabs.com/v1/{CAMPAIGN_ID}/subscribe with email, api_key, social_id (the referrer's social_id, found in ?kid= query param), ip, __url, and __ref. Notes the key must be server-side. Mentions v2 /tags/{TAG_ID}/lead as the JSON-based alternative for tag-based workflows. Reminds user to consider AnyForm + KOL.js if the signup happens in browser instead.
Result: User has a working server-side subscribe call with proper attribution and knows when to switch to AnyForm.
Troubleshooting
API returns "invalid api_key" even though the key is correct
Symptom: Calls fail with auth errors despite copying the key from Setup > Advanced Settings > API Access
Cause: Either the key was embedded in client-side JavaScript (which KickoffLabs explicitly disallows and may rotate-invalidate on detection), or the request is hitting a different campaign's API endpoint, or v1/v2 path mismatch
Solution: Verify the request comes from your server, not browser. Confirm the CAMPAIGN_ID in the URL matches the campaign whose key you copied. If you suspect key compromise, rotate it in Setup > Advanced Settings > API Access and update your backend env vars. Don't mix v1 and v2 in one call (v1 wants form-encoded, v2 wants JSON).
Webhooks fire but the __fraudulent field is empty when I expected fraud
Symptom: A lead clearly looks fraudulent (same IP repeating, disposable email) but the webhook arrives without a __fraudulent array
Cause: KickoffLabs's fraud detection runs heuristics — duplicate_ip only fires if signups come from the same IP within KickoffLabs's window; bounced requires a verification bounce, which only happens if double-opt-in / verify is configured; duplidate_email catches exact duplicates, not lookalikes
Solution: Enable email verification / double-opt-in on the campaign for bounced flags. Use the POST /v2/{CAMPAIGN_ID}/leads/verify endpoint as a programmatic verification trigger. For weaker fraud signals (disposable domains, lookalike emails), add a server-side check before forwarding to KickoffLabs.
Leaderboard endpoint only returns 50 leads — how do I get the top 100?
Symptom: GET /v2/{CAMPAIGN_ID}/leaderboard caps at 50 results
Cause: The endpoint enforces limit ≤ 50 by design — pagination is not supported on /leaderboardSolution: Pull more leads via GET /v2/{CAMPAIGN_ID}/leads/... (or use the leaderboard 50, then call individual leads beyond rank 50 via lead-by-ID endpoints), and rank client-side by contest_score. For most campaigns, top 50 is the meaningful slice — verify whether you actually need 100+.
Lead-cap auto-upgrade billed me unexpectedly after a viral spike
Symptom: Monthly bill jumped after a Product Hunt feature pushed leads above the plan cap
Cause: KickoffLabs auto-upgrades plans at $8 per 1,000 overage leads — by default this is silent
Solution: Set a campaign-level lead cap in dashboard settings (where supported per plan). Configure billing alerts via your payment processor. Upgrade to the next plan tier proactively if you're consistently within 20% of the cap — annual billing at the higher tier is often cheaper than per-overage charges.
