sales-skills/sales-upviral

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 networks)
• /sales-kickofflabs — KickoffLabs (viral waitlists / giveaways / milestone rewards with REST API v1+v2, AnyForm, KOL.js)
• /sales-referralkit — ReferralKit (no-code merge-tag-driven newsletter referrals, free up to 10K leads)
• /sales-sparkloop — SparkLoop (newsletter referrals + paid recommendations + partner network)
• /sales-referralhero — ReferralHero (full-stack referral/affiliate/waitlist/contest with multi-level Level 1/2/3 + coupon groups + REST API)
• /sales-affiliate-program — General affiliate program strategy and platform selection
• /sales-mailchimp — Mailchimp platform help (native ESP integration)
• /sales-activecampaign — ActiveCampaign platform help (native ESP integration)
• /sales-klaviyo — Klaviyo 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 when an integration is required

User says: "I want to run a viral giveaway and sync new leads straight into HubSpot automatically. Is the $79 Starter plan enough?" Skill does: Explains that Starter has NO API or webhooks — automated CRM sync requires the Business tier ($119/mo annual, 25K leads, 2 brands) which unlocks API + webhooks. Notes the cheaper path if budget is tight: a native HubSpot integration (UI-configured) or Zapier "New Lead" trigger may cover a simple sync, but webhooks/REST still need Business. Recommends Business and warns that the first campaign setup takes a few hours. Result: User upgrades to Business, wires the New Lead → HubSpot Zap (or REST get_leads poll), and budgets setup time.

Example 2: Reward-fulfillment pull via the API

User says: "I'm on Business. How do I get a list of everyone in my campaign who has 100+ points so I can ship their reward?" Skill does: Provides a form-encoded POST to https://app.upviral.com/api/v1/ with uvapikey, uvmethod=get_leads_points, campaign_id, operator >, points 99 (or >= semantics via =/>), plus start/size pagination. Shows parsing the JSON to extract emails, and suggests pairing with get_lead_details for shipping fields. Notes there's no MCP server, so this REST poll (or the Callback URL on reward-unlock) is the integration path. Result: User scripts a paginated get_leads_points pull and exports reward-eligible contacts.

Example 3: Fraud flags from same-IP referrals

User says: "A bunch of my referrals got marked suspicious. Why, and what should I do?" Skill does: Explains UpViral flags a referral as suspicious when the referred signup's IP matches the referrer's IP (gaming the point system). Flagged leads sit in the Fraud Detection section with three actions: activate (legit — count them), delete, or blacklist. Warns about false positives from shared office/household NAT IPs and recommends reviewing rather than bulk-deleting. Suggests adding email verification and limiting points-per-IP for prevention. Result: User reviews flagged leads, activates the legitimate shared-IP ones, blacklists obvious abusers, and tightens prevention settings.

Troubleshooting

API calls return errors / "unauthorized" even with a valid key

Symptom: Every API request fails despite a correct API key copied from the dashboard Cause: Either the account is on the Starter tier (no API access — API/webhooks are Business+), or the request is sending the key as an Authorization header instead of the uvapikey form field, or uvmethod/campaign_id is missing Solution: Confirm the plan is Business or Premium. Send a form-encoded POST to https://app.upviral.com/api/v1/ with uvapikey, uvmethod (the method name), and campaign_id. Do not use a Bearer header. Check the JSON response for the specific error message.

Callback URL (webhook) isn't firing

Symptom: The configured Callback URL never receives events Cause: Webhooks are gated to Business+; or the callback is set on the wrong campaign; or the triggering event (e.g. reward unlock) hasn't occurred yet Solution: Verify the plan tier. Set the Callback URL on the specific campaign under its settings. Test by triggering the event (have a test lead cross the reward threshold). If still nothing, fall back to a Zapier "New Lead" / "New Reward Unlocked" trigger, which is configured separately from the native callback.

Leads aren't syncing to ClickFunnels / Shopify / my funnel builder

Symptom: The native funnel-builder integration drops leads or doesn't connect Cause: Known flakiness — UpReviews repeatedly flag ClickFunnels, Shopify, and funnel-builder integrations as unreliable; there's also no native WordPress plugin Solution: Route leads through Zapier (New Lead trigger → your destination) or the REST API instead of the deep native integration. For WordPress, embed the UpViral form/script manually rather than expecting a plugin.

The campaign took hours to set up and widgets look broken

Symptom: First campaign is slow to build; drag-and-drop elements render incorrectly Cause: Documented learning curve and builder fragility (broken widgets, limited customization) Solution: Keep the design minimal inside UpViral. For polished landing pages, build externally (Unbounce/Leadpages/Framer) and use UpViral's embedded form or pop-up presentation format. Allocate a few hours for the first build and reuse it as a template afterward.