sales-upviral

What this skill does

# UpViral Platform Help

## Step 1 — Gather context

If `references/learnings.md` exists, read it first for accumulated platform knowledge.

1. **What are you trying to do?**
   - A) Pick a tier — Starter $79/mo (10K leads, no API) vs Business $119/mo (25K, API+webhooks) vs Premium $319/mo (100K, dedicated AM)
   - B) Launch a viral sweepstakes (point competition with a grand prize)
   - C) Run a giveaway / viral rewards campaign for lead gen
   - D) Build a pre-launch viral waiting list (Dropbox-style queue jumping)
   - E) Set up an evergreen milestone referral program
   - F) Connect API or webhooks — `add_contact` / `get_leads` / `add_points` / Callback URL
   - G) Interpret fraud flags (same-IP suspicious referrals) and decide activate/delete/blacklist
   - H) Integrate with Mailchimp / ActiveCampaign / ConvertKit / Klaviyo / HubSpot / Zapier
   - I) Compare UpViral to Viral Loops / KickoffLabs / Vyper / Prefinery / Gleam

2. **What's your campaign type?** Sweepstakes / giveaway-rewards / waiting-list / milestone — drives which points, reward, and verification settings matter.

3. **What's your ESP and site stack?** Drives whether a native ESP integration is enough or you need API/webhooks/Zapier glue — and whether you're forced onto the Business tier to unlock the API.

Skip-ahead rule: if the user's prompt already contains enough context, skip to Step 2.

## Step 2 — Route or answer directly

| If the question is about... | Route to... |
|---|---|
| General newsletter/audience growth strategy across all platforms | `/sales-audience-growth [question]` |
| Newsletter monetization (paid subs, sponsorships, ad networks) | `/sales-newsletter [question]` |
| KickoffLabs viral campaigns specifically | `/sales-kickofflabs [question]` |
| No-code newsletter-only referrals with merge-tag insertion | `/sales-referralkit [question]` |
| SparkLoop paid recommendations + partner network | `/sales-sparkloop [question]` |
| Full-stack referral/affiliate with multi-level Level 1/2/3 + coupon groups | `/sales-referralhero [question]` |
| Affiliate program strategy across many tools | `/sales-affiliate-program [question]` |
| ESP setup (Mailchimp, ActiveCampaign, Klaviyo, HubSpot) | `/sales-mailchimp`, `/sales-activecampaign`, `/sales-klaviyo`, `/sales-hubspot` |

If the question is UpViral-specific, continue to Step 3.

## Step 3 — UpViral platform reference

**Read `references/platform-guide.md`** for the full reference — tier gating (especially the API/webhooks Business+ gate), campaign type selection (sweepstakes / rewards / waiting-list / milestone / custom), presentation formats, fraud detection model, ESP/CRM integrations, the ClickFunnels/Shopify integration caveats, and comparisons with Viral Loops / KickoffLabs / Vyper / Prefinery / Gleam.

**Read `references/upviral-api-reference.md`** for the REST API documentation — base `https://app.upviral.com/api/v1/`, `uvapikey` + `uvmethod` form-encoded POST authentication, the eight methods (`add_contact`, `get_lead_details`, `get_lead_details_by_email`, `get_leads`, `get_leads_points`, `add_points`, `get_custom_fields`, `lists`), pagination (`start`/`size`), the Callback URL webhook payload, the PHP SDK, and the Business+ API gate.

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:

- **API and webhooks are gated to Business ($119/mo annual) and above.** Starter ($79/mo) has NO API/webhooks. If your project is a CRM sync, a data-warehouse pipeline, or any server-side automation, you must budget Business minimum — this is the single most common surprise. Verify before promising an integration.
- **Auth is two form-encoded params, not a header.** Every request POSTs `uvapikey` (your key) + `uvmethod` (the method name) + `campaign_id` (for most methods) as form-encoded fields to `https://app.upviral.com/api/v1/`. There is no Bearer header. Responses are JSON.
- **Use `get_leads_points` for reward fulfillment.** To find everyone who crossed a points threshold (e.g. unlocked a reward), call `get_leads_points` with an operator (`<`, `>`, `=`) and a points value rather than pulling all leads and filtering client-side.
- **Webhook = "Callback URL".** UpViral calls webhooks "Callback URL." Set it per campaign; it fires on events such as a lead unlocking a reward. Pair it with `get_lead_details` to enrich the payload, since the callback is lean.
- **Fraud detection is IP-based and semi-manual.** UpViral flags a referral as "suspicious" when the referred signup comes from the **same IP** as the referrer. Flagged leads land in the Fraud Detection section for you to **activate, delete, or blacklist**. It is not fully automatic — budget review time for high-volume campaigns.
- **Set aside real time for the first campaign.** Reviewers consistently describe setup as "long and complicated" — expect several hours for your first campaign. The drag-and-drop builder has known broken-widget and customization complaints; keep the design simple to avoid them.
- **It's a B2C viral tool.** UpViral is built for consumer viral sharing (Facebook/WhatsApp/X). It's a poor fit for B2B audiences who won't share for points — don't recommend it for B2B lead gen.
- **No native WordPress plugin; ClickFunnels/Shopify integrations are flaky.** Use the embedded-form or pop-up presentation formats, or post via Zapier/API, rather than relying on a deep funnel-builder integration.

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 and pricing that may shift.*

1. **API/webhooks require Business tier ($119/mo annual) or higher.** Starter ($79/mo) cannot call the API or receive callbacks. If a Starter user reports "API not working," the fix is usually an upgrade, not a code change.
2. **Auth params, not headers.** `uvapikey` and `uvmethod` are form-encoded POST fields. Developers used to `Authorization: Bearer` headers will get auth failures — UpViral does not use a header scheme.
3. **Fraud detection is IP-matching + manual triage.** Same-IP referral → "suspicious." You must manually activate/delete/blacklist. Legitimate users behind shared NAT/office IPs can be false-flagged — review before mass-deleting.
4. **Long setup / learning curve.** First campaign commonly takes several hours. Budget for it; don't promise a same-hour launch.
5. **Drag-and-drop builder is fragile.** Reviewers report broken widgets and limited customization. For pixel-perfect pages, build the landing page elsewhere (Unbounce/Leadpages/Framer) and use UpViral's embedded form or pop-up.
6. **No native WordPress plugin.** Despite "WordPress" appearing in integration lists, there's no first-party plugin — embed the form/script manually.
7. **ClickFunnels / Shopify / funnel-builder integrations break.** Multiple reviews flag these. Prefer Zapier or the API over deep native funnel integrations.
8. **$1/14-day trial is short.** Two weeks rarely shows a viral campaign's true performance. Plan to commit to at least one paid month to evaluate properly.
9. **B2C-only fit.** Point-for-share mechanics don't translate to B2B buyers. Wrong tool for enterprise/B2B lead gen.
10. **AI Credits are metered and scarce.** Starter gets 1/mo, Business 3/mo, Premium 10/mo — the AI copy/asset features are not unlimited.
11. **No MCP server.** Programmatic access is the REST API + Callback URL webhook + iPaaS (Zapier/Make/Pipedream/Integrately/Pabbly) only.
12. **Brand limits per tier.** Starter = 1 brand, Business = 2, Premium = 5. Agencies running many clients hit this fast — Premium or multiple accounts.

## 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 networ