Viral Loops
Start for freeBook a demo

Grow · Developers & API

Build the referral program into your own product.

One snippet loads the widgets. The JavaScript SDK tracks conversions from your front end, the REST API handles participants and rewards from your server, and webhooks send events back.

Start for free14-day free trial · No credit card requiredBook a demo
Plan
SDK on all plans, REST API from Plus
Works with
Any website, React, Next.js
Setup
One snippet in your <head>

convert.tswidgets.htmlREST API v3

1// a friend paid: count the referral2const url = 'https://app.viral-loops.com/api/v3/campaign/participant/convert';3await fetch(url, {4  method: 'POST',5  headers: { 'Content-Type': 'application/json' },6  body: JSON.stringify({7    user: { email: 'maya.r@…' },8    publicToken: VL_PUBLIC_TOKEN,9  }),10});

Result

  1. Maya R. convertedcounted for Jay B.
  2. rewardRedeemedsent to your webhook
Example data. Screens and labels from the Viral Loops app.

How does the API work?

  1. 1

    Add one snippet

    Paste the loader script into your <head> with your campaign ID. Then place each widget where you want it, as a custom element like <form-widget>.

  2. 2

    Track from your front end

    When the friend does the thing that counts, call campaign.track("conversion") with the JavaScript SDK.

  3. 3

    Call the REST API from your server

    REST API v3 registers participants, reports conversions, reads referrals and rank, flags participants and redeems rewards. Your server calls it with the secret API token.

  4. 4

    Get the events back

    Webhooks send participation, milestone reached and reward redeemed events to your endpoint. Failed deliveries are retried for up to 4 days.

What can you set up in the API?

Every option by its name in the app, with the plan that includes it.

Compare plans
JavaScript SDK
Load widgets, identify participants and track conversions from the browser.
All plans
Widgets as custom elements
Form, Popup Form, Milestone, Invitee Form, Referral URL, Sharing Options, Leaderboard, Stat and Progress Tracking, placed as HTML tags.
All plans
REST API
Participants, referrals, conversions, rank, campaign stats and rewards, over REST API v3.
Plus and up
Server-side conversions
Report a conversion from your server with the secret API token, with its value if you track revenue.
Growing and up
Allow only authorized conversions
Only conversions sent with your private API token count; conversions from the browser are ignored.
Public and secret tokens
The public token, your campaign ID, returns anonymised data. The secret API token returns full data and stays on your server.
Webhooks
Participation, milestone reached and reward redeemed events, sent to your endpoint. Custom Webhooks are on Power.
Plus and up
Webhooks Signature Verification
Check that each webhook came from Viral Loops.
Plus and up
IP-Restricted Webhook Access
Limit webhook access by IP address.
Growing and up
MCP Server
An MCP server for connecting AI tools to your program.
Plus and up
Full CSS Control
Restyle every widget with your own CSS.
Plus and up

Which templates and tools work with the API?

All integrations

FAQ

Developers & API FAQ

Do I need a developer to use Viral Loops?

No. You add one snippet to your site, and a little HTML is enough. The SDK and the API are there when you want to build the program into your own product.

Which plan includes the API?

The JavaScript SDK is on every plan. The REST API, webhooks, the MCP server and Full CSS Control are on Plus and up. Server-side conversions and IP-restricted webhook access need Growing, and Custom Webhooks need Power.

Which token do I use?

The public token, your campaign ID, works in the browser and returns anonymised data. The secret API token returns full data, so keep it on your server.

Is there a rate limit?

Yes. Per the developer docs, 300 requests a minute, and 25 a minute for conversions.

Does it work with React?

Yes. The developer docs have a guide for React and Next.js.

What happens if my endpoint is down?

Failed webhook deliveries are retried for up to 4 days. An endpoint that keeps failing for several days in a row is disabled.

More Grow features

All features

Build referrals into your own product.

Plans start at $35 a month, billed annually. Try it free for 14 days, or talk to our team.

Start for free14-day free trial · No credit card requiredBook a demo