viral-loops

n8n community node for the Viral Loops referral-campaign API (v3). Full endpoint coverage: participant registration with referrer attribution, participant data/rank/order/referrals/referrer, batch query, search, flag, conversions, rewards (pending/given/r

Package Information

Released: 2 mo ago
Downloads: 0 weekly / 0 monthly
Latest Version: 0.1.0

Available Nodes

Documentation generating…

Viral Loops icon
Viral Loops
Viral Loops referral campaign API (v3) — participants, rewards, campaign stats

Documentation

n8n-nodes-viral-loops

Open in Obsidian: obsidian://open?vault=Epic%20Tech%20Software&file=projects/epic-dashboards/n8n-nodes-viral-loops/README

n8n community node for the Viral Loops referral-campaign API (v3). Built by Epic Tech Software for the Epic Dashboards founding funnel; general-purpose. Ships prebuilt dist/ (same pattern as n8n-nodes-epic-ghl-subaccount) — no build step.

Spec source: official OpenAPI 3.1 definitions at developers.viral-loops.com/reference (fetched 2026-07-19).

Operations (full v3 coverage)

Resource Operations
Participant register (with referrer attribution + optional ready-to-share referralLink composition) · update · get data · get referrals · get referrer · get order · get rank · convert · query (batch) · search · flag
Reward get pending · get given · redeem (irreversible)
Campaign get stats · get data

API facts baked in

  • Base https://app.viral-loops.com/api/v3; auth = header literally named apiToken (campaign secret, no Bearer). Tokens are per-campaign (Campaign Wizard → Installation step) — one credential per campaign.
  • Registration returns {referralCode, isNew} only — no URL. The share link is <campaign landingPage>?referralCode=<code>; the node's Resolve Referral Link toggle (register/get) fetches /campaign/data and outputs referralLink composed for you.
  • Attribution = referrer.referralCode on registration. The web snippet also parses referralCode/refCode/ref URL params.
  • Rate limits/min: registration 80 · convert 25 · everything else 300.
  • Convert is template-restricted (Milestone, Altruistic, Online-to-Offline, Universal) — it does NOT work on waitlist (Startup Prelaunch) campaigns.
  • Outbound webhooks (configure per campaign → Integrations → Webhooks): participation, milestoneReached, rewardRedeemed. Unsigned — verify by calling the API back. Retries with exponential backoff up to 4 days; failing endpoints get auto-disabled. No conversion webhook (Zapier-only trigger).
  • Error envelope: {statusCode, error, message}.
  • Unverified corners (probe before relying): user.consents shape, refSource/acquiredFrom allowed values, referrals/referrer/rewards item shapes, participant-update required-fields contradiction.

Install on the Elestio n8n

Settings → Community Nodes → Install from npm (after publishing), or copy this folder into the instance's community-nodes dir. Publishing to npm: npm publish from this folder (Cameron's npm account; version bump per RELEASING.md conventions in the GHL node package).

Credential: Viral Loops API — paste the campaign's secret apiToken (+ optionally the publicToken/campaign id).

Note on the live founding-funnel workflows

The three ED — * funnel workflows (Founding List Intake + Viral Loops · VL Participant Lookup · VL Participation Webhook) intentionally use plain HTTP Request nodes with a generic Header-Auth credential named "Viral Loops apiToken", so they run without this package installed. This node is the reusable/typed path for everything after (rewards, flagging, search, future campaigns). Swap-in is 1:1.

Discussion