---
canonical_url: "https://docs.composio.dev/toolkits/viral_loops"
markdown_url: "https://docs.composio.dev/toolkits/viral_loops.md"
product: "platform"
version: null
last_updated: null
---

# Viral Loops

Viral Loops is a referral marketing platform for managing campaigns, participants, referrals, conversions, leaderboards, and rewards.

- **Category:** marketing automation
- **Auth:** API_KEY
- **Composio-managed OAuth available?** N/A
- **Tools:** 9
- **Triggers:** 0
- **Slug:** `VIRAL_LOOPS`
- **Version:** 00000000_00

## Tools

### Get Campaign Info

**Slug:** `VIRAL_LOOPS_GET_CAMPAIGN_INFO`

Return the connected campaign's identity, template, expiration mode and date, points, GDPR, and integration configuration without bulky presentation styling.

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Campaign Stats

**Slug:** `VIRAL_LOOPS_GET_CAMPAIGN_STATS`

Return the connected campaign's lead count and total referral count.

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Participant

**Slug:** `VIRAL_LOOPS_GET_PARTICIPANT`

Return one participant's profile, referral totals, rank, referrer, and reward summaries by email or referral code.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `email` | string | No | Participant email selector. Provide exactly one of email or referral_code. |
| `referral_code` | string | No | Participant referral-code selector. Provide exactly one of referral_code or email. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Participant Referrals

**Slug:** `VIRAL_LOOPS_LIST_PARTICIPANT_REFERRALS`

Return one participant's referrals by email or referral code, with explicit offset pagination. The provider's response fields and pagination metadata are preserved as returned.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `email` | string | No | Participant email selector. Provide exactly one of email or referral_code. |
| `limit` | integer | No | Maximum referrals requested for this page. The provider's maximum is unverified. |
| `offset` | integer | No | Zero-based number of referrals to skip. |
| `referral_code` | string | No | Participant referral-code selector. Provide exactly one of referral_code or email. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Look Up Participants

**Slug:** `VIRAL_LOOPS_LOOK_UP_PARTICIPANTS`

Batch lookup exact participant and referrer identifiers, returning matching campaign records with explicit offset pagination.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `limit` | integer | No | Maximum matching records requested. The provider's maximum is unverified. |
| `offset` | integer | No | Zero-based number of matching records to skip. |
| `referrers` | array | No | Referrer identifiers to look up. Each item must contain exactly one email or referral_code. |
| `participants` | array | No | Participant identifiers to look up. Each item must contain exactly one email or referral_code. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Register Participant

**Slug:** `VIRAL_LOOPS_REGISTER_PARTICIPANT`

Register an email address in the connected campaign, optionally with a referrer and participant metadata. This creates persistent participant data; Viral Loops provides no API operation to delete it.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `email` | string | Yes | Valid email address of the participant to register. |
| `consents` | object | No | Campaign consent names and values to store for this participant. |
| `last_name` | string | No | Participant's last name. |
| `extra_data` | object | No | Campaign-specific custom participant fields to store. |
| `first_name` | string | No | Participant's first name. |
| `acquired_from` | string | No | Acquisition channel or origin to record for this participant. |
| `referral_source` | string | No | Referral source value to record for this participant. |
| `referrer_referral_code` | string | No | Referral code of the participant who referred this registration. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Search Participants

**Slug:** `VIRAL_LOOPS_SEARCH_PARTICIPANTS`

Search campaign participants by text, conversion status, and acquisition source, with explicit offset pagination.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `limit` | integer | No | Maximum participants requested for this page; the provider's maximum is unverified. |
| `offset` | integer | No | Zero-based number of participants to skip. |
| `source` | string ("all" | "referred" | "organic") | No | How included participants were acquired. |
| `search_term` | string | No | Text to match against searchable participant fields. |
| `conversion_status` | string ("all" | "pending" | "converted") | No | Conversion state to include. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Track Participant Conversion

**Slug:** `VIRAL_LOOPS_TRACK_PARTICIPANT_CONVERSION`

IRREVERSIBLE: Record a conversion event for one registered participant. This operation cannot be undone and may affect conversion counts, campaign automation, and rewards. It is available only for Milestone Referral, Altruistic Referral, Online to Offline, and Universal Referral campaign templates; other templates reject it. Identify the participant by exactly one email or referral code, and optionally attach a numeric conversion value.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `email` | string | No | Participant email selector; provide exactly one of email or referral_code. |
| `value` | number | No | Numeric value associated with this irreversible conversion event. |
| `referral_code` | string | No | Participant referral-code selector; provide exactly one of referral_code or email. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Update Participant

**Slug:** `VIRAL_LOOPS_UPDATE_PARTICIPANT`

Update one participant's name, referral or conversion counts, or custom data, identified by email or referral code. Campaign emails and connected integration triggers default to off; when enabled, those side effects cannot be undone.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `email` | string | No | Participant email selector; provide exactly one of email or referral_code. |
| `last_name` | string | No | New last name; explicitly pass null to clear the stored value. |
| `extra_data` | object | No | Campaign-specific custom participant fields to merge into existing data. Omitted existing keys are retained. |
| `first_name` | string | No | New first name; explicitly pass null to clear the stored value. |
| `send_emails` | boolean | No | Whether this update may send campaign emails. Defaults to false. |
| `referral_code` | string | No | Participant referral-code selector; provide exactly one of referral_code or email. |
| `referral_count` | integer | No | New non-negative referral count to store for the participant. |
| `conversion_count` | integer | No | New non-negative conversion count to store for the participant. |
| `trigger_integrations` | boolean | No | Whether this update may trigger connected integrations. Defaults to false. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |