Using the Viral Loops API: A Developer Guide
This guide explains how to work with the Viral Loops API endpoints, with a focus on managing participants programmatically—ideal for custom implementations, integrations, and advanced automation.
Authentication
All API requests require a publicToken (public API key) which can be found in your campaign’s installation settings. Include it as part of your request body or headers depending on the endpoint.
Best Practices
Always validate emails before sending them to the API.
Ensure referrer codes are correct and valid (e.g., by checking the participant list).
Use webhooks in Viral Loops to automate syncing reward events to third-party platforms.
Rate limit: The API supports normal usage, but bulk imports should be throttled.
1) POST /campaign/participant
➤ Purpose: Add a new participant to your campaign
This is the most commonly used endpoint and is typically triggered when a user signs up for your campaign (e.g., through a form on your site or app).
How to Use
URL: https://app.viral-loops.com/api/v2/campaign/participant
Method: POST
Headers:
Content-Type: application/json
Required Parameters in Body:
json
CopyEdit
{
"campaignId": "YOUR_CAMPAIGN_ID",
"email": "user@example.com",
"firstName": "User",
"referrer": "REFERRAL_CODE", // optional
"customFields": {
"country": "US"
}
}
Parameter | Type | Required | Description |
campaignId | string |  | The ID of the campaign you’re adding the participant to |
string |  | Participant’s email address | |
firstName | string |  | Optional first name |
referrer | string |  | The referral code of the referrer, if any |
customFields | object |  | Object with custom user data (e.g., country, language) |
2) GET /campaign/participant
➤ Purpose: Retrieve participant data
Use this to get information about a specific participant (e.g., their referral count, status, reward tiers, etc.)
URL: https://app.viral-loops.com/api/v2/campaign/participant?email=user@example.com
Required Query Params:
email — the email of the participant
campaignId — your campaign ID
3)POST /campaign/participant/redeem
➤ Purpose: Redeem a reward manually
This is used to mark a participant's milestone as redeemed.
Body:
json
CopyEdit
{
"email": "user@example.com",
"campaignId": "YOUR_CAMPAIGN_ID",
"milestoneId": "ID_OF_REWARD"
}
4) Viral Loops API – Update a Participant
This guide explains how to use the PUT /campaign/participant endpoint to update an existing participant's data in a Viral Loops campaign. It’s useful when you want to:
Change the participant’s name, last name of referral count ( both referred leads and successful referrals)
Endpoint Overview
URL:
https://app.viral-loops.com/api/v2/campaign/participant
Method: PUT
Content-Type: application/json
Required Authentication
The secret API token and the participant’s current email are needed in the body to identify the participant.
Request Body Parameters
Parameter | Type | Required | Description |
Apitokken | string |  | Your secret API token (found in installation settings) |
string |  | The current email address of the participant to be updated | |
firstName | string |  | The new or updated first name |
referrer | string |  | Referral code of the person who referred the participant |
sendEmails boolean | object |  | Choose wether the new updated contact should be re-enrolled in the e-mails sent by VL campaing |
triggerIntegrations boolean Optional flag to trigger integrations. | object |  | Choose if the new updated contact will be re-enrolled in the active Itnegrations for the new values to be sent over |
Sample Request
json
CopyEdit
PUT /campaign/participant
Content-Type: application/json
{
"campaignId": "cl2ad12345a1ab601234",
"email": "old.email@example.com",
"newEmail": "new.email@example.com",
"firstName": "John",
"referrer": "ref-abc123",
"customFields": {
"city": "Amsterdam",
"membership": "gold"
}
}
Response
On success, you will receive a 200 OK status and a JSON object representing the updated participant:
json
CopyEdit
{
"status": "success",
"data": {
"email": "new.email@example.com",
"firstName": "John",
"customFields": {
"city": "Amsterdam",
"membership": "gold"
}
}
}
Common Issues
Status Code | Meaning | Likely Fix |
400 | Bad request | Make sure email and campaignId are provided |
404 | Participant not found | Verify that the email exists in the campaign |
409 | Email conflict | The newEmail is already used by another participant |
Use Cases
You want to associate new referral data with a participant
You’re syncing profile changes from an external CRM
5) Viral Loops API – Retrieve Participant Data
The GET /campaign/participant/data endpoint allows you to fetch detailed information about a specific participant in a Viral Loops campaign.
You can use this to:
View how many successful referrals a participant has made
Check their current reward status
Monitor their position in milestone or leaderboard campaigns
Access custom field data submitted with the participant
Important: Calls with the API Token retrieve full information. Calls with the public token return anonymised data.
Endpoint Overview
URL:
https://app.viral-loops.com/api/v2/campaign/participant/data
Method: GET
Required Parameters
This endpoint requires query parameters to be passed as part of the URL.
Parameter | Type | Required | Description |
string |  | Email address of the participant you want to retrieve | |
campaignId | string |  | Unique campaign ID (from your installation snippet or dashboard) |
Sample Request
Here’s how a sample API request might look:
GET https://app.viral-loops.com/api/v2/campaign/participant/data?campaignId=cl2ad12345a1ab601234&email=alex@example.com
Sample Response
json
CopyEdit
{
"status": "success",
"data": {
"email": "alex@example.com",
"firstName": "Alex",
"referralCount": 3,
"rewards": [
{
"milestone": 1,
"reward": "Free T-shirt",
"isRedeemed": true
},
{
"milestone": 2,
"reward": "50% Discount",
"isRedeemed": false
}
],
"customFields": {
"city": "Berlin",
"subscription": "premium"
},
"referredUsers": [
{
"email": "ref1@example.com",
"status": "joined"
},
{
"email": "ref2@example.com",
"status": "converted"
}
]
}
}
Use Cases
This endpoint is particularly useful when you want to:
Show referral status to your users inside your public dashboard or emails
Sync data with a CRM or backend system
Support operations, like manual reward redemption or data correction
Error Codes
Status Code | Meaning | Action |
400 | Missing required parameters | Ensure both email and campaignId are passed |
404 | Participant not found | Verify that the email is registered in the campaign |
500 | Server error | Try again or contact support if persistent |
Best Practices
Ensure the email passed is normalized (lowercase, no whitespace)
Use this endpoint to monitor top referrers in real-time
Combine this with /redeem or /update endpoints to build custom workflows
6) Viral Loops API – Retrieve Participant Referrals
The GET /campaign/participant/referrals endpoint allows you to fetch a list of users who were referred by a specific participant in a campaign.
This endpoint is ideal when you want to:
See who each participant referred
Track the referral status of invitees
Verify referral attribution logic
Endpoint Overview
Endpoint URL:
https://app.viral-loops.com/api/v2/campaign/participant/referrals
Method: GET
Content-Type: application/json
Required Query Parameters
Parameter | Type | Required | Description |
campaignId | string |  | Your campaign’s unique ID |
string |  | The email address of the participant whose referrals you want to retrieve |
Sample Request
GET https://app.viral-loops.com/api/v2/campaign/participant/referrals?campaignId=cl2ad12345a1ab601234&email=alex@example.com
Sample Response
json
CopyEdit
{
"status": "success",
"data": [
{
"email": "ref1@example.com",
"status": "converted",
"createdAt": "2025-06-05T10:30:00Z"
},
{
"email": "ref2@example.com",
"status": "joined",
"createdAt": "2025-06-06T08:45:00Z"
}
]
}
Use Cases
You can use this endpoint to:
Display referral progress in a user dashboard
Audit referral activity for reward qualification
Track invite statuses like joined, converted, or pending
Trigger emails or reward flows based on referral milestones
Error Handling
Code | Meaning | What to Check |
400 | Missing parameters | Ensure both email and campaignId are included |
404 | Participant not found | Make sure the participant exists in the specified campaign |
500 | Server/internal error | Retry or contact support |
Pro Tips
Add a timestamp filter (on your side) if you want to retrieve only recent referrals
Useful in ambassador programs and tiered reward systems to validate real-time performance
7) Viral Loops API – Convert a Participant (Trigger a Successful Referral)
The POST /campaign/participant/convert endpoint is used to register a successful referral by marking an already invited participant as “converted.”
This is essential for:
Rewarding referrers when a referred person completes a conversion event (e.g., purchase, signup)
Triggering milestone logic or unlocking rewards
Tracking conversion metrics across campaigns
Important: this endpoint will work only for the emails of participants who have already been referred to the campaign, and they have signed up as referrals.
Endpoint Overview
Endpoint URL: https://app.viral-loops.com/api/v2/campaign/participant/convert
Method: POST
Content-Type: application/json
Required Request Body Parameters
Parameter | Type | Required | Description |
campaignId | string |  | The unique ID of your campaign |
string |  | The email address of the participant being marked as “converted” |
Sample Request
POST https://app.viral-loops.com/api/v2/campaign/participant/convert
Content-Type: application/json
{
"campaignId": "cl2ad12345a1ab601234",
"email": "newuser@example.com"
}
Sample Success Response
json
CopyEdit
{
"status": "success",
"data": {
"email": "newuser@example.com",
"converted": true,
"referrer": "referrer@example.com",
"rewardTriggered": true
}
}
Use Cases
E-commerce: Trigger conversion after a referred customer makes a purchase
SaaS/Apps: Mark referrals as converted after a signup or onboarding event
Offline campaigns: Programmatically confirm a participant’s activity (e.g., store visit)
Error Handling
Code | Meaning | What to Check |
400 | Missing or invalid parameters | Ensure both email and campaignId are present and correct |
404 | Participant not found | Make sure the user was previously added via the /participant endpoint |
409 | Already converted | The participant has already been marked as converted |
500 | Internal server error | Retry or contact Viral Loops support |
Best Practices
Use this after the actual conversion (e.g. payment complete, email verified)
Avoid multiple conversions per user unless allowed by your campaign logic
Batch convert calls using backend logic if integrating with external events (e.g., webhook from Stripe or Shopify)
8) The POST /campaign/participant/flag endpoint allows you to flag a participant in a campaign — typically to mark them for fraud review or other manual interventions.
This is especially useful when you want to programmatically:
Disqualify suspicious entries
Track problematic users
Review participants with abnormal behavior
More specifically: Used to flag participants who have gotten early access or a reward and should be removed from the waiting list or leaderboard. The participants are not deleted from the campaign, they are simply excluded from the waitlist or leaderboard. This means they are also not displayed in the waitlist or leaderboard in the Viral Loops popup but you can still see them in your Campaign Dashboard and campaign exports.
Endpoint Overview
Endpoint URL:
https://app.viral-loops.com/api/v3/campaign/participant/flag
Method: POST
Required Request Body Parameters
Parameter | Type | Required | Description |
campaignId | string |  | The ID of the campaign where the participant is enrolled |
string |  | Email of the participant to flag | |
reason | string |  | The reason or context for flagging (e.g., "suspicious activity", "spam referral", etc.) |
Sample Request
http
CopyEdit
POST https://app.viral-loops.com/api/v2/campaign/participant/flag
Content-Type: application/json
{
"campaignId": "cl2ad12345a1ab601234",
"email": "user@example.com",
"reason": "duplicate entries from same IP address"
}
Sample Success Response
{
"status": "success",
"message": "Participant flagged successfully"
}
Error Handling
Code | Meaning | What to Check |
400 | Missing or malformed input | Ensure campaignId, email, and reason are all provided and correctly formatted |
404 | Participant not found | Make sure the email exists in the campaign before attempting to flag |
500 | Internal error | Retry or contact Viral Loops support |
Best Practices
Use this endpoint as part of your fraud detection or trust & safety operations
Flag does not delete or disqualify the user automatically — use it as a marker for internal review or manual disqualification
Pair with analytics tools to detect unusual behaviors (e.g., referral spam, high volume from same IP/email domain)
Follow-Up Actions
Once flagged, you may:
Manually review the participant from your Viral Loops dashboard
Use the [DELETE /campaign/participant] endpoint to remove them
Track flagged participants for internal records or reporting
9) Viral Loops API – Get Participant Order (Used for Shopify & WooCommerce Integrations)
The GET /campaign/participant/order endpoint retrieves the order details associated with a specific participant, based on their email and a referral code. This is typically used to verify a referred purchase for ecommerce platforms like Shopify or WooCommerce.
Endpoint Overview
Endpoint URL:
https://app.viral-loops.com/api/v2/campaign/participant/order
Method: GET
Content-Type: application/json
Authentication: Requires API Key
Query Parameters
Parameter | Type | Required | Description |
campaignId | string |  | The ID of the campaign |
string |  | Email of the participant (used to locate the order) |
Sample Request
GET https://app.viral-loops.com/api/v2/campaign/participant/order?campaignId=cl123456789abc&email=user@example.com&referralCode=my7uory
Sample Success Response
{
"status": "success",
"data": {
"email": "user@example.com",
"referralCode": "my7uory",
"orderId": "1234567890",
"orderAmount": "45.00",
"orderCurrency": "USD",
"campaignId": "cl123456789abc"
}
}
Error Responses
Code | Meaning | Troubleshooting Tips |
400 | Missing parameters | Ensure all required fields are included |
404 | No order found | Double-check if the email/referral code match a valid transaction |
500 | Server error | Retry later or contact support |
Use Cases
Validate a conversion from a referred user
Check whether the participant made a purchase
Track orders that should reward the referrer
Pro Tips
Make sure your Shopify or WooCommerce integration correctly forwards referral data at the time of purchase.
This endpoint can be used in a webhook workflow to auto-check if a purchase meets referral requirements.
Combine with POST /campaign/participant/convert to register successful conversions after validating the order.
10) Get Referrer by Participant
The GET /campaign/participant/referrer endpoint allows you to retrieve the referrer (the person who made the referral) of a specific participant. This is especially useful when building referral tracking dashboards or validating referral relationships for reward eligibility.
Endpoint Overview
Endpoint URL:
https://app.viral-loops.com/api/v2/campaign/participant/referrer
Method: GET
Content-Type: application/json
Authentication: Requires API Key
Query Parameters
Parameter | Type | Required | Description |
campaignId | string |  | The ID of the campaign |
string |  | The email of the participant whose referrer you're trying to find |
Sample Request
GET https://app.viral-loops.com/api/v2/campaign/participant/referrer?campaignId=cl123456789abc&email=invitee@example.com
Sample Success Response
json
CopyEdit
{
"status": "success",
"data": {
"referrer": {
"email": "referrer@example.com",
"name": "Jane Doe",
"referralCode": "abc123xyz",
"shareUrl": "https://viral-loops.com/referral?ref=abc123xyz",
"campaignId": "cl123456789abc"
}
}
}
Error Responses
Code | Meaning | Troubleshooting Tips |
400 | Missing campaign ID or email | Ensure both parameters are provided |
404 | Referrer not found | The participant may not have been referred |
500 | Server error | Retry later or contact support |
Use Cases
Find out who referred a participant
Display referral relationships in reporting tools
Custom reward logic (e.g. trigger reward only if a referral comes from a specific user)
Pro Tips
This is one-directional: You provide a participant and retrieve their referrer. If you want to see who they referred, use
GET /campaign/participant/referrals.Combine this endpoint with participant data and reward tracking for more complete CRM or marketing workflows.
11. Viral Loops API – Get Participant Rank
The GET /campaign/participant/rank endpoint allows you to retrieve the current rank (position) of a specific participant in the campaign leaderboard. This is especially useful for leaderboard-style referral campaigns where rank visibility is a key engagement driver.
Endpoint Overview
Endpoint URL:
https://app.viral-loops.com/api/v2/campaign/participant/rank
Method: GET
Content-Type: application/json
Authentication: Requires API Key
Query Parameters
Parameter | Type | Required | Description |
campaignId | string |  | The unique ID of your campaign |
string |  | The email address of the participant whose rank you want to retrieve |
Sample Request
GET https://app.viral-loops.com/api/v2/campaign/participant/rank?campaignId=cl123456789abc&email=participant@example.com
Sample Success Response
{
"status": "success",
"data": {
"rank": 5
}
}
This means the participant is currently ranked #5 on the leaderboard.
Possible Error Responses
Code | Meaning | Troubleshooting Tips |
400 | Missing campaign ID or email | Double-check that both parameters are present |
404 | Participant not found | Make sure the email is correct and that the user has joined the campaign |
500 | Server error | Retry later or contact support if persistent |
Use Cases
Display participant ranking inside your own dashboard or user portal
Show a user's leaderboard position in email communications
Encourage more sharing by showing live rank updates
Trigger milestone actions or special rewards based on rank
Tips & Notes
If your campaign does not use a leaderboard template, the rank may not be available.
To retrieve additional leaderboard data (like participants above/below), use the GET /campaign/leaderboard endpoint.
Combine with GET /participant/data for a full participant profile.
Troubleshooting
400 Bad Request: Likely due to a missing or malformed parameter.
403 Forbidden: Check if your API key/token is missing or incorrect.
409 Conflict: This email is already in the system (duplicate submission).
12. Get Referrer by Referred Participant
Endpoint: GET /campaign/participant/referrer
What Does This Endpoint Do?
This endpoint retrieves information about the referrer (the participant who shared their referral link) based on the email address of a referred participant. It’s a helpful tool for tracing who referred a specific participant.
Required Query Parameters
Parameter | Type | Description |
string | The email of the referred participant whose referrer you want to find. | |
apiToken | string | Your Secret API token, used to authenticate the request. You can find this in your campaign settings. |
Example Request
GET https://app.viral-loops.com/api/v3/campaign/participant/referrer?email=john.doe@example.com&apiToken=YOUR_SECRET_TOKEN
Example Successful Response
json
CopyEdit
{
"status": 200,
"data": {
"_id": "5ab1e567a3b6e700144d21c5",
"campaignId": "MyCampaign123",
"email": "referrer@example.com",
"firstName": "Alice",
"lastName": "Smith",
"referralCode": "abc123",
"referralsCount": 5,
"referredUsers": [...]
}
}
Common Use Cases
You want to check which user referred a specific contact in your CRM.
You’re building a reward attribution logic, and need to fetch the referrer before crediting a referral.
You want to show “referred by” info in a user dashboard or admin view.
Things to Keep in Mind
If the referred participant was not referred by anyone (i.e., signed up organically), the response may be empty.
Always keep your API token secret. Don’t expose it on the frontend.
Pro Tip
Combine this with the GET /campaign/participant-data and GET /campaign/participant-referrals endpoints to build a full participant journey and referral chain!
Reward endpoints
1. Pending Rewards
What this endpoint does
This endpoint allows you to retrieve the list of pending rewards for a specific participant in a Viral Loops campaign. Pending rewards are those that have been earned but not yet delivered or confirmed—useful when managing conditional rewards or when syncing with fulfilment systems.
Endpoint
GET https://api.viral-loops.com/v2/campaign/participant/rewards/pending
Authentication
You need to include the Campaign ID Or API Token in the request headers:
You need to include the following headers:
x-api-token: Your campaign’s secret API token
Or
x-campaign-id: The Campaign ID associated with the participant
You can find these in your Campaign Installation settings in the Viral Loops dashboard.
Query Parameters
Parameter | Type | Required | Description |
string |  Yes | The email of the participant you want to check |
Example:
bash
CopyEdit
GET /v2/campaign/participant/rewards/pending?email=john@example.com
Successful Response
Returns an array of the pending rewards (if any), including information such as:
json
CopyEdit
{
"data": [
{
"rewardId": "clupcvo8x0002xw0dbqg0xxxx",
"milestoneId": "milestone_5_referrals",
"status": "pending",
"createdAt": "2024-06-18T12:30:00Z",
"type": "gift_card",
"referralsRequired": 5
}
]
}
️Common Use Cases
Checking which participants have pending rewards before fulfillment.
Automating reward delivery with tools like Zapier or Make.
Building a rewards dashboard in your CRM or admin panel.
Notes
This endpoint only returns pending rewards. If the reward was already marked as delivered, it will not appear in the response.
If no rewards are pending for the provided email, the response will be an empty array.
Pro Tip
If you're syncing with systems like Shopify, Klaviyo, or a gifting platform, use this endpoint to check eligibility before triggering any external action.
2. Redeem reward
What this endpoint does
This endpoint allows you to manually mark a pending reward as redeemed for a campaign participant. It's ideal for workflows where you’re managing reward delivery yourself (e.g., physical gifts, gift cards, or store credits) and need to track reward fulfillment inside Viral Loops.
Endpoint
POST https://api.viral-loops.com/v2/campaign/participant/rewards/redeem
Authentication
You need to include one of the following headers:
x-api-token: Your campaign’s secret API token
Or
x-campaign-id: The Campaign ID associated with the participant
You can find these in your Campaign Installation settings in the Viral Loops dashboard.
Body Parameters
You need to send a JSON object with the following:
Parameter | Type | Required | Description |
string |  Yes | The email of the participant receiving the reward | |
milestoneId | string |  Yes | The ID of the milestone (can be found in campaign setup) |
rewardId | string |  Yes | The ID of the pending reward you want to mark as redeemed |
Example Payload
json
CopyEdit
{
"email": "john@example.com",
"milestoneId": "milestone_5_referrals",
"rewardId": "clupcvo8x0002xw0dbqg0xxxx"
}
Successful Response
Returns a confirmation that the reward has been marked as redeemed:
json
CopyEdit
{
"status": "success",
"message": "Reward successfully marked as redeemed"
}
️Use Cases
Marking a reward as delivered after processing gift cards or physical products.
Updating a participant’s reward status in custom admin workflows.
Preventing re-rewarding the same milestone in CRM or loyalty integrations.
Best Practices
Use this in combination with GET /rewards/pending to check reward status before redeeming.
Log this action in your internal tools for audit/tracking purposes.
Only redeem a reward after it has actually been fulfilled on your side.
Caution
Once a reward is marked as redeemed, it will no longer appear in the pending rewards list.
You cannot undo a redemption via the API—any mistake would require manual correction via the Viral Loops support team.