# Welcome to the Support Center A quick overview of ReferralHero and our Support Center [ReferralHero](https://referralhero.com/) is a powerful referral marketing platform that allows you to design, build, and run sophisticated referral programs to acquire new customers through **word of mouth**. This is our support center where you can find step-by-step install instructions and answers to FAQs. Try searching by keyword in the top right corner of this page to find something specific. You can always contact us directly at if you can't find something or need further assistance. ### How to integrate ReferralHero on your website or app ReferralHero offers flexible integration options for your website, web app, or mobile app. You can quickly set up using our embeddable widgets or choose our APIs and SDKs for more advanced customization. Most customers will find our embeddable widgets easy to implement, with little to no technical expertise needed. If you prefer to track your own forms or checkout flow on your website while ReferralHero manages the backend of your referral program, that’s also an option! For more advanced or customized solutions, our Javascript Web APIs, REST APIs, and SDKs provide the flexibility to build a fully tailored referral program, though some technical expertise is required. If you'd like us to handle these advanced integrations, feel free to reach out at for installation pricing. Let's get started... ### Live examples We've created live pages showcasing various referral campaign examples using our embeddable widgets to help you visualize how ReferralHero would appear on your site or web app.[‍](https://example-4.referralhero.com/) * [Startup Referral Program Example ](https://startup.referralhero.com/referral-program)(e.g. Refer 1 Lead -> Get $25, Refer 1 Customer -> Get $100) * [‍](https://example-2.referralhero.com)[Web App/Portal Example](https://webapp.referralhero.com/auth/login) (e.g. Login to Access, Get $50 Credit)[‍](https://example-2.referralhero.com/) * [Offline Business & Service Referral Program Example](https://offline.referralhero.com/referral-program) (e.g. Give a Free Month, Get $50 Cash)[‍](https://example-1.referralhero.com/) * [Waitlist & Contest Example](https://waitlist.referralhero.com/) (e.g. 1st place wins an iphone, etc.) *\* Please bear in mind that these are just examples and are by no means indicative of all the ways in which ReferralHero can be customized.* # Common Questions This page collects the most popular questions about ReferralHero. ## How to add a subscriber or referral manually? To add a subscriber or a referral manually to your campaign: * go to your campaign dashboard *> Subscribers* * Click the **+Add Subscriber** button in the top right corner * In the modal enter the subscriber's information, like the email address and name * Click **Add Subscriber**
To add a referral make sure to enter the referrer's email address or referral code in the **Referrer** field. (If you're adding ** who has been referred by **, make sure to enter <_john.doe@email_.com> in the Referrer field)
## Can I use my own signup / opt-in form? Yes! ReferralHero is a very dynamic software solution. You have a few options for using your own signup form and ReferralHero as your backend to power your referral program. You might want to use your own sign up form if you are looking for a more custom branding experience or want to collect additional opt-in user data than the ReferralHero widget can offer. Here are your options for using your own signup form: 1. Use your current CRM signup form and connect to ReferralHero using our native Zapier connection. Follow these instructions for Hubspot or [Mailchimp](/campaign-builder/integrations/mailchimp#how-to-use-a-mailchimp-signup-form). These are just examples; you can connect any CRM form to ReferralHero, and the connection process would be very similar. 2. Use a signup / survey widget and connect to ReferralHero using our native Zapier connection. Follow these instructions for [Typeform](/campaign-builder/integrations/typeform). This is just an example; you can connect any signup widget to ReferralHero, and the connection process would be very similar. 3. Build your own signup form using HTML / JavaScript and connect to ReferralHero with our [Javascript API](/integrate/javascript-web-api) or [REST API](/integrate/rest-api) (this option provides the most flexibility but requires technical knowledge). ## How does the ranking work? ReferralHero's ranking system is pretty simple. In a nutshell, ReferralHero offers two types of campaigns: points-based and referral-based. The ranking system is determined based on either the number of points or the number of referrals. This means that subscribers can be ranked and positioned in the leaderboard based on their accumulated points or the number of successful referrals they have made. Let's consider a points-based campaign as an example: * Sarah has 11 points * Tom has 8 points Sarah will be 1st on the list and Tom 2nd. #### What happens if multiple people share the same number of points? When multiple people share the same number of points, we look at when they signed up; the earlier, the better. For example: * Sarah has 11 points and signed up on Monday * Tom has 8 points and signed up on Wednesday * Mark has 8 points and signed up on Tuesday. Tom and Mark both have 8 points, but Mark signed up before Tom. So this is the ranking: 1. Sarah 2. Mark 3. Tom #### How many positions do I gain when a subscriber gains another point/refers a new person? Given the architecture of our referral system, it’s impossible to answer this question. An example will illustrate this. Continuing with our example, let's say Mark gains another point, bringing his total to 9 points. However, despite gaining points, Mark doesn't move up in the ranking because Sarah still has 11 points. This illustrates that earning a certain number of points doesn't automatically guarantee a higher position on the leaderboard. However, it also means that no one is ever truly out of the game, as there are opportunities to earn more points and improve their ranking. Consider this scenario: In a list of 1,000 subscribers, some have earned one point, some two, and some none. Now, a new person signs up and earns three points. This person now has the most number of points in the campaign and jumps to the top of the list, surpassing the 1,000 subscribers ahead of him despite being the last to sign up! #### To assign points in your campaign, follow these steps: 1. Go to your campaign dashboard > Edit Campaign > Goal > Conversion Events and Social Share Actions to enable a points-based campaign 2. In the campaign dashboard, go to Points to assign points for conversion events and/or points for social share actions #### Motivation Prompt for Inviting Friends Utilize the Motivation Prompt feature within the Dashboard Widget > Dashboard to inspire your subscribers to invite friends and elevate their ranking on the leaderboard. By inviting friends to join the campaign and accruing additional points, they can ascend to higher positions, enhancing their chances of securing the top spot. Here's how it works:
**Earn %x% points and jump to %jump\_position% position** Subscribers earn points for each friend they successfully invite to join the campaign. Upon earning an additional %x% points, they leap to the %jump\_position% position on the leaderboard. The more friends they invite, the greater their likelihood of climbing the ranks. Similarly, in referral-based campaigns, for every %x% successful referral, they progress to the %jump\_position% position. ## **How can a subscriber in my campaign see the status of their referrals?** Directly on the share widget. When building your campaign, you have the option to show or not show the *leaderboard*, *people referred*, and/or their *position* on the share widget. * Go to your campaign dashboard > Edit Campaign > Widget Builder > Dashboard Widget > Dashboard to customize the look and feel of your share widget
In addition, if you choose to *show reward images,* when a member unlocks a reward, the reward box will be grayed out and display "unlocked" as default.
Subscribers have a few way of accessing the share widget: 1. Directly after they sign up (this happens by default but you can also [do a redirect](/common-questions#how-do-i-redirect-users-to-a-different-page-after-sign-up) to a different page) 2. Automatically when they revisit your landing page Go to your campaign dashboard > Edit Campaign > Widget Builder > Dashboard Widget > Dashboard > Template Settings > Advanced Options and switch on **Open sharing screen if already signed up** 3. Check Status button on the Dashboard Widget Signup Form Go to your campaign dashboard > Edit Campaign >Widget Builder > Dashboard Widget > Signup Form, click on the ‘*Form Submit Button*’, in the '*Property Options'* tab, customize the text for the login button
## Can I install multiple Tracking Codes on my website? Depending on the date your account was created. Please email into if you want your account updated. * For accounts created before March 1, 2024: You need to install multiple global tracking codes on your website to run multiple campaigns. * For accounts created after March 1, 2024: You will only need to install the single global tracking code once on your website. ## Does ReferralHero support all languages? Yes. Depending on your needs, you can accomplish this in two different ways: 1. Edit the text of any campaign to the desired language. 2. Set up multiple campaigns for each language. It is not possible for a campaign to switch between multiple language selections. ## How do I change the referral links of existing subscribers? There could be many reasons why you want to change the referral links of your subscribers: * you put the widget on the wrong page by mistake * you have changed landing on your website * you have changed your website URL Whatever the reason, to update the URL of the referral links: 1. Go to your campaign dashboard > Edit campaign > Options 2. Enter the new URL in the Default Referral Link field. It must be a valid URL (eg: `https://mywebsite.com/refer-a-friend`, with http or https) 3. Click Save 4. A popup will appear. Choose your desired option to either “set as default for new” or “reset & set as new” 5. The referral link will be updated according to your selection
## How do I redirect users to a different page after sign up? You can redirect people to a separate page instead of displaying the sharing screen. Go to your campaign dashboard *>* Edit Campaign *>* Widget Builder > Dashboard Widget > Signup Form > click on ‘*Form Submit Button*’ > go to ‘*Property Options*’ > switch on ‘Redirect after sign up’ > enter a ‘Redirect URL
When you enable this option, people who sign up through one of our embeddable widgets will be automatically redirected to the URL you entered. To make it easy to know WHO has been redirected to that page, ReferralHero adds some parameters to the URL. They are: | Parameter | Description | | ----------------------- | ------------------------------------ | | **rh\_email** | The subscriber's email address | | **rh\_name** | The subscriber's name | | **rh\_extra\_field** | The subscriber's extra field value | | **rh\_extra\_field\_2** | The subscriber's extra field 2 value | | **rh\_code** | The subscriber's referral code | #### Displaying referral links A common use case is to redirect a person to a page and show them their referral link. There are two ways to achieve this: 1. **Use ReferralHero's widget**\ Just embed the ReferralHero widget on the destination page and make sure to switch on **Open sharing screen if already signed up** in Edit campaign > Widget Builder > Dashboard Widget > Dashboard > Template Settings > Advanced Options 2. **Use "rh\_code" parameter**\ If you have some coding skills, simply grab the `rh_code` parameter from the URL and use it create the referral link. Remember that a ReferralHero-valid referral link must use the `mwr` parameter in the URL. So for example, if you want to create a referral link that points to `https://mywbesite.com`, your referral link will be `https://mywbesite.com?mwr=`**`{rh_code}`** ## How do I test and review my campaign? To test your referral journey and all conversion events please take note of the following points and then follow our step-by-step process: **Important:** * You must clear your cookies or spin up a new incognito window every time you want to sign up (as a referral or non-referral). * You cannot have any other open browsers/windows/tabs to your website (otherwise you will still be cookied). {% hint style="success" %} We have these measures in place to prevent fraud (and we are very good at detecting it) so you need to avoid our anti-fraud system while you test. {% endhint %} **Process:** 1. Sign up as an non-referral and get your referral link from our Dashboard Widget or your subscriber list 2. Check ReferralHero subscriber list to make sure a new non-referral was created 3. Close out of any open browsers/windows/tabs to your website 4. Open a new incognito window, paste your referral link in the web address bar, and load the page 5. Check ReferralHero visitor list to make sure a new referred visitor was created 6. Browse your website and navigate to your first conversion event (ie. signup form, book meeting form, etc.) 7. Sign up and submit the form 8. Check ReferralHero subscriber list to make sure the referred visitor converted to a new referral * *If your Campaign Goal is set up to track one conversion event, the referral will be set to Confirmed.* * *If your Campaign Goal is set up to track two or three conversion events, the referral will be set to Pending.* 9. (If applicable) Proceed to trigger the second conversion event. * *If your Campaign Goal is set up to track two conversion events, the referral will be set to Confirmed.* * *If your Campaign Goal is set up to track three conversion events, the referral will be set to Unconfirmed.* 10. (If applicable) Proceed to trigger the third conversion event. * *If your Campaign Goal is set up to track three conversion events, the referral will be set to Confirmed.* ## How do I customize the CSS of the embeddable widgets? ReferralHero's embeddable widgets automatically use the font set for the parent container, however sometimes this means that the wrong font is used. To change the font of the widget, you have two options: 1. Change the Font Family in each individual design element, e.g. text element, etc, you use in the widget design. 2. Within the widget builder, the property options for each element give access to change the font, size, and style of any text. 3. Go to you campaign dashboard > Edit Campaign > Widget Builder > 'Signup Form' or 'Dashboard' > Template Settings > Custom CSS. \ For example, you can enter the following text to make font customizations: ```css #mtr-optin-form *, #mtr-sharing-screen * { font-family: 'Nunito' } ``` Don't forget to change 'Nunito' with the font-family you want to use. [Click here](https://github.com/maitre-app/style.css/blob/main/example) to see other stylizing options you can customize with CSS. # Templates # Affiliate Program The Affiliate Program template helps you set up a campaign where affiliates (partners, influencers, or content creators) promote your business and earn rewards for driving conversions. It’s designed for structured partnerships with a performance-driven focus. ### Campaign Goals Affiliate Programs support one goal type: * **Conversion events** – Reward affiliates when their referrals complete your defined conversion goal(s). Example: affiliates earn commission when referred customers make a purchase
### Participation Rules In an Affiliate Program, the admin controls whether referrals receive affiliate privileges. **Admin can choose to:** * Convert referrals to affiliates (manually or automatically) so they can generate their own referral link * Keep referrals as customers only, without affiliate privileges {% hint style="success" %} **NOTE:** You can add referrals to a secondary campagin (most commonly a referral campaign) with the “Add referred subscribers to a second campaign” option. This allows referrals to automatically join a campagin of their own (with different rules) and start referring! {% endhint %} **For referrals without affiliate privileges:** * Their profile shows no referral code and no referral link * Admin sees a **Convert to Affiliate** button to upgrade them at any time
**Referrals can become affiliates in two ways:** 1. Manual conversion by the admin using the **Convert to Affiliate** button 2. Self-activation by completing the **Advocate Dashboard widget** (if already in the campaign or cookied) 👉 If a referral without affiliate privileges tries to log in to the Advocate Dashboard widget, they will see this error: *"You are currently not an advocate for this campaign. Please sign up or contact the campaign manager for access."*
### Widgets & Activation ReferralHero provides three widgets for Affiliate Program campaigns: * **Advocate Dashboard widget** – For affiliate signup, login, and management * **Signup widget** – A customizable signup form to capture referrals * **Referral Welcome Banner** – A banner-style signup option to engage referrals **In Affiliate Programs:** * If a referral fills in the **Advocate Dashboard widget**, they are automatically converted into an affiliate (referral link created, affiliate automations triggered) * Automatic conversion does **not** occur through the **Signup widget** or **Referral Welcome Banner** ### Rewards * Supports the following reward types: Conversion Bonuses, Rewards for Advocates, and Manual Rewards * Does not support the non-referral Signup Bonus * Conversion Bonuses can only be configured for referrals
### Automations Affiliate Programs support most automation flows, except: * **Welcome Flow → Activation email/SMS** is not available ### When to Use Use the Affiliate Program template if you want to: * Build a structured network of affiliates, partners, or influencers * Reward affiliates strictly based on conversions * Control whether referrals themselves can become affiliates * Manage affiliate activation more carefully compared to open referral programs ### Key Features Alongside features available in all templates (e.g., customizable rewards, automated tracking, double-sided rewards), Affiliate Programs offer: * **Performance-driven structure** – Rewards are tied only to conversions * **Admin-controlled referral rights** – Decide if referrals can be converted into affiliates * **Controlled activation** – Only the Advocate Dashboard widget triggers automatic affiliate activation * **Manual conversion option** – Admin can upgrade referrals to affiliates at any time with the Convert to Affiliate button * **Cross-campaign flexibility** – When the **“Add referrals to a second campaign”** option is enabled, referrals are automatically added to the selected secondary campaign when the defined conversion event is met. In the secondary campaign, they are added as non-referrals
# Referral Program The Referral Program template helps you create a campaign where existing customers (advocates) refer new people to your business and receive rewards. It’s designed to drive growth through trusted recommendations while automatically tracking performance. ### Campaign Goals
Referral Programs support two goal types: * **Conversion events** – Reward advocates when their referrals complete your defined conversion goal(s). Example: reward an advocate when their friend signs up or makes a purchase * **Conversion events + Social actions** – Reward advocates with points both for completing social actions and when their referrals complete conversion goals. Example: advocates earn points for sharing on social media, plus rewards when referred friends convert ### Participation Rules * All participants automatically become advocates * Each participant receives a unique referral link to share * Referrals can also become advocates, continuing the cycle of sharing
### Widgets & Activation ReferralHero provides three widgets for Referral Program campaigns: * **Advocate Dashboard widget** – Advocates can sign up or log in, access their referral link, and track progress * **Signup widget** – A customizable signup form to engage new subscribers and automatically add them as advocates * **Referral Welcome Banner** – A banner-style signup option for embedding on your website to encourage participation **In Referral Programs:** * Anyone who signs up through **any widget** is immediately activated as an advocate * No additional activation steps are required ### Rewards * Supports all reward types: Conversion Bonuses, Rewards for Advocates, Rewards for Subscribers, and Manual Rewards * Includes non-referral Signup Bonus: Non-referrals can be rewarded upon signup, even if they were not referred *(Not available in Affiliate Programs)*
### Automations * Supports all automation flows * Includes Welcome Flow > Activation email/SMS: This message is sent to subscribers who have joined but have not yet referred anyone, reminding them about the campaign and motivating engagement *(Not available in Affiliate Programs)*
### When to Use Use the Referral Program template if you want to: * Grow your customer base organically through referrals * Encourage sharing across social media and personal networks * Incentivize both engagement and conversions * Run either a continuous or time-limited program ### Key Features In addition to features available in all templates (e.g., customizable rewards, automated tracking, double-sided rewards), Referral Programs include: * **Flexible goal options** – Conversions only, or conversions plus social actions * **Automatic advocacy** – Every participant receives a referral link * **Non-referral Signup Bonus** – Reward for non-referral signups * **Welcome Flow** – Automated email/SMS for inactive advocates # Contest You can add contest functionality to any of your ReferralHero campaigns. This allows you to: * Reward top advocates * Select random winners (see section: Select Random Contest Winners) * Issue manual rewards for any reason These functionalities are available depending on the template you've selected for the campaign.\ If you're using the Waitlist & Contest template, all contest features are enabled by default. For Affiliate Program, Referral Program, or Custom templates, you'll need to toggle Manual Rewards ON in the Rewards section to use these features.
FeatureAffiliate, Referral Program or CustomWaitlist & Contest
Reward top advocatesAvailable when Manual Rewards is toggled ONON by default
Select random winnersAvailable when Manual Rewards is toggled ONON by default
Issue manual rewardsAvailable when Manual Rewards is toggled ONON by default
## Manual Rewards for Promoted Winners A manual reward can be triggered when you promote a subscriber through the ReferralHero dashboard or API. To set up a manual reward: 1. Go to Edit Campaign > Rewards > Toggle ON Manual Rewards > Click Add Reward
2. Assign a name (this field is required — leaving it blank will result in a “can’t be blank” error), label, and description to the reward 3. You have the option to set the subscriber’s rank to the last position after promotion **Example:** If you run a weekly competition where the top 5 subscribers on the leaderboard win a reward, and you've enabled the setting to move promoted subscribers to the last position: * Promote the top 5 winners using the dashboard or API * Their ranks are automatically moved to the last positions * In the second week, a new set of top 5 winners can be selected * The previous winners no longer occupy top spots but can still refer others, earn points, and unlock milestone rewards This feature helps maintain fairness and ongoing engagement — without needing to delete past winners from the campaign.
## Promoted Reward Email Notification 1. Turn on the ‘Notify subscriber when this reward is sent’ toggle in the reward setup to send an email notification to the subscribers
2. Go to Edit Campaign > Automations > Reward Emails/SMS Messages 3. Locate the email/SMS for this particular reward 4. Customize the email/SMS 5. Toggle ON the email/SMS and save the changes
## Select Random Contest Winners ReferralHero utilizes the ‘Pickup’ Ruby Gem to choose winners for your contest campaigns. This Gem enables the selection of a winner from the subscriber list with different probabilities based on the number of points/referrals assigned to them. Subscribers with higher point/referral values have a higher chance of being chosen. {% hint style="success" %} **NOTE:** In 'Conversion Events' campaigns, the probability of winning is based on referrals. In 'Conversion Events and Social Share Actions' campaigns, the probability of winning is based on points. {% endhint %} **Example:** > 1\. SubA - 3 points (The chance of SubA to pick is 30% (3/10 \* 100))\ > 2\. SubB - 4 points (The chance of SubB to pick is 40% (5/10 \* 100))\ > 3\. SubC - 2 points (The chance of SubC to pick is 20% (2/10 \* 100))\ > 4\. SubD - 1 point (The chance of SubD to pick is 10% (1/10 \* 100)) > > They make a collection like,\ > \[SubA, SubA, SubA, SubB, SubB, SubB, SubB, SubC, SubC, SubD] The collection is a list that contains four different subscribers (SubA, SubB, SubC, and SubD), each with a different number of points they’ve accumulated. The percentages provided for each subscriber represent the probability of that subscriber being chosen at random from the list. SubA has a 30% chance of being chosen because it has three points, which is 30% of the total points (10) in the list. Similarly, SubB has a 40% chance of being chosen because it has four points, which is 40% of the total points in the list. ## Promote Subscribers There are three ways to promote subscribers: {% hint style="success" %} **NOTE:** * Only subscribers in a Contest or contest-feature enabled campaign with at least one manual reward created can be promoted. * If you have multiple manual rewards set up, it's possible for a subscriber to be promoted multiple times, potentially winning different rewards on separate occasions. {% endhint %} ### Method 1: Pick Winners Randomly 1. In the Subscribers list, check the box next to the subscribers who are qualified for the promoted reward. This will activate the “**Pick Winner**” button
2. Click the **“Pick Winner”** button to open a modal popup with a randomly selected winner
3. To choose a different winner, click the **“Pick new winner”** button to generate a new random selection 4. From the reward dropdown, select the reward you want to assign to the promoted winner 5. Click the **Promote** button to apply the reward ### Method 2: Bulk Promote a Set of Subscribers 1. In the Subscribers list, check the boxes next to the subscribers who are qualified for the promoted reward. This will activate the **“Promote”** button
2. Click the **“Promote”** button to open the **“Reward for Winners”** popup
3. Select the reward you want to assign to the selected subscribers 4. Click **“Promote”** ### Method 3: Promote a Specific Subscriber 1. Go to the subscriber's profile 2. In the **Campaign Info** section, click the three-dot dropdown 3. Select **“Promote”**
4. In the **“Reward for Winners”** popup, select the reward 5. Click **“Promote”** ### Unpromote Option 1. Once a subscriber is promoted, an **“Unpromote”** option will appear in the three-dot dropdown of the **Campaign Info** section within their profile
2. Unpromoting a subscriber will remove them from the Promoted list and place them back into their original position on the Subscribers list. {% hint style="warning" %} **NOTE:** You won’t be able to cancel the rewards that were sent to subscribers when they were promoted. {% endhint %} ## Promoted Subscribers List To view the list of promoted subscribers, select “Promoted” under the Group filter.
All promotions / unpromotions will be recorded in the subscriber’s Timeline Log.
# Website Referral Analysis ReferralHero's Website Referral Analysis uses our proprietary algorithm to accurately track and analyze unique visitors to your website. It automatically identifies advocates and referrals, providing deep data insights into naturally occurring referrals and showcasing the significant impact of word-of-mouth on your business. This tool provides the following benefits: * Automatically identify potential advocates * Automatically track the volume of referrals coming to your website * Automatically know what web pages get shared the most {% hint style="success" %} Note: If an active visitor is identified as a subscriber at any time, their profiles are matched and merged. {% endhint %} ## Active Visitor Profiles When the Website Referral Analysis feature is enabled, each website visitor will appear as either a Referred Visitor or a Non-Referred Visitor, depending on how they arrived at your site. **Referred Visitor** Referred visitors are users who arrive via a referral link. These profiles can be viewed in the Subscribers list by using the Group filters to segment by subscriber type.
**Non-Referred Visitor** Non-Referral Visitors are users who arrive without a referral link. A dedicated **Non-Referred Visitors tab** is available to view all non-referred visitors.
This view is only available when the **Display non-referred visitor profiles** toggle is enabled under the Launch settings in the Website Referral Analysis campaign.
## Implementing Website Referral Analysis It is recommended to run this tool by itself or alongside another one of ReferralHero’s growth tools. **Setting Up Website Referral Analysis** 1. Create a new campaign 2. Select the template “Website Referral Analysis”
3. Launch Settings 1. Install the ReferralHero global tracking code in the header of your website. 2. **Apply referral tracking to all website visitors** setting**:** 1. Enable this setting to apply referral tracking logic to every visitor on your website—even if they didn’t land via a referral link. 2. This feature automatically identifies advocates and referrals, offering deep data insights into naturally occurring referrals, such as when someone shares your website URL directly from their browser. 3. The Cookie Window determines how long a visitor cookie remains valid. By default, this is set to 90 days, meaning the unique visitor will be tracked for up to 90 days after visiting your website. {% hint style="success" %} Note: For accounts created after Feb 28 2024, you only need to install the global tracking code once. Skip this step if it has already been added to your website header. {% endhint %} **Scenario Overview 1** 1. A visitor arrives at your website without a referral link and is created as a non-referred visitor in the Website Analysis campaign. 2. The non-referred visitor signs up for your referral campaign, becoming a non-referral subscriber in the referral campaign. 3. They share their referral link with friends. 4. When a friend visits your website via the referral link, a referred visitor profile is created in the referral campaign. 5. The referred visitor signs up, converting into a referred subscriber in the referral campaign. **Scenario Overview 2** 1. A visitor arrives at your website without a referral link and is created as a non-referred visitor in the Website Analysis campaign. 2. They copy your website URL and share it with friends. 3. A friend visits your website via the shared link and is created as a referred visitor in the Website Analysis campaign. 4. The non-referred visitor later signs up for your referral campaign, becoming a non-referral subscriber in the referral campaign. 5. The referred visitor signs up, converting into a referred subscriber in the campaign. ## Remove MWR from Google Analytics Reports The unique MWR associated with each referral link can result in distinct values appearing in different columns within Google Analytics reports. Fortunately, Google Analytics provides an option to exclude URL parameters, ensuring a cleaner and more streamlined presentation of your data in the reports. {% hint style="warning" %} **NOTE:** This exclusion applies to future data tracked by Google Analytics and does not affect existing reports or page URLs that already have an MWR parameter attached. {% endhint %} **Steps to Remove MWR from Google Analytics Reports:** 1. In your Google Analytics account, navigate to the “Admin” section. 2. Under the View column, access "View Settings". 3. Locate the “Exclude URL Query Parameters” option and enter “mwr”. 4. Click on the Save button to apply the exclusion, and you're all set. # Net Promoter Score ReferralHero's Net Promoter Score feature streamlines the creation and management of NPS campaigns. With a dedicated template and an intuitive campaign builder boasting enhanced editing capabilities, our aim is to effortlessly collect valuable feedback from subscribers. This documentation provides a guide through the setup and customization of the NPS within ReferralHero. ## Implementing Net Promoter Score Make the NPS experience unique to your brand by customizing survey questions, appearance, and timing: 1. Create a new ReferralHero campaign 2. Select the “Net Promoter Score” template
3. Encourage participation by offering rewards for completing NPS. Set up enticing incentives to express gratitude to your subscribers for taking the time to provide valuable feedback
4. Access the NPS customization settings in Widget Builder. Edit the survey question to align with your brand voice. In addition to measuring customer perception based on one simple question — "How likely are you to recommend us to a friend or colleague?" — ReferralHero allows you to collect answers to an additional question of your choice and then display a thank-you message.
5. Effortlessly incorporate NPS surveys into your communication strategy by leveraging ReferralHero's advanced email automation features. This seamless integration ensures timely and consistent prompts for subscribers to complete the NPS survey, contributing to a smooth and effective feedback collection process.
6. ReferralHero empowers you to gather ongoing insights by allowing you to collect and request NPS multiple times.
# Goal # Goal Type ReferralHero supports two primary goal types. Choosing the right one depends on whether you want to reward advocates strictly for conversions or encourage additional engagement through a points-based system. ## **Conversion Events only** Use a **referral-based system** to reward advocates when their referrals complete a key action—such as signing up, making a purchase, or booking a demo.
Example: \ Jane refers Tom. Tom signs up for a webinar. Jane earns a reward. ## **Conversion Events + Social Actions** Use a **points-based system** to reward advocates for both referral conversions and extra actions, such as: * Sharing your campaign * Joining your social accounts * Earning points from multi-level referrals Advocates accumulate points and unlock rewards as they hit specific thresholds.
{% hint style="success" %} **NOTE:** When this goal type is selected, an additional section called **“Points”** appears in the campaign builder side menu. This is where you define how many points each action is worth. {% endhint %} Example:\ Jane earns: * 10 points for referring a paid customer * 10 points for joining your Telegram group * 5 points when her level-two referral signs up Jane’s points accumulate and unlock rewards as she reaches certain thresholds. #### **What This Affects:** 1. How rewards are triggered 1. **Referral-based goal:** Rewards are triggered when a referred user completes a key conversion action (e.g., signup, purchase) 2. **Points-based goal:** Rewards are unlocked when an advocate accumulates enough points from referrals and/or social actions 2. What subscribers see 1. **Referral-based goal:** Dashboards show the number of successful referrals 2. **Points-based goal:** Dashboards display accumulated points, and available actions to earn more points
{% hint style="warning" %} **Important:** Once a campaign is launched, changing the goal type may reset your subscribers’ progress. Make sure to choose the right type based on your campaign objectives. {% endhint %} # Conversion Events & Labels Conversion events represent the key actions in your referral journey. ## How Many Conversion Events Do You Want to Track? In ReferralHero, you can track up to three conversion events and assign clear labels to each one. Each conversion event progresses through the following linear stages.
#### **One Event** Track a single key action, such as: * Signing up for your newsletter * Joining a waitlist * Creating an account **Best for:** Simple campaigns focused on one primary conversion. #### **Two Events** Track a two-step journey, such as: * Signing up → Making a purchase * Registering → Attending a webinar **Best for:** Campaigns where a meaningful action follows the initial signup. #### **Three Events** Track a full customer journey, such as: * Signing up → Attending a demo → Purchasing a plan * Registering → Completing onboarding → Subscribing **Best for:** More complex funnels, especially in SaaS or B2B with multiple engagement points. ## **Label Each Conversion Event** Once you’ve selected how many events to track, assign a short and descriptive label to each one. These labels appear in your dashboard and are used throughout your campaign setup. **Examples:** * “Signed Up” * “Attended Webinar” * “Purchased Plan” * “Upgraded to Pro” Labels are used in: * **Analytics** – Track how users move through your funnel
* **Automations** – Trigger emails, webhooks, or SMS when a specific event is completed
* **Reward Tracking** – Issue rewards only when subscribers hit specific milestones
{% hint style="success" %} **Tip:** If you're using integrations like API, Zapier, or webhooks, match your event labels to your actual event names or property values. {% endhint %} ## **Unqualified Status** Referrals can be marked as **Unqualified**, a non-linear status that sits outside the standard conversion flow and does not follow the usual Pending → Unconfirmed → Confirmed progression. This status is used to identify referrals that should be excluded from progression through the standard funnel stages (for example: invalid, spam, or disqualified leads). Referrals can be moved to **Unqualified** from any stage and restored to their original stage. The label for this status can be customized (e.g. “Disqualified”, “Invalid Lead”).
{% hint style="info" %} **NOTES:** * Marking a referral as **Unqualified** does not affect analytics calculations: * Referral counts remain unchanged * Original conversion events are preserved * Unqualified referrals remain part of the referral system and may still be included in reward evaluation logic, depending on campaign configuration. {% endhint %} ### **Managing Unqualified Referrals** #### **Moving Referrals to Unqualified** Referrals can be marked as **Unqualified** through: * Manual updates in the admin dashboard * Bulk updates via CSV import * REST API * HubSpot integration * GoHighLevel integration * Zapier integration #### **Restoring Referrals** Referrals marked as **Unqualified** can be restored to their previous progression stage. When restored, the referral resumes its original stage. Restoration is available via: * Admin dashboard * REST API * Zapier integration
## **Referral Status** Each subscriber’s progress is automatically reflected in their **Referral Status**, which updates as they complete each event. This status determines when rewards are issued to the advocate. ✅ Learn more in the [Referral Status](https://support.referralhero.com/campaign-management/subscribers/subscriber-profile#referral-status) section. # Goal Settings ## Referral Conversion Value The Referral Conversion Value represents the revenue associated with a **confirmed referral** and is used as the default for each referred subscriber’s: * Conversion Value * Lifetime Spend
#### How It Works The value entered here sets the default conversion value and lifetime spend unless the subscriber’s values have already been set by: * An integration (e.g., Stripe, Hubspot) * The API * Manual updates via the Transactions section If any of these sources have already populated a subscriber’s `conversion_value` or `lifetime_spend`, this default value **will not overwrite** them. #### Updating the Default Value You can update this value at any time by editing the input field. When updated: * Any subscriber **without an overridden** conversion value or lifetime spend will be updated with the new default. * Subscribers **with existing values** from integrations, API, or manual transactions **will remain unchanged**. ## Memorable Referral Links By default, the referral links generated by ReferralHero are random alphanumeric strings like **d22c0810**. Wouldn't it be cool if you could use the subscriber's name to make the referral link more memorable? Something like **james23b**, for example? Luckily you can do that with just one click.\ Ok, that's a lie. It's actually two clicks. 1. Go to your campaign dashboard *> Edit Campaign > Goals*
2. Switch on **Use name to generate referral link** (first click) 3. Save the changes (second click) After you enable this feature, referral codes will be generated using the subscriber's first name and a random 4 digits string (to assure uniqueness). For example: * Subscriber's name: "James", Subscriber's referral code: "james7d52" * Subscriber's name: "Tim Fletcher", Subscriber's referral code: "tim1a54" ReferralHero **will NOT** use the subscriber's name and revert to the standard random string if: 1. a name is not present (obviously) 2. the name is less than four characters long (e.g: Tim or Sam) For example, a subscriber whose name is Bo Charleston will get a standard referral link of random characters. # Unique Identifier This is a very unique feature of ReferralHero. When you are setting up your campagin, you can select a unique identifier for your subscribers. Here are a few important things to know: * The unique identifier will be the ID we use to reference and add subscribers to your campagin * The unique identifier type cannot be changed after a subscriber has been added to your campaigns * The unique identifier is a required field in our Widget and APIs * The unique identifier requirement can only be bypassed when subscribers are created manually on the dashboard ### Selecting a Unique Identifier Type * [Email](/campaign-builder/unique-identifier/confirmation-email) * [Phone Number](/campaign-builder/unique-identifier/phone-number-verification) * Web3 Wallet Address * Other (customer ID, social media handle, etc.)
### Verifying the Unique Identifier After selecting a unique identifier, you will want to consider enabling the verification method. Subscriber verification is important for security reasons to ensure only real people are signing up for your campaign. These are your options: | Verification Options | Verification Behavior | | -------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Require Verification | The subscriber will be considered verified and added to your campaign only when the unique identifier is confirmed. | | Require Primary and [Secondary Verification](/campaign-builder/unique-identifier/sms-verification) | The subscriber will need to first confirm the primary verification method and then the secondary verification method (the subscriber will be considered verified and added to your campaign only when both are confirmed). | | Disable Verification | No verification method will be triggered, the subscriber will be added without any verification | If you choose to verify the unique identifier. Please read additional material on your selection: * Email Verification: [Sending the confirmation email](/campaign-builder/unique-identifier/confirmation-email) * Phone Number Verification: [Sending an SMS message](/campaign-builder/unique-identifier/phone-number-verification) * Crypto Wallet Address Verification: [Connecting crypto wallets](/campaign-builder/integrations/blockchain#crypto-wallet-address-verification) #### Phone Number Verification Behavior When phone number verification is enabled: * Invalid phone numbers are rejected during signup * Only valid phone numbers are accepted * SMS messages are only sent to valid phone numbers When phone verification is not enabled: * Invalid phone numbers are accepted * No SMS messages are triggered for invalid numbers ### Verification Considerations Each unique identifier has an optional verification process that you can enable. When deciding to enable this feature, consider: | Verify | Not Verify | | -------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- | | You're running a contest | You're running a referral or affiliate program | | Assurance a valid unique identifier was provided | You have your process to verify the subscriber | | Protection against [spambots](https://en.wikipedia.org/wiki/Spambot), email scams, and fake subscribers. | Our anti-fraud algorithm will identify potential spam and fake subscribers | | It is a legal requirement in your country | This additional step can sometimes restrict referrals | | Archived record documenting the subscriber's consent | Verification can be enabled at any time during your campagin | # Email Verification Everything you need to know about the double opt-in process There are some important things around the confirmation email feature to think through as you have a few options for subscriber verification. Subscriber verification is important for security reasons to ensure only real people are signing up for your campaign. These are your options: 1. Require Confirmation Email: The subscriber will be considered verified only when the email is confirmed 2. Require Email and [SMS Confirmation](/campaign-builder/unique-identifier/sms-verification): Subscribers will need to first confirm their email address and then their phone number via SMS (the subscriber will be considered verified only when both are confirmed). 3. Disable Verification Method: No email confirmation will be sent. The subscriber will be added without any verification When you activate the email verification method in your campaign, we automatically send a confirmation email to those who sign up. This email serves as a verification step, ensuring the accuracy of their provided email address. This process is commonly known as "double opt-in".
### Email Verification Process When the "Enable Verification Method" option is toggled ON for the unique identifier Email, ReferralHero sends a confirmation email containing a 6-digit verification code. Here is how it works: * A confirmation email with the code is sent to subscribers * The subscriber must enter the 6-digit code on the signup verification page to verify their email address * The code is valid for 10 minutes from the time it is sent ### Require Repeated Verification for Untrusted Devices Enable this option to require repeated verification during signup or login for devices that are not recognized. When activated, subscribers signing up or logging in from an untrusted device will need to verify their identity again. This feature enhances security by preventing unauthorized access from unknown devices. ### Frequently Asked Questions #### Can I disable the confirmation email? While HIGHLY discouraged, it is possible to disable the confirmation email. Go to your campaign dashboard > *Edit Campagin > Unique Identifier* and disable the toggle "**Enable verification method**". #### Can I send the confirmation emails through my own ISP? At the moment it is not possible to use your own ISP to send the confirmation email. #### What happens if subscribers don't verify their email address? If a subscriber doesn't verify their email address within 10 minutes, they will need to request a new code. #### Some people are not verifying their email address This is normal and it will always happen. According to research (backed by big email companies, such as MailChimp), the average drop-off rate for confirmation emails is [between 10% and 25%](https://www.quora.com/What-is-a-typical-abandonment-rate-for-email-verifications). Yes, you read that right. Up to 1 out of 4 people will never bother to confirm their email address. Why would they do that? This is a true mystery, but there are possible reasons: people forget to check their inbox, signup for products they are not really interested in, the email goes to the spam folder, you name it. #### My confirmation emails go to the spam folder. How do I fix it? Sometimes, your confirmation emails will go to the spam folder. It's very annoying when it happens but the most important thing that you need to remember is that it's inevitable. No company in the world has 100% delivery rate in the primary inbox. Modern email providers like Gmail, Yahoo, Outlook use extremely sophisticated anti-spam algorithms that use hundreds of factors to determine whether an email is spammy or not. Because so many factors are involved, it's impossible to determine the exact reason for why an email is marked as spam; however, we do know that two of the most important factors are "domain reputation" and "account history". **Domain reputation** Domain reputation refers to the reputation of the sending domain, in this case, ReferralHero (since all emails are sent by us unless you specify a different sending address). To send emails, we utilize [Postmark](https://postmarkapp.com/), which is an email provider known for its track record of high deliverability rates. This, combined with the best practices that we implement, results in an overall deliverability rate for ReferralHero of over 98%, which is exceptionally high for the industry. **Account history** The real "beast" when it comes to spam filters is personalization, which means that spam filters adapt to the history of each person. For example, if you mark as spam or simply ignore a specific type of email (eg: invoices), email providers such as Gmail or Yahoo will think that you're not interested in this type of emails and/or will eventually mark it as spam. So if some of your users receive the confirmation emails in the spam folder, is highly likely that they have marked some confirmation emails in the past as spam, What you can do to improve your deliverability Unfortunately, there is not a lot that you can do, but here are some best practices. 1. Don't use "spammy" words in your confirmation email body and subject. Avoid words like "special", "free", "etc". Just stick to the default and you'll be fine. 2. Tell your users to add the sender address "**" to their trusted senders' list. When enough people do it, Gmail will figure out that your confirmation emails are not spam. 3. Use a company email address as the reply-to address. If you're using a free email provider (gmail, yahoo, outlook, etc) and sending transactional emails, spam filters will raise a red flag. Better to use your company email address instead. Go to your campaign dashboard > Settings > Emails. 4. Use a custom domain sender. Although our default sending domain has a very high reputation, you might benefit (not last from a branding point of view) by using your own sending domain address. To do so you must be on the Pro or Premium plan. [Get in touch with us](mailto:support@referralhero.com) to set it up. # Phone Number Verification Phone number verification helps ensure that real people — not bots or duplicate accounts — are signing up for your campaign. When enabled, ReferralHero sends a verification SMS with a 6-digit code that the subscriber must enter to confirm their phone number. You can use phone verification as your primary method (if phone number is the unique identifier) or as a secondary method for added security. {% hint style="warning" %} Any SMS verification usage will incur a pay-as-you-go charge of $0.15 per successfully verified phone number, billed weekly. {% endhint %} ### Activate SMS in Your Account Before you can enable phone number verification, SMS must first be activated in your account. To get started: 1. Email to begin your SMS application 2. Complete the short application form (we’ll send it to you) 3. Once submitted, we’ll begin the verification and setup process, which typically takes 1–7 days 4. Once approved, SMS will be activated in your account and you’ll be able to use phone number verification in your campaign ### Verification Options You can choose from the following: 1. Require SMS Confirmation: The subscriber will be considered verified only when they confirm their phone number via a 6-digit SMS code 2. Require Email and SMS Confirmation: The subscriber must confirm both their email and phone number to be verified 3. Disable Verification Method: No confirmation SMS will be sent. The subscriber will be added without verification ### Phone Number Verification Process When phone number verification is enabled, ReferralHero will send a 6-digit code to the subscriber’s phone number. How it works: 1. The subscriber enters their phone number during signup 2. A confirmation SMS with a 6-digit code is sent 3. The subscriber enters the code on the signup verification page 4. Once verified, they are added to your campaign The code is valid for 10 minutes. If not verified in time, the subscriber can request a new code. {% hint style="warning" %} **IMPORTANT:** * **Phone numbers must be entered in international format (e.g., +16572206234)** * Invalid or incorrectly formatted numbers are **rejected** during signup, and SMS messages are only sent to valid numbers. * If 1-click sign-up is enabled, your users who opt-in through 1-click sign-up will not be sent a confirmation SMS. * When using the API, if "double\_optin" is disabled, your users will not be sent a confirmation SMS. {% endhint %}
### Require Repeated Verification for Untrusted Devices Enable this option to require repeated verification during signup or login for devices that are not recognized. When activated, subscribers signing up or logging in from an untrusted device will need to verify their identity again. This feature enhances security by preventing unauthorized access from unknown devices. # Secondary Verification Method A secondary or 2-step verification method allows you to verify the primary [unique identifier](broken://pages/hUHz83Slaly02DIhm3xr) and a second verification method as an additional security measure. Please make sure you have read our FAQ on the [confirmation email feature](/campaign-builder/unique-identifier/confirmation-email) before proceeding. Typically only the primary unique identifier must be confirmed before the subscriber is considered verified. However, when you use this feature the subscriber must now confirm both primary and secondary methods before they are considered verified. You can use any combination of verification methods however, here is an example of how it works: 1. User signs up for your campaign by entering their email address and phone number 2. An SMS with a confirmation link is sent to the phone number provided 3. After the user confirms their phone number a confirmation email is sent 4. After the email address is confirmed, the user is verified Subscribers will be considered verified ONLY when both their phone number and email address are verified. ### Options for a Second Verification Method After selecting a [unique identifier](broken://pages/hUHz83Slaly02DIhm3xr), you can set the following as secondary verification methods. 1. Email. [See here](/campaign-builder/unique-identifier/confirmation-email) for more information. 2. Phone Number. [See here](broken://pages/vJwjGYbfPBP1VVIgU1jw) for more information. 3. Crypto Wallet Address. ### Enable a Second Verification Method To enable a secondary verification method you must do this from the Unique Identifier section. Go to your campaign dashboard > *Edit Campaign > Unique Identider >* and switch on the **Require a Second Verification Method**.
# Quick Add Referral Verification When using the [Quick Add referral](https://support.referralhero.com/campaign-management/subscribers/quick-add-referral) feature, new referrals can be required to verify their email and/or SMS before being officially added to your campaign. ### **What is Quick Add Referral Verification?** Quick Add Referral Verification requires referrals added by an existing subscriber to confirm their email and/or SMS before they are enrolled in your campaign. This helps you: * Avoid fake or mistyped contact entries * Ensure referrals are real and have explicitly opted in * Comply with privacy and anti-spam regulations ### **How to Enable the 'Quick Add' Invitation Email/SMS?** 1. Go to your campaign dashboard > Edit Campaign > Automations > Welcome Emails/SMS Messages 2. Locate 'Quick Add' Invitation Email/SMS 3. Customize the content of the email/SMS 4. Save the changes
{% hint style="warning" %} If this email is enabled, the referred subscriber **must** click the confirmation link before being added to your campaign. {% endhint %} ### **How Verification Works** 1. A current subscriber logs in to their dashboard and uses the Quick Add form to refer someone by entering their name, email, and/or SMS 2. If the **Quick Add Invitation Email/SMS** is enabled, an email or SMS is automatically sent to the referred person, asking them to confirm their details 3. The referral must click the confirmation link in the email/SMS to complete their signup and officially join your campaign 4. Once confirmed, the referral appears as a verified subscriber, and the advocate will receive rewards (if applicable) 5. If a referral remains unverified, the Quick Add Invitation Email/SMS will be triggered again after 6 hours ### **Thank You Page** When subscribers verify their email address, you have two options: 1. Display their dashboard (default behavior) 2. Send them to a custom thank you page {% hint style="success" %} This option is not available for Quick Add Invitation SMS messages. {% endhint %} #### Redirect to a custom URL If you want to redirect subscribers to a custom URL of your choice: 1. Go to your campaign dashboard > Edit Campaign > Automations > Welcome Emails > Quick Add Invitation Email 2. Scroll to the bottom of the page and switch on the toggle **After email confirmation, send subscribers to a custom thank you page** 3. Enter the URL of your custom thank-you page and save your changes
When redirecting subscribers, ReferralHero will append the following parameters to your URL: * **rh\_email**, with the subscriber's email * **rh\_name**, with the subscriber's name * **rh\_code**, with the subscriber's unique referral code * **rh\_subscriber\_id**, with the subscriber's ID * **rh\_position**, with the subscriber's position in the list #### Showing ReferralHero's Sharing Screen on Your Custom Thank-You Page If you redirect people to a custom thank you page on your website, you would normally need to design this page yourself, including code to grab the referral link, generate sharing buttons, etc. However, there’s a simpler way: 1. Go to your campaign dashboard > Edit Campaign > Widget Builder > Advocate Dashboard > Dashboard > Template Settings 2. Switch on **Open sharing screen if already signed up** 3. Add the ReferralHero Advocate Dashboard Widget to your custom thank you page
Now when people are redirected to your custom thank you page, ReferralHero will recognize them and automatically open the sharing screen. {% hint style="warning" %} **NOTE**: Since ReferralHero uses cookies (which are device-specific), this won’t work if users confirm their email address from a different device than the one they used to sign up (e.g., sign up on a desktop but confirm via phone). {% endhint %} # ReCaptcha [ReCaptcha](https://www.google.com/recaptcha/) is an exceptional free software by Google that helps to spot bots and automated web behaviour. ReferralHero's ReCaptcha native integration allows you to substantially reduce (or eliminate completely) spammers and bots trying to cheat in your campaign. **Important**: ReCaptcha is a Premium feature. If you want to use you must have a Premium account or upgrade to one. Let's see how you can enable ReCaptcha for your campaign: ### Step 1 [Go to this page](https://www.google.com/recaptcha/admin) and create a free account on Google ReCaptcha. ![](https://d33v4339jhl8k0.cloudfront.net/docs/assets/57e920a8c697914f21031685/images/5aba0ac82c7d3a0e9366c36e/file-8kVBVp20ko.png) ### Step 2 Once in your admin, register a new site. The important things are: * choose the INVISIBLE Recaptcha * add your domain to the whitelist (otherwise it won't work). Eg: if your website is [https://mywebsite.com](https://mywebsite.com/), add "mywebsite.com". If you want to test it in your local environment, you can add "localhost" * accept the Terms of Service ![](https://d33v4339jhl8k0.cloudfront.net/docs/assets/57e920a8c697914f21031685/images/5aba0bca042863794fbea3e0/file-kT0CUQhJ2v.png) ### Step 3 Once you register a new site, copy the **Site Key** and **Secret key**. \ Below's a screenshot of what they will look like. ![](https://d33v4339jhl8k0.cloudfront.net/docs/assets/57e920a8c697914f21031685/images/5aba0c62042863794fbea3e4/file-RST31rNvyq.png) ### Step 4 Go to your campaign Overview> *Edit > Unique Identifier*.\ Enable Recaptcha and paste the Site Key and Secret Key in the corresponding fields on ReferralHero.
Save your changes and your campaign is officially ReCaptcha enabled! ### ReCaptcha badge ReCaptcha will automatically add a small badge on the bottom right corner. This badge can't be disabled and SHOULDN'T be as expressed in the ReCaptcha's Terms of Service that you have agreed. ![](https://d33v4339jhl8k0.cloudfront.net/docs/assets/57e920a8c697914f21031685/images/5aba0db02c7d3a0e9366c386/file-fAMIIx3pr3.png) # Subscriber Tags Subscriber tags help you segment and identify specific groups of subscribers within your campaign. They are primarily used to set up conditional reward logic, allowing you to trigger rewards when certain tag conditions are met. ### Creating and Managing Tags Before assigning tags to subscribers, you must first create them in the **Manage subscriber tags** section of your campaign settings.
### Tag Assignment Methods You can assign tags to subscribers in the following ways: 1. **Manually by the Admin** Tags can be added or edited directly from a subscriber’s profile via the campaign dashboard. 2. **Automatically Apply Advocate’s Tags to Referrals**\ In the **Manage subscriber tags** section, there’s a toggle: **Apply subscriber tags to their referrals**\ When enabled, any tags assigned to an advocate will also be applied to all of their referrals—alongside any tags the referrals receive through signup or API. 3. **Through Zapier**\ You can assign tags by passing them in your Zap when creating or updating a subscriber. 4. **Through the API**\ Tags can be included during subscriber creation or update by passing them in your API request. {% hint style="warning" %} **Important:** \ Tags must first be created in the **Manage subscriber tags** section before they can be assigned via the API or Zapier. If a tag does not exist, it will not be added—even if specified in the API request or passed through a Zap. {% endhint %} 4. **Via the Widget During Signup**\ You can configure a dropdown in your signup widget to let subscribers choose a tag during signup. 1. If a new subscriber selects a tag during signup, the tag is saved to their profile. 2. If the subscriber already exists in the same campaign with a tag, signing up again will not overwrite the existing tag. 3. If a subscriber exists in Campaign A with a tag and signs up via the widget of Campaign B, the new tag from Campaign B is added to their profile. The subscriber will then have tags from both Campaign A and Campaign B.
### Tag Behavior and Updates 1. **Renaming Tags**\ When a tag is renamed in the **Manage subscriber tags** section: 1. The new name will automatically appear on all subscriber profiles where the tag is currently assigned. 2. The change will also reflect in the Edit Subscriber modal. 2. **Deleting Tags**\ If a tag is deleted from the **Manage subscriber tags** section: 1. It will no longer be available for new tag assignments. 2. It will remain on existing subscribers who already had the tag. 3. Any tag-based reward logic using that tag will remain functional unless manually updated. ### Using Tags in Widgets and Automations The following merge tags are available for use in widgets and automations:
Merge TagDescriptionSignup ScreenDashboardEmailSMS
%advocate_tag%Displays the advocate’s tag✅✅✅✅
%tag%Displays the subscriber’s own tag❌✅✅✅
{% hint style="info" %} **NOTE:** `%tag%` is not available on the widget signup screen because the subscriber’s tag has not yet been assigned at the time the signup form is displayed. {% endhint %} # Integrations Connect your ReferralHero account to your favorite apps and services. {% content-ref url="/pages/-LudIfJ6fe9FQWfUtKtc" %} [Active Campaign](/campaign-builder/integrations/active-campaign) {% endcontent-ref %} {% content-ref url="/pages/DNZhKF17k7Oca4L6pzCQ" %} [Aweber](/campaign-builder/integrations/aweber) {% endcontent-ref %} {% content-ref url="/pages/fBwA2eKayNl3zCre3X5M" %} [Blockchain](/campaign-builder/integrations/blockchain) {% endcontent-ref %} {% content-ref url="/pages/-LudMeYo54jcwgJpCM0M" %} [Facebook Pixel](/campaign-builder/integrations/facebook-pixel) {% endcontent-ref %} {% content-ref url="/pages/RKbL5RNlrurYdxDWr1g2" %} [Calendly](/campaign-builder/integrations/calendly) {% endcontent-ref %} {% content-ref url="/pages/-LudQ0k8heQCz3ejMb3Y" %} [HubSpot](/campaign-builder/integrations/hubspot) {% endcontent-ref %} {% content-ref url="/pages/-LudOpLgb2Ysm0fWxC1z" %} [Intercom](/campaign-builder/integrations/intercom) {% endcontent-ref %} {% content-ref url="/pages/OtsW9Z8DfMAsyMpl964V" %} [KakaoTalk](/campaign-builder/integrations/kakaotalk) {% endcontent-ref %} {% content-ref url="/pages/SpyjqMfK2oAnm38Ikm15" %} [Klaviyo](/campaign-builder/integrations/klaviyo) {% endcontent-ref %} {% content-ref url="/pages/-LudGfh7X56U8YdEDnfa" %} [Mailchimp](/campaign-builder/integrations/mailchimp) {% endcontent-ref %} {% content-ref url="/pages/ZPGkhi5wQuyd1rtNf0rn" %} [Salesforce](/campaign-builder/integrations/salesforce) {% endcontent-ref %} {% content-ref url="/pages/-LudTTz1a-t\_C8GzTi7c" %} [SendLane](/campaign-builder/integrations/sendlane) {% endcontent-ref %} {% content-ref url="/pages/-LudOIB-1dgt7CwYhxiP" %} [Slack](/campaign-builder/integrations/slack) {% endcontent-ref %} {% content-ref url="/pages/8FSlHrGksaq0gEazta5X" %} [Stripe](/campaign-builder/integrations/stripe) {% endcontent-ref %} {% content-ref url="/pages/RK3knkqNPUCO6nP1zsR7" %} [Tango Card](/campaign-builder/integrations/tango-card) {% endcontent-ref %} {% content-ref url="/pages/ShaEOlSqjcv1DQhnfaOw" %} [Tremendous](/campaign-builder/integrations/tremendous) {% endcontent-ref %} {% content-ref url="/pages/qLfWuKRFFgvxlZKZPiOl" %} [Typeform](/campaign-builder/integrations/typeform) {% endcontent-ref %} {% content-ref url="/pages/-LudUJRvbvoJEwfUhUY5" %} [Webhooks](/campaign-builder/integrations/webhooks) {% endcontent-ref %} {% content-ref url="/pages/-LvGWukwPHZe6YhkT-dy" %} [Zapier](/campaign-builder/integrations/zapier) {% endcontent-ref %} {% content-ref url="/pages/MdoDasLPtQRsEZa0ksGh" %} [Zoho](/campaign-builder/integrations/zoho) {% endcontent-ref %} # Active Campaign ReferralHero allows you to automatically sync your subscribers with an ActiveCampaign list of your choice. To connect your Active Campaign account: 1. Go to your campaign dashboard > *Edit Campaign > Integrations > ActiveCampaign* and click on **Connect your Active Campaign account** 2. In the popup, enter your **API URL** and **API KEY (**You can find those by going to your Active Campaign account, under *My Settings > Developer)* 3. After you connect your account, choose a list from the drop-down and save the changes. {% hint style="info" %} If you create or remove lists in your Active Campaign account and need to update the lists on ReferralHero, just click on the **Update lists** button. {% endhint %} ### Custom fields {% hint style="warning" %} **IMPORTANT**: Custom fields are mandatory and will be added to your ActiveCampaign list automatically. {% endhint %} When a person signs up we send a bunch of extra data to ActiveCampaign that is stored in your account's custom fields.(Refer to the [official ActiveCampaign Custom Fields Documentation](https://help.activecampaign.com/hc/en-us/articles/221433307-Custom-fields) for more info). The Custom Fields we include are: | CUSTOM FIELD | Description | | -------------------------- | -------------------------------------------------- | | **SUB\_ID** | Subscriber's id | | **FIRST\_NAME** | Subscriber's first name | | **LAST\_NAME** | Subscriber's last name | | **PHONE** | Subscriber's phone number | | **EX\_FIELD** | Subscriber's extra field value | | **EX\_FIELD\_2** | Subscriber's second extra field value | | **CODE** | Subscriber's unique referral code | | **REF\_LINK** | Subscriber's unique referral link | | **TOT\_REF** | Subscriber's total number of referrals | | **SOURCE** | Subscriber's source. If empty value will be "None" | | **REFERRER** | Subscriber's referrer's email address. | | **FB\_LINK** | Subscriber's unique Facebook referral link | | **TW\_LINK** | Subscriber's unique Twitter referral link | | **EM\_LINK** | Subscriber's unique email referral link | | **LASTREF** | Timestamp of last referral | | **POSITION** | Subscriber's position | | **POINTS** | Subscriber’s total accumulated points | | **MWR** | Subscriber's referrer's referral code | | **OPTION\_FIELD** | Subscriber's option field value | | **TERMS\_AND\_CONDITIONS** | Subscriber's T\&C field value | {% hint style="warning" %} **Important:** Initially, the fields created are hidden by default. You need to make them available for lists under the advanced field options: {% endhint %} To manage custom fields: 1. Go to Manage Fields, You will see all custom fields listed
2. Click on the edit icon to open a popup 3. Click on Advanced Options and select the visibility settings
{% hint style="warning" %} **IMPORTANT**: If you have other custom fields that are required in your list, the sync will fail. Make sure you have NO required custom fields in your list. {% endhint %} ReferralHero will automatically update these custom fields when things change (eg: when a subscriber refers a new person, their `TOT_REF` value changes). # Aweber The ReferralHero / Aweber integration provides a robust set of features that empower you to: * Import Existing Contacts from Aweber to ReferralHero * Automatically Sync ReferralHero Subscribers to Aweber ## Import Aweber Contacts to ReferralHero If you have existing contacts in your Aweber account and you want to import/subscribe them all to your ReferralHero campaign, you'll want to follow these instructions: 1. 1.Go to your Campaign Dashboard > Subscribers > Import and click on the tab Import from CRM 2. If you haven't connected your Aweber account yet, please do it now by clicking on the button Setup Integration 3. Choose the Aweber list from which you want to import contacts/subscribers 4. Specify a URL for the referral link. This is the URL that we will use to generate the referral link for your subscribers. For example, if you use[ http://mywebsite.com](http://mywebsite.com/), the referral link will be '' 5. Optional: Choose to "Send Welcome Email" at the time of import. Note, you must activate your Welcome Email in Automations before enabling the "Send Welcome Email" 6. Click on the button Import
{% hint style="info" %} We will import your subscribers into your ReferralHero campaign immediately. Depending on how many subscribers you are importing, it might take from a few minutes to several hours. We will send you an email when the import is finished. {% endhint %} {% hint style="warning" %} **NOTE:** If you turn on the Aweber integration (see the section below), ReferralHero will populate the custom fields in your Aweber account with the subscriber's values. {% endhint %} ## Sync ReferralHero Subscribers to Aweber If you want to automatically add ReferralHero subscribers to Aweber follow these instructions: 1. Log into ReferralHero 2. Go to your Campaign Dashboard > Edit Campaign > Integrations > Aweber 3. Click ‘Connect your Aweber account’
4. Choose the Aweber account that you want to connect to ReferralHero 5. Choose the Aweber contact list from the Aweber List dropdown 6. Then click Save
The integration will automatically create the following custom fields in your Aweber account. | FIELD | Description | | ---------------- | -------------------------------------------------- | | **SUB\_ID** | Subscriber's id | | **MWR** | Subscriber’s referrer’s referral code | | **EX\_FIELD** | Subscriber's extra field value | | **EX\_FIELD\_2** | Subscriber's second extra field value | | **CODE** | Subscriber's unique referral code | | **REF\_LINK** | Subscriber's unique referral link | | **TOT\_REF** | Subscriber's total number of referrals | | **SOURCE** | Subscriber's source. If empty value will be "None" | | **LAST\_REF** | Timestamp of last referral | | **FB\_LINK** | Subscriber’s Facebook link | | **TW\_LINK** | Subscriber’s Twitter link | | **EM\_LINK** | Subscriber’s email link | | **POSITION** | Subscriber’s position | | **POINTS** | Subscriber’s total accumulated points | | **REFERRER** | Subscriber’s referrer’s name | Now when a person signs up for your ReferralHero campaign, they will be immediately added to your Aweber account. {% hint style="info" %} **NOTE:** ReferralHero will automatically update these custom fields when a person signs up or when things change (eg: when a subscriber refers a new person, their TOT\_REF value changes). {% endhint %} # Blockchain The ReferralHero Blockchain Integration is very powerful and allows you to track and confirm on-chain conversion events for referrals. When a referral meets the defined event their referral status will change from [pending to confirmed](/campaign-management/subscribers/subscriber-profile#referral-status) and the referral will officially count towards the advocate (ie. points accumulated, rewards unlocked, etc.). ReferralHero currently supports on-chain tracking for: * BNB Chain * Ethereum * Solana To use this feature ReferralHero subscribers must have verified crypto wallet addresses. ### Crypto Wallet Address Verification {% hint style="success" %} To enable the blockchain integration you must: 1\. Set 'crypto wallet address' as the primary/secondary unique identifier AND **2a. If you are using our widget to create subscribers**, they must verify their crypto wallet address OR **2b. If you are using our Javascript API, REST API, or SDK to create subscribers**, you must send these fields (crypto\_wallet\_address & crypto\_wallet\_provider) to the subscriber profile, as [shown here](/integrate/javascript-web-api/adding-a-subscriber-manually#add-a-crypto-wallet-address-manually). {% endhint %} To enable crypto wallet address verification through our widget: 1. Go to Edit Campaign > Unique Identifier > select Web3 Wallet Address as your primary or secondary unique identifier 2. Enable Verification Method > select the crypto wallets you would like to activate to verify wallet addresses
3. Users will now be given the option to connect and verify their crypto wallet address directly through our widget.
4. ReferralHero will automatically check to see if the chosen wallet is activated in the browser extension. If it is, the wallet will automatically connect, and once the 'sign up' is complete the subscriber will be verified.
### Blockchain On-Chain Tracking To set up the Blockchain on-chain tracking integration: 1. Go to your campaign dashboard > *Edit Campaign > Integrations > Blockchain* and click on **Add Event To Track**
2. In the popup, enter the following: 1. Blockchain on which the transaction occurs 2. Name your tracking event 3. Select the conversion value that should be displayed in the subscriber profile 4. Set up as many relevant on-chain definitions 3. Click Start Tracking to close the popup Click Save {% hint style="success" %} **NOTE:** * Blockchain integration only works for campaigns set up with ‘multi-step conversion events’ as the campaign goal * You will not be able to use the Blockchain integration to track events that do not occur on a blockchain, e.g. fiat on-ramp transactions, etc {% endhint %} #### Blockchain On-Chain Tracking Example The following example illustrates how a ReferralHero on-chain tracking event can be set up: 1. Add the event to track by specifying the blockchain, event name, the conversion event (tokens transferred), and the transaction definitions (e.g. contract address).
2. A referral signs up to your referral campaign, and later performs the required event on BNB Chain. 3. The on-chain transaction occurs and is created on the BNB Chain.
4. The referral’s status is confirmed and the conversion value is sent to ReferralHero for your onward action.
# Calendly The ReferralHero / Calendly Integration is very powerful and allows you to track and reward subscribers based on booked sales calls or demos. 1. Go to your Calendly account 2. Go to My Calendly -> Event Types -> Edit Event ![](/files/z3sb7RFpOlFRfXZMklZx) 3\. Go to Additional Options -> Confirmation Page and change the following options: * *On Confirmation*: Select “Redirect to an external site” * *Redirect URL*: Add the URL of a page that will act as a “Thank You Page” after the person submits the Calendry form (Note: you may have to create this page on your website so you can have a dedicated URL) * *Pass event details to your redirect page:* Check the box ![](/files/67JeleA41AYo6eOHWGgN) 4\. Make sure you have added the ReferralHero Global Tracking script to the \ tag of your website. 5\. Add one of the following scripts to \ tag specifically on the "Thank You Page" or page used for the Redirect URL above. Use **RH\_MFxxxxxxxxxx.form.submit()** to add both non-referrals and track referrals to the referral campaign. Replace `'MFxxxxxxxxxx'` with your specific campaign UUID. ```javascript ``` **If you have the ReferralHero "Terms and Conditions" feature enabled** (D*esign > Opt-in Form*) for your campaign. Use this script instead: ```javascript ``` Use **RH.pendingReferral()** to track only referrals with ‘Pending’ status to the multi-step conversion event campaign ```javascript ``` {% hint style="info" %} Note: This will pass the Full Name and Email of the invitee to your ReferralHero campaign and create a subscriber. If you want to pass additional data to ReferralHero you will have to add additional variables, see [Calendly documentation here](https://help.calendly.com/hc/en-us/articles/360040257613#information-you-can-send-in-the-redirect-url-0-0). {% endhint %} Now, every time a Calendly form is submitted, a subscriber (a referral or non-referral) will be added to ReferralHero. # Cash Payouts The **Cash Payouts** feature lets you send cash rewards directly to your ReferralHero subscribers’ bank accounts. ReferralHero handles the entire payout process—collecting funds, sending payouts straight to their bank accounts, and supporting year-end 1099 tax reporting for eligible recipients in the United States. Additional reward payout & processing fees apply. See full details [here](https://referralhero.com/terms). ### **Set Up Cash Payouts** 1. Go to Integrations > Cash Payouts 2. Click **Enable Cash Payouts**
3. Select who should pay the processing fee from the **Who Should Pay the Processing Fee?** dropdown
Once enabled, your existing billing payment method will automatically be used as the funding source for cash payouts. ### **Enable Cash Payouts in a Reward** 1. Go to the reward you want to pay via this feature 2. In Reward Overview, enable Cash Payouts
3. Enter the Reward Value 4. Click "Save" to confirm your reward settings Once enabled, the reward will automatically use the selected funding method when processing payouts. {% hint style="success" %} **NOTE:** Enabling this option also creates a new **Connect Bank Account** email and SMS automation. {% endhint %} ### **Subscriber Bank Connection Workflow** 1. When the reward is unlocked, ReferralHero checks whether the subscriber has a bank account connected: 1. If the bank account is not connected: 1. A Connect Bank Account email/SMS automation is triggered 2. The message includes an onboarding link for connecting their bank account 3. This automation is sent every time a reward is unlocked until the subscriber connects their bank 4. The subscriber can trigger the Connect Bank Account automation manually from their ReferralHero Advocate Dashbaord in the My Rewards section
5. An admin can trigger the Connect Bank Account automation manually from the subscriber profile in the Rewards Unlocked section
2. Once the bank account is connected: 1. The Connect Bank Account automation stops 2. Normal reward emails and SMS messages resume 2. When a reward is paid, ReferralHero will automatically deposit the payout amount into the subscriber's connected bank account 3. ReferralHero stores a Bank Connected field in the subscriber profile.
### **Connect Bank Account Automation** You can edit the Connect Bank Account email and SMS by going to *Automations > Reward Emails/SMS messages*.
1. The automation is sent as soon as the reward is unlocked, regardless of reward delivery settings (e.g., immediately or pending) 2. The %reward\_value% merge tag in this automation shows the sum of all unlocked & unpaid rewards 3. The %connect\_bank\_link% merge tag generates a secure, subscriber-specific link that takes them directly to the bank account connection flow. Include it in your email body, SMS message, or set it as the button URL — without it, subscribers won't be able to connect their bank account and receive their cash payout. ### **Widget Settings** The Cash Payouts feature is fully integrated into the My Rewards section of the widget, allowing subscribers to self-trigger the Connect Bank Account automation. **Dashboard Widget Builder** 1. The default text of the Connect Bank Account Message that appears below the list of unlocked rewards on the live widget can be customized
**Live Widget** 1. A Connect Bank button appears below the Connect Bank Account message 2. When clicked, the subscriber receives the Connect Bank Account email and SMS automation 3. The message and button remain visible until the subscriber connects their bank account
# Discord Follow these steps to integrate Discord within the Advocate Dashboard: #### Get Your Discord Invite Link 1. Open Discord and go to your server 2. Right-click the channel where you want users to join 3. Click "Invite People" 4. Copy the invite link #### Connect Discord to the Advocate Dashboard 1. Go to Widget Builder > Advocate Dashboard > Dashboard 2. Add the "Social Actions" element 3. In the Discord Text Customization section, paste your Discord Server Invite Link
4. Save the changes #### User Experience 1. The user clicks the Join Discord button on the Advocate Dashboard
2. A Discord login popup opens, prompting the user to log in
3. The user clicks Authorize on the next page
4. The user clicks Accept Invite on the next page to complete the join
5. Once they join, the **"Join"** button on the Dashboard updates to a checkmark
6. **"Joined Discord Server verified"** is logged in the subscriber's profile on your admin dashboard
7. If points are assigned for joining Discord, the user earns them automatically # Facebook Pixel You can integrate your Facebook Pixel with ReferralHero to understand your user behaviour and traffic. A Facebook pixel collects data about people who visit or sign up to your campaign, so that you can more effectively plan your ad campaigns to find new customers. ### Add a Facebook pixel ID to your campaign 1. Grab your Facebook Pixel ID from your [Facebook Ads Manager](https://www.facebook.com/ads/manager/pixel/facebook_pixel) 2. Go to your campaign dashboard > *Edit campaign > Integrations > Facebook Pixel* 3. Toggle **Enable Facebook Pixel** and enter the Pixel ID 4. Save the changes
{% hint style="info" %} After you add the pixel to your campaign, then you can make sure that it's working by using Facebook Ads Manager. Learn about [how to tell if your Facebook pixel is working](https://www.facebook.com/business/help/218844828315224) from the Facebook Help Center. {% endhint %} {% hint style="warning" %} **NOTE**: If you've recently added a Facebook pixel to your online store, then you need to wait for customer activity before you'll see any data in Facebook Ads Manager. {% endhint %} ### Facebook Pixel Events ReferralHero sends 3 standard events to Facebook: * **PageView**\ When a user visits your campaign. * **Lead**\ When a person signs up to your campaign. * **CompleteRegistration**\ When a person verifies their email address. Note that if the Email confirmation is enabled that number of "Lead" events might be higher than the number of "CompleteRegistration" events due to some people not confirming their email address. ### Trigger Facebook Pixel Manually To trigger the Facebook Tracking Pixel manually, just use the **afterSuccess** callback in the Configuration file and choose which events you want to send. ```markup ``` # Gift Cards Send gift card rewards directly to your ReferralHero subscribers across 200+ countries. ReferralHero handles the entire payout process—collecting funds, sending gift cards, and supporting year-end 1099 tax reporting for eligible recipients in the United States. Recipients choose from 1,000+ gift card options, including Visa/Mastercard, Apple, Nike, Airbnb, and charitable donations. {% hint style="info" %} **Note**: Additional gift card reward payout & processing fees apply (starting at 2.5% + $0.50 per payout), paid by the account owner or deducted from the recipient's reward amount. See full details [here](https://referralhero.com/pricing#cash-payouts) {% endhint %} ## Setting Up Gift Cards To set up the Gift Cards integration in ReferralHero, follow these steps: 1. Navigate to Integrations > Gift Cards in your ReferralHero campaign dashboard 2. Click ‘Enable Gift Cards’ 3. Select who should pay the processing fee 4. Select the reward currency 5. Click Save
**Supported Reward Types** Subscribers can redeem rewards from a wide range of payout options, including: * Merchant gift cards (e.g. Amazon, Starbucks, and more) * Prepaid Visa / Mastercard cards * Charity donations ReferralHero supports multi-currency reward payouts. ## Setting Up Gift Card Rewards To configure gift card rewards in ReferralHero: 1. Go to the Rewards section in your ReferralHero campaign dashboard 2. Click the Add Reward button 3. Configure your reward trigger and reward conditions 4. Enable the ‘Issue Gift Card Reward’ option in the Reward Overview section
5. Enter the reward value 6. Click Save Reward ## Gift Card Reward Processing Flow When a subscriber becomes eligible for a reward, ReferralHero automatically handles the payout lifecycle. **Step 1: Charge Attempt** ReferralHero attempts to charge for: * Reward value * Processing fee {% hint style="info" %} **Note**: Additional gift card reward payout & processing fees apply (starting at 2.5% + $0.50 per payout), paid by the account owner or deducted from the recipient's reward amount. See full details [here](https://referralhero.com/pricing#cash-payouts) {% endhint %} **Step 2: Charge Result** * If the charge fails * The reward is not sent * The failure reason is logged in the subscriber activity timeline * If the charge succeeds * ReferralHero proceeds with reward creation. **Step 3: Reward Creation** ReferralHero creates the reward request through our 3rd party gift card provider and generates a secure gift card link for the subscriber. **Step 4: Reward Delivery** The gift card link is: * Delivered through your configured email and/or SMS automations * Available in the subscriber’s profile Subscribers can use the gift card link to select and redeem their preferred gift card option. ## Processing Fee Options ReferralHero allows you to decide who covers the payout processing fee. **Option 1: Charge Processing Fee to My Account** The subscriber receives the full reward amount. **Example:** * Reward value: $20.00 * Processing fee: $1.00 * Total charge to campaign admin: $21.00 * Amount subscriber receives: $20.00 **Option 2: Pass Processing Fee to Recipient** The processing fee is deducted from the subscriber’s payout amount. **Example:** * Reward value: $20.00 * Processing fee: $1.00 * Total charge to campaign admin: $20.00 * Amount subscriber receives: $19.00 ## Reward Notifications Configuring reward emails and SMS messages: 1. Go to Automations > Reward Emails / SMS Messages in your ReferralHero campaign dashboard 2. Use the merge tag *%gift\_card\_link%* in the email or SMS body to display the gift card link 3. Customize the content as desired 4. Click Save When the reward is sent, the subscriber will receive the gift card link via email or SMS. **Gift Card Link Click Tracking** ReferralHero automatically tracks when a subscriber clicks their gift card reward link. These events are visible in: * Activity Log * Email analytics * SMS analytics # GoHighLevel The ReferralHero / GoHighLevel integration is a robust solution offering several powerful functionalities: * Import existing contacts from GoHighLevel to ReferralHero * Automatically add new GoHighLevel contacts to ReferralHero * Sync ReferralHero subscribers to your GoHighLevel account * Use your own GoHighLevel form to add new contacts to your ReferralHero campaign * Trigger a ReferralHero conversion event when an Opportunity Status or Stage changes in GoHighLevel ### Import GoHighLevel Contacts into ReferralHero If you have existing contacts in GoHighLevel and want to import them into your ReferralHero campaign, follow these steps: 1. Go to your *Campaign Dashboard → Edit Campaign → Add Subscribers → Import via Integration.* 2. If your GoHighLevel account is not connected yet, go to the Integrations section and complete the connection. 3. Once connected, the **Import from GoHighLevel** block will appear. Click Import to import your contacts. 4. Imported subscribers will automatically receive the Welcome Email/SMS if it is enabled in your campaign. {% hint style="success" %} **NOTE:** The import starts immediately. Depending on the number of subscribers, it may take from a few minutes to several hours. You will receive an email when the import is complete. {% endhint %}
{% hint style="warning" %} **IMPORTANT:** If you turn on the GoHighLevel integration (see the section below), ReferralHero will populate the custom fields in your GoHighLevel account with the subscriber's values. {% endhint %} ### Automatically Add New GoHighLevel Contacts to ReferralHero #### Step 1: Install GoHighLevel Tracking Code To ensure accurate tracking of contacts, install the GoHighLevel tracking code on your website: 1. Log in to your GoHighLevel account. 2. Go to *Settings → External Tracking → External Tracking Script Installation.* 3. Copy the tracking script and embed it on your website. #### Step 2: Configure Contact Creation Tracking ReferralHero’s **GoHighLevel Contact Created** event automatically identifies whether new contacts are non-referrals or referrals, and adds them to your ReferralHero campaign. 1. In ReferralHero, navigate to *Edit Campaign → Integrations → GoHighLevel.* 2. Click **Connect your GoHighLevel account**.
3. Choose the GoHighLevel account you want to connect. 4. Toggle on **Enable GoHighLevel Integration**. 5. In the **GoHighLevel Events** section, click **Add Event to Track**. 6. Select **Create Contact** as the **GoHighLevel Event Type**. 7. Give the event a name. 8. In **Trigger Event Type**, choose whether to: * **Add All (Non-Referrals and Referrals)** * **Add Referrals Only** 9. Click **Start Tracking**.
#### Automatically Created Custom Fields in GoHighLevel When the integration is enabled, the following custom fields will be created in your GoHighLevel account: | **SUB\_ID** | Subscriber's id | | ------------------- | -------------------------------------- | | **EX\_FIELD** | Subscriber's extra field value | | **EX\_FIELD\_2** | Subscriber's second extra field value | | **OPTION\_FIELD** | Subscriber's option field value | | **CODE** | Subscriber's unique referral code | | **FB\_LINK** | Subscriber’s Facebook link | | **TW\_LINK** | Subscriber’s Twitter link | | **EM\_LINK** | Subscriber’s email link | | **REF\_LINK** | Subscriber's unique referral link | | **TOT\_REF** | Subscriber's total number of referrals | | **LAST\_REF** | Timestamp of last referral | | **MWR** | Subscriber’s referrer’s referral code | | **POSITION** | Subscriber’s position | | **POINTS** | Subscriber’s total accumulated points | | **REFERRER** | Subscriber’s referrer’s name | | **REFERRER\_EMAIL** | Subscriber’s referrer’s email | Now when a person signs up for your ReferralHero campaign, they will be immediately added to your GoHighLevel account. {% hint style="success" %} **NOTE**: ReferralHero will automatically update these custom fields when a person signs up or when things change (eg: when a subscriber refers a new person, their TOT\_REF value changes). {% endhint %} ### How to Use Your Own GoHighLevel Signup Form While the **Contact Created** event is recommended, high-volume forms (100+ new contacts/day) can be tracked using a redirect URL and ReferralHero JavaScript on a thank-you page. #### Step 1: Create a Custom Thank-You Page 1. Create a thank-you page on your website. 2. Add one of the following ReferralHero JavaScript codes to your thank-you page. **Option 1:** Use **RH.form.submit()** to add both non-referrals and track referrals to the referral campaign ``` ``` **Option 2:** Use **RH.pendingReferral()** to track only referrals with ‘Pending’ status to the multi-step conversion event campaign ``` ``` #### Step 2: Configure Your GoHighLevel Form 1. Go to your *GoHighLevel Form → Settings.* 2. Select **Redirect to URL** from the **On Submit** dropdown. 3. Enter your custom thank-you page URL with parameters: [https://mywebsite/thankyoupage?email={{contact.email}}\&firstName={{contact.first\_name}}\&lastName={{contact.last\_name}}\&phone={{contact.phone}}
]()
4. Save the form New form submissions will now be added to both your GoHighLevel contact list and ReferralHero campaign. ### Track a GoHighLevel Conversion Event You can trigger actions in ReferralHero when GoHighLevel contacts undergo an **Opportunity Status** or **Opportunity Stage** change. 1. Go to the **GoHighLevel Integration** page in ReferralHero. 2. Click **Add Event To Track**. 3. Enter a name for the event. 4. Select the GoHighLevel event type to track (e.g., Opportunity Status or Opportunity Stage ). 5. Choose the specific status or stage that triggers the event. 6. Select the **Trigger Event Type** based on the action you want ReferralHero to perform. **Available ReferralHero Actions:** * Add All (Non-Referrals and Referrals) * Add Referrals Only * Update Total Spend * Change Referral Status (most common use case) **Change Referral Status to Unqualified** * The **Change Referral Status** event allows updates from any current referral status to **Unqualified** (one-way updates) * When **Unqualified** is selected in the “Referral status changes to” dropdown, the “Referral status changes from” dropdown is removed * Referrals are automatically moved to **Unqualified** when the trigger condition is met, regardless of their current status * Unqualified is a non-linear status and does not follow the standard conversion flow
# HubSpot The ReferralHero/HubSpot integration is a robust solution offering several powerful functionalities: * Import existing contacts from HubSpot to ReferralHero * Automatically Add NEW HubSpot contacts to ReferralHero * Sync ReferralHero subscribers to your HubSpot account * Use your own HubSpot form to add new HubSpot contacts to your ReferralHero campaign * Trigger a ReferralHero conversion event when there is a lifecycle or deal stage update on HubSpot ## Import HubSpot contacts to ReferralHero If you have existing contacts in your HubSpot account and you want to import/subscribe them all to your ReferralHero campaign, you'll want to follow these instructions: 1. Go to your *Campaign Dashboard > Edit Campaign > Add Subscribers > Import via Integration*. 2. If your HubSpot account is not connected yet, go to the Integrations section and complete the connection. 3. Choose the HubSpot account from which you want to import contacts/subscribers. 4. The imported subscribers will automatically receive the welcome email if the **Welcome Email** is active in the campaign. 5. Click on the button **Import**
{% hint style="info" %} We will import your subscribers into your ReferralHero campaign immediately. Depending on how many subscribers you are importing, it might take from a few minutes to several hours. We will send you an email when the import is finished. {% endhint %} {% hint style="warning" %} **NOTE:** If you turn on the HubSpot integration (see the section below), ReferralHero will populate the custom fields in your HubSpot account with the subscriber's values. {% endhint %} ## Add New Hubspot Contacts to ReferralHero {% hint style="danger" %} **IMPORTANT:** To ensure accurate tracking of HubSpot contacts, please make sure the **HubSpot Tracking Code** is installed on your website. This is necessary to allow ReferralHero to track referrals accurately. You can find the tracking code in your HubSpot account by going to **Settings → Tracking & Analytics → Tracking Code**. Once copied, embed it on your website. {% endhint %} ReferralHero's HubSpot Contact Created event is a proprietary algorithm that accurately tracks and identifies people as non-referrals or referrals and adds them to your ReferralHero campaign when a new contact is created in your Hubspot account. 1. In ReferralHero, navigate to Edit Campaign > Integrations > HubSpot, and click the "Connect your HubSpot account" button.
2. Choose the HubSpot account you want to connect to ReferralHero 3. Choose the HubSpot contact list from the HubSpot Domain dropdown 4. Click Save 5. The "Hubspot Contact Created" event is automatically created upon account connection.
If the event is not created in your account, manually create the "Hubspot Contact Created" event. 1. Utilize the "Add event to track" button within the HubSpot integration page. Choose the “Create Contact” event type.
2. Decide if you want to add all (non-referrals and referrals) or referrals only when a new HubSpot Contact Created event occurs. The integration will automatically create the following custom fields in your HubSpot account. | **CODE** | Subscriber's unique referral code | | ----------------- | -------------------------------------------------- | | **EX\_FIELD** | Subscriber's extra field value | | **EX\_FIELD\_2** | Subscriber's second extra field value | | **LAST\_REF** | Timestamp of last referral | | **POINTS** | Subscriber’s total accumulated points | | **POSITION** | Subscriber’s position | | **REF\_LINK** | Subscriber's unique referral link | | **REFERRER** | Subscriber’s referrer’s name | | **SOURCE** | Subscriber's source. If empty value will be "None" | | **SUB\_ID** | Subscriber's id | | **TOT\_REF** | Subscriber's total number of referrals | | **EM\_LINK** | Subscriber’s email link | | **FB\_LINK** | Subscriber’s Facebook link | | **TW\_LINK** | Subscriber’s Twitter link | | **MWR** | Subscriber’s referrer’s referral code | | **OPTION\_FIELD** | Subscriber's option field value | Now when a person signs up for your ReferralHero campaign, they will be immediately added to your HubSpot account. {% hint style="info" %} **NOTE**: ReferralHero will automatically update these custom fields when a person signs up or when things change (eg: when a subscriber refers a new person, their TOT\_REF value changes). {% endhint %} ## How to Use Your Own HubSpot Signup Form Generally, it is recommended to use our Contact Created event (explained above) however if you want to specifically track individual HubSpot forms or if you have a high volume form (100+ new contacts per day) you can track form submissions to ReferralHero by incorporating the ReferralHero JavaScript into your HubSpot form. **Add ReferralHero JavaScript to Your HubSpot Form** 1. Add one of the following JavaScript codes to the end of your HubSpot HTML form code. This code will seamlessly track new signups from your HubSpot form to your ReferralHero campaign. {% hint style="info" %} **NOTE:** You need to replace the **hubspot\_form\_id** with your own HubSpot form ID. {% endhint %} Use **RH.form.submit()** to add both non-referrals and track referrals to the referral campaign ```javascript window.RHConfig = { callbacks: { ready: function() { setTimeout(function(){ var form = document.getElementById('hs-form-iframe-0').contentWindow.document.getElementById('hubspot_form_id'); form.addEventListener("submit", function(e){ var data = { email: form.querySelector('#email-hubspot_form_id').value, name: form.querySelector('#firstname-hubspot_form_id').value + ' ' + form.querySelector('#lastname-hubspot_form_id').value }; if (RH) { RH.form.submit(data); } }); }, 2000); } } } ``` Use **RH.pendingReferral()** to track only referrals with ‘Pending’ status to the multi-step conversion event campaign ``` window.RHConfig = { callbacks: { ready: function() { setTimeout(function(){ var form = document.getElementById('hs-form-iframe-0').contentWindow.document.getElementById('hubspot_form_id'); form.addEventListener("submit", function(e){ var data = { email: form.querySelector('#email-hubspot_form_id').value, name: form.querySelector('#firstname-hubspot_form_id').value + ' ' + form.querySelector('#lastname-hubspot_form_id').value }; if (RH) { RH.pendingReferral(data); } }); }, 2000); } } } ``` 2\. (Optional) To send other values from the HubSpot form to your ReferralHero campaign add this to the data line: ```javascript referral_hero_field_name: form.querySelector(’#HUBSPOT_FIELD_NAME').value ``` For example to send submitted data to the ReferralHero Extra Field profile field add: ```javascript extra_field: form.querySelector('#extra_field-hubspot_form_id').value ``` 3\. Now when someone signs up through your HubSpot form, they will be added to your HubSpot contact list and ReferralHero campaign. ## **Track a HubSpot Conversion Event** If your HubSpot contacts undergo a "Lifecycle Stage" or a "Deal Stage", you can trigger the following actions in ReferralHero: 1. Add all (non-referrals and referrals) 2. Add referrals only 3. Total spend updates 4. Change referral status (most common use case)
**Steps:** 1. Click the "Add Event To Track" button. 2. Provide a name for the event. 3. Select the HubSpot event type and stage to track. 4. Choose the 'Trigger Event Type' option corresponding to the action you want to perform in ReferralHero, such as changing a referral status. **Change Referral Status to Unqualified** * The **Change Referral Status** event allows updates from any current referral status to **Unqualified** (one-way updates) * When **Unqualified** is selected in the “Referral status changes to” dropdown, the “Referral status changes from” dropdown is removed * Referrals are automatically moved to **Unqualified** when the trigger condition is met, regardless of their current status * Unqualified is a non-linear status and does not follow the standard conversion flow
# Intercom ReferralHero allows you to automatically sync your subscribers with your Intercom account. To connect your Intercom account, go to your campaign dashboard > *Edit Campaign > Integrations > Intercom*. After you connect your account, you can enable/disable the sync between ReferralHero and Intercom. {% hint style="warning" %} **NOTE**: only people who sign up on ReferralHero AFTER you enable the Intercom integration will be added to your Intercom account. {% endhint %} ### User Attributes When a person signs up we send a bunch of extra data to Intercom that is stored in your account's user attributes. (Refer to the [official Intercom Documentation](https://www.intercom.com/help/en/articles/320-tracking-user-data-in-intercom) for more info). The User attributes we send are: | User Attribute | Description | | -------------------- | -------------------------------------- | | **NAME** | Subscriber's name | | **EXTRA\_FIELD** | Subscriber's extra field value | | **EXTRA\_FIELD\_2** | Subscriber's second extra field value | | **CODE** | Subscriber's unique referral code | | **REFERRAL\_LINK** | Subscriber's unique referral link | | **PEOPLE\_REFERRED** | Subscriber's total number of referrals | | **LAST\_REFERRAL** | Timestamp of last referral | # KakaoTalk ReferralHero's KakaoTalk integration adds a powerful sharing channel to your options, alongside email, SMS, WhatsApp, Facebook, Twitter, and more. In this guide, we'll walk you through integrating KakaoTalk into ReferralHero, enhancing your referral marketing efforts. ## Creating Your Kakaotalk Developers Account Follow the steps below to create a developer's account on KakaoTalk: 1\. To register for a developer's account, visit the following link: . 2\. After logging in, click on the 'My Application' link at the top, which will redirect you to this link: . 3\. Click on 'Add an application,' which opens a modal where you can input application details
4\. The list page will display all applications.
5\. Click on the application link, and you will find four keys on the page. To use the KakaoTalk share ability feature in the RH widgets, you need to add the 'JavaScript key' in RH.
6\. On the same page, navigate to the 'Platform' section and click on 'Go to Platform Settings.'
7\. At the bottom of the page, under the 'Web' Platform, click on 'Register Web Platform.'
8\. You will see a form in a modal box where you should enter the domains where our widgets will be added on your website. You can include up to 10 domains by clicking the 'Modify' button on the page.
9\. Ensure that your developer account is attached to your KakaoTalk account. ## Enabling KakaoTalk Share in Dashboard To enable KakaoTalk share in the Dashboard, follow these steps: 1\. Go to Widget Builder > Dashboard Widget > Dashboard 2\. Toggle on 'KakaoTalk' in the "Social Links" element. i. Enter a title for your share message ii. Enter your KakaoTalk JavaScript Key in the input box iii. Edit the share message iv. Upload a share image
# Klaviyo The ReferralHero/Klaviyo integration is very powerful and can work together in a few ways: * Import existing subscribers from Klaviyo to ReferralHero * Sync ReferralHero with Klaviyo * Add ReferralHero subscriber data into your Klaviyo emails using template tags ## How to import subscribers from **Klaviyo** If you have existing contacts in your Klaviyo account and you want to import/subscribe them all to your ReferralHero campaign, you'll want to follow these instructions: 1. Go to your campaign dashboard > Subscribers > Import and click on the tab **Import from CRM.** 2. If you haven't connected your Klaviyo account yet, please do it now by clicking on the button "Setup Integration". 3. Choose a Klaviyo list from which you want to import subscribers. If you can't see a specific list (for example because you created it recently) click on the link "Update lists". 4. Specify a URL for the referral link. This is the URL that we will use to generate the referral link for your subscribers. For example, if you use[ http://mywebsite.com](http://mywebsite.com/), the referral link will be '' 5. Optional: Choose to "Send Welcome Email" at the time of import. Note, you must activate your Welcome Email in Automations before enabling the "Send Welcome Email". 6. Click on the button "Import" ![](/files/Wi7AXkPSMFV37stnfXSt) We will import your subscribers into your ReferralHero campaign immediately. Depending on how many subscribers you are importing, it might take from a few minutes to several hours. We will send you an email when the import is finished. {% hint style="info" %} **NOTE**: If you turn on the [Klaviyo integration](#sync-referralhero-subscribers-to-klaviyo), ReferralHero will populate the custom properties in your Klaviyo list with the subscriber's values. {% endhint %} ## Sync ReferralHero subscribers to Klaviyo ReferralHero allows you to automatically sync your ReferralHero subscribers with a Klaviyo list of your choice. To connect your Klaviyo account, go to your campaign dashboard > *Edit Campaign > Integrations > Klaviyo* After you connect your account, choose a Klaviyo list from the drop-down menu and save the changes. If you create or remove lists in your Klaviyo account and need to update the lists on ReferralHero, just click on the "Update lists" link. ![](/files/9ikWqKdYIvnxmvCF1WEA) {% hint style="info" %} Note: Depending on when you connect your Klaviyo account, you might have subscribers or data in ReferralHero that was not synced to Klaviyo. If you find this is the case, simply click the "re-sync" button to do a full ReferralHero data push to Klaviyo. {% endhint %} The following custom properties will now be automatically created in your Klaviyo list. (Refer to the official [Klaviyo custom properties documentation]() for more info). | CUSTOM PROPERTY | Description | | ---------------- | -------------------------------------------------- | | **SUB\_ID** | Subscriber's id | | **FNAME** | Subscriber's first name | | **LNAME** | Subscriber's last name | | **MWR** | Subscriber’s referrer’s referral code | | **EX\_FIELD** | Subscriber's extra field value | | **EX\_FIELD\_2** | Subscriber's second extra field value | | **CODE** | Subscriber's unique referral code | | **REF\_LINK** | Subscriber's unique referral link | | **TOT\_REF** | Subscriber's total number of referrals | | **SOURCE** | Subscriber's source. If empty value will be "None" | | **LASTREF** | Timestamp of last referral | | **FB\_LINK** | Subscriber’s Facebook link | | **TW\_LINK** | Subscriber’s Twitter link | | **EM\_LINK** | Subscriber’s email link | | **POSITION** | Subscriber’s position | | **POINTS** | Subscriber’s total accumulated points | | **REFERRER** | Subscriber’s referrer’s name | {% hint style="info" %} **NOTE**: ReferralHero will automatically update these custom properties when a person signs up or when things change (eg: when a subscriber refers a new person, their TOT\_REF value changes). {% endhint %} ## How to use **template tags in Klaviyo** Though a guide on Klaviyo's template tags is beyond the scope of this article (and we recommend you to read [Klaviyo's official template tags guide](https://help.klaviyo.com/hc/en-us/articles/115005084927-Guide-to-Template-Tags-and-Variable-Syntax#custom-properties2)), we have created an example of how to use the custom properties ReferralHero sends to your list for your Klaviyo emails. Assuming you are importing all ReferralHero custom properties as described above, let's say you want to send out an email where you remind your subscribers about your referral program and to keep sharing their code. The body of your email could then look like this: > Hey {{ first\_name }}, > > Only 7 days left in our competition. > > Remember that you can win a FREE holiday in the Caribbeans if you invite 5 friends. > > Just share your unique referral link and convince your friends to sign up: > > Your referral link: {{ person|lookup:'REF\_LINK' }} > > Best regards, ![](/files/17CzM0TaHeuUSP2QuUPG) # Mailchimp The ReferralHero/Mailchimp integration is very powerful and can work together in a few ways: * Import existing subscribers from Mailchimp to ReferralHero * Use your own Mailchimp signup form to add new subscribers to your Mailchimp contact list and ReferralHero campaign * Sync ReferralHero with Mailchimp * Add ReferralHero subscriber data into your Mailchimp emails using merge tags ## How to import subscribers from MailChimp If you have existing contacts in your Mailchimp account and you want to import/subscribe them all to your ReferralHero campaign, you'll want to follow these instructions: 1. Go to your campaign dashboard > Subscribers > Import and click on the tab **Import from CRM.** 2. If you haven't connected your Mailchimp account yet, please do it now by clicking on the button "Setup Integration". 3. Choose a MailChimp list from which you want to import subscribers. If you can't see a specific list (for example because you created it recently) click on the link "Update lists". 4. Specify a URL for the referral link. This is the URL that we will use to generate the referral link for your subscribers. For example, if you use[ http://mywebsite.com](http://mywebsite.com/), the referral link will be '' 5. Optional: Choose to "Send Welcome Email" at the time of import. Note, you must activate your Welcome Email in Automations before enabling the "Send Welcome Email". 6. Click on the button "Import" ![](/files/Pwzj71QP8zKV46HvU8Mi) We will import your subscribers into your ReferralHero campaign immediately. Depending on how many subscribers you are importing, it might take from a few minutes to several hours. We will send you an email when the import is finished. {% hint style="info" %} **NOTE**: If you turn on the [Mailchimp integration](#sync-referralhero-subscribers-to-mailchimp), ReferralHero will populate the custom fields in your MailChimp list with the subscriber's values. {% endhint %} ## How to use a Mailchimp signup form If you want to use a Mailchimp signup form, instead of the ReferralHero Widget, to add subscribers to your Mailchimp contact list and ReferralHero campaign, you'll want to follow these instructions: #### Part I: **Creating a Mailchimp Form** 1. Log in to your Mailchimp account 2. Create a new Signup Form with the following fields:
Field Label/Tag DescriptionVisibility
Email (Required Field)Subscriber’s email addressVisible
FNAMESubscriber’s first nameVisible
LNAMESubscriber’s last nameVisible
\*Ex\_Field and Ex\_Field\_2 are commonly used to store additional user data such as address and phone number and in which case, field visibility should be set to ‘Visible’ 3\. Go to Signup Forms > Embedded Forms to generate HTML code to embed in your site to collect signups #### Part II: **Adding the ReferralHero Javascript and Mailchimp HTML code to your website** 1. Add the below [Javascript](/integrate/javascript-web-api/adding-a-subscriber-manually) function to the end of your Mailchimp HTML code. This function will add the new signup automatically from your Mailchimp form to your ReferralHero campaign. ```javascript ``` {% hint style="info" %} **Optional:** To send other values from the Mailchimp form to your ReferralHero campaign add this to the data line: ‘referral\_hero\_field\_name': form.querySelector(’#mce-MAILCHIMP\_FIELD\_NAME').value For example to send submitted data to the ReferralHero Extra Field profile field add: extra\_field: form.querySelector('#mce-EX\_FIELD').value {% endhint %} 2\. Paste the Mailchimp and ReferralHero code together into your website where you'd like the form to show. It should look similar to the below: ![](/files/rmoTBsizTaWPbNnPUXVD) 3\. Now when someone signs up through your Mailchimp form, they will be added to your Mailchimp contact list and ReferralHero campaign. ## Sync ReferralHero subscribers to Mailchimp ReferralHero allows you to automatically sync your ReferralHero subscribers with a MailChimp list of your choice. To connect your MailChimp account, go to your campaign dashboard > *Edit Campaign > Integrations > MailChimp* After you connect your account, choose a MailChimp list from the drop-down menu and save the changes. If you create or remove lists in your MailChimp account and need to update the lists on ReferralHero, just click on the "Update lists" link. ![](/files/x5OngKEzUFJ5N2FTf1yZ) {% hint style="info" %} Note: Depending on when you connect your Mailchimp account, you might have subscribers or data in ReferralHero that was not synced to Mailchimp. If you find this is the case, simply click the "re-sync" button to do a full ReferralHero data push to Mailchimp. {% endhint %} The following custom fields will now be automatically created in your Mailchimp list. (Refer to the[ official MailChimp Merge Tags Documentation](http://kb.mailchimp.com/merge-tags/using/getting-started-with-merge-tags) for more info). | CUSTOM FIELD | Description | | ---------------- | -------------------------------------------------- | | **SUB\_ID** | Subscriber's id | | **FNAME** | Subscriber's first name | | **LNAME** | Subscriber's last name | | **MWR** | Subscriber’s referrer’s referral code | | **EX\_FIELD** | Subscriber's extra field value | | **EX\_FIELD\_2** | Subscriber's second extra field value | | **CODE** | Subscriber's unique referral code | | **REF\_LINK** | Subscriber's unique referral link | | **TOT\_REF** | Subscriber's total number of referrals | | **SOURCE** | Subscriber's source. If empty value will be "None" | | **LASTREF** | Timestamp of last referral | | **FB\_LINK** | Subscriber’s Facebook link | | **TW\_LINK** | Subscriber’s Twitter link | | **EM\_LINK** | Subscriber’s email link | | **POSITION** | Subscriber’s position | | **POINTS** | Subscriber’s total accumulated points | | **REFERRER** | Subscriber’s referrer’s name | To view the custom fields in your MailChimp list go to Mailchimp.com, then go to *Audiences > Settings > List fields and |MERGE| tags*. Your page should look like this:
{% hint style="info" %} **NOTE**: If you have other custom fields that are required in your list, the sync will fail. Make sure you have NO required custom fields in your list. {% endhint %} {% hint style="info" %} **NOTE**: ReferralHero will automatically update these custom fields when a person signs up or when things change (eg: when a subscriber refers a new person, their TOT\_REF value changes). {% endhint %} ## How to use merge tags in MailChimp Though a guide on MailChimp merge tags is beyond the scope of this article (and we recommend you to read [Mailchimp's official guide](http://kb.mailchimp.com/merge-tags/getting-started-with-merge-tags)), we have created an example of how to use the custom fields ReferralHero sends to your list for your newsletters. Assuming you are importing all ReferralHero custom fields as described above, let's say you want to send out a newsletter where you remind your subscribers about your referral program and to keep sharing their code. The body of your email could then look like this: ![](https://d33v4339jhl8k0.cloudfront.net/docs/assets/57e920a8c697914f21031685/images/595f8dba2c7d3a707d7b8042/file-rKubxUCzev.png) And when you send the email, the custom fields will be replaced with the correct value. ![](https://d33v4339jhl8k0.cloudfront.net/docs/assets/57e920a8c697914f21031685/images/595f8e2b0428637ff8d45f50/file-D0GNE95S3y.png) # Salesforce The ReferralHero / Salesforce integration provides a robust set of features that empower you to: * Import Existing Contacts from Salesforce to ReferralHero * Automatically Sync ReferralHero Subscribers to Salesforce * Track a Salesforce Conversion Event {% hint style="warning" %} **NOTE:** Before connecting the ReferralHero/Salesforce integration, API access needs to be enabled in your Salesforce organization. API access is enabled by default in most Salesforce editions, including Enterprise, Unlimited, and Developer editions but a few editions like Professional do not include API access, and you need to enable API access or upgrade to a higher Salesforce edition. {% endhint %} ## Import Salesforce contacts to ReferralHero If you have existing contacts in your Salesforce account and you want to import/subscribe them all to your ReferralHero campaign, you'll want to follow these instructions: 1. Go to your *Campaign Dashboard > Edit Campaign > Add Subscribers > Import via Integration.* 2. If you haven't connected your Salesforce account yet, please do it now by clicking on the button **Set up Integrations**.
3. Choose the Salesforce object (Leads or Person Accounts) from which you want to import contacts/subscribers. 4. Click on the button **Import** {% hint style="info" %} We will import your subscribers into your ReferralHero campaign immediately. Depending on how many subscribers you are importing, it might take from a few minutes to several hours. We will send you an email when the import is finished. {% endhint %} {% hint style="warning" %} **NOTE:** If you turn on the Salesforce integration (see the section below), ReferralHero will populate the custom fields in your Salesforce account with the subscriber's values. {% endhint %} ## Sync ReferralHero subscribers to Salesforce If you want to automatically add ReferralHero subscribers to Salesforce follow these instructions: 1. Go to your *Campaign Dashboard > Edit Campaign > Integrations > Salesforce* 2. Click ‘**Connect your Salesforce account**’ 3. After connecting your account, toggle the Salesforce object (Leads or Person Accounts) you would like to create when a ReferralHero subscriber is added 4. Select a sync option 5. Then click **Save**
{% hint style="info" %} **Note**: ReferralHero will first attempt to sync with the Salesforce profile. If found, we will sync; if not found, we will create it as you defined with the toggle. {% endhint %} The integration will automatically create the following custom fields in your Salesforce account. | FIELD | Description | | ----------------- | -------------------------------------------------- | | **Code\_\_c** | Subscriber's unique referral code | | **ExField\_\_c** | Subscriber's extra field value | | **ExField2\_\_c** | Subscriber's second extra field value | | **LastRef\_\_c** | Timestamp of last referral | | **Points\_\_c** | Subscriber’s total accumulated points | | **Position\_\_c** | Subscriber’s position | | **RefLink\_\_c** | Subscriber's unique referral link | | **Referrer\_\_c** | Subscriber’s referrer’s name | | **Source\_\_c** | Subscriber's source. If empty value will be "None" | | **SubId\_\_c** | Subscriber's id | | **TotRef\_\_c** | Subscriber's total number of referrals | | **EmLink\_\_c** | Subscriber’s email link | | **FbLink\_\_c** | Subscriber’s Facebook link | | **TwLink\_\_c** | Subscriber’s Twitter link | | **MWR\_\_c** | Subscriber’s referrer’s referral code | {% hint style="warning" %} **Note:** The connected user must have the appropriate permissions to create custom fields on the selected Salesforce object. Additionally, ensure that the "Customize Application" permission is enabled for the connected user account. Without this permission, custom fields cannot be created. {% endhint %} Now when a person signs up for your ReferralHero campaign, they will be immediately synced/added to your Salesforce account.
{% hint style="info" %} **Note**: ReferralHero will automatically update these custom fields when a person signs up or when things change (eg: when a subscriber refers a new person, their TOT\_REF value changes). {% endhint %} ## Salesforce Account Configuration Configuring your Salesforce account is essential for the ReferralHero integration to function properly. After establishing the integration, it's imperative to follow these steps to ensure seamless operation within your Salesforce environment. {% hint style="info" %} **Note**: Please ensure that API access is enabled in Salesforce. API access is typically enabled by default in most Salesforce editions, including Enterprise, Unlimited, and Developer editions. For more information, refer to the [Salesforce documentation](https://help.salesforce.com/s/articleView?id=sf.security_api_access_control_about.htm\&type=5). {% endhint %} #### **Remote Site Settings** 1. Navigate to “Remote Site Settings” using the “Quick Find” search box in Salesforce Setup. 2. Click the “New Remote Site” button. 3. Enter the following ReferralHero site URL in the “Remote Site URL” field: 4. Click Save.
#### Field Accessibility Settings 1. Go to “Field Accessibility” using the “Quick Find” search box in Salesforce Setup. 2. Choose the record type (e.g., Lead or Contact) for which you want to update field accessibility. 3. Click “View by Fields”.
4. Select the profile (e.g., System Administrator) to modify the field’s accessibility. 5. Ensure that both “Field-Level Security” and “Page Layout” are set to “Visible”.
6. Save the changes. The field “Code” is now “Editable” for the selected profile.
7. Repeat the process for the following custom fields: * *SubId\_\_c* * *ExField\_\_c* * *ExField2\_\_c* * *Code\_\_c* * *FbLink\_\_c* * *TwLink\_\_c* * *EmLink\_\_c* * *RefLink\_\_c* * *TotRef\_\_c* * *Source\_\_c* * *LastRef\_\_c* * *Position\_\_c* * *Points\_\_c* * *MWR\_\_c* * *Referrer\_\_c* 8. Verify that all field-level security settings are correctly applied in the profile. Ensure that field access for all custom fields is now “Editable”.
{% hint style="info" %} **NOTE**: Updating "Field Accessibility" is crucial because it lets you decide which user profiles should see these new fields and where they should appear on the page layouts. By default, all RH custom fields are hidden, so adjusting these settings is necessary to control who can access these fields and where they appear on different layout configurations. {% endhint %} #### Additional Salesforce Account Type Configuration Considerations The ReferralHero integration is compatible with different Salesforce editions, but certain editions have limitations based on API and Apex class availability. Below is an outline of the supported editions and the corresponding functionality: **Starter Suite Edition** * API Access: Enabled. The integration can connect to Salesforce. * Apex Class: Not available. * Event Tracking: Not supported. * Summary: While the Starter edition allows for basic connectivity with Salesforce, it does not support event tracking due to the absence of Apex class functionality. **Pro Suite Edition** * API Access: Not enabled. The integration cannot connect to Salesforce. * Apex Class: Not available. * Event Tracking: Not supported. * Summary: The Pro edition does not support the ReferralHero integration because API access and Apex classes are unavailable. **Enterprise Edition** * API Access: Enabled. The integration can connect to Salesforce. * Apex Class: Available. * Event Tracking: Fully supported. * Summary: The Enterprise edition fully supports the ReferralHero integration, including event tracking through the Apex class. **Unlimited Edition** * API Access: Enabled. The integration can connect to Salesforce. * Apex Class: Available. * Event Tracking: Fully supported. * Summary: The Unlimited edition provides complete functionality for both Salesforce connectivity and event tracking. **Developer Edition** * API Access: Enabled. The integration can connect to Salesforce. * Apex Class: Available. * Event Tracking: Fully supported. * Summary: The Developer edition fully supports the integration, including both connection and event tracking. **Einstein Suite Edition** * API Access: Enabled. The integration can connect to Salesforce. * Apex Class: Available. * Event Tracking: Fully supported. * Summary: The Einstein edition fully supports the integration, including both connection and event tracking. {% hint style="warning" %} **Notes:** * API access is essential for the ReferralHero integration. Ensure that the user profile linked to the integration has API access enabled. * For editions that support API access, event tracking requires the Apex class to be available. Without Apex class functionality, events cannot be tracked. {% endhint %} ## Track a Salesforce Conversion Event If your Salesforce contacts are associated with “Opportunity”, you can add an event in the Salesforce integration that creates a rule to trigger the following actions in ReferralHero whenever there is a defined Opportunity Stage change in Salesforce. 1. Contact added 2. Total spend updates 3. Referral change from pending to unconfirmed/confirmed status
#### Steps: 1. Click the ‘Add event to track’ button 2. Give the event a name 3. Select the Salesforce opportunity stage to track 4. Select the 'Trigger Event Type' option that corresponds to the action you want to perform in ReferralHero, such as adding a contact or changing a referral status. # SendLane ReferralHero allows you to automatically sync your subscribers with a SendLane list of your choice. To connect your Sendlane account: 1. go to your Campaign Dashboard > *Edit Campaign > Integrations > SendLane* and click on **Connect your Sendlane account** 2. In the popup, enter your API Key, your HASH Key and your DOMAIN (You can find those by going to your Sendlane account, under *Account Settings)* 3. After you connect your account, choose a list from the drop-down and save the changes. {% hint style="info" %} If you create or remove lists in your Sendlane account and need to update the lists shown in the dropdown on ReferralHero, just click on the **Update lists** link . {% endhint %} ### Custom fields When a person signs up we send a bunch of extra data to SendLane that is stored in your list's custom fields. The Custom Fields we send are: | CUSTOM FIELD | Description | | ---------------- | -------------------------------------------------- | | **SUB\_ID** | Subscriber's id | | **EX\_FIELD** | Subscriber's extra field value | | **EX\_FIELD\_2** | Subscriber's second extra field value | | **REF\_CODE** | Subscriber's unique referral code | | **REF\_LINK** | Subscriber's unique referral link | | **TOT\_REF** | Subscriber's total number of referrals | | **REF\_SOURCE** | Subscriber's source. If empty value will be "None" | | **LAST\_REF** | Timestamp of last referral | # Slack To integrate ReferralHero with Slack: * go to * Choose your team, press configure * in configurations press add configuration * choose channel, press "Add Incoming WebHooks integration" You will get your Slack webhook. It looks like this: **...**. Go to your campaign dashboard > *Edit Campaign > Settings > Integrations > Slack* and paste that webhook URL. (Don't forget to save!)
That's it! From now on you will receive a Slack notification every time a new person signs up on your campaign. # Stripe The ReferralHero Stripe is a powerful integration that enables a seamless connection between your ReferralHero account and your Stripe payment gateway. This support document provides a comprehensive overview of the integration's key features, outlining how you can make the most of this powerful tool for your referral marketing campaigns. Here is what can be done with the ReferralHero Stripe integration: * Import Stripe customers into ReferralHero * Create customers in ReferralHero when starting an onboarding flow or completing a Stripe payment page/checkout * Track Stripe trialing, active, and other subscription events in ReferralHero * Track Stripe transactions * Sync Stripe customer's conversion value and total spend to RerferralHero * Apply Stripe coupons to customers when a ReferralHero reward is unlocked * Apply Stripe credit to customers when a ReferralHero reward is unlocked ## Connect Stripe Account to ReferralHero Follow these steps to securely link your Stripe account to ReferralHero for a reliable integration. 1. In the Stripe Dashboard, navigate to Developers > API Keys section, ensure you grant the necessary permissions in your Stripe account for event tracking with RH
2. Go to Stripe Dashboard > Developers > API Keys and copy the Secret Key
3. If you would like to enable Test mode in the integration, turn on “Test mode” in your Stripe Dashboard and copy the Test Secret Key
4. In ReferralHero, go to Edit Campaign > Integrations > Stripe, and click the button "Connect your Stripe account"
5. Enter the Stripe Secret Key in the API KEY text box 6. Click "Connect"
8. The "Transaction Tracking" event is automatically generated upon connecting your Stripe account 9. Your Stripe account is now successfully connected
{% hint style="success" %} **NOTE:** The "Transaction Tracking" event automatically includes Stripe transactions in the "Transactions" tab under the "Reward Logs". {% endhint %}
## Test the Integration with Stripe "Test Mode" Test mode is a testing environment that simulates creating real events without the risk of affecting live transactions or moving actual money. It allows you to verify that the integration between ReferralHero and Stripe is functioning as expected. To enable test mode, enter your Stripe test API key in the ReferralHero integration settings. This ensures you can safely test the integration, verify referral tracking, and validate workflows without impacting live data or customer activity. Using test mode is essential for confirming the setup of your referral program before launching it to your audience. ## Import Stripe Customers into ReferralHero 1. In your ReferralHero campaign dashboard, go to Add Subscribers > Import via Integration > Import from Stripe 2. Click "Import"
{% hint style="success" %} **NOTE:** 1. If your "Welcome Email" automation is active, your imported list will receive this email 2. Import may take 1 to 2 hours to complete, depending on the number of customers in your Stripe account {% endhint %} ## Automatic Creation of Customers in ReferralHero You can create customers in ReferralHero when they are added to Stripe using the following methods: #### **Custom Form** Use the ReferralHero JavaScript [RH\_MFxxxxxxxxxx.form.submit()](https://support.referralhero.com/integrate/javascript-web-api/adding-a-subscriber-manually) or [RH.pendingreferral()](/integrate/javascript-web-api/track-custom-referral-events#add-a-pending-referral) when implementing a custom form/checkout on your website to capture signup or customer information. Data will be automatically synced with ReferralHero when they are created in Stripe. #### **Stripe Payment Link** You need to create a custom Stripe thank you page on your website to use this feature. Follow the steps below to generate unique payment links with Stripe and add customers automatically when payment is completed. 1. Go to your website and add the following ReferralHero script to your Stripe thank you page: 
<script>
window.RH_MFxxxxxxxxxx_Config = {
callbacks: {
ready: function() {
let checkout_id = new URLSearchParams(document.location.search).get('session_id');
if(RH_MFxxxxxxxxxx){
console.log("present");
RH_MFxxxxxxxxxx.stripe_checkout(checkout_id)
}else{
console.log("absent");
}
}
}
}
</script>
{% hint style="success" %} **NOTE:** The `RH_MFxxxxxxxxxx.stripe_checkout()` function works like [`RH_MFxxxxxxxxxx.organicTrackReferral()`](https://support.referralhero.com/integrate/javascript-web-api/track-custom-referral-events#track-referral-conversion-or-add-subscriber). On the conversion page, it records referrals as: * **Confirmed** if your campaign has one conversion event * **Unconfirmed** if your campaign has two or three conversion events {% endhint %} 2. Go to your Stripe dashboard > Payments > Payment Links and click "+ New"
3. Choose a product on the "Payment Page" tab
4. Go to the "After Payment" tab, check the option "Don't show confirmation page" to redirect customers to the custom thank you page on your website 5. Enter your custom thank you page URL by attaching an additional parameter session\_id as shown below to the URL text box: \ [https://mywebsite/Stripethankyoupage***`?session_id={CHECKOUT_SESSION_ID}`***](https://mywebsite/Stripethankyoupage?session_id={CHECKOUT_SESSION_ID}) 6. Click "Create link"
7. Copy the payment link created and send it to your customer
8. The customer will be created in ReferralHero when they complete the payment {% hint style="success" %} **NOTE:** * **Non-Referral Creation**: The RH\_MFxxxxxxxxxx.stripe\_checkout() creates a non-referral by default when triggered. * **Pending Referral Confirmation**: If the subscriber already exists as a pending referral, the referral is confirmed automatically. * **Referred Visitor Conversion**: If a referral cookie exists, the referred visitor is converted into an unconfirmed/confirmed referral. {% endhint %} ## Definitions to Track Referral Events There are three types of Stripe events that can be tracked in the integration based on specific Stripe activities:
1. Stripe Status Change: Monitor changes in customer statuses (such as trialing or active) to trigger referral actions in ReferralHero 2. Payment Succeeds in Stripe: Record referral events when specific payment transactions occur in Stripe 3. Customer Created: Add new Stripe customers automatically to ReferralHero {% hint style="success" %} **NOTE:** The **Transaction Occurs** event is automatically created when the Stripe account is connected. It logs the transaction data in the “Transactions” tab, sets the Conversion Value and updates the Lifetime Spend with the Stripe Total\_Spend in the subscriber profile. You must track this event if you plan to use affiliate reward structures. {% endhint %} **Example 'Stripe Status Change' event** This example illustrates an event that sets the referral status from 'pending' to 'unconfirmed' when a Stripe subscription state moves into trialing.
**Example 'Payment Succeeds' event** This example illustrates an event that sets the referral status from 'unconfirmed' to 'confirmed' when a customer's Stripe payment amount is greater than $50.
**Example 'Transaction Tracking' event** This example illustrates the event that sends the Stripe transaction data, which is logged in the “Transactions” tab. It also sets the Conversion Value and updates the Lifetime Spend with the Stripe Total\_Spend in the subscriber profile.
## Apply Stripe Coupons Enhance your referral campaigns by offering discounts through Stripe coupons, seamlessly integrated with ReferralHero. Stripe customers' accounts will automatically apply a discount code when they unlock a reward in ReferralHero. 1. Set up a reward in your ReferralHero campaign 2. Go to your Stripe integration in ReferralHero and click the button "Add reward coupon"
3. Select the coupon you would like to apply to the Stripe customer from the dropdown 4. Select the reward that the customer needs to unlock to earn the discount **Example ‘Reward Coupon’ event** This example illustrates that when the Stripe customer successfully refers one referral and unlocks the reward "Reward for Advocate",
the 'Reward Coupon' event set up for the reward will automatically apply the discount code "50OFFOneTime" to the customer's account in Stripe.
## Apply Stripe Credit Enhance your referral program by applying Stripe credit directly to customers' accounts when they unlock a reward in ReferralHero. This feature allows you to offer incentives without requiring a separate discount code or manual intervention. 1. Navigate to the Reward Overview section and enable the "Apply Stripe credit" option
2. Set the reward value in the Reward Value section
3. Once a subscriber unlocks the reward, the corresponding credit amount will be automatically applied to their Stripe account
## Track Stripe Transactions ReferralHero supports ongoing transaction tracking, empowering you to reward affiliates for transactions that occur over time. This feature allows you to provide commissions beyond the initial transaction. {% hint style="success" %} **NOTE:** For existing Stripe customers, the first-ever payment amount becomes the Conversion Value, and the Stripe Total\_Spend is reflected as the Lifetime Spend in the ReferralHero subscriber profile. {% endhint %} **Scenario Overview** Stripe integration events: 1. “Transaction Tracking” 2. "Stripe Status Change" event triggered when a subscriber moves into "Active", setting the referral to confirmed. Reward settings: 1. Reward the advocate for each transaction completed by a “Confirmed” referral 2. Reward the advocate 10% of each transaction by the “Confirmed” referral 3. Reward should recur for 10 transactions
**Expected Behavior of Events:** 1. A Pending referral is simultaneously created in ReferralHero when a Trialing customer is created in Stripe 2. The Trialing customer purchases a $200 plan and transitions into Active status in Stripe 3. "Stripe Status Change" event triggers, changing the referral status from Pending to Confirmed 4. "Transaction Tracking" event is triggered, logging data in the Transactions tab, and updating the subscriber profile 5. A reward of $20 is unlocked by the advocate 6. The referral makes another payment in Stripe 7. “Transaction Tracking” event is triggered again, logging data in the Transactions tab, and updating the subscriber profile 8. Rewards are unlocked by advocate for 10 transactions # Tango Card We recommend using ReferralHero and Tango Card if you want to automatically send gift cards when a member in your ReferralHero campaign unlocks a reward. Tango Card makes it easy for the recipient to receive and choose a gift card. To see more information about Tango Card and all available gift card options to the recipient [see here](https://www.tangocard.com/reward-link/). You will need a Zapier account and a Tango Card account before you start. 1. Log into your Zapier account and create a new Zap. 2. Search for and find the ReferralHero App 3. Follow the prompts and connect your ReferralHero account to Zapier with your ReferralHero API. ![](/files/OSYR9WEoeYzyS7P0K2ie) 4\. Choose the trigger event that will send a gift card and the correct campaign ![](/files/w6rrOqCEC6GchHCb7PWV) 5\. Search for and find the Tango Card app 6\. Action Event should be set to "Send Reward" 7\. Connect your Tango Card Account to Zapier ![](/files/BfCtKDWxd8x0s6E3K52E) Log into your TangoCard account and go to Settings -> API Keys -> Generate API Key (if you don't have one). If you are unable to access the API Settings or do not see this option please contact their support team at or . In the meantime and/or if you do not have a Sandbox account to test the ReferralHero -> Zapier ->TangoCard connection you can use the below Sandbox Credentials. Sandbox environments do not store real funds. Test Sandbox Credentials for Zapier: * Platform name: ZapierDemo * Platform key: WEzIsMS$j\@Rybc?GE?PA&\&LUHCcBgG?mQtjd\@pRm\&ksw * Environment: Sandbox When you are ready to connect your own Sandbox or Production platform to Zapier pull the API Key and Platform Name from your TangoCard Account. ![](/files/zhRRDsu2ex90nxrnePru) 8\. Choose your Account "Platform Customer Name", "Platform Account Name", and "Reward Type" ![](/files/4ZInVAgWTdtqazqR9W7J) 9\. Write in the gift card value you would like to issue as a reward from your Tango Card account balance, ex. 10 (for $10) 10\. Select Recipient First Name, Last Name, and Email Address from the ReferralHero data pull (if you do not see the correct option, click "show all options") ![](/files/4EgbAxldYm39ADtTfDhX) 11\. Enter the Email Template ID or ETID attached to an email template within Tango Card Reward Templates that you would like to use. Enter E000000 for the Tango Card Standard email template. ![](/files/VCXkPpNh2ZfC7kxkMEaz) 12\. (Optional) Enter a custom message to send with the reward when the Zap is triggered. In order to populate this Zap message within the Tango Card email template you must include the {{message}} dynamic tag in the email. ![](/files/x6jamnDqlmgZK5qiDvRi) 13\. (Optional) This is an internal only note or ReferralHero data that can be used for record keeping orders in Tango Card. Recipients will not see what is entered in the notes field. ![](/files/BneRNuvMn1mdAoVlQ222) 14\. Continue and Test the connection to ensure everything is set up correctly. NOTE: If you have a Production Credentials set up this will issue a gift card with real funds. 15\. Turn on Zap to set "Live". 16\. If you have used the Tango Card Standard Email Template above, when the gift card is issued through Tango Card, it will look like below. To Customize the template you must create one and then change the ETID from the previous step. ![](/files/bLp4N52rbCCYJc0HnRUf) 18\. NOTE: You must have a positive account balance in your Tango Card account for the Zap to work. As gift cards are issued to winners from ReferralHero to Tango Card, your Tango Card account balance will decrease. 19\. When the gift card email is issued via Tango Card the recipient will click the link within the email and be able to choose a gift card with the balance that was issued by the Zap. # Telegram Follow these steps to integrate Telegram within the Advocate Dashboard: #### Create a Bot with BotFather 1. Open Telegram and search for BotFather 2. Start a chat and send the command: **/newbot** 3. Follow the instructions: * Provide a name for your bot * Choose a username (must end in "bot", e.g. MyReferralBot) 4. Once set up, BotFather will generate a bot token #### Add the Bot as an Administrator to Your Channel 1. Open your Telegram channel 2. Tap the three-dot menu in the top-right corner 3. Select "Manage Channel" 4. Click "Administrators" 5. Select "Add Administrator" and choose the bot created in Step 1 6. Save the changes #### Connect Your Bot to the Advocate Dashboard 1. Go to Widget Builder > Advocate Dashboard > Dashboard 2. Add the "Social Actions" element 3. In the "Telegram Text Customization" section: * Enter your bot token in "Telegram Bot Token" * Provide your "Telegram Invite Link"
4. Save the changes #### User Experience 1. The user clicks the Join Telegram button on the Advocate Dashboard
2. They enter their phone number on the next page
3. Telegram sends a confirmation message to their Telegram account
4. The user confirms the request
5. The user successfully joins the group 6. The "Join" button on the Dashboard updates to a checkmark
7. "Joined Telegram Channel verified" is logged in the subscriber's profile on your admin dashboard
8. If points are assigned for joining Telegram, the user earns them automatically # Tremendous Send money rewards to ReferralHero subscribers in over 200 countries. With our powerful Tremendous integration, choose from over 1,000 reward payouts including gift cards, Visa, Mastercard, ACH payments, PayPal, Venmo, or charitable donations. This comprehensive guide will walk you through the necessary steps to set up and leverage the Tremendous Integration within ReferralHero, ensuring a smooth rewards experience. {% hint style="info" %} Note: Before you begin, make sure you have an active [Tremendous account](http://tremendous.com), have created a Tremendous campaign template, and loaded funds to your account. {% endhint %}
## Setting Up Tremendous Integration To set up the Tremendous integration in ReferralHero, follow these steps: 1. Navigate to Integrations > Tremendous in your ReferralHero campaign dashboard. 2. Click on ‘Connect your Tremendous account’
3. Log in to your Tremendous account 4. On the next page, click the ‘Authorize’ button to grant ReferralHero access to your Tremendous account
5. Once your Tremendous account is successfully connected, select the desired Tremendous campaign you wish to integrate with 6. Choose the preferred reward currency for your reward
{% hint style="info" %} Note: If you don't see the Tremendous campaign in the list, make sure you have created one in Tremendous, and click on ‘Update list’ to refresh the available campaigns {% endhint %} 7. Click on ‘Save’ to save the integration settings ## Setting Up ReferralHero Rewards with Tremendous In this setup, we will configure a ReferralHero reward to send a reward email containing a Tremendous reward link. This link will be used to redeem the monetary reward. **To configure ReferralHero rewards, follow these steps:** 1. Go to the Rewards section in your ReferralHero campaign dashboard 2. Click the Add Reward button 3. In the Reward Overview, enable the 'Issue Tremendous reward' toggle
4. Enter a reward value
{% hint style="info" %} Note: You must specify the reward value to place a Tremendous order, otherwise the value will be zero {% endhint %} 5. Enable Reward Notification to notify the subscriber when the reward is sent
6. Click 'Save Reward' to save your settings **Configuring the Reward Email** 1. Go to Automations > Reward Emails in your ReferralHero campaign dashboard 2. Use the merge tag %tremendous\_reward\_link% in the email body to display the reward link when sent
3. Customize the email body according to your preferences 4. Click Save to apply the changes When the ReferralHero reward is sent, the email will include the Tremendous reward link
## **Example** **Reward Setup under the Reward section in your ReferralHero campaign** Reward Trigger: reward the advocate every time 1 referral is confirmed\ Reward Value: fixed amount of 10\ Reward Delivery: release immediately\ Reward Email: Enabled, utilizing the %tremendous\_reward\_link% merge tag in the email body **Tremendous Reward Link Sent** Upon a ReferralHero subscriber receiving a Tremendous reward link, the following outcomes will be observed: 1. The ReferralHero Reward Logs will indicate the reward was successfully sent to the recipient
1. The Tremendous Reward History will reflect the reward link order with the reward value defined in ReferralHero
3. The recipient will receive the Tremendous reward link via the ReferralHero reward email
## Tremendous Reward Processing Behavior **Successful Tremendous Reward Delivery** If the Tremendous reward has been sent successfully, it is logged in the subscriber’s Timeline Log as: * For individual rewards
* For group rewards
**Failed Tremendous Reward Delivery** In situations where the Tremendous reward fails to send due to issues such as: * Insufficient funds in your Tremendous account * No campaign selected in the integration Errors are logged in the subscriber’s Timeline Log as: * For individual rewards
* For group rewards
**When a Tremendous Reward Fails to Send** * For individual rewards * In the Rewards Unlocked section, the reward status changes to Failed, which is also reflected in the subscriber profile * To send a failed reward, click the three-dot dropdown, and select 'Send' * For group rewards * The status of the individual rewards within a group reward will remain as Pending, while the group reward will update to Failed. The individual rewards have not been paid because the parent group reward failed * To send a failed reward, go to the Group Payouts section or click into the group reward and pay on the Details page. The option to manually send/pay individual rewards within a group reward is not available in the Rewards Unlocked section # Typeform Typeform allows you to create a dynamic and customizable sign up form while using ReferralHero as your backend to power your referral program! You may want to use Typeform if you are looking to improve the user sign up experience or to collect additional user opt-in data than you can collect with the native ReferralHero widget. This is also a great option if you are not a developer as the set up with Typeform is very easy! There are two methods to integrate ReferralHero with Typeform: 1. Use Typeform's 'Redirect to URL' feature 2. Use Zapier to connect Typeform and ReferralHero ### Method 1: Use Typeform's 'Redirect to URL' Feature You will need a Typeform Plus account or higher to use the Redirect feature. **General user journey:** 1. Referral visits your website and gets cookied 2. Referral visits your webpage with your Typeform embedded on it or your Typeform hosted site 3. Referral completes Typeform and is redirected back to your website with their email in the URL parameter 4. Call RH JavaScript on page load #### **Setting Up the Redirect URL in Typeform** ‘Redirect to URL’ sends respondents to a single link of your choice after they click Submit on your Typeform. 1. Create a Typeform page to accept the respondent's email address (or another unique identifier) 2. Add a ‘Redirect to URL’ ending by clicking the + sign next to Endings in the left-hand sidebar of the Create panel
3. In the settings of the redirect ending, follow these steps to add variable value captured from the ‘unique identifier’ page to the redirect link
i. Add your referral landing page URL in the following format to the Settings: ii. Click the + sign in the Settings to add the variable value, i.e. the email from the ‘unique identifier’ page, to the end of the redirect URL
iii. Make sure the final redirect URL looks like the following example: ### **Adding RH JavaSscript to the Redirect Page** 1. Make sure you have added the ReferralHero Global Tracking script to the \ tag of your website 2. In addition, add one of the following scripts to the \ tag of the Redirect URL page Use **RH.form.submit()** to add both non-referrals and track referrals to the referral campaign ``` ``` Use **RH.pendingReferral()** to track only referrals with ‘Pending’ status to the multi-step conversion event campaign ``` ``` Use **RH.trackReferral()** to track referrals only on the redirect page ``` ``` Use **RH.organicTrackReferral()** to track referrals OR add non-referrals on the redirect page ``` ``` ### Method 2: Use Zapier to Connect Typeform and ReferralHero You will need a Typeform account and a Zapier account before you start. #### Creating a Typeform 1. Log in to your Typeform account 2. Create a new Typeform that can accept at least two RH required fields: name and email address (turn on the setting ‘Required’) 3. On the right side panel, go to Logic > Advanced > Hidden Fields ![](/files/RM0xidCCK5w4G5jElK2l) 4\. Add a Hidden Field then change the name of the hidden field from @hidden1 to **@mwr**, then click save. ![](/files/8cq2kGc9tBIxZFAfwN4Q) 5\. Publish the Typeform #### Embedding the Typeform 1. In Typeform, go to the tab ‘Share’ 2. Choose the way you want your Typeform to be embedded in your web page * For example, go to ‘Standard’ if you want to present the Typeform as part of your website Click ‘Get the code’, then click ‘Copy code’ 3. Click ‘Get the code’, then click ‘Copy code’ ![](/files/nOVS4vSgNL1NmzGBX8oZ) ![](/files/FCsLVn48o2lh2nfuLgdg) 4\. Go to your web page, paste the code to where you want your Typeform to appear on the page 5\. Add the following to the code between the data-tf-widget and data-tf-hidden parameters: **data-tf-transitive-search-params="mwr"** Your code will be slightly different but these can be used as a reference: {% hint style="success" %} **Example 1:** \
\
\ **Example 2:** \
\
\ {% endhint %} 6\. Save the code #### Creating a Zap 1. Log in to Zapier 2. Create a new Zap 3. Search for Typeform as the Trigger App 4. The Trigger Event is ‘New Entry Triggers when a form is submitted’ ![](/files/tFGvcjNswvNU9VcEWc4X) 5\. Connect your Typeform account 6\. Choose the Typeform form you set up in the previous step in the Set Up Trigger 7\. Search for ReferralHero as the Action app 8\. The Action Event is ‘Add Subscriber Adds a new subscriber to a list’ ![](/files/BpA5L29KqdB6gnMbYAxw) 9\. Connect to your ReferralHero account by entering the API Key ![](/files/VwRukPA1aSu7Cnr18qZT) 10\. In the Set Up Action, the following five fields are mandatory fields * Campaign: your ReferralHero campaign * Email address: Typeform email * Referral URL: your default referral link address * Full name: Typeform name * Referrer: Mwr (hidden field) ![](/files/lhFIZpf1NLZNGfWT6WjT) 11\. Then Test & Continue 12\. Turn on Zap # Webhooks Webhooks are used to send events from ReferralHero to your server. You can decide which events to send to your server. To enable webhooks: * go to your campaign dashboard > *Edit Campaign > Integrations > Webhooks* * Click on the **+ New Webhook** button * In the popup, add your endpoint URL and toggle the events you want to receive * Click on **Create Webhook**
*** ### Webhook Payload Verification To ensure that your webhook payloads are authentic and have not been tampered with, ReferralHero includes a signature header in every webhook request. You can use this signature to validate requests. ⚠️ **Important:** Make sure to **enable the “Payload Verification” toggle**. Once enabled, a secret key will be generated. This key is required to decode and validate the signature header in your application that receives the webhook.
*** ### Where to Find Your Webhook Secret Key You can find your Webhook Secret Key in two places: **Option 1: From Profile Menu** 1. Log in to your **ReferralHero dashboard**. 2. Click on your **profile button** (top-right corner). 3. In the popup, select **Webhook Secret**. 4. You will see your **Webhook Secret Key** along with an option to **regenerate** it if needed.
**Option 2: From Campaign Settings** 1. Log in to your ReferralHero dashboard. 2. Click **Edit Campaign** for the campaign you want. 3. Go to the **Integration** tab. 4. Click on **Webhook**, and you will see the Webhook Secret Key.
Use this secret key in your server code to verify incoming webhooks. *** ### Steps to Verify a Webhook 1. **Read the raw request body** (e.g., `request.raw_post` in Rails). 2. **Retrieve the signature** from the `X-ReferralHero-Signature` header. 3. **Recompute the HMAC-SHA256 hash** of the raw body using your Webhook Secret Key as the secret. 4. **Compare** your computed value with the signature header. If they match, the webhook is valid. *** Code Examples {% tabs %} {% tab title="Ruby" %} ```ruby require 'openssl' require 'base64' class WebhooksController < ActionController::API skip_before_action :verify_authenticity_token def receive raw_payload = request.raw_post signature = request.headers['X-ReferralHero-Signature'] secret = ENV['REFERRALHERO_API_KEY'] computed_signature = Base64.strict_encode64( OpenSSL::HMAC.digest('sha256', secret, raw_payload) ) unless ActiveSupport::SecurityUtils.secure_compare(signature.to_s, computed_signature) render json: { error: 'Invalid signature' }, status: :unauthorized and return end data = JSON.parse(raw_payload) # handle data... head :ok end end ``` {% endtab %} {% tab title="Python (Flask)" %} ```python from flask import Flask, request, abort import hmac, hashlib, base64, os app = Flask(__name__) @app.route('/webhook', methods=['POST']) def webhook(): raw = request.get_data() signature = request.headers.get('X-ReferralHero-Signature', '') secret = os.environ['REFERRALHERO_API_KEY'].encode() digest = hmac.new(secret, raw, hashlib.sha256).digest() computed = base64.b64encode(digest).decode() if not hmac.compare_digest(signature, computed): abort(401) data = request.get_json() # handle data... return '', 200 ``` {% endtab %} {% tab title="Node.js (Express)" %} ```javascript const express = require('express'); const crypto = require('crypto'); const app = express(); app.use(express.raw({ type: 'application/json' })); app.post('/webhook', (req, res) => { const rawBody = req.body; // Buffer const signature = req.header('X-ReferralHero-Signature') || ''; const secret = process.env.REFERRALHERO_API_KEY; const computed = crypto.createHmac('sha256', secret).update(rawBody).digest('base64'); if (!timingSafeEqual(signature, computed)) { return res.status(401).send('Invalid signature'); } const data = JSON.parse(rawBody.toString('utf8')); // process data... res.sendStatus(200); }); function timingSafeEqual(a, b) { const bufA = Buffer.from(a || ''); const bufB = Buffer.from(b || ''); if (bufA.length !== bufB.length) return false; return crypto.timingSafeEqual(bufA, bufB); } ``` {% endtab %} {% endtabs %} *** ✅ **Backward Compatible**: If you do not check this header, your existing webhooks will continue to work without any changes.\ 🔒 **Recommended**: Implement signature validation to ensure authenticity and security of incoming webhooks. ### Events ReferralHero sends a `POST HTTP` request with a `JSON` payload when specific events occur. There are 6 types of events: #### **new\_registration** {% tabs %} {% tab title="Description" %} Sent when a new person subscribes to your list. If you the confirmation email is disabled, the event is sent as soon as the person is subscribed to the list. {% endtab %} {% tab title="Response" %} ```yaml { response: "new_registration", list_uuid: "MFXXXX", //The UUID of your list subscriber_id: "sub_123ABC", // Subscriber's ID name: "John Doe", //Subscriber's name first_name: "John", last_name: "Doe", email: "john.doe@email.com", //Subscriber's email extra_field: "+1 2348891123", // Subscriber's extra field's value extra_field_2: "USA", // Subscriber's second extra field's value code: "2hg36dvs", //Subscriber's unique referral code source: "facebook", //Subscriber's source. If the subscriber doesn't have a source the value will be "direct_visit" referred: true, referrer: { subscriber_id: "sub_123CCD", people_referred: 2, referral_link: "http://mywebsite.com/LINK_PLAIN", points: 3, last_referral_at: 1702017953, name: "Mark Doe", first_name: "Mark", last_name: "Doe", email: "mark@yahoo.com" extra_field: "+1 2348894454", extra_field_2: "USA", option_field: "Los Angeles", code: "fd336dff", phone_number: "+1 2348894454", crypto_wallet_address: "0x0000000000000000000000000000000000000011" }, //This property can have 3 possible values: an empty string (if the subscriber has not been referred), an object containing data of the referral (if the subscriber has been referred) or "subscriber_deleted" (if the subscriber has been referred but the user has been deleted.) referral_link: "http://mywebsite.com/LINK_PLAIN", created_at: 1234567889 // Timestamp of the subscriber's sign up } ``` {% endtab %} {% endtabs %} #### **subscriber\_promoted** {% tabs %} {% tab title="Description" %} Sent when a subscriber is promoted. {% endtab %} {% tab title="Response" %} ```yaml { response: "subscriber_promoted", list_uuid: "MFXXXX", subscriber_id: "sub_123ABC", source: "facebook", referred: false, referral: { subscriber_id: "sub_123CCD", people_referred: 2, referral_link: "http://mywebsite.com/LINK_PLAIN", points: 3, last_referral_at: 1702017953, name: "Mark Doe", first_name: "Mark", last_name: "Doe", email: "mark@yahoo.com" extra_field: "+1 2348894454", extra_field_2: "USA", option_field: "Los Angeles", code: "fd336dff", phone_number: "+1 2348894454", crypto_wallet_address: "0x0000000000000000000000000000000000000011" }, people_referred: 3, //Number of people referred referral_link: "http://mywebsite.com/LINK_PLAIN", created_at: 1234567889 // Timestamp of the subscriber's promotion name: "John Doe", //Subscriber's name first_name: "John", last_name: "Doe", email: "john.doe@email.com" //Subscriber's email extra_field: "+1 2348891123", // Subscriber's extra field's value extra_field_2: "USA", // Subscriber's second extra field's value option_field: "Florida", // Subscriber's option field's value code: "2hg36dvs", phone_number: "+1 2348891123", crypto_wallet_address: "0x0000000000000000000000000000000000000000" } ``` {% endtab %} {% endtabs %} #### **subscriber\_updated** {% tabs %} {% tab title="Description" %} Sent when a subscriber field is updated. {% endtab %} {% tab title="Response" %} ```yaml { "response": "subscriber_fields_updated", "list_uuid": "MF833ac6ee2d", // Unique list identifier "subscriber_id": "sub_61ad4723e3a9", // Unique ID of the subscriber "source": "referral", // Source of the subscriber (e.g., referral, direct_visit) "referred": false, // Whether the subscriber was referred "referral": null, "referral_link": "https://campaign.referralhero.com/MF833ac6ee2d/signup?mwr=1296cda7", // Personalized referral URL "people_referred": 0, "created_at": 1746795375, // Timestamp of subscriber creation "last_referral_at": null, "name": "Jane Doe", // Full name "first_name": "Jane", // First name "last_name": "Doe", // Last name "email": "jane.doe@example.com", // Email address "extra_field": "Company ABC", "extra_field_2": "Product Manager", "extra_field_3": "New York", "extra_field_4": "Referral Campaign A", "option_field": "Option 1", "code": "1296cda7", "phone_number": "+1234567890", // Phone number "crypto_wallet_address": "0xABCDEF1234567890" } ``` {% endtab %} {% endtabs %} #### **subscriber\_deleted** {% tabs %} {% tab title="Description" %} Sent when a subscriber is deleted. {% endtab %} {% tab title="Response" %} ```yaml { response: "subscriber_deleted", list_uuid: "MFXXXX", subscriber_id: "sub_123ABC", last_referral_at: 1702017953, name: "John Doe", //Subscriber's name first_name: "John", last_name: "Doe", email: "john.doe@email.com" //Subscriber's email extra_field: "+1 2348891123", // Subscriber's extra field's value extra_field_2: "USA", // Subscriber's second extra field's value option_field: "Florida", // Subscriber's option field's value code: "2hg36dvs", phone_number: "+1 2348891123", crypto_wallet_address: "0x0000000000000000000000000000000000000000" } ``` {% endtab %} {% endtabs %} #### **reward\_unlocked** {% tabs %} {% tab title="Description" %} Sent immediately when a subscriber qualifies for and unlocks a reward. {% endtab %} {% tab title="Response" %} ```yaml { "response": "reward_unlocked", "list_uuid": "MFABC123", "subscriber_id": "sub_ABC123", "bonus_id": 178, // Unique ID of the reward unlocked "reward_name": "$100 Giftcard", // Name of reward "reward_value": 100, // Value of the reward if set "name": "John Smith", // Subscriber's full name "first_name": "John", "last_name": "Smith", "email": "john.smith@email.com", // Subscriber's email "extra_field": null, // Custom field #1 (optional) "extra_field_2": null, // Custom field #2 (optional) "extra_field_3": null, // Custom field #3 (optional) "extra_field_4": null, // Custom field #4 (optional) "code": "YYY999", // Unique referral code "people_referred": 5, // Number of successful referrals "referral_link": "ReferralHero | Referral Program Software for B2B & B2C Brands ", // Personalized referral URL "phone_number": "", // Subscriber's phone number "crypto_wallet_address": "" // Wallet address if used } ``` {% endtab %} {% endtabs %} #### **reward\_sent** {% tabs %} {% tab title="Description" %} Sent when a reward is actually delivered to the subscriber. This happens only after conditions like 'Hold until manually reviewed' or 'Hold for X days' are fulfilled or Reward delivery set to\ 'Unlock and send reward immediately'. {% endtab %} {% tab title="Response" %} ```yaml { "response": "reward_sent", "list_uuid": "MFABC123", "subscriber_id": "sub_ABC123", "bonus_id": 178, // Unique ID of the reward sent "reward_name": "$100 Giftcard", // Name of reward "reward_value": 100, // Value of the reward if set "name": "John Smith", // Subscriber's full name "first_name": "John", "last_name": "Smith", "email": "john.smith@email.com", // Subscriber's email "extra_field": null, // Custom field #1 (optional) "extra_field_2": null, // Custom field #2 (optional) "extra_field_3": null, // Custom field #3 (optional) "extra_field_4": null, // Custom field #4 (optional) "code": "YYY999", // Unique referral code "people_referred": 5, // Number of successful referrals "referral_link": "https://referralhero.com/?mwr=YYY999", // Personalized referral URL "phone_number": "", // Subscriber's phone number "crypto_wallet_address": "" // Wallet address if used } ``` {% endtab %} {% endtabs %} ### Errors Please send back a blank response with a status code of `200`. \ All not-200 responses will be considered errors. After 10 consecutive bad responses, the webhook will be disabled. If a webhook fails, we will try to deliver it 3 times over a period of 5 minutes. ### How to test a webhook To test a webhook just click on the **Test** button next to the webhook URL you want to test.\ We will ping your webhook URL with a JSON file containing fake data. # Zapier The ReferralHero native [Zapier](https://zapier.com/apps/referralhero/integrations) app is a very powerful integration that allows you to connect with 1,500+ third-party apps so that you can send data from one to the other without writing any code. Here is what you can do with a Zap (let us know if you want us to add something else): **ReferralHero Triggers And Actions** ReferralHero allows you to send data to a third-party app when the following events occur, * **New Subscriber**: when a new subscriber is added to your campaign * **New Referral**: when a new referral is added to your campaign * **Referral Status Change**: when the referral status is changed from Pending to Unconfirmed/Confirmed * **Reward Unlocked**: when a specific reward is unlocked by a subscriber * **Subscriber Deleted**: when a subscriber is deleted ReferralHero allows you to receive data from a third-party app when the following events occur, * **Add Points**: add a specified number of points to a subscriber * **Add Subscriber**: add a new subscriber to your campaign * **Confirm Referral**: change the referral status from Unconfirmed to Confirmed * **Track Referral Conversion Event**: change the referral status from Pending to Unconfirmed/Confirmed * **Track Transaction**: allows you to pass transaction data * **Update Subscriber**: allows you to update a subscriber Examples: In example #1 we'll create a Zapier integration so that every time somebody unlocks a reward in our referral program they are tagged in our ConvertKit account.\ In example #2 we'll create a Zapier integration so that every time a new customer is added to our Stripe account, they are added to ReferralHero. {% hint style="info" %} Please notice these are just examples to illustrate how to send data from and to ReferralHero using Zapier. {% endhint %} ### Example #1: Tag people who win a reward in ConvertKit **Step 1**: Login or sign-up on [Zapier](https://zapier.com). **Step 2**: Click on the **Make a Zap!** button in the top-right corner. **Step 3**: You will now be redirected to the Zapier editor. In the search bar, type "ReferralHero" to find the latest ReferralHero app "ReferralHero (1.2.5)" ![](/files/-LvGbaLIVtabk9ABBQgI) {% hint style="info" %} If you can't find the ReferralHero app in Zapier, [go to this page](https://zapier.com/developer/public-invite/16418/latest/) and add the app to your account. {% endhint %} **Step 4**: Choose **Reward Unlocked** as Trigger event from the drop-down menu and click the **Continue** button.
**Step 5**: Connect your ReferralHero account by clicking on the **Sign-in to ReferralHero** button and entering the ReferralHero Zapier API key which you can find in your account *Edit Campaign> Integrations > Zapier.*
**Step 6**: Choose your ReferralHero Campaign and Reward
**Step 7**: Click the **Continue** button. Then click on **Test Trigger** to import a test event (we'll need this later). **Step 8**: Click the **Continue** button to finish editing. It's now time to send this data to ConvertKit. ![](/files/-LvGecjZ8KNe-I1lbFRk) **Step 9**: In the search bar type "convertkit" to find the ConvertKit app. ![](/files/-LvGeo91xNGamybPZfFk) **Step 10**: Choose **Add Tag to Subscriber** as Action event from the drop-down menu and click the **Continue** button. ![](/files/-LvGfH6GEKUR2ygvGOQp) **Step 11**: Connect your ConvertKit account by entering the ConvertKit API private and secret key. Click on the **Continue** button. **Step 12**: In the **Tag** field choose a tag from your ConvertKit account (note: the tag must already exist in your account). In the **Email** field we want to use the email address that we got from ReferralHero. To do so, click the icon to the right of the field. A drop-down will open with the data retrieved with our previous test. Select the **Email** option and click on **Continue** to finish this step.
**Step 13**: If you want to test your integration, click on the **Test Action** button. If the test is successful, you should see a green message. **Step 14**: Click on **Publish Zap** and turn the Zap on! ### Example #2: Add Stripe customers to ReferralHero **Step 1**: Login or sign-up on [Zapier](https://zapier.com). **Step 2**: Click on the **Make a Zap!** button in the top-right corner. **Step 3**: You will now be redirected to the Zapier editor. In the search bar, type "Stripe" to find the Stripe app. **Step 4**: Choose **New Customer** as Trigger event from the drop-down menu and click the **Continue** button. ![](/files/-LvGpXSm2xg-wzyAXR4s) **Step 5**: Connect your Stripe account by clicking on the **Sign-in to Stripe** button. **Step 6**: Click the **Continue** button. Then click on **Test Trigger** to import a test event (we'll need this later). **Step 7**: Click the **Continue** button to finish editing. It's now time to send this data to ReferralHero. ![](/files/-LvGq6RclCo_72bRJday) **Step 8**: In the search bar, type "ReferralHero" to find the latest ReferralHero app "ReferralHero (1.2.5)". **Step 9**: Choose **Add Subscriber** as Action event from the drop-down menu and click the **Continue** button. ![](/files/-LvGqOgtNzC9rYSgVhu6) **Step 10**: Connect your ReferralHero account by clicking on the **Sign-in to ReferralHero** button and entering the ReferralHero Zapier API key which you can find in your account *Edit Campaign> Integrations > Zapier.* **Step 11**: In the **Campaign** field pick your ReferralHero campaign. In the **Email** field we want to use the email address that we got from Stripe. To do so, click the icon to the right of the field. A drop-down will open with the data retrieved with our previous test. Select the **Email** option. Finally in the **Referral URL** enter the URL that will be used to generate the referral link and click on **Continue** to finish this step. ![](/files/-LvGrcitKz4GWOvC4n8g) {% hint style="info" %} **Note**: campaign, email address and referral URL are required fields but you can send additional data to ReferralHero such as the full name. {% endhint %} **Step 12**: If you want to test your integration, click on the **Test Action** button. If the test is successful, you should see a green message. **Step 13**: Click on **Done Editing** and turn the Zap on! # Zoho The ReferralHero / Zoho integration provides seamless functionality, empowering you to: * Import Existing Contacts from Zoho to ReferralHero * Automatically Sync ReferralHero Subscribers to Zoho ## Import Zoho Contacts to ReferralHero If you have existing contacts in your Zoho account and want to import/subscribe them all to your ReferralHero campaign, follow these instructions: 1. Go to your Campaign Dashboard > Subscribers > Import and click on the tab Import from CRM. 2. If you haven't connected your Zoho account yet, please do it now by clicking on the button Setup Integration. 3. Specify a URL for the referral link. This is the URL that we will use to generate the referral link for your subscribers. For example, if you use[ http://mywebsite.com](http://mywebsite.com/), the referral link will be '' 4. Optional: Choose to "Send Welcome Email" at the time of import. Note, you must activate your Welcome Email in Automations before enabling the "Send Welcome Email" 5. Click on the button Import
We will import your subscribers into your ReferralHero campaign immediately. Depending on how many subscribers you are importing, it might take from a few minutes to several hours. We will send you an email when the import is finished. {% hint style="info" %} NOTE: If you have created custom fields in your Zoho account, ReferralHero will populate them with the subscriber's values. {% endhint %} ## Sync ReferralHero Subscribers to Zoho If you want to automatically add ReferralHero subscribers to Zoho, follow these instructions. ### Step 1: Create custom fields in Zoho 1. Log into your Zoho account 2. Go to Setup > Customization > Modules and Fields > Contacts 3. On the Contacts page, go to Fields, then click on the button “Create and Edit Fields” 4. Create the following custom fields | Field | Description | | -------------- | -------------------------------------------------- | | SUB\_ID | Subscriber's id | | MWR | Subscriber’s referrer’s referral code | | EX\_FIELD | Subscriber's extra field value | | EX\_FIELD\_2 | Subscriber's second extra field value | | CODE | Subscriber's unique referral code | | REF\_LINK | Subscriber's unique referral link | | TOT\_REF | Subscriber's total number of referrals | | SOURCE | Subscriber's source. If empty value will be "None" | | LASTREF | Timestamp of last referral | | FB\_LINK | Subscriber’s Facebook link | | TW\_LINK | Subscriber’s Twitter link | | EM\_LINK | Subscriber’s email link | | POSITION | Subscriber’s position | | POINTS | Subscriber’s total accumulated points | | REFERRER\_NAME | Subscriber’s referrer’s name |
### Step 2: Set up Zoho integration 1. Log into ReferralHero 2. Go to your Campaign Dashboard > Edit Campaign > Integrations > Zoho 3. Click ‘Connect your Zoho account’![](/files/d6J0ZqMQx5RkSQgLT5IF) 4. After you connect your account, toggle on the integration 5. Then click Save Now, when a person signs up for your ReferralHero campaign, they will be immediately added to your Zoho account. {% hint style="info" %} NOTE: ReferralHero will automatically update these custom fields when a person signs up or when things change (eg: when a subscriber refers a new person, their TOT\_REF value changes). {% endhint %} # Tasks ReferralHero Tasks allow administrators to create custom activities that subscribers can complete as part of a campaign. Tasks provide a flexible way to engage subscribers through additional campaign activities and track participation beyond standard referral actions. ### Task Setup Workflow Setting up Tasks involves several steps across the ReferralHero admin dashboard. **Step 1: Enable Tasks** Go to *Campaign Builder > Goal* and enable **Enable Advocate Tasks** in section *#4: Do you want advocates to complete tasks for rewards?* Enable this option if you want advocates to complete tasks as part of the campaign and unlock rewards based on task completion.
{% hint style="info" %} Tasks are available only for **Conversion Event** campaigns. {% endhint %} **Step 2: Configure Tasks** Administrators can configure each task by defining how subscribers complete the activity, how completion is validated, whether approval is required, the number of allowed submissions, and the task status. Go to *Campaign Builder > Tasks* and click **Add a Task** to create a new task.
The **New Task** form includes the following configuration options:
ConfigurationDescription
IconUpload an icon for the task. PNG, JPG, or SVG formats are supported. A simple square icon with a transparent background is recommended
Task NameThe name of the activity shown to subscribers
DescriptionAdditional instructions or details about the task
Task URLThe link subscribers will open to complete the task
Validation RequirementDefines how subscribers provide proof that they completed the task
ApprovalDetermines whether the task requires administrator approval
# of SubmissionsDefines how many times a subscriber can submit the task
After completing the required fields, click **Create task** to add the task to the campaign. **Step 3: Configure Task Rewards** Tasks can be used as a reward condition. Go to *Campaign Builder > Rewards > Rewards for Advocates* and enable **Unlock reward for completing a task**. This allows advocates to unlock rewards after completing the required tasks.
**Step 4: Display Tasks on the Advocate Dashboard** Tasks can be displayed using the **Tasks** element in the Widget Builder. Go to *Campaign Builder > Widget Builder > Advocate Dashboard > Dashboard* and add the **Tasks** element to display available tasks on the advocate dashboard.
* The **Choose Task** dropdown lists all tasks configured within the campaign * Once a task is selected, the widget preview automatically populates with the information configured for that task * Multiple Tasks elements can be added to the advocate dashboard ### Manage Task Submissions Once subscribers submit tasks, administrators can receive notifications, review submissions, and update task statuses from the ReferralHero admin dashboard. **Task Submission Notifications** Administrators can receive an email notification when a subscriber submits a task. To enable task submission notifications: 1. Go to *Manage Access*. 2. In the **Email Notifications** dropdown, select **New Task Submission Notification** for the administrator who should receive the notification.
Once enabled, the selected administrator will receive an email notification when a new task submission is received. **Task Statuses** Tasks can have the following statuses: * **Submitted**: The subscriber has submitted the task and it is waiting for review * **Approved**: The task submission has been approved * **Rejected**: The task submission has been rejected #### Managing Tasks from the Admin Dashboard Task submissions can be managed from two locations: * **Tasks** section in the admin dashboard * **Subscriber Profile** **Tasks Section** The **Tasks** section in the left navigation menu provides a centralized view of task activity.
Administrators can: * View submitted tasks * Review task details * Approve or reject tasks requiring manual approval * Monitor current task status **Subscriber Profile** The **Task Submissions** section displays submitted tasks for the subscriber.
Administrators can: * Review task submissions * Update task status when approval is required * View task history All task-related actions are logged in the subscriber timeline. # Rewards # Reward Types ReferralHero supports four types of rewards to help you design flexible and effective referral programs. Each reward type serves a different purpose and is suited for specific campaign strategies.
## Available Reward Types
Reward TypesWhat it isWho gets itWhere it appliesExample
Conversion BonusesConversion Bonuses are unlocked when a subscriber completes a conversion event (e.g. signs up, makes a purchase, books a demo).The person who completes the conversion event receives the reward.Available in both referral-based and points-based campaigns.A referred user signs up—this triggers a Conversion Bonus that is rewarded to the referred user.
Rewards for AdvocatesThese rewards are unlocked when a subscriber (the advocate) refers someone who goes on to complete a conversion event.The advocate who referred the new subscriber.Available in referral-based campaigns.An advocate receives a gift card after 3 of their referrals complete a conversion event such as signing up or making a purchase.
Rewards for SubscribersThese are points-based rewards unlocked when a subscriber earns a specific number of points. Points can be accumulated through conversion events and social actions (e.g. sharing on social media, referring friends).Any subscriber who reaches the required number of points.
Available in points-based campaigns.A subscriber earns 100 points by referring friends and sharing content on Twitter. They then unlock a reward such as a discount code.
Manual Rewards

Manually triggered rewards granted by an admin via the dashboard or API. These rewards are not automatically unlocked through system rules.

Manual Rewards support two configurations:

  • Promoted Rewards – triggered when a subscriber is promoted (e.g. leaderboard winners or ranked selections)
  • One-Off Rewards – manually granted one-time rewards not tied to promotion or ranking
Any subscriber, manually selected by the admin.
Available in both referral-based and points-based campaigns.

Promoted: You reward the top 5 subscribers in a weekly leaderboard

One-Off: You grant a one-time reward to a specific user for exceptional contribution

### Manual Reward Configurations Manual Rewards can be configured based on how and why they are granted. #### Promoted Rewards Typical use cases include leaderboard competitions or ranked campaigns where top performers are selected and rewarded. ✅ Learn more in the [Manual Rewards for Promoted Winners](https://support.referralhero.com/campaign-builder/templates/contest#manual-rewards-for-promoted-winners) section. #### One-Off Rewards One-Off Rewards are manually granted rewards that are not tied to promotion, ranking, or automated rules. They are used when an admin wants to issue a single, non-repeating reward to a specific subscriber outside of structured campaign logic. **Where to trigger One-Off Rewards:** One-Off Rewards can be issued from the following locations: 1. **Subscriber Profile (Campaign Info section)** * Go to the Campaign Info section * Click the 3-dot menu * Select *Send One-Off Reward* to issue a reward 2. **Subscriber Profile (Rewards Unlocked section)** * Navigate to the Rewards Unlocked section * Click *Send One-Off Reward* to manually assign a reward 3. **Reward Logs page** * Go to Reward Logs * Click *Send One-Off Reward* button to manually create and issue a reward 4. **REST API** * Issue One-Off Rewards programmatically using the Trigger Manual Rewards endpoint {% hint style="success" %} **Summary:** * **Conversion Bonuses** reward the action-taker (e.g. the referred user). * **Rewards for Advocates** incentivize those who successfully refer others. * **Rewards for Subscribers** drive ongoing participation through a points-based system. * **Manual Rewards** give admins full flexibility to reward engagement outside automated triggers. * All rewards will appear in the **Reward Logs** section, along with their current **Reward Status** (e.g. Pending, Sent, Canceled, etc). {% endhint %} ## Reward Availability by Campaign Goal Type | Campaign Type | Conversion Bonuses | Rewards for Advocates | Rewards for Subscribers | Manual Rewards | | ---------------------------------- | :----------------: | :-------------------: | :---------------------: | :------------: | | Referral-based (conversion only) | ✅ | ✅ | ❌ | ✅ | | Points-based (conversion + social) | ✅ | ❌ | ✅ | ✅ | # Reward Status The new Reward Status feature allows you to track the progress of all rewards. **Pending:** Rewards that have been unlocked but have not been sent to the recipient due to the Reward Delivery settings. **Sent:** Rewards that have been unlocked and sent to the recipient. **Resent:** Rewards that have been manually triggered to be sent again after already being sent once. **Canceled:** Rewards that were unlocked, entered into the pending status, and then were manually canceled. **Failed:** Rewards that could not be sent due to an issue, such as insufficient funds in your Tremendous account. **Flagged:** Rewards that have been marked for review due to potential issues, such as suspected fraud or unusual activity. {% hint style="info" %} Note: If the reward is manually Resent, the exact same reward/reward email is sent again. {% endhint %} You can view Reward Status in several locations: 1. Reward Overview > Timeline Log: displays all reward actions in chronological order 2. Reward Logs: provides a list view of all unlocked rewards 3. Subscriber Profiles: displays all rewards unlocked and related status by the subscriber ## Reward Logs You can select a reward status (All, Pending, Sent, Resent, Canceled, Failed or Flagged) and use the search bar to filter results. You can also order the rewards by date according to your filter or selection. Each reward will have an Action option that allows you to send or resend, as well as cancel, the reward.
## Subscriber Profiles Rewards Unlocked You can also find the Reward Status, Date Triggered, and Reward Value in the section Rewards Unlocked under the subscriber profile. Each reward will have an Action option that allows you to send or resend, as well as cancel, the reward.
# Reward Settings ReferralHero's advanced reward settings allow you to configure additional types of rewards and custom reward rules. These settings give you greater control over who receives rewards, when rewards are triggered, and how they’re delivered. ## Reward Overview Settings ### Manually Add Eligibility Enable this option to manually apply reward eligibility to specific advocates via their subscriber profile. * **By default** (when this is disabled), all subscribers are eligible for the reward. * **When enabled**, rewards will **not** be available to any subscriber unless eligibility is manually granted.
To manually assign reward eligibility: 1. Go to the subscriber profile 2. Click the 3-dot dropdown in the **Campaign Info** section 3. Select **Edit Info** 4. In the popup, check or uncheck rewards in the **Eligible Rewards** dropdown
## Reward Conditions Settings ### Reward Tiers Enable this option to set **minimum and maximum conditions** for a reward. Commonly used to increase reward amounts as users reach higher tiers. * **Referral count-based rewards**: Unlock the reward when the number of referrals falls between X and Y * **Transaction-based rewards**: Unlock the reward when the **total transaction value** of referred users falls between $X and $Y
**Example tier setup:** | Tier | Transaction Range | Reward | | :----: | :---------------: | :----: | | Tier 1 | $0–$200 | $5 | | Tier 2 | $201–$400 | $10 | | Tier 3 | $401–$600 | $15 | * At $80 → Tier 1 is unlocked * At $400 → Tier 2 is unlocked * At $500 → Tier 3 is unlocked {% hint style="success" %} **NOTES:** * The *referrals’ accumulated transaction value* is the sum of **all** referred users’ transaction amounts. * All values are **inclusive**. To avoid triggering multiple rewards at once, make sure the same number isn't used as both the upper limit of one tier and the lower limit of the next (e.g., avoid using $200 as both the upper limit of $0–$200 and the lower limit of $200–$400). {% endhint %} ### **Time-Based Reset Period** When enabled, referral counts used for unlocking rewards automatically reset at the start of each selected calendar period. This condition only applies if the reward is triggered by **generating a referral** (not available when triggered by referral transactions).
**Options:** * **Monthly** – Referral counts reset on the first day of every month * **Quarterly** – Referral counts reset on the first day of each calendar quarter (Jan 1, Apr 1, Jul 1, Oct 1) * **Yearly** – Referral counts reset on the first day of every year (Jan 1) **Example:** * **Reward trigger:** Every 1 referral * **Reward tiers:** * Tier 1: 1–3 referrals → Reward value: 1000.00 * Tier 2: 4–7 referrals → Reward value: 1500.00 * Tier 3: 8+ referrals → Reward value: 2000.00 * **Time-based reset period:** Monthly * **Behavior:** A reward from the appropriate tier is unlocked every time a referral is added during August. At the start of September, referral counts reset, and new rewards begin tracking for the month * Rewards triggered under “Reward Reset” for Tier 1 (1000.00), Tier 2 (1500.00), and Tier 3 (2000.00) * On Aug 27, confirmed rewards were **sent** for Tier 1–3 depending on referral counts * On Sep 8, new rewards were **triggered again** for Tier 1–3, showing the reset in action
### Subscriber Tag Apply tag-based restrictions to this reward to limit eligibility to specific segments. * **Advocate Tag**: Filters who can earn the reward * **Referral Tag**: Filters who can trigger the reward **Tag match options:** * **ALL** – Includes all subscribers (tagged and untagged) * **ANY** – Includes only subscribers with at least one tag * **NONE** – Includes only untagged subscribers
### **Date Range** When enabled, this condition restricts a reward to only be earned within a specified date range. This condition is available for both reward triggers: **generating a referral** and **referral transactions**.
**Configuration:** * **Start Date** – The first date when the reward can be earned * **End Date** – The last date when the reward can be earned {% hint style="success" %} **NOTE:** Dates are **inclusive**, meaning rewards can be unlocked on both the start date and the end date. {% endhint %} **Example:** * **Reward trigger:** Every 1 referral * **Date range:** Aug 09, 2025 – Aug 31, 2025 * **Behavior:** Rewards are only unlocked for referrals generated within the defined period (Aug 09–Aug 31). If a referral is added on Sep 1 or later, no reward will be triggered. ### Conversion Value Enable this to unlock a reward only when the referred user’s conversion amount exceeds a defined threshold. **Example:**\ Unlock a reward only if the referred user spends more than **$50**.
## Product Condition Settings Unlock the reward only when a referred subscriber purchases a specific product. A single reward can include multiple eligible product IDs, and **ANY** of the listed products will count toward unlocking the reward. This applies to all reward types (conversion bonus, transaction reward, and referral-based advocate rewards). {% hint style="success" %} **NOTE:** If Reward Tier conditions are enabled, tier calculations aggregate totals across all listed product IDs. {% endhint %} Supported methods: * **Product ID**: Matches a product ID sent via the API or added manually in the **Transactions** section * **Stripe Product**: If using Stripe integration, the reward is unlocked when the designated Stripe product is purchased Useful when rewards should only be issued for specific product purchases, now with the flexibility to include multiple products under a single reward.
## Reward Value Settings Enable this to define the reward amount given when the reward is unlocked. This can be a fixed amount, percentage, or custom item depending on your reward delivery method (e.g., gift card, coupon, manual credit, etc.).
{% hint style="success" %} **Notes:** * If selecting ‘**percentage of referral conversion value’**, the conversion value must be set in the subscriber profile to calculate the reward value. Otherwise, the reward value will return as 0. * If selecting ‘**percentage of each transaction**’, the transaction amount must be set in the Transactions section to calculate the reward value. Otherwise, the reward value will return as 0. * This feature is not available in points-based campaigns. {% endhint %} ## Reward Duration Settings 1. **For referral-based campaigns** 1. **Referral count-based rewards**:\ Enable duration to allow the same reward to unlock multiple times over a set time period. 2. **Transaction-based rewards**: \ Enable duration to make the reward recur based on referred user transactions. You can set a maximum total reward value per referral. **Example:**\ An advocate earns 10% on every referral transaction, up to a maximum of $100 per referral. If a referral completes 12 transactions at $100 each: 1. The advocate earns rewards for the first 10 transactions only (10 × $10 = $100). 2. Rewards for transactions 11 and 12 will not be unlocked.
{% hint style="info" %} This feature is not available when using Reward Tiers. {% endhint %} 2. **For points-based campaigns:** Enable duration to allow the same reward to unlock **multiple times** over a time period. The reward will recur at the specified interval, for a set number of times. ## Reward Delivery Settings Choose how and when rewards are released: * **Immediately upon unlocking**, or * **After a time delay**, which includes: * Held until manually reviewed and released * Held for a specified number of days before being released These delays act as a security buffer to ensure the referral passes a refund or chargeback window. When a delay is applied, rewards are unlocked with a **Pending** status. Pending rewards can be sent or canceled at any time from the ReferralHero dashboard. (Reward notifications can also include a **QR code**, allowing authorized users to scan and securely update the reward status. This provides an additional way to manage Pending rewards before they are marked as Sent. For full details, see the [Reward QR](https://support.referralhero.com/campaign-builder/automations/reward-qr) support guide. ) #### **Additional Delivery Options** * **Group reward payouts and hold until** *(available if a reward value is set)*:\ Unlocked rewards can be grouped and released together either: * When manually reviewed and released, or * When a specified payout amount is reached * **Stripe integration** *(available if Stripe integration is enabled)*: \ Hold unlocked reward for **set days**, and if the **Stripe customer is active**, send the reward—otherwise, cancel it. This helps ensure the referral is valid and the customer remains active.
## Advanced Reward Settings Examples **Example 1** Reward Value: $10 fixed amount\ Reward Frequency: recur every 1 month, total 3 times\ Reward Delivery: release immediately
REWARDTRIGGER DATESENT DATESUBSCRIBERVALUETOTALSTATUS
NameApr 19, 2023Apr 19, 2023Email1010 of 30Sent
NameApr 19, 2023Est. May 19, 2023Email1020 of 30Pending
NameApr 19, 2023Est. Jun 19, 2023Email1030 of 30Pending
**Example 2**\ Reward Value: 10% of the conversion value\ Reward Frequency: $300 conversion value, recur every 1 month, total 3 times\ Reward Delivery: release immediately
REWARDTRIGGER DATESENT DATESUBSCRIBERVALUETOTALSTATUS
NameApr 19, 2023Apr 19, 2023Email3030 of 90Sent
NameApr 19, 2023Est. May 19, 2023Email3060 of 90Pending
NameApr 19, 2023Est. Jun 19, 2023Email3090 of 90Pending
{% hint style="success" %} Note: If a reward triggers every time a subscriber refers three referrals and the reward value is based on the percent of referral conversion value, the sum of all three referral conversion values will be used to calculate the reward value. {% endhint %} # Group Rewards Group Rewards allow multiple unlocked rewards to be combined and released together. This keeps delivery consistent, reduces payout frequency, and ensures integrations work correctly. This feature is especially useful for monetary rewards and campaigns with multiple reward tiers. ### How It Works When setting up a reward, you can enable **Group Rewards**: * **Reward Value** → Toggle **Activate reward value** ON and assign a value * **Reward Delivery** → In **Group reward payouts and hold until**, choose one of: * Amount is reached then release * Manually reviewed and released * The 1st of every month then release * The 1st and 15th of every month then release #### Group Reward Rules Once Group Rewards are enabled, the following rules apply consistently across all grouped rewards: | **Setting** | **Behavior** | | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | | **Issue Tremendous reward** | Issued once per Group Reward | | **Activate coupon code** | Issued once per Group Reward | | **Apply Stripe credit** | Credit values from each reward are summed, and the total is applied once to the subscriber’s Stripe account | | **Stripe coupons** | Only one coupon is issued to the subscriber’s Stripe account, regardless of how many rewards are grouped | | **Group Reward delivery method** | Rewards exceeding $2,000 are automatically split into smaller groups | | **Notify subscriber** | One email or SMS is sent per Group Reward. The `%group_payout_reward_value%` merge tag displays the total combined value | #### Stripe Coupons Setup All of the settings listed in the **Group Reward Rules** table are configured within the reward setup, except for Stripe coupons. To configure Stripe coupons for Group Rewards: 1. Go to Integrations > Stripe 2. In the Stripe reward coupons section, click Add reward coupon
3. In the When reward is sent dropdown, select Group Reward 4. In the Apply Stripe coupon dropdown, select the Stripe coupon to be applied 5. Click Apply Coupon to save your changes
### Tracking Rewards Each unlocked reward is still logged individually in **Reward Logs**
ReferralHero combines these into a **single Group Reward**, visible in the [**Group Payouts**](https://support.referralhero.com/campaign-management/rewards/group-payouts) section
### Examples #### **Example 1: Threshold-Based Group Payout** **Reward 1:** $25 fixed amount; Group Reward ON > *held until $75 threshold is reached* **Scenario:** * Each $25 reward is logged individually in Reward Logs * Once 3 rewards accumulate ($25 × 3 = $75), the Group Reward is released * A Group Reward entry is created in Group Payouts **Result:**\ ➡️ A single **Group Reward of $75** is created and delivered
#### **Example 2: Multiple Reward Types Combined** **Reward 1:** Unlocks at every 1 pending referral → $10; Group Reward ON > *Manually Reviewed and Released*\ **Reward 2:** Unlocks at every 1 confirmed referral → $20; Group Reward ON > *Manually Reviewed and Released* **Scenario:** * An advocate refers 10 people * 6 confirmed, 4 pending **Reward Calculation:** * Pending referrals: 10 × $10 = $100 * Confirmed referrals: 6 × $20 = $120 * Combined total = $220 **Delivery:** * Admin reviews and approves payout **Result:**\ ➡️ A single **Group Reward of $220** is created and delivered #### Example 3: Stripe Coupons vs Stripe Credits **Reward 1:** Unlocks at 2 referrals → $10 Stripe credit; Group Reward ON\ **Reward 2:** Unlocks at 4 referrals → 1 Stripe coupon; Group Reward ON **Scenario:** * Advocate reaches 4 referrals **Reward Calculation:** * At 2 referrals → $10 Stripe credit added * At 4 referrals → 1 Stripe coupon added * Combined into single Group Reward **Result:**\ ➡️ The **Group Reward** contains **one Stripe coupon** and **a $10 Stripe credit**, delivered together in the subscriber’s Stripe account # Transactions ReferralHero supports ongoing transaction tracking, allowing you to reward advocates for transactions completed by their referrals. This is ideal for affiliate programs where commissions are based on recurring or one-time purchases. {% hint style="info" %} This feature is only available when your campaign **Goal** is set to **Conversion Event**. {% endhint %} ### Sending Transaction Data When a referred subscriber completes a transaction, ReferralHero can automatically reward the advocate based on that transaction. Transaction data can be sent to ReferralHero using any of the following methods: * **Stripe** (native integration) * **JavaScript API** * **REST API** * **Manual entry** via the dashboard Each transaction is logged with detailed information, enabling accurate tracking and reward issuance. ### Transaction Log All successful transactions are recorded in the **Transactions** tab under **Reward Logs**. Each entry includes: * **Time**: When the transaction was logged * **Subscriber**: The person who completed the transaction * **Type**: Indicates whether the transaction is a referral * **Transaction ID**: Stripe Payment ID or one provided via API * **Transaction Amount**: The total amount of the transaction * **Product ID** *(optional)*: The ID of the product * **Reward ID** *(if applicable)*: The ID of the reward that was triggered * **Reward Value** *(if applicable)*: The value of the reward issued {% hint style="info" %} If our Stripe integration is being used, we save the `payment_intent` and `amount` from the `charge.succeeded` event, which represents the Payment ID and Payment Amount for a Stripe transaction. {% endhint %}
### Setting Up Affiliate Rewards To configure how and when advocates are rewarded for referred transactions: **1. Enable Transaction-Based Rewards** Toggle ON the setting: > Unlock reward on referral transactions\ > Reward the advocate for each transaction by a \[conversion event 1 / 2 / 3] referral. This determines which referral status qualifies for rewards (e.g., confirmed referrals only).
**2. Define Reward Value** Choose how the reward is calculated: * **Fixed amount**: e.g., $10 per transaction * **Percent of transaction**: e.g., 10% of each transaction * **Defined in transaction**: Provide a `reward_value` directly via the API
**3. Set Reward Duration** Determine how long rewards should be issued: * **By number of transactions**: e.g., reward the first 3 purchases * **By time period**: e.g., reward all transactions within 6 months * **Maximum total reward value**: Set a cap on the total rewards given per referral
# Widget Builder The ReferralHero Widgets are our ready-made components that can be quickly inserted into your page to display the signup form, the sharing screen, and more. We currently have five embeddable widgets: * ReferralHero Advocate Dashboard * ReferralHero Referral Signup Widget * ReferralHero Referral Welcome Banner * ReferralHero Sharing Widget * ReferralHero Source Capture * ReferralHero Floating Button You can use one or more on your website/web app to have a quick way to allow people to sign up for your referral program, get their referral link, and check their status. {% hint style="warning" %} **IMPORTANT** * If your website undergoes a major design change where themes and template files are replaced or content in your `` tags or anywhere else the Tracking Code is installed are replaced, it's a possibility you will need to re-install the Tracking Code. * The ReferralHero Dashboard, Signup, Floating Widget, or Javascript API [RHform.submit()](/integrate/javascript-web-api/adding-a-subscriber-manually) can only be used **once on a single webpage**. Do not add them multiple times on the same webpage. {% endhint %} ### Advocate Dashboard (Recommended) This widget can be embedded or triggered as a popup in your website/web app, or used as a standalone landing page. It features a signup form (bypassable if subscribers are identified via our API) and a Dashboard. Designed to promote engagement in your campaign, it provides access to a personal dashboard where subscribers can find their referral link or QR code, track referrals, view rewards, or check the leaderboard. This is how the user will experience this widget: 1. The signup form is first shown (bypassable if subscribers are identified via our API) 2. The Dashboard is shown after a successful signup
{% hint style="warning" %} If the [email confirmation requirement is enabled](/campaign-builder/unique-identifier/confirmation-email), the user signing up must confirm their email before they will be added to your campaign. {% endhint %} **To install the Dashboard Widget on your website:** 1. Go to your *Campaign Overview> Edit Campaign > Launch* and copy your **Global Tracking Code** 2. Add the ReferralHero Global Tracking Code to your site so that it loads on each webpage. This is typically done by adding it to the `` section of your website 3. Paste `
` exactly where you want the widget to appear on your page. It must be within the `` of your page. ```markup
``` ### Referral Signup Widget This widget can be embedded into your website or used as a standalone landing page. It features a dynamic message or signup form, specifically designed to engage and convert identified referrals. Use this widget if you: * Want to display a different marketing message or landing page to inbound "friends" signing up for your campaign (ex. someone special thought about you, sign up and get your coupon code). * Want multiple places to capture leads on your website (ie. you want to add a signup form at the bottom of each of your blog posts). This is how the user will experience this widget: 1. The signup form is first shown 2. The confirmation screen is shown after a successful signup
{% hint style="warning" %} If the [email confirmation requirement is enabled](/campaign-builder/unique-identifier/confirmation-email), the user signing up must confirm their email before they will be added to your campaign. {% endhint %} **To install the Signup Widget on your website:** 1. Go to your *Campaign Overview > Edit Campaign > Launch* and copy your **Global Tracking Code** 2. Add the ReferralHero Global Tracking Code to your site so that it loads on each webpage. This is typically done by adding it to the `` section of your website 3. Paste `
` exactly where you want the widget to appear on your page. It must be within the `` of your page. ```markup
``` ### Referral Welcome Banner This banner is displayed on the top or bottom of your website. It features a dynamic message or signup form, specifically designed to engage and convert identified referrals. This is how the user will experience this widget: 1. The signup form is first shown (to **Referrals Only** or **Non-Referrals Only**) 2. The confirmation screen is shown after a successful signup
**To install the Welcome Banner on your website:** 1. Go to your *Campaign Overview > Edit Campaign > Launch* and copy your **Global Tracking Code** 2. Add the ReferralHero Global Tracking Code to your site so that it loads on each webpage. This is typically done by adding it to the `` section of your website 3. Go to your *Campaign Overview> Edit Campaign > Launch > Step #3 > Referral Welcome Banner > Toggle ON* 4. Decide if you want the widget to display for **Referrals Only** or **Non-Referrals Only**
### Sharing Widget {% hint style="warning" %} This widget is identical to the Advocate Dashboard, except no new subscribers can sign up directly through the widget. For that reason, it's recommended to use the Advocate Dashboard for most setups. {% endhint %} Install this widget if you want a place to show current subscribers their participation status in your campaign where they can get their unique referral URL, check their number of referrals, and see any rewards that have been unlocked. Use this widget if you: * Want a stand-alone landing page to host your referral program for people who are **already signed up**. * Plan to use your own signup form and want to redirect people to another page with the Sharing Widget. * Have identified the user by other means and want to show the Sharing Widget (ex. you require a login into your web app, identifying the user, therefore they don't need to "sign up to our widget" and can be just shown the Sharing Widget). {% hint style="warning" %} People not already subscribed to your campaign will not be able to sign up through this widget and will receive an "email not found error message". {% endhint %} This is how the user will experience this widget: 1. The subscriber is identified automatically. If the subscriber is not able to be identified automatically, they will be prompted to check their status or "login" 2. The sharing screen is shown
**To install the Sharing Widget on your website:** 1. Go to your Campaign Overview > *Edit Campaign > Launch instructions* and copy your **Tracking Code** 2. Add the ReferralHero Tracking Code to your site so that it loads on each webpage. This is typically done by adding it into the `` section of your website 3. Paste `
` exactly where you want the widget to appear on your page. It must be within the `` of your page. ```markup
``` ### Source Capture A popup or embedded widget that asks visitors how they heard about you and who referred them. It helps collect self-reported attribution data to improve referral tracking accuracy. This widget can be used in two ways: * Embedded directly into a page using a `
` (same approach as other widgets) * As a ReferralHero-hosted standalone landing page This is how the user will experience this widget: 1. The visitor selects how they heard about the product or who referred them 2. They proceed through a short guided flow to confirm and submit their information 3. Submission is captured and linked to referral attribution data where available
**To install the Source Capture Widget on your website:** 1. Go to *Campaign Overview > Edit Campaign > Launch* and copy your **Global Tracking Code** 2. Add the ReferralHero Global Tracking Code to your site (typically in the `` section) 3. Paste the widget container where you want it to appear. It must be within the `` of your page. ```
``` **Behavior Notes:** * If referral or visitor data is already available, the widget may skip early steps and proceed directly to confirmation or success states * If partial data exists, fields will be prefilled when available * Submitted data is stored and associated with existing subscriber profiles when applicable * If a subscriber already exists, their existing profile is reused instead of creating duplicates * If the widget is closed mid-flow, available data may still be captured and processed automatically ### Floating Button The Floating Button is a button fixed on the screen and overlays your webpage. Install this widget if you want to allow your users to sign up from any page on your website. Use this widget if you: * Want a 'call to action' to join your referral program to appear on every page of your website. This is how the user will experience this widget: 1. The Floating Button is clicked 2. The Advocate Dashboard will appear in the form of a popup. {% hint style="warning" %} The Floating Button only shows on pages where you DO NOT use the Advocate Dashboard, Signup, or Sharing Widget. If the Floating Button and the other ReferralHero Widgets are on the same page the other Widgets will be given precedence and the Floating Button will not appear. {% endhint %} ![](/files/-LugifgSCrVyWfSNyO1A) **To install the Floating Button on your website:** 1. Go to your *Campaign Overview > Edit Campaign > Launch instructions* and copy your **Tracking Code** 2. Add the ReferralHero Tracking Code to your site so that it loads on each webpage. This is typically done by adding it into the `` section of your website 3. Go to your *Campaign Overview > Edit Campaign > Launch > Step #2 > Section D* 4. Click on the toggle **Enable Floating Button** and customize the text and color of the button 5. Changes will be saved automatically {% hint style="success" %} **NOTE:** The **Default Button Label** (e.g. "Join our referral program") will automatically change to the **Identified Subscriber Button Label** (e.g. "Share your link") once the subscriber is identified. {% endhint %}
### Customize the widget Our widget editors will give you the ability to customize the look and feel of either widget to match your brand guidelines. However, if you are looking for some additional stylizing options you can do this through CSS. **To edit the CSS of the widget(s):** 1. Go to you *Campaign Overview > Edit Campaign > Widget Builder > Signup Form or Dashboard > Template Settings > Advanced Options > Custom CSS* 2. Enter the following element(s) in the **Custom CSS** field and add the custom styling. To see a [list of the customizable CSS elements and some examples click here](https://github.com/maitre-app/style.css/blob/main/example). #### Note on changing the font for the widgets: ReferralHero's embeddable widgets automatically use the font set for the parent container, however sometimes this means that the wrong font is used. This example would change the font of both widgets: ```css .mtr-optin-form *, .mtr-sharing-screen * { font-family: 'Nunito' } ``` Don't forget to change 'Nunito' with the font-family you want to use. # 'Quick Add' Referral The 'Quick Add' Referral feature is a way for current subscribers to directly add referrals through the ReferralHero Widget. Depending on your settings, these new subscribers can be directly added or given the option to opt-in to your ReferralHero campaign. This feature gives you the ability to grow your subscriber list faster and follow up with these new subscribers in various ways. Here are a few examples of why you might want to use this feature: 1. **Generating Leads Fast** You incentivize customers to provide leads and relevant contact information so you can do the follow-up. ie. You're a SAAS business. A current customer refers or ‘Quick Adds’ a lead and your sales team can directly follow up, instead of hoping the lead contacts you. 2. **Mass Brand Exposure** You have customers who are willing to immediately provide friends' contact information in exchange for a reward. ie. You're an e-commerce business. You ask current customers to refer or ‘Quick Add’ 5 friends by providing their contact info and you can send a branded email asking them to opt-in and join your newsletter, follow on social, etc. 3. **Offline Service/Product** You have customers who want to refer people but asking them to "share a link" is not ideal for one reason or another. Instead, they can directly submit leads and get credit for the referral(s). ie. You're a plumbing company and incentivize customers to refer neighbors. The customer recommends your plumbing service in a conversation with a friend and later submits or ‘Quick Adds’ their information. 4. **Team Events** You host team events and one of the participants can directly add other members and get credit for the referral(s). ie. You're a website that organizes team events (relay races, group fundraisers, etc.). The team leader can invite or ‘Quick Add’ other team members and get a reward for each person who joins. These are only a few of the many use cases for this feature. Please let us know by emailing if you are using this feature in a different way! ## How to enable the 'Quick Add' Referrals feature? 1. Go to your campaign dashboard > Edit Campaign > Widget Builder > Dashboard 2. Add the 'Quick Add’ Form element to the Dashboard 3. Save the changes
{% hint style="warning" %} **NOTE:** By default, “Quick Add” referrals are added immediately to your campaign. If you also enable the **'Quick Add' Invitation Email**, the lead will be invited to opt in before being added. Otherwise, “Quick Add” referrals will follow your existing campaign rules (such as [Manual Review](/campaign-management/subscribers/subscriber-profile/manual-review) or [Automation Emails](/campaign-builder/automations)). {% endhint %} Please see [Quick Add Referral Verification](https://support.referralhero.com/campaign-builder/unique-identifier/quick-add-referral-verification) for full instructions on enabling the Quick Add Invitation Email. # Automations Automations are our built-in, behaviour-triggered messages — sent via **email/SMS** — that keep subscribers informed, engaged, and rewarded throughout your referral campaign. ReferralHero offers **14 powerful automations out of the box** (the most in the industry), with more coming soon. ### Welcome Automations Sent to new subscribers based on their referral status and your campaign’s conversion goal. | Message | Subscriber Type | Description | | -------------------------------- | -------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | | **Verification Message** | Non-referrals & referrals (based on setting) | Sent to subscribers to **verify** their email or phone number. | | **Welcome Message** | Non-referrals Only | Sent to subscribers who have not been referred when they are **added to your campaign**. | | **Referral Welcome Message** | Referrals Only | Sent to referrals if your campaign tracks only one conversion event, or when they complete the final conversion event in a multi-step campaign. | | **Pending Welcome Message** | Referrals Only | Sent to referrals after completing the **first** conversion event in a campaign that tracks two or three events. | | **Follow-Up Message** | Non-referrals & referrals | Sent to subscribers **after a set amount of time** (e.g., 6 hours) after signup. | | **Activation Message** | Non-referrals & referrals | Sent to subscribers **who haven’t referred anyone** after a set time (e.g., every 30 days). | | **Quick Add Invitation Message** | Referrals Only | Sent to referrals added through the **Quick Add** feature. | ### Participation Automations Triggered when advocates actively participate by referring others. | Message | Subscriber Type | Description | | ---------------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------ | | **First Referral Message** | Any | Sent to advocates when they refer their **first** friend. | | **Referral Message** | Any | Sent to advocates when they **generate a referral**, except the first (which triggers the First Referral Message). | | **Referral Visitor Message** | Any | Sent to advocates when a **unique referred visitor clicks their referral link**. | | **Milestone Message** | Any | Sent to advocates when they **reach a specific number of referrals** (e.g., 5 referrals). | | **Reminder Message** | Any | Sent to advocates who **haven’t referred anyone in a while** (e.g., 30 days since last referral). | ### Reward Automations Triggered when a subscriber qualifies for or is manually given a reward. | Message | Subscriber Type | Discription | | -------------------------------- | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Reward Message** | Any | Sent when a subscriber **unlocks a reward**. One message per reward, unless rewards are grouped (then one message for the group). | | **Promoted Reward Message** | Any | Sent when a subscriber is manually **promoted via the dashboard or API**. | | **Connect Bank Account Message** | Any | Sent when a subscriber **unlocks a reward** that's been configured to send a **cash payout**. Learn more [here](https://support.referralhero.com/campaign-builder/integrations/cash-payouts#subscriber-bank-connection-workflow). | ### Email Builder ReferralHero uses an email builder that supports both simple editing and advanced customization. You can edit emails using the visual editor, which supports text editing, personalization using merge tags, and full layout control. For advanced customization, you can also use custom HTML. #### **Custom HTML** If you want full control over design and styling, you can insert your own HTML. To use custom HTML: **Step 1:** Click the **Source code** button (second from the right in the toolbar)
**Step 2**: Paste your HTML code into the popup and save your changes ### Merge Tags A merge tag looks like a snippet of text. ReferralHero replaces that text with the dynamic content the merge tag refers to, like the person name or email. This is the complete list of available merge tags:
Merge tagDescription
%name%Subscriber's name
%email%Subscriber's email address
%crypto_wallet_address%Subscriber's Crypto wallet address
%phone_number%Subscriber's phone number
%confirmation_link%Quick add invitiation email confirmation link
%referrer%Referrer's name if present otherwise Referrer's email address
%reward_value%Reward value
%referral_code%Subscriber's unique referral code
%position%Subscriber's position in list (Eg: 5)
%position_ordinal%Subscriber's position in list in ordinal number (Eg: 5th)
%people_ahead%Number of people ahead in the queue
%referral_link%Subscriber's referral link
%total_referred%Subscriber's total number of referrals
%subscriber_id%Subscriber's id.
%coupon%A unique random coupon code from a Coupon Group of your choice
%group_payout_reward_value%Group payout reward value
%tremendous_reward_link%A unique Tremendous reward link.
%facebook_link%Referral link with source set to "Facebook"
%facebook_icon%Facebook icon with a link to share on Facebook.
%facebook_share_link%Facebook link to share via Facebook.
%twitter_link%Referral link with source set to "Twitter"
%twitter_icon%Twitter icon with a link to share on Twitter.
%twitter_share_link%Twitter link to share via Twitter.
%email_link%Referral link with source set to "Email"
%email_icon%Email icon with a link to share via email.
%email_share_link%Email link to share via email.
%whatsapp_link%Referral link with source set to "Whatsapp"
%whatsapp_icon%Whatsapp icon with a link to share on Whatsapp.
%whatsapp_share_link%Whatsapp link to share via Whatsapp.
%facebook_messenger_link%Referral link with source set to "Facebook Messenger"
%facebook_messenger_icon%Facebook Messenger icon with a link to share on Facebook Messenger.
%facebook_messenger_share_link%Facebook Messenger link to share via Facebook Messenger.
%linkedin_link%Referral link with source set to "Linkedin"
%linkedin_icon%Linkedin icon with a link to share on Linkedin.
%linkedin_share_link%Linkedin link to share via Linkedin.
%reddit_link%Referral link with source set to "Reddit"
%reddit_icon%Reddit icon with a link to share on Reddit.
%reddit_share_link%Reddit link to share via Reddit.
%telegram_link%Referral link with source set to "Telegram"
%telegram_icon%Telegram icon with a link to share on Telegram.
%telegram_share_link%Telegram link to share via Telegram.
%line_link%Referral link with source set to "Line"
%line_icon%Line icon with a link to share on Line.
%line_share_link%Line link to share via Line.
%advocate_dashboard%Link to the advocate's dashboard
%advocate_first_name%Advocate's first name
%advocate_last_name%Advocate's last name
%advocate_tag%Advocate's tags (comma-separated)
%tag%Subscriber's tags (comma-separated)
%extra_field%Subscriber's extra field 1
%extra_field_2%Subscriber's extra field 2
%extra_field_3%Subscriber's extra field 3
%extra_field_4%Subscriber's extra field 4
%first_name%Subscriber's first name
%last_name%Subscriber's last name
%last_referral_name%Name of last referral
%referral%Referrals for which reward/automation is unlocked
%total_positions%Total positions in the list
### Test Message ReferralHero allows you to send test messages — for both email/SMS — before launching your automation. To send a test: * Scroll to the bottom of the automation editor. * Enter an email address or phone number. * Click Send Test Email/SMS. {% hint style="warning" %} ReferralHero will send the latest saved version of your message, so make sure to save your work before sending a test. {% endhint %}
# A/B Testing Automations When it comes to engagement, even small variations to your automation emails can have a big impact. With A/B testing, you have a way of determining what your participants are positively responding to, giving you better insights to optimise your automation emails. ### What Is A/B Testing? **A/B testing is a way to compare two versions of a single variable** (in this case, the subject line of an email)**, by testing a Subscriber’s response to variable A against variable B.** In layman terms, it means that you create two subject lines for an email (Version A and Version B), and ReferralHero will send a random version to each subscriber. This ensures that the test is randomised and holds statistical significance. ### How to run an A/B test **ReferralHero allows you to A/B test the Subject Line of your Automation emails**.\ To enable A/B testing for an Automation email: * Go to your campaign dashboard > Edit Campaign > Automations > email you want to use for the A/B test (e.g: the Welcome email) * Switch the toggle **A/B Test Subject Line** * A second field for Version B of your subject line will appear * Enter an alternate subject line * Save your changes
### How to stop an A/B test To stop an A/B test, simply switch off the toggle **A/B Test Subject Line** and save the changes. {% hint style="warning" %} **IMPORTANT**\ When you stop a running A/B test, all the stats about the test will be lost. Before you cancel it, make sure to check the reports located in your account, Analytics -> Automations. {% endhint %} ### How to determine a winner After you start an A/B test for an email, ReferralHero will automatically begin collecting stats. You can view the report at any time by navigating to *Analytics > Automations*.
Since we are only A/B testing the subject line, the number we are interested in is the open rate. In this case, Version A has a 77.8% open rate versus a 60% open rate for Version B. Version A is the winning version. You should stop the A/B test and use Version A’s subject line as your main subject line. **When should you be confident enough to pick a winner?** It's really up to you to decide when an A/B test produces significant results, but we think you can confidently pick a winner when you have *sent at least 1K emails* for each version and the *difference between the open rates is at least 10%*. # Delay Welcome Message The Delay Welcome Message feature lets you schedule welcome messages to new subscribers. Messages can be sent immediately, or after a set number of hours or days. This applies to both Welcome Email and Welcome SMS messages and works consistently for all **non-referrals**, regardless of how they join a campaign (import, form signup, or API). ### Settings In the Welcome Email/SMS settings, select: * **Send this email/SMS:** `[Immediately / X hours / X days]`
{% hint style="success" %} **NOTES:** * A subscriber’s message is canceled if they unsubscribe, are deleted, or become a referral before the scheduled send time. * Only one scheduled Welcome Email/SMS per subscriber can exist at a time. {% endhint %} ### Send Timing #### Hour-Based Delays * **Email:** Sent at the next hour-aligned `:00` after the delay period.\ **Example:** Subscriber added at **07:18**, 1-hour delay → Email sent at **09:00**. * **SMS:** Sent exactly X hours after the subscriber is added.\ **Example:** Subscriber added at **07:18**, 1-hour delay → SMS sent at **08:18**. #### Day-Based Delays * **Email:** Sent on the scheduled day at the next hour-aligned `:00` after the day delay.\ **Example:** Subscriber added on **March 1 at 07:18**, 1-day delay → Email sent on **March 2 at 08:00**. * **SMS:** Sent on the scheduled day at 9:00 AM local country time.\ **Example:** Subscriber added on **March 1 at 07:18**, 1-day delay → SMS sent on **March 2 at 09:00** country time**.** {% hint style="success" %} **NOTE:** SMS scheduling detects **country only** (not state or city). For example, any U.S. number (+1) defaults to **America/New\_York (Eastern Time)**, even if the subscriber is in a different U.S. time zone. {% endhint %} #### Changing Send Timing If you update the Welcome Email/SMS settings after some subscribers already have scheduled messages: * **Existing subscribers** remain on their original schedule. * **New subscribers** follow the updated schedule. # Reward QR The Reward QR feature in Automations lets you control when a reward notification is sent and enables QR-based reward status updates. With this feature, you can: * Send reward email/SMS at either the **Pending** or **Sent** stage * Include a QR code in the reward message * Update reward status by scanning the QR code, with secure login verification This is ideal for manual or offline reward fulfillment where confirmation is required before marking a reward as sent. ### Reward Delivery and Automation This feature is available when **Reward Delivery** is set to **“Hold”.** In the Automation Setup, select when the reward email/SMS should be sent:
* **Unlocked (Pending)** → send reward when it reaches the Pending stage * **Sent** → send reward after the status is updated to Sent If **Pending** is selected, the toggle **Send QR Code to Update Reward Status** allows the reward message to include a QR code. Scanning this QR code lets authorized users update the reward status securely.
{% hint style="success" %} **NOTE:** 1. The **"Send when this reward is \[Sent / Unlocked]"** option does not appear if Reward Delivery is set to immediate. 2. The toggle **"Send QR Code to Update Reward Status"** does not appear if **"Send when this reward is"** is set to **Sent**. 3. For email automations, this feature is available only in **Basic Mode**. {% endhint %} ### QR Code Workflow Scanning the QR code follows this process: 1. Scan QR code 2. Login required (ReferralHero account) 3. View update screen with subscriber and reward details 4. Update reward status 5. Save changes #### QR Update Screen
**Editable fields:** * Name * Email * Phone * Reward Status **Read-only fields:** * Type * Reward Saving changes to the **Reward Status** updates the reward in the system. # Options # Tracking This section gives you control over how referrals are attributed and how long advocate cookies are valid. ### Attribution Model The Attribution Model determines which advocate gets credit for a referral when a conversion occurs. You can choose between two models: 1. First Touch Attribution\ Credits the first advocate who introduces your brand to the referral. Use this if you want to reward discovery and reach—ideal for expanding your audience and rewarding those who spark initial interest. 2. Last Touch Attribution\ Credits the last advocate who successfully drives the referral through your first conversion event. Choose this if your focus is on final impact, giving credit to advocates who play a crucial role in converting referrals.
The `%advocate_first_name%` merge tag in widgets will automatically display the appropriate advocate’s name based on the selected attribution model. * If you're using First Touch Attribution, `%advocate_first_name%` will always display the first advocate who originally referred the visitor to your site. This ensures that the advocate who introduced your brand gets consistent credit and visibility. * If you're using Last Touch Attribution, `%advocate_first_name%` will instead display the most recent advocate who referred the visitor before their first conversion event. This emphasizes the final and most impactful interaction that led to the conversion. {% hint style="success" %} **NOTE:** This is an **account-level** setting. Changing it will update the attribution model across all campaigns in your account. Only one advocate cookie is created per visitor. {% endhint %} ### Cookie Window The Cookie Window determines how long an advocate's tracking cookie remains valid for a referred visitor. By default, the cookie window is set to 90 days, meaning advocates can receive credit for conversions that happen up to 90 days after their referral link is clicked.
{% hint style="success" %} **NOTE:** This is a **campaign-level** setting. Any changes made will apply only to the campaign you're editing—other campaigns will maintain their own cookie window settings. {% endhint %} # 1-Click Signup The 1-Click Signup feature allows subscribers to sign up for your referral program within your email or newsletter with a single click. It removes the need for a complicated signup and confirmation process for your existing contacts. You can include the 1-Click Signup link in your own newsletter or any cross-promotional email lists to increase the opt-in rate and create a seamless signup experience for your potential new referral program subscribers. You might want to use this feature if you already have a list of email subscribers and are looking for an alternative to the [Import Existing Contacts feature](/common-questions#how-do-i-import-existing-contacts). ### Example Let's say you want to run a referral program and have an existing mailing list. Since you already have their email address you don't want to ask them to sign up again on ReferralHero. You could import them using our import feature, but maybe you don't want to import all of them. Instead, you want people to choose to participate in your campaign. 1-click sign-up is the solution to this problem. The "1-click sign-up" flow is very simple: you send out invite links to your email list. When they click on the link, ReferralHero will automatically add them to the campaign, without sending a confirmation email. We'll also automatically open up the sharing screen of the form, which means people can start sharing their referral links immediately. A few things to note: * people who click on the link will sign up without the need to verify their email address * people who sign up through this feature **won't count as referrals** even if they come from a referral link * if ReCaptcha is enabled in your campaign, this feature **won't work** * if you have enabled Terms and Conditions in your campaign, this feature **won't work** ### Enable 1-click sign-up By default this feature is disabled. To enable it for your campaign: * go to your campaign dashboard > *Edit campaign > Options* * switch on **Enable 1-Click sign-up** * Save the changes ### Send out 1-Click Signup links to your existing users Now that you have enabled this feature, you simply need to send people to your referral program page using a link **formatted in a specific way**. More specifically, your link must contain the `rh_email` parameter, whose value is the email address of the person you want to sign up. Optionally, you can add the `rh_name` parameter to send the name of the subscriber, the `rh_extra_field` parameter to send the value of the extra field and the `rh_extra_field_2` parameter to send the value of the second extra field. As an example, if your referral program page is `https://mywebsite.com/contest`, your link will have to be formatted like this `https://mywebsite.com/contest?rh_email={EmailAddress}` where `{EmailAddress}` is the email address of your existing user. ### A real-life example with MailChimp In real life, you are likely to send out links through your favorite autoresponder or email platform, like MailChimp, ActiveCampaign, etc. In this example, we will use MailChimp, but these instructions apply to virtually any email platform. Let's imagine this scenario: * you have a list on MailChimp with 2,000 subscribers and you want to send them a link to sign up for your contest automatically, with no extra effort. * Your contest page is located at **** You can send your list a newsletter with their unique sign-up link by using [Mailchimp merge tags](http://kb.mailchimp.com/merge-tags/getting-started-with-merge-tags). In MailChimp, the merge tag for the subscriber email is `*|EMAIL|*` , so all you need to do is to send your subscribers the following link: `https://mywebsite.com/contest?rh_email=*|EMAIL|*` MailChimp will automatically replace the merge tag \*|EMAIL|\* with the email address of each recipient. ![](/files/-LudeCK7gXlEnJrTwy1m) # Add Subscribers ### Add Manually To manually add a subscriber or referral to your campaign: 1. Go to your campaign dashboard > Subscribers 2. Click the **Add Subscriber** button in the top right corner 3. In the modal, enter the subscriber’s information, such as email address and name 4. Click **Add Subscriber**
{% hint style="success" %} **Note:** Click **Customize Fields** in the modal to control which fields are visible when adding a subscriber. {% endhint %} To add a referral, make sure to enter the advocate’s unique identifier or referral code in the Advocate field. (For example, if you're adding **, who was referred by **, enter ** in the Advocate field.)
### Upload CSV File To import your existing users/subscribers in ReferralHero, go to your Campaign Builder > Add Subscribers > Upload CSV File.
On that page, you can upload a CSV file containing the data of your existing users. #### File Formatting {% hint style="success" %} * Your CSV file must have headers, and they must be **lowercase**. * We highly recommend using our [example file](https://app.referralhero.com/maitre_import_example.csv) as a starting point, and please delete all blank rows/columns in your file before uploading. {% endhint %} Here are all the fields that you can use with your import: | column | description | | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **email** | Subscriber's email address | | **domain** |

Default referral link (e.g: ).
\* If left blank, the default referral link set in the GOAL campaign builder will be used

| | **name** | Subscriber's name | | **phone number** |

Subscriber's phone number (eg: +141234xxx34)
Country code must be present.

| | **extra field** | Subscriber's extra field (e.g: age) | | **extra field 2** | Subscriber's extra field 2 (eg: country) | | **date** | Subscriber's sign up date (DD/MM/YYYY or DD/MM/YYYY HH:MM) | | **referrals** | Subscriber's number of referrals. Useful if you're importing people who have already accumulated referrals from a previous referral program | | **referrer** | Use this column to indicate the referrer (or advocate) of a subscriber. The value is the email address of the referrer | {% hint style="success" %} **Good to know** * All imported subscribers will have *Imported from csv* as their source. * You can choose to send a Welcome email to imported subscribers by enabling it in the **Automations** section. The Welcome email will only be sent if one has been created and is currently active. * If you’ve enabled integration with your CRM, imported contacts will also be synced to your connected CRM list. If a contact already exists in your CRM list, their name and custom fields will be updated. * You can navigate to another page while the import is in progress. The **Upload** button will become active again once the import is complete. {% endhint %} ### Import via Integration You can also import contacts, users, or customers directly from your connected integrations. To do this, go to your Campaign Builder > Add Subscribers > Import via Integration, and select from the available integration sources.
{% hint style="success" %} If your **Welcome Email** automation is active, imported subscribers will receive this email—just like those added manually or via CSV upload. {% endhint %} # Launch The Launch section offers two ways to set up your campaign: * **Easy Mode** – Quick setup using built-in tools with minimal coding * **Advanced Mode** – Flexible setup with APIs and integrations for full customization Use the tables below as an index to explore the different setup paths for One-Step, Two-Step, and Three-Step conversions in both modes. Click any item to jump directly to the relevant instructions. ## **Easy Mode**
Best for quick setup using our built-in tools with minimal coding: | One-Step Conversion | Two-Step Conversion | Three-Step Conversion | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | |

  1. Install the ReferralHero Global Tracking Code
|

  1. Install the ReferralHero Global Tracking Code
|

  1. Install the ReferralHero Global Tracking Code
| |

  1. Choose how advocates will access their dashboard
|

  1. Choose how advocates will access their dashboard
|

  1. Choose how advocates will access their dashboard
| |
  1. Do you want to display a referral welcome message?
|
  1. Do you want to display a referral welcome message?
|
  1. Do you want to display a referral welcome message?
| |
  1. Choose how to track when a referral completes your main conversion event
|
  1. Choose how to track when a referral completes your first conversion event
|
  1. Choose how to track when a referral completes your first conversion event
| | |
  1. Choose how to track when a referral completes your last conversion event
|
  1. Choose how to track when a referral completes your second conversion event
| | | |
  1. Choose how to track when a referral completes your last conversion event
|
## **Advanced Mode**
Gives you more flexibility, using APIs and custom integrations for tailored experiences: | One-Step Conversion | Two-Step Conversion | Three-Step Conversion | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | |

  1. Install the ReferralHero Global Tracking Code
|

  1. Install the ReferralHero Global Tracking Code
|

  1. Install the ReferralHero Global Tracking Code
| |

  1. Choose how to automatically add new users or customers to your campaign:

    Integrations

    Javascript web API

    Rest API

|

  1. Choose how to automatically add new users or customers to your campaign:

    Integrations

    Javascript web API

    Rest API

|

  1. Choose how to automatically add new users or customers to your campaign:

    Integrations

    Javascript web API

    Rest API

| |
  1. Choose how advocates will access their dashboard

Javascript web API

Rest API

|

  1. Choose how advocates will access their dashboard

Javascript web API

Rest API

|

  1. Choose how advocates will access their dashboard

Javascript web API

Rest API

| |
  1. Do you want to display a referral welcome message?
|
  1. Do you want to display a referral welcome message?
|
  1. Do you want to display a referral welcome message?
| |
  1. Choose how to track when a referral completes your main conversion event

Javascript web API

Rest API

|
  1. Choose how to track when a referral completes your first conversion event

Javascript web API

Rest API

|
  1. Choose how to track when a referral completes your first conversion event

Javascript web API

Rest API

| | |
  1. Choose how to track when a referral completes your last conversion event

Javascript web API

Rest API

|
  1. Choose how to track when a referral completes your second conversion event

Javascript web API

Rest API

| | | |
  1. Choose how to track when a referral completes your last conversion event

Rest API

|
## Launch Steps ### Install the ReferralHero Global Tracking Code Install the ReferralHero global tracking script on every page of your website by placing it inside the `` `` tags. This script enables us to track advocates, referred users, and conversion events. You only need to install the script once. Skip this step if it has already been added to your website header.
{% hint style="warning" %} **IMPORTANT:** This step is required for all other tracking methods to function properly. Without the global tracking script, referral tracking and conversion events will not work. {% endhint %} ### Choose How Advocates Access Their Dashboard Decide how your advocates can access their personal dashboard—where they’ll find their unique referral link, track referrals, view rewards, and monitor other stats. The **Advocate Dashboard** widget includes: * A **signup form** (which can be skipped if the subscriber is already identified via API) * A **share screen** designed to increase engagement with your campaign #### Option 1: ReferralHero Hosted Landing Page (No Installation Required) ReferralHero provides a public dashboard for your campaign. **URL format:**\ `https://campaign.referralhero.com/MFxxxxxxxxxx/dashboard` You can use this if you prefer not to embed any code on your website. {% hint style="warning" %} Replace `MFxxxxxxxxxx` with your campaign UUID. {% endhint %} #### Option 2: Embed Within Your Webpage You can embed the Advocate Dashboard directly into your site using a simple `
` element inside your page’s `` tags. You can add this wherever you want the dashboard to appear. **Embed format:** ```
``` #### **Option 3: Inline Button** Add an inline button that opens the Advocate Dashboard as a pop-up when clicked. This button is placed within your page’s `` tags. To use the inline button: 1. Toggle on **“Enable Inline Button”** in Step #2.C of the Launch section 2. Add the following `
` to your webpage: ```
``` 3. Customize the button behavior and appearance: 1. **Default Button Label:** Shown to unidentified users 2. **Identified Subscriber Button Label:** Shown when a user is recognized as logged in via API, allowing you to personalize the message based on login status
#### **Option 4: Floating Button** Enable a floating button that sticks to your website (CTA-style) and opens the Advocate Dashboard in a pop-up. To use the floating button: 1. Toggle on **“Enable Floating Button”** in Step #2.D of the Launch section 2. Customize the button behavior and appearance: 1. **Default Button Label:** For unidentified users 2. **Identified Subscriber Button Label:** For logged-in users, allowing dynamic text based on user status 3. Choose the button’s placement on your site ### **Display a Referral Welcome Message (Optional)** The ReferralHero Welcome Banner appears at the top or bottom of your website and is designed to engage and convert your website visitors. It can display a signup form or a dynamic message, depending on your setup. To use the Referral Welcome Banner: 1. Toggle on **“Enable Referral Welcome Banner”** 2. Choose from the dropdown whether to show the banner to referrals only or non-referrals only
### **Track Referral Conversions** This step determines **when a referral is officially counted** in your campaign. You’ll define how ReferralHero tracks referral activity as users move through your funnel—from signup to conversion. The setup depends on how many conversion events your campaign includes. Choose the configuration that matches your funnel: * [One-Step Conversion](https://support.referralhero.com/campaign-builder/launch/one-step-conversion) * [Two-Step Conversion](https://support.referralhero.com/campaign-builder/launch/two-step-conversion) * [Three-Step Conversion](https://support.referralhero.com/campaign-builder/launch/three-step-conversion) # One-Step Conversion If your campaign tracks just one conversion event, follow the steps below to set up tracking. ## **Easy Mode vs Advanced Mode** There are two ways to configure your campaign setup.
Choose the mode that best fits your setup needs: | Easy Mode (no coding required) | Advanced Mode (custom setup) | | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | |
  1. Install the ReferralHero Global Tracking Code
|
  1. Install the ReferralHero Global Tracking Code
| |
  1. Choose how advocates will access their dashboard
|
  1. Choose how to automatically add new users or customers to your campaign:
    Integrations
    Javascript web API
    Rest API
| |
  1. Do you want to display a referral welcome message?
|
  1. Choose how advocates will access their dashboard

Javascript web API

Rest API

| |
  1. Choose how to track when a referral completes your main conversion event
|
  1. Do you want to display a referral welcome message?
| | |
  1. Choose how to track when a referral completes your main conversion event

Javascript web API

Rest API

|
## **Tracking Methods** Below are the available methods for tracking your one-step conversion campaign: ### **Method 1: Referral Signup Widget** The ReferralHero Signup Widget can be embedded in your site or used as a standalone landing page. It’s designed to capture signups and identify referrals effectively. **To use this method:**\ Toggle on **“Enable Referral Signup Widget”** in the Launch settings.
#### Option 1: ReferralHero Hosted Landing Page (No Installation Required) ReferralHero provides a hosted landing page with the signup widget already included. **URL format:**\ `https://campaign.referralhero.com/MFxxxxxxxxxx/signup` You can use this if you prefer not to embed any code on your website. {% hint style="warning" %} Replace `MFxxxxxxxxxx` with your campaign UUID. {% endhint %} #### Option 2: Embed Within Your Webpage You can embed the widget directly into your site using a simple `
` element placed anywhere inside your page’s `` tags. **Embed format:** ```
``` #### **Option 3: Inline Button** This method shows the signup widget as a popup when a button is clicked. To use the inline button: 1. Toggle on **“Enable Inline Button”** in the Launch settings 2. Add the following `
` to your webpage inside the `` tag: ```
``` 3. Customize the button label and behavior for both unidentified and identified users ### **Method 2: My Website Signup Form** Automatically track form submissions from your own website and add users to your ReferralHero campaign as subscribers or referrals. To enable this method: 1. Toggle on **“Automatic Form Tracking”** in the Launch settings 2. Under **“On Form Completion”**, choose: * **Add non-referrals and referrals** – Track all submissions * **Add referrals only** – Track only submissions from identified referrals 3. Under **“Select Forms”**, enter the URLs of pages that contain forms (comma-separated) 4. Click **“Get Forms”** to allow ReferralHero to crawl and list detected forms 5. Toggle on the forms you’d like to track. \ *If your form doesn’t appear, check our alternative methods for adding subscribers and referrals.* 6. Click **“Save”** to confirm your settings.
# Two-Step Conversion If your campaign tracks two conversion events, follow the steps below to set up tracking. ## **Easy Mode vs Advanced Mode** There are two ways to configure your campaign setup.
Choose the mode that best fits your setup needs: | Easy Mode (no coding required) | Advanced Mode (custom setup) | | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | |
  1. Install the ReferralHero Global Tracking Code
|
  1. Install the ReferralHero Global Tracking Code
| |
  1. Choose how advocates will access their dashboard
|
  1. Choose how to automatically add new users or customers to your campaign:

Integrations

Javascript web API

Rest API

| |
  1. Do you want to display a referral welcome message?
|
  1. Choose how advocates will access their dashboard

Javascript web API

Rest API

| |
  1. Choose how to track when a referral completes your first conversion event
|
  1. Do you want to display a referral welcome message?
| |
  1. Choose how to track when a referral completes your last conversion event
|
  1. Choose how to track when a referral completes your first conversion event

Javascript web API

Rest API

| | |
  1. Choose how to track when a referral completes your last conversion event

Javascript web API

Rest API

|
## **Tracking Methods** Below are the available methods for tracking your two-step conversion campaign: ### Tracking Methods for **Conversion Event 1** #### **Method 1: Referral Signup Widget** The ReferralHero Signup Widget can be embedded in your site or used as a standalone landing page. It’s designed to capture signups and identify referrals effectively. **To use this method:**\ Toggle on **“Enable Referral Signup Widget”** in the Launch settings.
#### Option 1: ReferralHero Hosted Landing Page (No Installation Required) ReferralHero provides a hosted landing page with the signup widget already included. **URL format:**\ `https://campaign.referralhero.com/MFxxxxxxxxxx/signup` You can use this if you prefer not to embed any code on your website. {% hint style="warning" %} Replace `MFxxxxxxxxxx` with your campaign UUID. {% endhint %} #### Option 2: Embed Within Your Webpage You can embed the widget directly into your site using a simple `
` element placed anywhere inside your page’s `` tags. **Embed format:** ```
``` #### **Option 3: Inline Button** This method shows the signup widget as a popup when a button is clicked. To use the inline button: 1. Toggle on **“Enable Inline Button”** in the Launch settings 2. Add the following `
` to your webpage inside the `` tag: ```
``` 3. Customize the button label and behavior for both unidentified and identified users #### **Method 2: My Website Signup Form** Automatically track form submissions from your own website and add users to your ReferralHero campaign as subscribers or referrals. To enable this method: 1. Toggle on **“Automatic Form Tracking”** in the Launch settings 2. Under **“On Form Completion”**, choose: * **Add non-referrals and referrals** – Track all submissions * **Add referrals only** – Track only submissions from identified referrals 3. Under **“Select Forms”**, enter the URLs of pages that contain forms (comma-separated) 4. Click **“Get Forms”** to allow ReferralHero to crawl and list detected forms 5. Toggle on the forms you’d like to track. \ *If your form doesn’t appear, check our alternative methods for adding subscribers and referrals.* 6. Click **“Save”** to confirm your settings.
#### **Method 3: CRM Integrations** You can set up the **HubSpot** integrations to trigger referral conversion event 1 automatically. [Learn more.](https://support.referralhero.com/campaign-builder/integrations/hubspot) ### Tracking Methods for **Conversion Event 2** #### **Method 1: Manual Update** You can manually trigger the referral conversion by updating the referral status in the **Subscribers** section. [Learn more.](https://support.referralhero.com/campaign-management/subscribers/update-referral-status) #### **Method 2: Visit to Successful Conversion URL** This method updates a referral’s status from Conversion Event 1 to Conversion Event 2 when they visit a specific URL—typically a thank you page or final step in your funnel. To use this method: 1. Toggle on **“Visits Successful Conversion URL”** in the Launch setting 2. Enter the destination URL in the field provided
#### **Method 3: Integrations** You can set up integrations to trigger conversion event 2: * **Zapier** – Set up a Zapier automation to update the referral status. * **CRM or Payment Tools** – Trigger events through: * HubSpot * Stripe * Salesforce * Blockchain event Setup instructions are available in the ReferralHero [integrations ](https://support.referralhero.com/campaign-builder/integrations)documentation. # Three-Step Conversion If your campaign tracks three conversion events, follow the steps below to set up tracking. ## **Easy Mode vs Advanced Mode** There are two ways to configure your campaign setup.
Choose the mode that best fits your setup needs: | Easy Mode (no coding required) | Advanced Mode (custom setup) | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | |
  1. Install the ReferralHero Global Tracking Code
|
  1. Install the ReferralHero Global Tracking Code
| |
  1. Choose how advocates will access their dashboard
|
  1. Choose how to automatically add new users or customers to your campaign:

Integrations

Javascript web API

Rest API

| |
  1. Do you want to display a referral welcome message?
|
  1. Choose how advocates will access their dashboard

Javascript web API

Rest API

| |
  1. Choose how to track when a referral completes your first conversion event
|
  1. Do you want to display a referral welcome message?
| |
  1. Choose how to track when a referral completes your second conversion event
|
  1. Choose how to track when a referral completes your first conversion event

Javascript web API

Rest API

| |
  1. Choose how to track when a referral completes your last conversion event
|
  1. Choose how to track when a referral completes your second conversion event

Javascript web API

Rest API

| | |
  1. Choose how to track when a referral completes your last conversion event

Rest API

|
## **Tracking Methods** Below are the available methods for tracking your three-step conversion campaign: ### Tracking Methods for **Conversion Event 1** #### **Method 1: Referral Signup Widget** The ReferralHero Signup Widget can be embedded in your site or used as a standalone landing page. It’s designed to capture signups and identify referrals effectively. **To use this method:**\ Toggle on **“Enable Referral Signup Widget”** in the Launch settings.
#### Option 1: ReferralHero Hosted Landing Page (No Installation Required) ReferralHero provides a hosted landing page with the signup widget already included. **URL format:**\ `https://campaign.referralhero.com/MFxxxxxxxxxx/signup` You can use this if you prefer not to embed any code on your website. {% hint style="warning" %} Replace `MFxxxxxxxxxx` with your campaign UUID. {% endhint %} #### Option 2: Embed Within Your Webpage You can embed the widget directly into your site using a simple `
` element placed anywhere inside your page’s `` tags. **Embed format:** ```
``` #### **Option 3: Inline Button** This method shows the signup widget as a popup when a button is clicked. To use the inline button: 1. Toggle on **“Enable Inline Button”** in the Launch settings 2. Add the following `
` to your webpage inside the `` tag: ```
``` 3. Customize the button label and behavior for both unidentified and identified users #### **Method 2: My Website Signup Form** Automatically track form submissions from your own website and add users to your ReferralHero campaign as subscribers or referrals. To enable this method: 1. Toggle on **“Automatic Form Tracking”** in the Launch settings 2. Under **“On Form Completion”**, choose: * **Add non-referrals and referrals** – Track all submissions * **Add referrals only** – Track only submissions from identified referrals 3. Under **“Select Forms”**, enter the URLs of pages that contain forms (comma-separated) 4. Click **“Get Forms”** to allow ReferralHero to crawl and list detected forms 5. Toggle on the forms you’d like to track. \ *If your form doesn’t appear, check our alternative methods for adding subscribers and referrals.* 6. Click **“Save”** to confirm your settings.
#### **Method 3: CRM Integrations** You can set up the **HubSpot** integrations to trigger referral conversion event 1 automatically. [Learn more.](https://support.referralhero.com/campaign-builder/integrations/hubspot) ### Tracking Methods for **Conversion Event 2** #### **Method 1: Manual Update** You can manually trigger the referral conversion by updating the referral status in the **Subscribers** section. [Learn more.](https://support.referralhero.com/campaign-management/subscribers/update-referral-status) #### **Method 2: Visit to Successful Conversion URL** This method updates a referral’s status from Conversion Event 1 to Conversion Event 2 when they visit a specific URL—typically a thank you page or final step in your funnel. To use this method: 1. Toggle on **“Visits Successful Conversion URL”** in the Launch setting 2. Enter the destination URL in the field provided
#### **Method 3: Integrations** You can set up integrations to trigger conversion event 2: * **Zapier** – Set up a Zapier automation to update the referral status. * **CRM or Payment Tools** – Trigger events through: * HubSpot * Stripe * Salesforce * Blockchain event Setup instructions are available in the ReferralHero [integrations ](https://support.referralhero.com/campaign-builder/integrations)documentation. ### Tracking Methods for **Conversion Event 3** #### **Method 1: Manual Update** You can manually trigger the referral conversion by updating the referral status in the **Subscribers** section. [Learn more.](https://support.referralhero.com/campaign-management/subscribers/update-referral-status) #### **Method 2: Integrations** You can set up integrations to trigger conversion event 2: * **Zapier** – Set up a Zapier automation to update the referral status. * **CRM or Payment Tools** – Trigger events through: * HubSpot * Stripe * Salesforce * Blockchain event Setup instructions are available in the ReferralHero [integrations ](https://support.referralhero.com/campaign-builder/integrations)documentation. # Misc # Forward & Refer The ReferralHero Forward & Refer feature is a powerful tool that allows you to grow your email list fast and track natural subscriber engagement. This feature is useful if you want to allow subscribers to easily refer friends by forwarding your email or newsletter to a friend. When they forward your email to a friend, ReferralHero will track when the friend visits your website and signs up for your newsletter! Here is the typically expected behavior: 1. You set up the Forward & Refer feature and include it in your email URLs. 2. Subscriber reads your email or newsletter. 3. Subscriber organically forwards (aka shares) your email to a friend. 4. Friend clicks any link within the email (to further read the article, get information about your website, or sign up for your newsletter). 5. ReferralHero tracks and rewards the referrer when the friend clicks, signs up for your newsletter, and becomes a referral. ### Set Up The Forward & Refer Feature 1. Install the ReferralHero Global Tracking Code on your website if you haven't done so already. 2. [Integrate ReferralHero with your ESP](/campaign-builder/integrations) to pass over and store subscribers’ referral CODE
3\. Find a link you want to enable Forward & Refer tracking to and add ?mwr=CODE to the end of any email or newsletter URL. {% hint style="warning" %} **IMPORTANT:** Use your ESP merge tag to replace and attach the corresponding referral CODE shown above. {% endhint %} 4\. For MailChimp, that would look like this: [www.newsletterarticle.com?mwr=\*|CODE|\*](http://www.newsletterarticle.com?mwr=*|CODE|*)
5\. Complete this for every link (hyperlink, image, etc.) within your email, or set it up to automatically apply the dynamic URL parameter if your EPS allows. 6\. Use the [ReferralHero Signup Widget](/campaign-builder/embeddable-widgets#referralhero-signup-widget) or [your own signup form](/integrate/javascript-web-api/adding-a-subscriber-manually) to track when a friend signs up for your newsletter. 7\. For the first time ever, you'll now be able to track and reward subscribers when they forward your emails and their friends sign up for your newsletter! Sit back and watch your subscriber grow exponentially. # Custom Attribution ### Custom Source Attribution Sources are a great way to measure your marketing efforts. ReferralHero **tracks the traffic source of each subscriber automatically** if you are using a ReferralHero widget or our Javascript API. By default, ReferralHero will attribute a source to each subscriber based on the previous referring site e.g. Facebook, Twitter, Facebook Messenger, Email, Whatsapp, Telegram, Linkedin, etc. If you want to get more granular and track your own referring channel (e.g. Facebook ads or your newsletter), simply add the [UTM parameter](https://blog.hubspot.com/customers/understanding-basics-utm-parameters) utm\_source to the URL. ReferralHero will capture the custom utm\_source if one is defined and attribute the traffic source accordingly. For example, let's say you send out a newsletter and want to track signups. You can create a link like: `http://mylandingpage.com?utm_source=newsletter` to use in your newsletter. ReferralHero will capture the custom utm\_source and set it as the source for the traffic coming from that link. Here is an example of the ReferralHero Analytics page capturing multiple sources:
### **Other UTM Tracking Parameters** In addition to tracking sources, you can also set up other static UTM parameters across your whole referral campaign. This would be useful if you wanted to see in google analytics how much traffic was being sent to your website as a result of your referral program. To send a campaign parameter to Google Analytics, and apply it across all unique referral links, add the UTM parameter utm\_campaign to your default referral URL. ReferralHero will automatically add the subscriber’s unique tracking variable to the end. To edit your default referral link go to *Edit Campagin > Options > Default Referral Link* \ \&mwr=1a34fe4 Set as default referral URL The unique tracking variable will be automatically added for each subscriber {% hint style="info" %} **NOTE:** If you're looking to track goals or send conversion events to Google Analytics when a ReferralHero widget is submitted, [see here](/common-questions#how-can-i-track-sign-ups-in-google-analytics). {% endhint %} # Platform-specific Instructions Step-by-step instructions for the most popular platforms such as WordPress, SquareSpace, Shopify and more. {% content-ref url="/pages/-LuiHobypEvMISTG3AgM" %} [WordPress](/integrate/platform/wordpress) {% endcontent-ref %} {% content-ref url="/pages/-LuiGj3lSZ-iEXuJHy2v" %} [Google Tag Manager](/integrate/platform/google-tag-manager) {% endcontent-ref %} {% content-ref url="/pages/-LuiMtT0HylRtSS2HgsI" %} [SquareSpace](/integrate/platform/squarespace) {% endcontent-ref %} {% content-ref url="/pages/-LuiNyBEYbYfKRiSl\_YQ" %} [ClickFunnels](/integrate/platform/clickfunnels) {% endcontent-ref %} {% content-ref url="/pages/-LuiOxvL4gYvN5IwD0NO" %} [Unbounce](/integrate/platform/unbounce) {% endcontent-ref %} {% content-ref url="/pages/-LuiQc2SFc417waeWGEC" %} [Instapage](/integrate/platform/instapage) {% endcontent-ref %} {% content-ref url="/pages/-LuidWiOWeKqsrjbp4z1" %} [Shopify](/integrate/platform/shopify) {% endcontent-ref %} {% content-ref url="/pages/-LuiekiUvyonemkqW0OE" %} [Carrd](/integrate/platform/carrd) {% endcontent-ref %} {% content-ref url="/pages/-LuiQYT4X9csE4bLGRTh" %} [WIX](/integrate/platform/wix) {% endcontent-ref %} # Google Tag Manager {% hint style="warning" %} **IMPORTANT** Google Tag Manager is often targeted by AdBlocker and extensions such as Ghostery, which means that some people might block Google Tag Manager when visiting your website. When this happens, ReferralHero will not be loaded. {% endhint %} **Step 1**: Login in Google Tag Manager and go to the container you want to use. **Step 2**: Click **Add a new tag.** **Step 3:** Give it a name (e.g: ReferralHero Tracking Code) and select Custom HTML **Step 4:** Go to your campaign dashboard *> Installation instructions* and copy the **Tracking Code** **Step 5:** In the textarea, paste the ReferralHero Tracking Code. ![](/files/-LuiHRGHuNGXowtrNeQq) **Step 6**: Now we need to tell Google Tag Manager when trigger the script. Scroll down to the **Triggering** section, click on it and choose when to trigger the tag. We highly recommend selecting **All pages** to load the ReferralHero Tracking code on all your pages but feel free to set up another targeting rule. ![](/files/-LuiHWCbVE-NHOcJrUWv) **Step 7**: Save your tag. **Step 8**: Click the **Submit** button on the upper right-hand side of the page to publish your changes. The ReferralHero Tracking Code will be automatically loaded on every page! ## How can I track sign-ups in Google Analytics? To track a sign-up in Google Analytics simply use the **afterSuccess** callback and choose which events you want to send. ```markup ``` # WordPress {% hint style="info" %} **Note:** ReferralHero cannot be used on free hosted WordPress.com websites, as these platforms do not support the installation of custom plugins. Additionally, custom JavaScript is blocked from being embedded on such sites. If your WordPress blog uses caching plugins, please ensure you clear the cache to properly integrate the script. {% endhint %} To install the ReferralHero Tracking Code on your WordPress theme, one option is to add it directly to the `header.php` file. However, modifying the theme in this way will only affect your local copy of the theme. This means that if the theme is updated or re-installed later, your changes, including the ReferralHero Tracking Code, will be lost. To avoid this, we recommend using a WordPress Script Management Plugin. This approach ensures that your tracking code remains intact, even if the theme is updated. ## **Installing ReferralHero using a Script Installation Plugin** **Step 1:** First, check if you already have a header/footer script management plugin installed on your WordPress website. If you do not have one, there are several free options available to help you add scripts to the header or footer of your site. We recommend using either [**WPCode**](https://wordpress.org/plugins/insert-headers-and-footers/) or [**OH Add Script to Individual Pages Header Footer**](https://wordpress.org/plugins/oh-add-script-header-footer/). **Step 2:** Install the selected header/footer script plugin on your WordPress website. {% hint style="danger" %} While issues with installing a WordPress script management plugin are uncommon, please note that any plugin you choose is not managed by ReferralHero. If you encounter any difficulties during installation or face compatibility issues, you will need to contact the plugin's author for support. {% endhint %} **Step 3:** Go to your ReferralHero *Campaign Overview > Edit Campaign > Launch instructions* and copy your **ReferralHero Global Tracking Code.**
**Step 4:** Use the plugin you installed to paste the ReferralHero Tracking Code into the header of your site. If you are using the **OH Add Script** plugin, paste the script into the designated box as shown below.

In "add script to be added to the header of the page" section of the OH plug-in, add your global tracking code:

```javascript !function(m,a,i,t,r,e){if(m.RH)return;r=m.RH={},r.uuid =t,r.loaded=0,r.base_url=i,r.queue=[],m.rht=function() {r.queue.push(arguments)};e=a.getElementsByTagName('script') [0],c=a.createElement('script');c.async=!0,c.src= 'https://referralhero-global-code.s3.amazonaws.com/'+'production'+ '/'+t+'.js',e.parentNode.insertBefore(c,e)}(window,document, 'https://app.referralhero.com/','RHxxxxxxxxx'); ``` {% hint style="warning" %} Replace 'RHxxxxxxxxxx' with your unique uuid. {% endhint %} **Step 5:** [Download the ReferralHero plugin](https://app.referralhero.com/maitre-2-wp.php.zip) and install it on your website. **Step 6:** Add the ReferralHero embeddable widgets on your page by pasting the special shortcode \
\
exactly where you want the form to appear in your page.
{% hint style="warning" %} Replace the `MFxxxxxxxxxx` with your specific campaign UUID. {% endhint %} # Webflow ## Adding the ReferralHero Tracking Code **Step 1:** Log into your Webflow account, select your project, and navigate to the **Settings** page. **Step 2:** In the **Settings** menu, go to **Custom Code**. **Step 3:** Go to your ***Campaign** > **Edit Campaign** > **Launch** instructions* and copy your **Global** **Tracking Code**
**Step 4:** Paste the **ReferralHero Tracking Code** into the **Head Code** text area, then save your changes.
## Embedding the ReferralHero Widget **Step 1:** After adding the tracking code, Go to the Webflow dashboard, select your project, and enter **Designer Mode**. **Step 2:** Navigate to the page where you want to install ReferralHero. **Step 3:** Add an **Embed** element by clicking the **+** icon and selecting **Code Embed**.
**Step 4:** Drag the Embed element to the exact spot where you want the widget to appear. **Step 5:** In the Embed code editor, paste `
/div>`
**Step 6:** Save your changes and publish the website. The embedded widget should now appear on your selected page. ## Adding ReferralHero Custom Tracking to Webflow Forms **Step 1:** After adding the ReferralHero tracking code, go to the Webflow dashboard, select your project, and enter **Designer Mode**. **Step 2:** Navigate to the page containing the form where you want to apply the ReferralHero custom tracking method. **Step 3:** Click on the form to select it, then select each input field (like **Name**, **Email**, and **Phone**) individually. **Step 4:** With a field selected, go to the **Element Settings** panel (usually found on the right side of the screen).
**Step 5:** Under the **ID** section, enter a unique ID for each field. For example: * Set the ID of the email field to `email-field`. * Set the ID of the name field to `name-field`. * Set the ID of the phone field to `phone-field`. * Set the ID of the submit button to `Submit`. **Step 6:** Once the IDs are set, go to **Page Settings > Custom Code**. **Step 7:** In the **Head Code** section, add the following JavaScript code. This script waits until the page is fully loaded, captures the form data on submit, and then sends it to ReferralHero:
{% hint style="info" %} **Important:** * Replace `RH_MFxxxxxxxxx` with your actual ReferralHero campaign ID. * Confirm that `signup-form` matches the **ID** of your form in Webflow. Adjust as necessary if your form has a different ID. * To learn more about ReferralHero JavaScript custom methods, Click [here](https://berylsystems.gitbook.io/referral-hero-documentation/integrations/javascript-web-api). {% endhint %} **Step 8:** Save your changes and publish the site. This code will intercept the form submission, capture the data from each field, and send it to ReferralHero using the custom method. # SquareSpace {% hint style="warning" %} **IMPORTANT** If your SquareSpace's theme uses AJAX, you must disable it before you install ReferralHero, otherwise it won't work. You can read the instructions [here](https://support.squarespace.com/hc/en-us/articles/115000253288-Ajax-loading). {% endhint %} **Step 1**: Login onto your Squarespace account, choose your website and go to the **Settings**. **Step 2**: From the **Settings menu,** navigate to **Advanced** > **Code Injection** ![](/files/-LuiN82YnIplhrPElMD1) **Step 3:** Go to your *Campaign Overview> Edit Campaign > Launch instructions* and copy your **Tracking Code** **Step 4**: Paste the ReferralHero Tracking Code in the Header section text area and save your changes. **Step 5**: Go back go Squarespace dashboard and click Pages. **Step 6**: Choose the page where you want to install ReferralHero and click **Edit**. **Step 7**: In edit mode, add a content block **Code**. ![](/files/-LuiNVyq05tXWE1Vc4A5) **Step 8**: In the content area, paste `
` {% hint style="warning" %} **Important:** Replace `'MFxxxxxxxxxx'` with your actual campaign UUID. {% endhint %} **Step 9**: Save your changes and the embeddable widget will appear on the page. # ClickFunnels The ReferralHero / ClickFunnels integration provides seamless functionality, empowering you to use your own ClickFunnels form to capture signups. ## ClickFunnels Classic 1. Log into your ClickFunnels account 2. Access the Funnel page by hovering over the ClickFunnels drop-down menu from your dashboard and clicking on Funnels 3. Choose the funnel you want to edit by clicking on the Funnel Name 4. Select the desired funnel step 5. Click on the Edit Page button of your funnel page to access the Page Editor 6. Scroll down and click “Get CSS Info” to note the button ID
7. Go to Settings > Tracking Code
8. Add the following scripts to the Header Code section:\ i. ReferralHero Global Tracking Code\ ii. Replace the button ID and campaign ID with your ClickFunnels button ID and ReferralHero campaign ID 
<script>
    document.addEventListener('DOMContentLoaded', function () { 
        var submitButton = document.querySelector('#tmp_button-310 a'); 
        submitButton.onclick = function () { 
            var form = document.getElementById('cfAR'); 
            var data = { 
                email: form.querySelector('#cf_contact_email').value 
            }; 
            if (RH_MFxxxxxxxxx) { 
                RH_MFxxxxxxxxx.pendingReferral(data); 
            } 
        }; 
    });
</script>
9. Save the changes ## ClickFunnels 2 1. Log into your ClickFunnels account 2. Go to Sites > Funnels 3. Access the Funnel page 4. Choose the funnel you want to edit by clicking on the Funnel Name 5. Select the desired funnel step 6. Click on the Edit Page button of your funnel page to access the Page Editor
7. Click on the button where you would like to add the script to edit the property, then go to the “Advanced” tab
8. In the section “Custom Attributes”, click “Add Custom Attribute”. Then enter “data-rh-form” in the Name field, and “true” in the Value field. Then save the changes
9. Click on the \ at the top right. Then go to the “Header Code” tab
10. Add the Global Tracking Code and the following javascript. Then click Save 
<script>
document.addEventListener('DOMContentLoaded', function () {
  var submitButtons = document.querySelectorAll('[data-rh-form] a');
  submitButtons.forEach(function (submit) {
    submit.onclick = function () {
      var form = document.getElementById('cfAR');
      var data = {
        email: form.querySelector('#cf_contact_email').value,
        utm_source: form.querySelector('#utm_source').value,
        extra_field: form.querySelector('input[name="recognition_display_name"]') ? form.querySelector('input[name="recognition_display_name"]').value : null,
        extra_field2: form.querySelector('input[name="recognition_display_link"]') ? form.querySelector('input[name="recognition_display_link"]').value : null
      };
      if (data.extra_field === null) {
        delete data.extra_field;
      }
      if (data.extra_field2 === null) {
        delete data.extra_field2;
      }
      if (RH_MFxxxxxxxxxx) {
        RH_MFxxxxxxxxxx.form.submit(data);
      }
    };
  });
});
</script>
[^1]: replace this button ID with your ClickFunnels button ID [^2]: replace this campaign ID with your ReferralHero campaign ID if the multi campaigns feature is enabled # Unbounce {% hint style="info" %} **Note** To use [Script Manager](https://documentation.unbounce.com/hc/en-us/articles/203879070-Using-Custom-JavaScript-and-CSS-on-Your-Landing-Page) you need to use your custom domain. If you do not wish to use your custom domain, replace steps 2 and 3 with the instructions in [this article](https://documentation.unbounce.com/hc/en-us/articles/203879070-Using-Custom-JavaScript-and-CSS-on-Your-Landing-Page). {% endhint %} **Step 1**: Login to Unbounce and open your landing page. **Step 2**: Go to **Settings > Script Manager** and click on **Add your script**. **Step 3**: From the drop-down, select **Custom Script** and give it a name (e.g: **ReferralHero).** ![](/files/-LuiPBowE4aARJlS9h1C) **Step 4:** Go to your *Campaign Overview > Edit Campaign > Launch instructions* and copy your **Tracking Code.** **Step 5:** Select **Head** within **Placement** and **All** within **Included on**. Paste the ReferralHero Tracking Code and save the changes. ![](/files/-LuiPM0_45bIcAGLDMQ2) **Step 6:** Go back to your Unbounce dashboard and open your landing page. **Step 7:** From the left sidebar, add a **Custom HTML** element. ![](/files/-LuiPX421Xvt6oPFctNn) **Step 8**: In the editor, enter `
` {% hint style="warning" %} **Important:** Replace `'MFxxxxxxxxxx'` with your actual campaign UUID. {% endhint %} **Step 9**: Save your changes and the embeddable widget will appear on the page. # Instapage **Step 1**: Login to Instapage and open your landing page. **Step 2**: Click on **Settings** from your edit screen and select **Javascript**. ![](/files/-LuicvE38W85WA6_TFBE) **Step 3:** Go to your *Campaign Overview > Edit Campaign > Launch instructions* and copy your **Tracking Code.** **Step 4:** Select **Head** and paste the Tracking Code. ![](/files/-Luid5zqQuPIiggpCqlY) **Step 5**: On your page create an HTML element by clicking on **HTML**. ![](/files/-LuidCRpgce1ELkksQFU) **Step 6**: Click on **Edit** and enter `
` {% hint style="warning" %} **Important:** Replace `'MFxxxxxxxxxx'` with your actual campaign UUID. {% endhint %} **Step 7**: Save your changes and the embeddable widget will appear on the page. # Shopify The ReferralHero integration with Shopify enhances your referral program by providing multiple ways to engage customers and accurately track referrals. This guide will walk you through the essential steps to ensure a seamless setup: * **Add the ReferralHero Global Tracking Script:** Install the global tracking script in the header of your Shopify site to activate your referral program and capture referral data. * **Add a ReferralHero Widget to a Content Page:** Embed the widget on a content page to make it easy for users to engage with your referral program. * **Sign Up Customers and Track Referrals After Purchase:** Ensure that customers are signed up for tracking after they complete a purchase, enabling accurate referral tracking. * **Track Referrals and Their Transactions:** Monitor referrals and their transactions to measure the effectiveness of your referral program and gather insights on customer behavior. {% hint style="info" %} **IMPORTANT!** **Regardless of your chosen setup for the referral program, installing the ReferralHero Global Tracking Script in the header of your Shopify website is crucial.** This script is the foundation for tracking referrals and ensures your referral program functions correctly across all pages of your site. Without this step, your referral tracking and engagement features will not operate as intended. {% endhint %} ## Add the Global Tracking Script The ReferralHero Global Tracking Script is essential for tracking referral data and powering your ReferralHero campaigns. Here’s how to get it up and running on your Shopify site: **STEP 1 -> Log into Your Shopify Account**: Start by accessing your Shopify dashboard followed by going to **Online Store** and then **Themes**. **STEP 2 -> Edit Your Theme**: Click the **Actions** button in the top right corner and select **Edit Code**.
**STEP 3 -> Locate the Theme File**: Under **Layout**, find and select `theme.liquid`. This is where you'll add your tracking script.
**STEP 4 -> Copy Your Tracking Code**: In ReferralHero, navigate to **Campaign Overview** > **Edit Campaign** > **Launch Instructions**. Copy the Tracking Code provided.
**STEP 5 -> Paste the Code**: In the **theme.liquid** file, paste the ReferralHero Tracking Code between the `` and `` tags, ensuring it’s just before the closing `` tag.
**STEP 6 -> Save Your Changes**: Hit **Save** to apply the changes. Your ReferralHero Global Tracking Code is now installed and ready to go! By following these steps, you ensure that ReferralHero can effectively track referral data across your Shopify store, setting the stage for a successful referral program. ## Adding a ReferralHero Widget to a Content Page Want to boost your referral program with a dedicated 'Refer a Friend' page? Here's how you can easily add a ReferralHero Widget to any content page in your Shopify store. **Step 1:** Navigate to the specific page where you want the widget to appear. **Step 2:** In the editor, click the **Show HTML** icon at the top right.
**Step 3:** Copy and paste the ReferralHero Widget script into the text area. For example, to use the ReferralHero Advocate Dashboard Widget, add `
`. **Step 4:** Save your changes, and voilà! The ReferralHero Widget will now appear on your page. If you're setting up a campaign with a custom event like a purchase, follow through with the next steps for a seamless integration. ## Using Custom Events and Pixels for Tracking Leverage Shopify's Custom Events and Web Pixels to track non-referrals, referrals, and transactions effortlessly. Let's say you want to track referrals and their transactions on the post-checkout page or thank you page. Follow these steps **Step 1:** Navigate to **Settings** > **Customer Events** in your Shopify dashboard. **Step 2:** Click on the **Add a Custom Pixel** button.
**Step 3:** Copy the Global Tracking Script from your ReferralHero campaign and paste it into the custom pixel field.
**Step 4:** Copy the following snippet to track referrals and transactions on the post-checkout event. ```javascript window.RHConfig = { callbacks: { ready: function() { analytics.subscribe("checkout_completed", async(event) => { const data = { email: event.data?.checkout?.email, transaction_id: event.data?.checkout?.order?.id, amount: event.data?.checkout?.totalPrice?.amount, product_id: event.data?.checkout?.lineItems[0]?.variant?.product?.id, }; RH.trackReferral(data.email); RH_MFxxxxxxxxx.trackTransaction(data); }); } } }; ``` {% hint style="info" %} **Note:** * You can find more information on available customer events and data value variables by checking this [link](https://shopify.dev/docs/api/web-pixels-api/standard-events). * If you want to track ordinary subscriber & referrals both you can use this method`RH_MFxxxxxxxxxx.organicTrackReferral(uniqueIdentifier);`For more methods and detailed usage, refer to the [javascript methods](https://support.referralhero.com/integrate/javascript-web-api/track-multi-step-conversion-events#track-referral-conversion-event-or-add-an-organic-subscriber). {% endhint %} **Step 5:** Once you've configured everything, click the **Save** button.
**Step 6:** After adding the custom pixel and configuring the necessary code, you’ll need to connect the pixel to your online store.
Your pixel is now linked to the event, and ReferralHero will begin tracking the referral data and transactions associated with any of those events. {% hint style="danger" %} Please be aware if you're currently using additional scripts in the checkout section to add scripts to the Thank You and Order Status pages, this feature will be deprecated and removed after August 28, 2025. Therefor to ensure your tracking continues to function correctly, you should switch to using [web pixels](https://berylsystems.gitbook.io/referral-hero-documentation/integrations/platform-specific-integration/shopify#using-custom-events-and-pixels-for-tracking). {% endhint %} # Carrd **Step 1**: Login onto Carrd and open your site. **Step 2**: Click on the **+** and choose **Embed.** ![](/files/-LuieyLqWIHCYiWAb2ez) **Step 3:** Go to your *Campaign Overview > Edit Campaign > Launch instructions* and copy your **Tracking Code.** **Step 4**: Paste the ReferralHero Tracking Code in the **Code** field. Make sure the **Type** is set to **Code** and **Style** is set to **Hidden / Head**. ![](/files/-Luif7lNr0AKSqN-sSLy) {% hint style="info" %} You can move this block wherever you want because it won't show anywhere. {% endhint %} **Step 5**: Create another Embed element (as in step 2) but this time set **Style** to **Inline.** In the Code field enter `
` {% hint style="warning" %} **Important:** Replace `'MFxxxxxxxxxx'` with your actual campaign UUID. {% endhint %} ![](/files/-LuifPRJ_fIGoeFMTJ9H) **Step 6**: Save your changes and the embeddable widget will appear on the page. # WIX ReferralHero's integration with Wix is a straightforward process that involves just a few simple steps. Please follow the instructions below to integrate ReferralHero with your Wix site. ### Step 1: Retrieve the Section ID 1. Access your Wix site's editor by going to your site's dashboard and clicking "Edit Site."
2. Navigate to the page where you want to embed the ReferralHero widget. 3. Click "Add a Section" on the left side of the Editor. 4. Choose a category from the options. 5. Select the desired section to add it to your page. 6. Publish your site.
7. View your live site, right-click, and select "Inspect" to open the developer tools.
8. In the "Elements" panel of the developer tools, locate the section you just created. 9. Take note of the section ID.
### Step 2: Add Custom Code to Your Wix Site 1. In your ReferralHero campaign, navigate to the Launch tab to retrieve the global tracking code specific to your campaign. 2. Add your ReferralHero global tracking code to line #2 in the code provided below. 3. Insert the section ID noted earlier on line #16 in the code below. {% hint style="info" %} **Replace** `'MFxxxxxxxxxx'` **with your specific campaign UUID.** {% endhint %} {% code lineNumbers="true" %} ```html ``` {% endcode %} 4. Go to the "Settings" section in your WIX site's dashboard. 5. Click the "Custom Code" tab within the "Advanced" section.
6. Click "+ Add Custom Code" at the top right.
7. Paste your ReferralHero global tracking code and the section id code snippet in the provided text box.
**Example code:** {% code lineNumbers="true" %} ```html ``` {% endcode %} 8. Under the "Add Code to Pages" option, select "All Pages." 9. Under the "Place Code in" option, choose "Head." 10. Click "Apply" to save the changes.
Following these steps, the ReferralHero widget will be successfully added to your WIX site. # Javascript Web API The **ReferralHero JavaScript Web API** is a powerful JavaScript library that allows you to integrate referral campaigns directly into your application with a high level of customization. While embeddable widgets can also be customized to fit your brand, they come with certain limitations in terms of design and functionality, as they are pre-built components that you can easily add from your ReferralHero account. Alternatively, with the JavaScript Web API, you have the flexibility to fully customize the code, giving you complete control over the design and functionality of your referral program. The **JavaScript Web API** enables you to: * **Add New Subscribers**: Seamlessly integrate subscriber registration into your application. * **Trigger Referrals**: Automate the referral process based on specific user actions. * **Access Participant Data**: Retrieve limited participant data to enhance user experiences. * **Generate Embeddable Widgets**: Create and customize widgets dynamically using JavaScript. * **Customize User Interfaces**: Tailor the design and functionality of signup forms, dashboards, and other components to match your brand’s specific needs and aesthetic. By leveraging the JavaScript Web API, you can create a highly customized referral program that integrates seamlessly with your application, providing a unique and optimized experience for your users. [**Ready to get started?**](https://berylsystems.gitbook.io/referral-hero-documentation/integrations/javascript-web-api/getting-started) Follow this step-by-step guide to implement the JavaScript Web API and begin integrating your personalized referral campaign today. # Getting Started The first and most crucial step is to install the **ReferralHero Global Tracking Code** on your website. This step is mandatory to ensure that your referral campaign can track user activities across your site and function correctly. **Follow these steps to add the Tracking Code to your website:** **Step 1 : Access Your Campaign Dashboard:** * Log in to your ReferralHero account. * Navigate to your campaign dashboard and select **Launch**. * Copy your unique Global Tracking Code from this section.
**Step 2 : Add the Tracking Code to Your Website:** * Insert the **Global Tracking Code** into the `` section of your website's HTML. This ensures the code is loaded on every page of your site, enabling comprehensive tracking of user interactions. * **Verify the Installation**: Ensure that the code is correctly placed by checking your site's source code or using browser developer tools.
**Step 3 : Enable the Global RH Object**: * Once the Global Tracking Code is installed, your web pages will have access to the global `window.RH` object. This object is essential for interacting with ReferralHero’s features and tracking user actions. By completing these steps, you ensure that your website is fully integrated with ReferralHero. # Configuration file ReferralHero utilizes a configuration file behind the scenes, containing all the properties of your campaign, such as the color of buttons, header text, social buttons to display, and more. > **Note:** Use the custom configuration file only if you want to customize the properties of your campaign. **Custom Configuration File** You can manually override any setting by using a custom configuration file. To do this, instantiate a global `window.RH_MFxxxxxxxxxx_Config` object **before** the Tracking Pixel. The custom configuration file must be instantiated **before** the Tracking Pixel; otherwise, it won't work. This is particularly useful when you want to make changes "on-the-fly" or only on specific pages. You don't need to specify every property—just include the settings you want to change, and ReferralHero will use your campaign defaults for the rest. {% hint style="danger" %} **Important:** * The custom Configuration file must be instantiated before the Tracking Pixel or else it won't work. * Replace `'MFxxxxxxxxxx'` with your actual campaign UUID. {% endhint %} ```javascript ``` The [**callbacks**](https://berylsystems.gitbook.io/referral-hero-documentation/integrations/javascript-web-api/callbacks) section is where you can define custom functions that will execute in response to specific events. For example, you might use callbacks to handle actions after a user submits a form or interacts with the campaign in a particular way. This part of the code is currently empty, but you can add functions here to customize the behavior based on your campaign needs. For more details on how to use callbacks, refer to the Callbacks article. **Key Points** * The `window.RH_MFxxxxxxxx_Config` object must be instantiated before the Tracking Pixel. * You only need to include the properties you want to override; ReferralHero will use campaign defaults for others. * The configuration allows for dynamic adjustments to the campaign on specific pages or conditions. # Callbacks Callbacks in ReferralHero are functions that get executed when specific events occur during the tracking and referral process. You define these callbacks within the `window.RHConfig` object. Each callback serves a particular purpose, allowing you to customize the behavior of your referral system. ### Defining Callbacks Callbacks are properties of the global variable `window.RHConfig`. Here's a general structure: ```html ``` {% hint style="info" %} **IMPORTANT:** Callbacks must be defined BEFORE the Tracking Pixel. {% endhint %} | Callbacks | Description | | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **onLoad** | This callback is triggered before everything else. It’s useful for initializing variables or performing actions that need to happen as soon as the tracking script is loaded. | | **ready** | Triggered when the Tracking Code is fully initialized, all widgets are generated, and all required libraries are loaded. This is usually the place to put logic that should run as soon as your tracking is ready to go. | | **beforeSubmit** | This callback is triggered right before the sign-up form is submitted. It’s useful for modifying the data that will be sent to the server. It receives an object containing form data like `name` and `email`. | | **success** | Triggered after the sign-up form has been successfully submitted. This callback receives an object with the response of the submission. Initializing this callback will prevent the default sharing screen from appearing. | | **afterSuccess** | Triggered after the form has been successfully submitted. Like `success`, it receives the submission response. However, initializing this callback will NOT prevent the sharing screen from appearing. | | **error** | This callback is triggered if there is an error during the form submission. It’s useful for handling errors gracefully. | | **popupOpen** | Triggered when a popup is opened. This can be used to track popup usage or to customize what happens when a popup is displayed. | | **popupClose** | Triggered when a popup is closed. Use this to track or manage actions after the user closes a popup | | **subscriberNotFound** | Triggered when an email that doesn’t exist in the system is used to check the status of a subscriber. | | **subscriberLoaded** | Triggered when a subscriber is identified. This is useful for loading subscriber-specific data or customizing the experience based on the subscriber’s information. | | **emailNotValid** | Triggered when the email entered is not valid. It receives a `reason` parameter explaining why the email is considered invalid. | | **serverProblem** | Triggered when the server returns a 500 or 4XX error, indicating a server-side issue. | ### Syntax for defining callbacks {% tabs %} {% tab title="Callbacks" %} ```html ``` {% endtab %} {% endtabs %} # Add a subscriber There are multiple ways to add subscribers to ReferralHero and generate referral links. Below, we walk through two methods using our JavaScript Web API to add subscribers. You might want to use one of these functions if you prefer: **Web Signup Form**: * Integrate the `add subscriber` function into your own web signup form. This allows you to add subscribers or identify them at the time of form submission. * This method is ideal for custom signup forms where you want to control the user experience and capture subscriber information seamlessly. **Web Login Page**: * Incorporate the `add subscriber` function into your web login page to add or identify subscribers during the login process. * This approach is useful if you want to track users as they log in while also adding them to your referral program automatically. {% hint style="danger" %} **Note:** When you add a subscriber using our JavaScript Web API, you’re leveraging our powerful global tracking script and cookie system. This means that the default referral link doesn't need to direct potential subscribers to a specific page URL containing the 'add a subscriber' function. Instead, our global tracking script automatically cookies and tracks each user as they visit and browse your website. When a visitor interacts with your form or page containing the 'add a subscriber' function, they will seamlessly convert into an "active subscriber." {% endhint %} ## **Adding a Subscriber (**Referred or Non-Referred**)** ```javascript RH_MFxxxxxxxxxx.form.submit(uniqueIdentifier); ``` When adding a subscriber to your ReferralHero campaign, you can track different conversion events based on your campaign goals. This guide explains how to add both referred and non-referred subscribers. {% hint style="info" %} **GOAL: One Conversion Event** * **Referral**: If the user is referred, a referral will be automatically created and set to **Confirmed** in the appropriate campaign. * **Non-referral**: A non-referred subscriber will be created in the specified campaign UUID. * **Existing Subscriber**: If the subscriber already exists in our database, they will be "identified". Existing data will not be overwritten, but additional data will be added. {% endhint %} {% hint style="info" %} **GOAL: Two or Three Conversion Events** * **Referral**: If the user is referred, a referral will be created and set to **Pending** in the appropriate campaign. * **Non-referral**: A non-referred subscriber will be created in the specified campaign UUID. * **Existing Subscriber**: If the subscriber already exists in our database, they will be "identified". Existing data will not be overwritten. {% endhint %} **Using the `RH_MFxxxxxxxxxx.form.submit()` Function** To add a subscriber according to the above logic, use the `RH_MFxxxxxxxxxx.form.submit()` function and pass the user information such as email address, name, etc. Here's an example of how to implement this in your form: {% hint style="danger" %} **IMPORTANT** * Replace `'MFxxxxxxxxxx'` with your specific campaign UUID. * The fields `'#email'`, `'#phone_number'`, `'#crypto_wallet_address'`, or any other unique identifiers enabled in your campaign are required and must not be left blank. * The ReferralHero Dashboard, Signup Widget, Floating Widget, or JavaScript API (`RH_MFxxxxxxxxxx.form.submit()`) should only be included once per webpage. Do not include multiple instances of these elements on the same page. {% endhint %} {% tabs %} {% tab title="JavaScript" %} ```html ``` {% endtab %} {% tab title="Web From" %} ```html
``` {% endtab %} {% endtabs %} If a referral link is not used, the system will create a **non-referred subscriber**. If a referral link is used, the system will evaluate the conversion events and create or update the referral accordingly. * **For a campaign with one conversion event**, a referral will be created and set to **Confirmed** upon completion of the event. Subscriber 1 (without referral code) , subscriber 2 (used subscriber 1's referral code)
* **For campaigns with two or three conversion events**, a referral will be created and set to **Pending** until the additional events are completed. Subscriber 1 (without referral code) , subscriber 2 (used subscriber 1's referral code)
## Example: Add a Subscriber (Custom Unique Identifier - Crypto Wallet Address) If you are utilizing the ReferralHero Blockchain integration, you must also include the `#crypto_wallet_provider` in your data. To add a subscriber using their crypto wallet address, use the `RH_MFxxxxxxxxxx.form.submit()` function. This approach is especially useful when integrating with a custom 'wallet connect' system, enabling efficient management and tracking of participants based on their wallet information. By providing both the wallet address and provider details, you can seamlessly integrate and track subscribers within your referral program. {% tabs %} {% tab title="JavaScript" %} ```html ``` {% endtab %} {% tab title="Web Form" %} ```html
``` {% endtab %} {% endtabs %} {% hint style="info" %} **Important:** If you are using the ReferralHero Blockchain integration, you must include the `#crypto_wallet_provider` in the following format: * metamask * phantom * coinbase * ledger * exodus * trezor * myetherwallet * jaxx * guarda * trustwallet *If you need to include additional wallet providers, please email us at ****.* {% endhint %} ## Running Multiple Campaigns Imagine you are running an e-commerce platform and need to direct new customers and returning customers to different referral campaigns. Follow these steps to set up your ReferralHero integration: 1. **Install the Global Tracking Script** Ensure that the ReferralHero Global Tracking Script is added to the `
` section of your website. This will enable tracking across all pages. 2. **Define Campaigns** Identify the campaign UUIDs for new customers and returning customers. 3. **Submit Subscriber Information** * **For New Customers:** Use the following function to add new customers to the specified campaign: Copy ```javascript RH_MFxxxxxxxxxx.form.submit(); // Campaign 1 ``` * **For Returning Customers:** Use this function to track returning customers and ensure they are placed in the appropriate campaign: Copy ```javascript RH_MFxxxxxxxxxx.form.submit(); // Campaign 2 ``` *Note: Replace* `MFxxxxxxxxxx` *with your actual campaign UUIDs.* # Add a Pending Referral ```javascript RH.pendingReferral(uniqueIdentifier); ``` This function is used to track referrals that enter the first step of a multi-step conversion event . {% hint style="warning" %} **GOAL: Two or Three Conversion Events** Your campaign Goal must be set up to track two or three conversion events, only then the following tracking logic will take place: * **Tracking Referrals:** * When a user is referred to your campaign, they enter the first step of your multi-step conversion event. * At this point, a referral will be automatically created and marked as "Pending" within the appropriate campaign. This status indicates that the referral has begun the conversion process but hasn't yet completed all the necessary steps. * **Non-Referrals:** * If the user is not a referral (i.e., they weren't referred by someone else in your campaign), no action is taken. Specifically, no subscriber record will be created for them. * This ensures that only those users who are actually referred are tracked within the multi-step process. {% endhint %} **Implementation Example** To add a pending referral, simply call ReferralHero's `RH.pendingReferral()` function, passing in user information such as an email address, name, or any other identifier set up for your campaign. Here is an example of how to implement this: {% tabs %} {% tab title="JavaScript" %} ```html ``` {% endtab %} {% tab title="Web Form" %} ```html

Track Pending Referral

``` {% endtab %} {% endtabs %} {% hint style="danger" %} IMPORTANT * '#email, '#phone\_number', '#crypto\_wallet\_address' or '#other ID' that have been enabled as the campaign unique identifier is required and can’t be blank. * The ReferralHero Dashboard, Signup, Floating Widget, or Javascript API can only be used once on a single webpage. Do not add them multiple times on the same webpage. {% endhint %} **Check if a Pending Referral is Tracked or not** 1. **Open the Console:** * Before submitting the form, open your browser's Developer Tools and go to the **Console** tab. 2. **Submit the Form:** * Fill in the form fields (e.g., name and email) and click "Submit." 3. **Check the Console:**

Pending Referral is successfully tracked (Referred by someone)

Pending Referral is successfully tracked (Referred by someone)

* After confirming in the console that the pending referral is tracked, you can then verify that the referral appears as "Pending" in your ReferralHero dashboard.
# Track multi-step conversion events ReferralHero supports tracking multi-step conversion events, enabling you to reward referrers who guide others through various stages of a conversion process. This feature is ideal for campaigns where you want to track actions such as signing up and purchasing, booking a call and making a purchase, or creating an account and subscribing. {% hint style="info" %} **Important:** To utilize multi-step conversion tracking, ensure your campaign is set up to track multiple conversion events. You can configure this by going to your campaign dashboard, selecting **Edit campaign > Goal**, and opting for "Track two or three conversion events. {% endhint %} **Example Scenario:** **Use Case:** Imagine a company that offers a high-end fitness program. They want to reward users who refer others to complete two specific actions: scheduling a free trial session and then signing up for a paid membership. 1. **Initial Action:** The referred individual schedules a free trial session. * The referral's status is marked as ‘Pending,’ which is tracked when adding the subscriber. 2. **Completion of Membership Signup:** The referred person subsequently signs up for a paid membership. * The referral’s status is updated to ‘Unconfirmed’ or ‘Confirmed,’ depending on your campaign’s configuration. This status change is tracked based on the provided steps. By implementing multi-step conversion tracking with ReferralHero, you can accurately monitor and reward referrers based on the detailed stages of the referral process. ## Track Referral Conversion Event Only To track a conversion event, use the following function: ```javascript RH.trackReferral(uniqueIdentifier); ``` Here, `uniqueIdentifier` refers to the unique identifier of the person who has converted (e.g., email, phone number, crypto wallet address). This value is required to accurately track the conversion. {% hint style="info" %} When tracking a referral conversion using `RH.trackReferral(uniqueIdentifier)`, the following logic is applied: * **If the referral already exists in the campaign as Pending:** The system will automatically recognize and update the status of the referral. * **If the referral is cookied (recognized through cookies):** A new referral is automatically created in the appropriate campaign. * **If it is not a referral:** The system will do nothing, and no action will be taken. **The status of the referral will then be set as follows:** * **Confirmed** (If your campaign tracks two conversion events) * **Unconfirmed** (If your campaign tracks three conversion events) {% endhint %} **Example: Tracking a Paid Plan Upgrade** Suppose you want to track a referral when a user upgrades to a paid plan. You can trigger the `RH.trackReferral()` function at the point of purchase, as shown below: ```html ``` In this example, you should replace `uniqueIdentifier` with the actual unique identifier of the user (e.g., their email). **Alternative: Tracking on Page Load** If you prefer to trigger the referral tracking when a user visits a specific page (e.g., a "Thank You" page after conversion), it's recommended to place the `RH.trackReferral()` call inside the `ready()` callback to ensure the ReferralHero object is fully loaded: ```html ``` **Implementation Example:-** {% tabs %} {% tab title="JavaScript" %} ```html ``` {% endtab %} {% tab title="Web Form" %} ```html
``` {% endtab %} {% tab title="Developer COnsole" %}
{% endtab %} {% endtabs %} {% hint style="danger" %} **Important:** Replace `'MFxxxxxxxxxx'` with your actual campaign UUID. This UUID is essential to correctly track and manage referrals and subscribers in the correct campaign. {% endhint %} **Example Scenario:** * **Referred User:** A user referred by someone else signs up on your lead magnet page and is marked as a Pending referral. Later, this user completes a purchase. The `RH_MFxxxxxxxxxx.organicTrackReferral()` function updates the referral status from Pending to Confirmed or Unconfirmed, depending on the campaign setup. * **Non-Referred User:** A user who was not referred completes a purchase. The `RH_MFxxxxxxxxxx.organicTrackReferral()` function adds this user as a subscriber to your campaign, allowing them to start referring others. ## Sending Extra Data With Tracking In addition to tracking a referral conversion using `RH.trackReferral(uniqueIdentifier)` you can send extra data about the referral by adding an optional second parameter. This allows you to include details such as the name of the subscriber, the value of the conversion, and more. **Example:** Here's how you can send extra data along with the referral tracking: {% tabs %} {% tab title="JavaScript" %} ```html ``` {% endtab %} {% tab title="Web Form" %} ```html

Referral Conversion Form






ht ``` {% endtab %} {% tab title="Developer Console" %}

Output

{% endtab %} {% tab title="ReferralHero Dashboard" %}

The data is sucessfully added & referral is tracked.

{% endtab %} {% endtabs %} {% hint style="danger" %} Here’s a breakdown of the optional extra data parameters you can send: * **`name`:** The subscriber's name. This helps personalize records and communication with the user. * **`value`:** The monetary value of the referral. For instance, if the referral is worth $100, you should provide the value as 100. This parameter is useful for financial reporting and analysis. * **`transaction_id`:** A unique identifier for the transaction. This is important for linking the referral to a specific purchase or event, which facilitates detailed tracking and reporting. * **`category`:** The type of referral. This helps categorize the referral, which is beneficial if you are tracking conversions across different products or stages. It also aids in generating detailed reports. {% endhint %} By including this extra data, you can gain deeper insights into your referral campaigns, making it easier to analyze performance and optimize your strategies. ## Tracking Referrals Without Emails ReferralHero typically requires a unique identifier to track referrals. However, if you don’t have the actual email address or identifier of the referral, you can use a randomly generated identifier. The important thing is to ensure that the identifier is unique to avoid conflicts. Here’s how you can generate a unique identifier and use it for tracking: **Example Code** You can create a random unique identifier, such as a fake email address, and use it for tracking. Here’s a sample code snippet to demonstrate this: ``` ``` > **Note:** > > While this method allows you to track referrals without having the actual email address or identifier, ensure that the random identifier you generate is unique each time. This approach is useful for situations where you don’t need to track the specific identity of the referral but still want to capture referral actions. ## Callback Optionally, you can execute a function after the referral has been tracked by adding a callback function as an argument to the `RH.trackReferral()` function. Here's how you can do it: **Example with Extra Data** If you need to send additional data, use the callback function as the third parameter: ``` ``` **Example without Extra Data** If you don't need to send any extra data, you can pass the callback function as the second parameter: ``` ``` # Track Transaction ReferralHero provides the ability to track ongoing transactions, allowing you to reward affiliates not just for the initial transaction but for subsequent transactions as well. This is particularly useful for businesses that want to offer commissions for recurring purchases, upgrades, or any other form of ongoing customer engagement. ## Why Track Ongoing Transactions? * **Maximize Affiliate Engagement**: By rewarding affiliates for ongoing transactions, you incentivize them to drive not just sign-ups but also long-term, high-value customers. * **Encourage Customer Retention**: Affiliates are more likely to promote your brand if they know they can earn commissions on recurring purchases, leading to better customer retention. ## How Does It Work? To track ongoing transactions, you pass transaction data to ReferralHero using the method mentioned below. This method records details about each transaction, such as the transaction amount, product ID, and customer email. By doing so, ReferralHero can attribute these transactions to the appropriate affiliate and calculate commissions accordingly. ```javascript RH_MFxxxxxxxxxx.trackTransaction(data); ``` ## Example: Tracking a Transaction This example dynamically collects transaction details from a form and then tracks the transaction when the form is submitted. {% tabs %} {% tab title="First Tab" %} ```html ``` {% endtab %} {% tab title="Second Tab" %} ```html
``` {% endtab %} {% tab title="Developer Console" %}

If Transaction is tracked successfully

If Transaction is not tracked

{% endtab %} {% endtabs %} {% hint style="warning" %} Replace the `MFxxxxxxxxxx` with your specific campaign UUID. {% endhint %} To verify that the transaction tracking is working correctly, you can follow these steps: 1. **Navigate to the Main Page**: Start by logging into your ReferralHero account and navigating to the main dashboard. 2. **Access Reward Logs**: Once on the main dashboard, go to the "Reward Logs" section in sidebar. This is where all tracked transactions and rewards are recorded. 3. **View Transactions**: Within the "Reward Logs" section, find the "Transaction" sub-section. This will display all the transactions that have been tracked by ReferralHero. 4. **Check for Latest Transaction**: Look through the list of transactions to find the most recent one. Verify that the details (e.g., amount, product ID, customer email) match the data you passed in your transaction tracking script. If the latest transaction is listed with the correct details, it confirms that the transaction tracking is functioning as expected. If it's not there, double-check the implementation of your tracking script to ensure that all required data is being correctly captured and passed to ReferralHero. # Identify a Subscriber The `RH.identify` function is used to identify a subscriber so that they don’t need to manually enter their information again, such as their email address or name. This function is particularly useful for displaying embeddable widgets on internal pages of your website where you already have the subscriber’s unique identifier. ```javascript RH_MFxxxxxxxxxx.identify(data, force, callback); ``` {% hint style="info" %} **Note:** The `RH.identify` function is an advanced version of the '[Add a Subscriber](https://berylsystems.gitbook.io/referral-hero-documentation/integrations/javascript-web-api/add-a-subscriber)' function and offers additional properties like `upsert`, `force identification`, and more. It is not always necessary to call `RH.identify` if you have already used an '[Add a Subscriber](https://berylsystems.gitbook.io/referral-hero-documentation/integrations/javascript-web-api/add-a-subscriber)' function, as 'Add a Subscriber' will also identify the subscriber. {% endhint %} ## Parameters 1. **Data** (Object, Required): An object containing user data. At a minimum, this object must include the unique identifier of the user. Additional fields can be included as needed. 2. **Force** (Boolean, Optional): Determines whether to override an existing session. The default value is `false`. Set this to `true` to force identification even if the user is already identified. 3. **Callback** (Function, Optional): A callback function that is executed if the identification succeeds. This function receives the subscriber data as a parameter. ```javascript var myFunc = function(data) { console.log(data); } var data = { email: "john@smith.com", name: "John Smith", extra_field: "USA", extra_field_2: null, upsert: true } RH_MFxxxxxxxxxx.identify(data, false, myFunc); ``` {% hint style="danger" %} **Important:** Replace `'MFxxxxxxxxxx'` with your actual campaign UUID. {% endhint %} ### Implementation Example Here’s how you might use the `RH.identify` function with a form submission: {% tabs %} {% tab title="JavaScript" %} ```html ``` {% endtab %} {% endtabs %} ## Detailed Behavior 1. **Automatic Subscriber Creation**: When the `RH.identify` function is called, ReferralHero will check if a subscriber with that specific unique identifier exists. * **If a subscriber is not found**, a new subscriber is automatically created using the data sent over, bypassing the verification method. * **If the subscriber with that unique identifier already exists**, ReferralHero simply returns the existing subscriber data. If you don’t want to automatically create a new subscriber when one isn't found (e.g., to allow manual opt-in), set the `upsert` property to `false`. 2. **Load Callback**: The ReferralHero Tracking Code loads asynchronously. If you intend to execute any `RH` functions on page load, you must wait until the library has completely loaded. Use the `callbacks.ready` method to ensure that the code runs only after ReferralHero has finished loading. 3. **Force Identification**: By default, if a cookie session is already present (e.g., the user has already been identified in the past), ReferralHero will not attempt to identify the user again to improve the user experience. This avoids unnecessary delays (typically around 1 second). If you want to identify users every time regardless of an existing session, set the `force` parameter to `true`. {% hint style="danger" %} **Note:** Our recommendation is to **not force identification**, as it can degrade the user experience. If you force identification, ReferralHero will check the existence of the subscriber every time a person visits that page, which can slow down your website. {% endhint %} {% hint style="info" %} **Important** * If you have already called the `RH.form.submit()` function on a portal signup/login form, there is no need to call `RH.identify()` again on an internal page as the subscriber is already identified. * The `upsert` property allows you to update an existing subscriber's information or create a new subscriber if one does not exist. Setting `upsert` to `false` prevents the automatic creation of a new subscriber. * The `force` parameter can be used to override an existing session and re-identify the user if needed. However, avoid using it to prevent impacting user experience. * The `callback` parameter allows you to execute custom code upon successful identification, making it easier to handle responses or perform additional actions. {% endhint %} ## ReCaptcha Unfortunately, if you're using ReCaptcha, `RH_MFxxxxxxxxxx.identify()` will not work. # Identify a Referrer Here, we'll explore how to use the `RH_MFxxxxxxxxx.referrer` variable, a powerful tool for retrieving the referrer code associated with a user. By leveraging this variable, you can tailor your code to execute specific actions based on whether or not a user was referred to your site. The `RH_MFxxxxxxxxxx.referrer` variable is a key component in tracking and utilizing referral codes in your website or application. By using this variable, you can detect whether a user has been referred by someone else and trigger specific actions based on that information. This section will guide you through the practical applications of `RH_MFxxxxxxxxxx.referrer`, how it works, and how you can implement it in your own code. ## What is the `RH_MFxxxxxxxxxx.referrer` Variable? The `RH_MFxxxxxxxxx.referrer` variable stores the referrer code if it is available. This code can be found in the URL query string (e.g., `?mwr=xxxxxxxx`) or stored within a cookie named `__maitre-referrer-` in the user's browser. The referrer code typically represents a unique identifier associated with the person who referred the user to your site. * **URL-Based Referrer Code**: When a user clicks on a referral link, the referrer code is appended to the URL, allowing your site to recognize the referral. * **Cookie-Based Referrer Code**: If the user’s browser has the `__maitre-referrer-` cookie, it indicates that the user was referred previously, even if they navigate to your site later without the referral link in the URL. The `RH_MFxxxxxxxxxx.referrer` variable does not require any specific method calls. Instead, it is automatically available in your code once the ReferralHero script is loaded on your site. When called, `RH_MFxxxxxxxxxx.referrer` will return the referrer code if it exists, or `undefined` if no referrer code is present. ## Implementing `RH_MFxxxxxxxxxx.referrer` in Your Code Here’s a basic example of how you can implement the `RH_Mfxxxxxxxxxx.referrer` variable in your code: Copy ```javascript window.RHConfig = { callbacks: { ready: function() { if (RH_MFxxxxxxxxxx) { var referrerCode = RH_MFxxxxxxxxxx.referrer; if (referrerCode) { // Logic to execute if a referrer code is present console.log("Referrer Code Found: " + referrerCode); // Example: Apply discount, personalize page, etc. } else { // Logic if no referrer code is found console.log("No Referrer Code Detected"); } } } } } ``` * **Step 1**: The script waits until ReferralHero is fully loaded by using the `ready` callback. * **Step 2**: It checks whether the `RH_MFxxxxxxxxxx.referrer` variable has a value. * **Step 3**: Depending on whether a referrer code is present, different logic can be applied. For instance, you might apply a discount if a referrer code is found. {% hint style="warning" %} **Important:** Replace `'MFxxxxxxxxxx'` with your actual campaign UUID. This UUID is essential to get the correct referrer code. {% endhint %} ## Practical Applications of `RH_MFxxxxxxxxxx.referrer` Knowing whether a user was referred allows you to enhance their experience on your website. Here are two practical examples: 1. **Automatic Discount Application**: Suppose you want to offer a special discount to users who were referred by others. By checking if `RH_MFxxxxxxxxxx.referrer` has a value, you can automatically apply a discount code during the checkout process. 2. **Personalized Landing Page Content**: You can personalize the text, offers, or even the entire layout of a landing page based on the referrer code. For instance, if the user was referred by a friend, you might display a welcome message mentioning the referrer’s name. **Implementation Example Applying discount if Referred:** {% tabs %} {% tab title="JavaScript" %} ```html ``` {% endtab %} {% tab title="Web Form" %} ```html
``` {% endtab %} {% tab title="Outputs" %}

If Referred:-

If not Refered:-

{% endtab %} {% endtabs %} *This is just an example; you can use it in your own way. You can replace the `console.log` statement with your own logic, depending on your use case.* # Generate Dashboard Widget You can integrate the ReferralHero Dashboard Widget into your website to allow users to sign up, log in, and share referrals. This widget can be generated and added to your webpage using JavaScript. The complete ReferralHero Dashboard Widget, which includes both the signup/login form and the sharing screen, you can use the following JavaScript function: ```javascript RH_MFxxxxxxxxxx.generate.form(); ``` This function returns an HTML element containing the full widget. You can then append this widget to a specific element on your page to make it visible to users. ### **Steps to Display the Widget** * **Create an HTML Element**: First, add a `div` element to your webpage where you want the widget to appear. For example: ```html
``` * **Generate and Append the Widget**: Use the following JavaScript code to generate the widget and append it to the `div` element created above: ```html ``` ### **Displaying the Dashboard Widget in a Popup** To enhance user engagement and streamline interactions, you can display the ReferralHero Dashboard Widget in a popup. This approach allows users to access the signup/login form and sharing screen without navigating away from their current page. **Generating the Widget Popup** You can easily display the widget in a popup by calling the `RH_MFxxxxxxxxxx.generate.popup()` function. This function creates a popup containing the widget, providing a seamless user experience. Here's how to implement it: * **Create a Button to Trigger the Popup**: Add a button or any clickable element to your webpage that will open the popup when clicked. ```html ``` * **Write JavaScript to Handle the Button Click and Open the Popup**: Use the following JavaScript code to generate the widget and display it in a popup when the button is clicked: ```html ``` {% hint style="warning" %} **Note:** * **Ensure the ReferralHero Tracking Code is Installed**: Make sure that the ReferralHero Tracking Code is correctly included on your page to enable the generation and display of the widget. * Replace MFxxxxxxxxx with your specific campaign UUID. {% endhint %} # Generate Sharing-Screen ReferralHero provides a function to generate the Sharing Screen of the Dashboard Widget. Before generating the Sharing Screen, it's essential to identify the subscriber. Once the subscriber is identified, you can use the following method: ```javascript RH_MFxxxxxxxxxx.generate.sharing_screen(); ``` Generating the sharing screen manually can be advantageous in scenarios where you want to control exactly when and where the sharing screen appears. For instance, you might want to display the sharing screen after a user has completed a specific action, such as signing up or purchasing a product, or when they click a button. **Steps to Implement** 1. **Identify the Subscriber**: Ensure that the subscriber is identified using the `RH_MFxxxxxxxxxx.form.submit()` or `RH_MFxxxxxxxxxx.identify()` method. 2. **Generate the Sharing Screen**: Call the `RH_MFxxxxxxxxxx.generate.sharing_screen()` method to create the Sharing Screen HTML element. 3. **Append the Sharing Screen to Your Page**: You can append the generated Sharing Screen to any element on your webpage, such as a `div` container. This will make the Sharing Screen visible to your users. **Example Implementation** Here's an example of how to display the Sharing Screen within a `div` element with the ID `sharing-screen`: ```html
``` {% hint style="warning" %} Replace the `MFxxxxxxxxxx` with your specific campaign UUID. {% endhint %} ## Displaying the Sharing Screen in a Popup To display the sharing screen in a popup, you can call the following function: ```javascript RH_MFxxxxxxxxxx.generate.popup(RH_MFxxxxxxxxxx.generate.sharing_screen()); ``` This command will create the sharing screen and display it inside a popup window. This approach is useful for keeping your page clean and only showing the sharing options when necessary. **Example: Triggering the Popup on a Button Click** If you want to display the sharing screen when a user clicks a button, you can implement it like this: ```html ``` **Practical Use Case** This approach is perfect for scenarios where you want to offer a clean and focused user experience by only showing referral options when a user is ready, such as after completing a purchase or signing up for a service. It ensures that the sharing screen doesn't clutter the page and only appears when needed. # ReactJS In this section, we will review the different methods to include the ReferralHero external JavaScript library in a ReactJS project. {% hint style="info" %} **Please Note:** * `RH_MFxxxxxxxxxxx` are placeholders for your campaign's UUID, which you will need to replace with your actual campaign UUID. {% endhint %} ## **Create and Set Up the React Application:** **Step 1: Create a React Application** Open your terminal or command prompt and use the following command to create a new React app: ```jsdoc npx create-react-app name_of_the_app ``` **Step 2: Navigate to the Application Directory** After the application has been created, navigate to the project directory using: ``` cd name_of_the_app ``` **Step 3: Open the Project Structure** Navigate through the default structure generated by `create-react-app`. The main file you’ll be working with is `App.js` located in the `src` folder & can design your custom pages.
Now you're ready to start adding your custom code or configurations! ## **Add ReferralHero Global Tracking Code** **Option 1: Add in** `public/index.html` 1. Navigate to the `public` folder in your React application. 2. Open `index.html`. 3. Inside the `` section, add the ReferralHero tracking script: {% tabs %} {% tab title="public/index.html" %} ```html React App
``` {% endtab %} {% endtabs %} **Option 2: Add in `src/App.js` (Root File)** 1. Open `src/App.js` in your React app. 2. Inside the `useEffect` hook, include the script dynamically: {% tabs %} {% tab title="src/App.js" %} ```javascript import { useEffect } from 'react'; function App() { useEffect(() => { const script = document.createElement('script'); script.textContent = ` !function(m,a,i,t,r,e){if(m.RH)return;r=m.RH={},r.uuid =t,r.loaded=0,r.base_url=i,r.queue=[],m.rht=function() {r.queue.push(arguments)};e=a.getElementsByTagName('script') [0],c=a.createElement('script');c.async=!0,c.src= 'https://referralhero-global-code.s3.amazonaws.com/'+'production'+ '/'+t+'.js',e.parentNode.insertBefore(c,e)}(window,document, 'https://app.referralhero.com/','RHxxxxxxxxx'); `; document.body.appendChild(script); return () => { document.body.removeChild(script); }; }, []); return (

Welcome to My App

); } export default App; ``` {% endtab %} {% endtabs %} Both methods will enable the ReferralHero script in your React application. Use the one that fits best with your project structure! ## **Installing the ReferralHero Widget** You have the flexibility to add the ReferralHero widget to specific components or pages of your application. Since the global tracking script is already included in the root file, you don’t need to add it again on each page. ### **Steps to Install the Widget** 1. **Choose the Widget to Install** * ReferralHero provides multiple widget types, such as the Signup Widget, Dashboard Widget, and Sharing Widget. * You can select the appropriate widget based on your campaign goals. 2. **Insert the Widget's HTML Element** * After adding the tracking script, include the widget's HTML code into your React component where you want the widget to appear. You need to replace the placeholder `MFxxxxxxxxxx` with your campaign's UUID. 3. **Code Example: Adding a widget in a component**: * For example , here we have added the advocate dashboard widget in newly created dashboard component. You can add it wherever you want. {% tabs %} {% tab title="src/Dashboard.js" %} ```javascript function Dashboard() { return (
{/* Add the ReferralHero widget here */}
); } export default Dashboard; ``` {% endtab %} {% endtabs %} {% hint style="info" %} **Note:** The `MFxxxxxxxxxx` is a placeholder and should be replaced with your campaign's UUID. {% endhint %} ## **Adding ReferralHero Custom Methods for Tracking User Actions** To utilize custom methods like `RH.form.submit` ,`RH.trackReferral` , etc in your React application, follow these steps: ### 1) Using `RH.form.submit` Method: The `RH.form.submit` method allows you to add subscribers to your referral campaign directly from your forms. This integration simplifies the signup process for your users, making it easy for them to join your referral program. For more detailed information about `RH.form.submit` and its functionalities, click [here](https://berylsystems.gitbook.io/referral-hero-documentation/integrations/javascript-web-api/add-a-subscriber). {% tabs %} {% tab title="Method" %} ```javascript const handleSubmit = (e) => { e.preventDefault(); const data = { email: email, name: name, phone_number: phone, }; if (window.RH_MFxxxxxxxx) { window.RH_MFxxxxxxxxx.form.submit(data) console.log("Subscriber created or tracked successfully"); } else { console.log("Subscriber not tracked"); } }; ``` {% endtab %} {% tab title="React Component" %} ```jsx import React, { useState } from 'react'; const Register = () => { const [email, setEmail] = useState(''); const [name, setName] = useState(''); const [phone, setPhone] = useState(''); const handleSubmit = (e) => { e.preventDefault(); const data = { email: email, name: name, phone_number: phone, }; if (window.RH_MFxxxxxxxxx) { window.RH_MFxxxxxxxxx.form.submit(data) console.log("Subscriber created or tracked successfully"); } else { console.log("Subscriber not tracked"); } }; return (
setName(e.target.value)} placeholder="Name" required /> setEmail(e.target.value)} placeholder="Email" required /> setPhone(e.target.value)} placeholder="Phone Number" />
); }; export default Register; ``` {% endtab %} {% endtabs %} ### 2) Using `RH.pendingReferral` Method: To track referrals that enter the first step of a multi-step conversion event, you can use the `RH.pendingReferral` method. For more detailed information about `RH.pendingReferral` and its functionalities, click [here](https://berylsystems.gitbook.io/referral-hero-documentation/integrations/javascript-web-api/add-a-pending-referral). {% tabs %} {% tab title="Method" %} ```jsx useEffect(() => { window.RHConfig = { callbacks: { ready: function () { const form = document.getElementById("referral-form"); if (form) { form.addEventListener("submit", function (e) { e.preventDefault(); const data = { name: form.querySelector('#name').value, email: form.querySelector('#email').value, }; window.RH.pendingReferral(data); }); } }, }, }; return () => { window.RHConfig = {}; }; }, []); ``` {% endtab %} {% tab title="React Component" %} ```jsx import React, { useEffect } from 'react'; const Login = () => { useEffect(() => { window.RHConfig = { callbacks: { ready: function () { const form = document.getElementById("referral-form"); if (form) { form.addEventListener("submit", function (e) { e.preventDefault(); const data = { name: form.querySelector('#name').value, email: form.querySelector('#email').value, }; window.RH.pendingReferral(data); }); } }, }, }; return () => { window.RHConfig = {}; }; }, []); return (
); }; export default Login; ``` {% endtab %} {% endtabs %} ### 3) Using `RH.trackReferral` Method: The `RH.trackReferral` method is used to track referrals or add them to a campaign if they already exist as "Pending." If a referral is recognized through cookies, a new referral will automatically be created in the appropriate campaign. If the user is not a referral, no action will be taken by the system. For more detailed information about `RH.trackReferral` and its functionalities, click [here](https://berylsystems.gitbook.io/referral-hero-documentation/integrations/javascript-web-api/track-multi-step-conversion-events#track-referral-conversion-event-only). {% tabs %} {% tab title="Method" %} ```jsx useEffect(() => { window.RHConfig = { callbacks: { ready: function () { const form = document.getElementById("refer-form"); if (form) { form.addEventListener("submit", function (e) { e.preventDefault(); const email = form.querySelector('#email').value; const data = { name: form.querySelector('#name').value, transaction_id: form.querySelector('#transaction_id').value, }; window.RH.trackReferral(email, data); }); } }, }, }; return () => { window.RHConfig = {}; }; }, []); ``` {% endtab %} {% tab title="React Component" %} ```jsx import React, { useEffect } from 'react'; const Refer = () => { useEffect(() => { window.RHConfig = { callbacks: { ready: function () { const form = document.getElementById("refer-form"); if (form) { form.addEventListener("submit", function (e) { e.preventDefault(); const email = form.querySelector('#email').value; const data = { name: form.querySelector('#name').value, transaction_id: form.querySelector('#transaction_id').value, }; window.RH.trackReferral(email, data); }); } }, }, }; return () => { window.RHConfig = {}; }; }, []); return (
); }; export default Refer; ``` {% endtab %} {% endtabs %} ### 4) Using `RH.organicTrackReferral` Method: The `RH.organicTrackReferral` function is used to track referrals or add non-referred subscribers to your ReferralHero campaign on the conversion page. This function ensures that both referred and non-referred users are accurately tracked and recorded in your campaign. For more detailed information about `RH.organicTrackReferral` and its functionalities, click [here](https://berylsystems.gitbook.io/referral-hero-documentation/integrations/javascript-web-api/track-multi-step-conversion-events#track-referral-conversion-event-or-add-an-organic-subscriber). {% tabs %} {% tab title="Method" %} ```jsx useEffect(() => { window.RHConfig = { callbacks: { ready: function () { const form = document.getElementById("organic-referral-form"); if (form) { form.addEventListener("submit", function (e) { e.preventDefault(); const data = { name: form.querySelector('#name').value, email: form.querySelector('#email').value, phone_number: form.querySelector('#phone').value, }; window.RH_MFxxxxxxxxxxx.organicTrackReferral( data); }); } }, }, }; return () => { window.RHConfig = {}; }; }, []); ``` {% endtab %} {% tab title="React Component" %} ```jsx import React, { useEffect } from 'react'; const Refer = () => { useEffect(() => { window.RHConfig = { callbacks: { ready: function () { const form = document.getElementById("organic-referral-form"); if (form) { form.addEventListener("submit", function (e) { e.preventDefault(); const data = { name: form.querySelector('#name').value, email: form.querySelector('#email').value, phone_number: form.querySelector('#phone').value, }; window.RH_MFxxxxxxxxxx.organicTrackReferral( data); }); } }, }, }; return () => { window.RHConfig = {}; }; }, []); return (
); }; export default Refer; ``` {% endtab %} {% endtabs %} ### 5) Using `RH.trackTransaction` Method: This method allows you to track transactions by passing relevant transaction data such as the amount, product ID, and customer email. For more detailed information about `RH.trackTransaction` and its functionalities, click [here](https://berylsystems.gitbook.io/referral-hero-documentation/integrations/javascript-web-api/track-transaction). {% tabs %} {% tab title="Method" %} ```jsx useEffect(() => { window.RHConfig = { callbacks: { ready: function () { const form = document.getElementById("transaction-form"); if (form) { form.addEventListener("submit", function (e) { e.preventDefault(); const data = { email: form.querySelector('#email').value, amount: form.querySelector('#amount').value, product_id: form.querySelector('#product_id').value, transaction_id: form.querySelector('#transaction_id').value, }; window.RH_MFxxxxxxxxxx.trackTransaction(data); }); } }, }, }; return () => { window.RHConfig = {}; }; }, []); ``` {% endtab %} {% tab title="React Component" %} ```jsx import React, { useEffect } from 'react'; const Transaction = () => { useEffect(() => { window.RHConfig = { callbacks: { ready: function () { const form = document.getElementById("transaction-form"); if (form) { form.addEventListener("submit", function (e) { e.preventDefault(); const data = { email: form.querySelector('#email').value, amount: form.querySelector('#amount').value, product_id: form.querySelector('#product_id').value, transaction_id: form.querySelector('#transaction_id').value, }; window.RH_MFxxxxxxxxxx.trackTransaction(data); }); } }, }, }; return () => { window.RHConfig = {}; }; }, []); return (
); }; export default Transaction; ``` {% endtab %} {% endtabs %} By implementing this, ReferralHero will record the transaction and handle the attribution automatically. By leveraging these powerful methods—`form.submit`, `pendingReferral`, `trackReferral`, `organicTrackReferral`, and `trackTransaction`—you can efficiently manage user tracking, referrals, and transaction attribution in your ReferralHero campaigns. # REST API So you are building an integration with ReferralHero. GREAT! We're very excited that you want to add-on to our platform. Before you dive in and start coding, make sure you read this page to know how to structure your app. ### **Overview** The ReferralHero API is organized around [REST](http://en.wikipedia.org/wiki/Representational_State_Transfer). Our API has predictable, resource-oriented URLs. [JSON](http://www.json.org/) is returned by all API responses, including errors. ReferralHero API is in active development, hence expect things to change. We will add new endpoints and change minor details here and there, but if *we* introduce breaking changes we will notify you at least 2 weeks in advance. ### **API Endpoint** Calls for ReferralHero API are relative to the URL **** ### **API Token** All API calls require an **API token** sent in the request **headers**. You can find your API Token in your **ReferralHero Account > API Page**. Your API token carries many privileges, so be sure to keep it secret! \ Do not share your secret API token in publicly accessible areas such GitHub, client-side code, and so forth. Also, you should write back-end only code, since front-end code will expose your API token and can be used for malicious activities. All API requests should be made over [HTTPS](http://en.wikipedia.org/wiki/HTTP_Secure). API requests without authentication will fail with the error code "no\_token". ### Authentication All API requests must be authenticated using an API token. **Preferred (**Recommended) **:** Authorization: `Bearer YOUR_API_TOKEN` **Alternative :** X-API-Key: `YOUR_API_TOKEN` > Use X-API-Key only if your client cannot send the Authorization header. **Headers** | Name | Value | Description | | ------------- | ----------------------- | ------------------ | | Authorization | Bearer `YOUR_API_TOKEN` | (Preferred) | | X-API-Key | `YOUR_API_TOKEN` | Alternative option | ### Responses * Data is returned in JSON. * Any non-`200` HTTP response code can be considered an error. ### **Rate limiting** Currently, we apply a "soft" limit of 5,000 API calls per hour. Get in touch with us if you need to increase it. If your request rate exceeds our limits, you will receive an HTTP status of 429 with an error code "too\_many\_calls". We hope you enjoy using our API and please report any bugs or unexpected behavior :) # Errors ReferralHero uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the `2xx` range indicate success, codes in the `4xx` range indicate an error that failed given the information provided (e.g., a required parameter was omitted, an update failed, etc.), and codes in the `5xx` range indicate an error with ReferralHero's servers (these are rare). When a request returns an error we always try to provide a clear explanation of what went wrong. Errors are returned as JSON files and follow the same structure: ```json { status: "error", message: "Error explanation" // Eg: "Missing API token" code: "error_code" // Eg: no_token } ``` ### **Status** Our API raises errors for many reasons and when this happens the "status" attribute will always be "error". We recommend writing code that gracefully handles all possible API exceptions. ### **Message** A human-readable message providing more details about the error. ### **Code** The type of error returned. See list of possible errors below: | Error codes | Explanation | | ------------------------------ | ---------------------------------------------------------- | | no\_token | "api\_token" parameter is missing or blank | | invalid\_token | "api\_token" provided does not exist | | inactive\_account | Account associated with this API token is inactive | | too\_many\_calls | Rate limit hit. Wait 60 minutes to reset the counter. | | no\_list\_uuid | "uuid" parameter is missing or blank | | invalid\_list | "uuid" provided belongs is invalid | | no\_subscriber\_id | "subscriber\_id" parameter is missing or blank | | subscriber\_not\_found | subscriber provided does not exist | | no\_email\_address | "email" parameter is missing or blank | | invalid\_email\_address | "email" provided is not a valid email. | | no\_name | "name" parameter is missing or blank | | no\_points | "points" parameter is missing or blankno\_hosting\_url | | no\_hosting\_url | "hosting\_url" parameter is missing or blank | | error\_list\_creation | Something went wrong when creating a new list. | | subscriber\_already\_promoted | Subscriber's already been promoted | | subscriber\_not\_promoted | Subscriber is not promoted, hence it can't be "unpromoted" | | bad\_request | Missing required params | | reward\_not\_found | The provided reward does not exist | | invalid\_status | The provided 'status' does not exist | | no\_coupons | The "coupons" parameter is missing or blank | | error\_coupon\_group\_creation | Errors occured while creating coupon | | coupon\_group\_created | Coupon created successfully | # Webhooks Interacting with a third-party API like ReferralHero's can introduce two problems: * Services not directly responsible for making an API request may still need to know the response of that request * Some events, like deleting a subscriber, are not the result of a direct API request Webhooks solve these problems by letting you register a URL that we will notify anytime an event happens in your campaign. When the event occurs—for example, when a user successfully subscribes to your list, ReferralHero will send a webhook notification to your registered webhooks. Understand that you only need to use webhooks for behind-the-scenes events. \ The results of most ReferralHero requests—including new subscriptions—are reported synchronously to your code, and don't require webhooks for verification. ### Important Considerations Due to the nature of network requests, your application should assume webhook requests could arrive out of order or could even fail to arrive; webhooks should be used only as notifications and not as a primary ReferralHero data source (make sure your application could still work when webhook is not available). # Objects ## List Your ReferralHero list, also known as your campaign, is where you store and manage all of your subscribers. Your subscribers will always be added to one list and can't be transferred to another list. {% tabs %} {% tab title="Attributes" %} | Attributes | | | | --------------- | ----------- | -------------------------------------------------------------------- | | **uuid** | `string` | The unique identifier of the campaign | | **name** | `string` | The campaign name | | **subscribers** | `integer` | The total subscribers count | | **created\_at** | `timestamp` | Unix timestamp (expressed in UTC) of when the list has been created. | | {% endtab %} | | | {% tab title="Example" %} ```yaml { "uuid": "MFxxxxxxxxx", "name": "My amazing sweepstake", "created_at": 1487347070, "subscribers": 0 } ``` {% endtab %} {% endtabs %} ## Subscriber A subscriber is a person who is added to one of your lists. Subscribers belong to precisely one list and can't be transferred. {% tabs %} {% tab title="Attributes" %}
Attributes
Attributes
idintegerThe unique identifier of the subscriber
namestringThe name of the subscriber
emailstringThe email of the subscriber
extra_fieldstringThe extra field value of the subscriber
extra_field_2stringThe extra field 2 value of the subscriber
codestringThe referral code of the subscriber
positionstringThe position of the subscriber in the list (if applicable)
referredbooleanTrue if the subscriber has been referred, false if not.
referral_valueintegerThe monetay value of the referral.
referral_categorystringThe type of subscriber. Useful for creating reports or segmenting subscribers.
transaction_idstringThe unique ID of the transaction. Useful when tracking referrals for purchases.
referred_byobjectAn object containing the subscriber's referrer information.
people_referredintegerThe total number of referrals of the subscriber.
level_2_confirmed_referralsintegerThe total number of level 2 confirmed referrals of the subscriber.
level_3_confirmed_referralsintegerThe total number of level 3 confirmed referrals of the subscriber.
promotedbooleanTrue is the subscriber is in the "winners" list, false if not.
promoted_attimestampUnix timestamp (expressed in UTC) of when the subscriber has been promoted.
verifiedbooleanTrue if the subscriber has verified their email address, false if not.
verified_attimestampUnix timestamp (expressed in UTC) of when the subscriber has verified their email address.
risk_levelintegerSubscriber's fraudulence level expressed as an integer from 0 (none) to 5 (extremely likely)
pointsintegerThe number of points of the subscriber
hoststringUrl used to generate the referral link.
sourcestringThe source of the subscriber.
devicestringThe decide used by the subscriber to sign up.
created_attimestampThe date the participant was added to the campaign (UTC milliseconds)
updated_attimestampUnix timestamp (expressed in UTC) of the last time the subscriber has been updated.
phone_numberstringIf phone_number is the Unique Identifier
crypto_wallet_addressstringIf crypto_wallet_address is the Unique Identifier
other_identifier_valuestringIf custom ID is the Unique Identifier
extra_field_3stringThe extra field 3 value of the subscriber
extra_field_4stringThe extra field 4 value of the subscriber
option_fieldstringThe option field of the subscriber
conversion_amountintegerThe conversion amount generated by the subscriber
visitorsintegerThe number of visitors referred by the subscriber
pending_referralsintegerThe number of pending referrals for the subscriber
unconfirmed_referralsintegerThe number of unconfirmed referrals for the subscriber
referral_linkstringThe unique referral link of the subscriber
referral_statusstringThe current status of the subscriber, if referred
universal_linkstringThe universal referral link of the subscriber
stripe_customer_idstringThe Stripe Customer ID linked to the subscriber
tagsarrayAssign tags to subscribers
{% endtab %} {% tab title="Example" %} ```yaml { "id": "sub_2bad325a25d7", "name": "John Doe", "email": "john.doe@gmail.com", "phone_number": "+1228374652", "crypto_wallet_address": "tb1qxyzxy", "crypto_wallet_provider": "Coinbase", "other_identifier_value": "", "extra_field": "Signup", "extra_field_2": "USA", "extra_field_3": "Item3", "extra_field_4": "Item4", "option_field": "Are you invited?", "conversion_amount": 1.0, "code": "c4fb914e", "position": 174, "referred": true, "referred_by": { "id": "sub_8a5b8df578c6", "name": "Nishchay", "email": "test123@gmail.com", "code": "1b52f1e0", "people_referred": 2, "points": 1 }, "visitors": 8, "pending_referrals": 3, "unconfirmed_referrals": 2, "people_referred": 2, "level_2_confirmed_referrals": 2, "level_3_confirmed_referrals": 2, "promoted": false, "promoted_at": null, "verified": true, "verified_at": 1738954543, "points": 1, "risk_level": 3, "host": "https://app.referralhero.com/MFxxxxxxxxxx/signup", "source": "Admin", "device": "Mobile", "referral_link": "https://app.referralhero.com/MFxxxxxxxxx/signup?mwr=c4fb914e", "referral_status": "Payment Pending", "referral_status_at": 1738954543, "universal_link": "https://app.referralhero.com/MFxxxxxxxxxxx/universal_link?mwr=c4fb914e", "stripe_customer_id": "cus_TEST123456789", "tags": ["tag1", "tag2"], "created_at": 1738954543, "last_updated_at": 1738954701 } ``` {% endtab %} {% endtabs %} ## Reward The `Reward` Object contains detailed reward information about a single reward that was set up for a campaign. {% tabs %} {% tab title="Attributes" %} | Attributes | | | | --------------- | --------- | ------------------------------------------------- | | **title** | `string` | The name of the reward | | **description** | `string` | The description of the reward | | **referrals** | `integer` | The number of referrals needed to win this reward | | {% endtab %} | | | {% tab title="Example" %} ```yaml { "title": "30% discount on our Pro Plan", "description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit.", "referrals": 2 } ``` {% endtab %} {% endtabs %} # Endpoints Reference ## Authentication All API requests must be authenticated using an API token. **Preferred (**Recommended) **:** Authorization: `Bearer YOUR_API_TOKEN` **Alternative :** X-API-Key: `YOUR_API_TOKEN` > Use X-API-Key only if your client cannot send the Authorization header. **Headers** | Name | Value | Description | | ------------- | ----------------------- | ------------------ | | Authorization | Bearer `YOUR_API_TOKEN` | (Preferred) | | X-API-Key | `YOUR_API_TOKEN` | Alternative option | {% hint style="info" %} You can find your api token by navigating to **ReferralHero dashboard > Account > API** {% endhint %} ## Lists Locations where you can find most of the required parameters: | Path Parameters | Location | | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | name | *ReferralHero dashboard > Campaign name* | | uuid |

ReferralHero dashboard > Campaign > Installation > Instructions

The 12-letter id that starts with ‘MF’ in the Tracking Code, e.g. Mxxxxxxxxxx

| ### Create a new list `POST` `https://app.referralhero.com/api/v2/lists` Create a new list/campaign in your account. #### Path Parameters | Name | Type | Description | | ------- | ------ | -------------------- | | website | string | Default Referral URL | | name | string | Your list name | {% tabs %} {% tab title="200 " %} ```yaml { "status": "ok", "data": { < List object > }, "calls_left": 1000, "timestamp": 1487659010 } ``` {% endtab %} {% endtabs %} ### Retrieve all lists `GET` `https://app.referralhero.com/api/v2/lists` Get all the lists/campaigns in your account. Results are paginated (10 results per page).\ Only active lists will be retrieved. #### Path Parameters | Name | Type | Description | | ---- | ------ | --------------------------------------- | | page | string | Page you want to jump to. By default 1. | {% tabs %} {% tab title="200 " %} ```yaml { "status": "ok", "data": { "response": "lists_retrieved", "lists": [ { < List object > }, { < List object > }, ... ], "pagination": { "total_pages": 7, "current_page": 1, "per_page": 10, "total_objects": 67 } }, "calls_left": 1000, "timestamp": 1487658324 } ``` {% endtab %} {% endtabs %} ### Get List Leaderboard `GET` `https://app.referralhero.com/api/v2/lists/:uuid/leaderboard` Retrieve leaderboard of the top 10-100 subscribers in a list. #### Path Parameters | Name | Type | Description | | ----- | ------ | ---------------------------------------------------------- | | uuid | string | Your list UUID | | count | string | Number (10-100) of subscribers returned in the leaderboard | {% tabs %} {% tab title="200 " %} ```yaml { "status": "ok", "data": { "ranking": [ { < Subscriber object > }, { < Subscriber object > }, ... ] }, "calls_left": 1000, "timestamp": 1487659347 } ``` {% endtab %} {% endtabs %} ### Get list rewards `GET` `https://app.referralhero.com/api/v2/lists/:uuid/bonuses` Retrieve list of rewards from a list. #### Path Parameters | Name | Type | Description | | ---- | ------ | -------------- | | uuid | string | Your list UUID | {% tabs %} {% tab title="200 " %} ```yaml { "status": "ok", "data": [ { < Reward object > }, { < Reward object > } ], "calls_left": 1000, "timestamp": 1487659708 } ``` {% endtab %} {% endtabs %} ## Subscribers Locations where you can find most of the required parameters: | Path Parameters | Location | | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | uuid |

ReferralHero dashboard > Campaign Overview> Edit Campaign > Launch > Instructions

The 12-letter id that starts with ‘MF’ in the Tracking Code, e.g. MF078d000987

| | email | The email of the subscriber | | domain | *ReferralHero dashboard > Campaign > Options > Default Referral Link* | | subscriber\_id | *ReferralHero dashboard > Campaign > Subscribers* | ### Add a subscriber `POST` `https://app.referralhero.com/api/v2/lists/:uuid/subscribers` #### Path Parameters | Name | Type | Description | | ------------------------ | ------- | ------------------------------------------------------------------------------------- | | uuid | string | The list uuid | | email | string | The email of subscriber (if unique identifier) | | phone\_number | string | The phone number of subscriber (if unique identifier) | | crypto\_wallet\_address | string | The wallet address of subscriber (if unique identifier) | | other\_identifier\_value | string | The other identifier value of subscriber (if unique identifier) | | name | string | The name of the subscriber | | status | string | Use 'custom\_event\_pending' to set the referral status to pending | | transaction\_id | string | The unique ID of the transaction. Useful when tracking referrals for purchases. | | conversion\_category | string | The type of subscriber. Useful for creating reports or segmenting subscribers. | | conversion\_value | number | The monetary value of the referral. | | device | string | The device used by the subscriber to sign up. Used for analytics. | | source | string | The source of the subscriber. Used for analytics. | | double\_optin | boolean | If set to `false` the subscriber will not received a confirmation email. | | points | integer | The number of points for the subscriber. It only works for "contest" campaigns. | | referrer | string | Set a referrer for the subscriber by providing the referrer's referral code or email. | | extra\_field | string | The extra field of the subscriber | | extra\_field\_2 | string | The extra field 2 of the subscriber | | domain | string | The URL for the referral link | | stripe\_customer\_id | string | Stripe Customer ID | | advocate\_name | string | Name of the advocate | | tags | array | Assign tags to subscribers | | self\_reported\_source | string | The source the subscriber selected when asked how they heard about the campaign | {% tabs %} {% tab title="200 " %} ```yaml { "status": "ok", "data": { "response": "subscriber_created", < Subscriber object > }, "calls_left": 1000, "timestamp": 1487661494 } ``` {% endtab %} {% endtabs %} {% hint style="info" %} **Note for Web Integrations:** When deciding between using our Javascript Web API or REST API to interact with ReferralHero, it is generally advisable to '[add a subscriber](/integrate/javascript-web-api/adding-a-subscriber-manually)' using the Javascript Web API as you will take advantage of our powerful global tracking script and cookie. Once a subscriber is added to our database, you can manage that subscriber and campaign more freely using either the Javascript Web API or REST API. {% endhint %} ### Track referral conversion event `POST` `https://app.referralhero.com/api/v2/lists/:uuid/subscribers/track_referral_conversion_event` Use when your Campaign Goal is set to track two or three conversion events. **If the referrer is present** in the API request params, we will check the referral unique identifier in your campaign and, if found, the referral status will be updated and, if not found, we will create the referral and set the referral status. **If the referrer is not present** in the API request params, we will check the referral unique identifier in your campaign and, if found, the referral status will be updated and, if not found, the referral will not be created. **The Referral Status Is Set To:** Confirmed (if tracking two conversion events) Unconfirmed (if tracking three conversion events) \ **Note**: 1\. Your campaign Goal must be set up to track two or three conversion events otherwise, an error will return. 2\. If the referral is present in ReferralHero with pending status, a successful response `custom_event_completed` will return. 3\. If the referral unique identifier is not present in the ReferralHero, but the referrer unique identifier is present, a successful response `custom_event_completed` with the data of the new confirmed referral will return. 4\. If a referral exists but the referral status is not pending, the error `custom event is already completed` will return. 5\. If the referral unique identifier is not present in ReferralHero and the referrer is also not provided in the API, the error `referrer is invalid or not present` will return. 6\. If the referral status is unconfirmed or confirmed, the error `custom event is already completed` will return. #### Path Parameters | Name | Type | Description | | ------------------------ | ------ | -------------------------------------------------------------------- | | uuid | string | Your list UUID | | email | string | The email of subscriber (if unique identifier) | | phone\_number | string | The phone number of subscriber (if unique identifier) | | crypto\_wallet\_address | string | The crypto wallet address of subscriber (if unique identifier) | | other\_identifier\_value | string | The identifier value of subscriber (if unique identifier) | | referrer | string | The unique identifier of the referrer | | conversion\_value | string | Referral conversion value | | stripe\_customer\_id | string | Stripe Customer ID | | transaction\_id | string | Assign a transaction id to the conversion event | | product\_id | string | Product ID (normally used if rewards are based on specific products) | | tags | array | Assign tags to subscriber | {% tabs %} {% tab title="200 " %} ```yaml { "status": "ok", "data": { "response": "custom_event_completed", < Subscriber object > }, "calls_left": 1000, "timestamp": 1487661494 } ``` {% endtab %} {% endtabs %} ### Confirm referral by Subscriber ID `POST` `https://app.referralhero.com/api/v2/lists/:uuid/subscribers/:subscriber_id/confirm` Use when your Campaign Goal is set to track three conversion events and you want to confirm referrals when your third conversion event occurs (e.g: upgrade to a paid plan, end of trial, etc). **The Referral Status Is Set To:** Confirmed (if tracking three conversion events) **Note**: 1\. Your campaign Goal must be set up to track three conversion events otherwise, an error will return. 2\. Only verified referrals can be confirmed. Trying to confirm a non-verified referral will return a `subscriber_not_found` error. #### Path Parameters | Name | Type | Description | | ----------------- | ------ | ------------------------- | | uuid | string | Your list UUID | | subscriber\_id | string | The ID of the subscriber | | conversion\_value | string | Referral conversion value | {% tabs %} {% tab title="200 " %} ```yaml { "status": "ok", "data": { "response": "subscriber_confirmed", < Subscriber object > }, "calls_left": 1000, "timestamp": 1487661494 } ``` {% endtab %} {% endtabs %} ### Confirm referral by Unique Identifier `POST` `https://app.referralhero.com/api/v2/lists/:uuid/subscribers/confirm` Use when your Campaign Goal is set to track three conversion events and you want to confirm referrals when your third conversion event occurs (e.g: upgrade to a paid plan, end of trial, etc). **The Referral Status Is Set To:** Confirmed (if tracking three conversion events) **Note**: 1\. Your campaign Goal must be set up to track three conversion events otherwise, an error will return. 2\. Only verified referrals can be confirmed. Trying to confirm a non-verified referral will return a `subscriber_not_found` error. #### Path Parameters | Name | Type | Description | | ------------------------ | ------ | --------------------------------------------------------------- | | uuid | String | Your list UUID | | email | String | The email of subscriber (if unique identifier) | | crypto\_wallet\_address | String | The wallet address of subscriber (if unique identifier) | | phone\_number | String | The phone number of subscriber (if unique identifier) | | other\_identifier\_value | String | The other identifier value of subscriber (if unique identifier) | | conversion\_value | string | Referral conversion value | {% tabs %} {% tab title="200: OK " %} ```json { "status": "ok", "data": { "response": "subscriber_confirmed", < Subscriber object > }, "calls_left": 1000, "timestamp": 1487661494 } ``` {% endtab %} {% endtabs %} ### Update a subscriber `POST` `https://app.referralhero.com/api/v2/lists/:uuid/subscribers/:subscriber_id` Update a single subscriber.\ Note: only verified subscribers can be updated. Trying to update a non-verified subscriber will return a subscriber\_not\_found error. #### Path Parameters | Name | Type | Description | | ------------------------ | ------ | ------------------------------------------------------------------------------ | | uuid | string | The list UUID | | name | string | The name of the subscriber | | email | string | The email of subscriber (if unique identifier) | | phone\_number | string | The phone number of subscriber (if unique identifier) | | crypto\_wallet\_address | string | The wallet address of subscriber (if unique identifier) | | other\_identifier\_value | string | The other identifier value of subscriber (if unique identifier) | | extra\_field | string | The extra field of the subscriber | | extra\_field\_2 | string | The extra field 2 of the subscriber | | points | string | The number of points of the subscriber. It only works for "contest" campaigns. | | subscriber\_id | string | The ID of the subscriber | | stripe\_customer\_id | string | Stripe Customer ID | | tags | array | Assign tags to subscribers | | address | string | The address of the subscriber | | city | string | The city of the subscriber | | country | string | The country of the subscriber | | referral\_status | string | unqualified / qualified | {% tabs %} {% tab title="200 " %} ```yaml { "status": "ok", "data": { "response": "subscriber_updated", < Subscriber object > }, "calls_left": 1000, "timestamp": 1487661494 } ``` {% endtab %} {% endtabs %} ### Add points to a subscriber `POST` `https://app.referralhero.com/api/v2/lists/:uuid/subscribers/add_points` Add points to an existing subscriber for any reason.\ **Note**: Trying to add points to a non-existing subscriber will return a `subscriber_not_found` error. #### Path Parameters | Name | Type | Description | | ------------------------ | ------ | --------------------------------------------------------------- | | uuid | string | Your list UUID | | email | string | The email of subscriber (if unique identifier) | | phone\_number | string | The phone number of subscriber (if unique identifier) | | crypto\_wallet\_address | string | The crypto wallet address of subscriber (if unique identifier) | | other\_identifier\_value | string | The other identifier value of subscriber (if unique identifier) | | points | string | The number or points to add | {% tabs %} {% tab title="200 " %} ```yaml { "status": "ok", "data": { "response": "points_added", < Subscriber object > }, "calls_left": 1000, "timestamp": 1487661494 } ``` {% endtab %} {% endtabs %} ### Track Transactions (Single Transaction) `POST` `https://app.referralhero.com/api/v2/lists/:uuid/subscribers/add_transactions` This allows you to pass transaction data to ReferralHero. | Name | Type | Description | | ------------------------ | ------ | --------------------------------------------------------------- | | uuid | string | Your list UUID | | email | string | The email of subscriber (if unique identifier) | | phone\_number | string | The phone number of subscriber (if unique identifier) | | crypto\_wallet\_address | string | The crypto wallet address of subscriber (if unique identifier) | | other\_identifier\_value | string | The other identifier value of subscriber (if unique identifier) | | amount (required) | string | Amount of the transaction | | transaction\_id | string | Transaction ID | | product\_id | string | Product ID | | lifetime\_spend | string | Total lifetime spend | | reward\_value | string | Set a reward value with the transaction | **Response** {% tabs %} {% tab title="200" %} ```json { "status": "ok", "data": { "id": 592, "transaction_id": "MFa19e08789720240219142611", "transaction_time": "2024-02-19T14:26:11.000Z", "amount": 56665, "product_id": "12345", "response": "transaction_added" }, "calls_left": null, "timestamp": 1708352775 } ``` {% endtab %} {% endtabs %} ### Track Bulk Transactions `POST` `https://app.referralhero.com/api/v2/lists/:uuid/subscribers/add_bulk_transactions` This allows you to pass multiple transaction data to ReferralHero in bulk. Once processing is complete, the results will be emailed to the admin with a CSV file containing the transaction status. You can pass up to **500 transactions** at a time. | Name | Type | Description | | ------------------------ | ------ | --------------------------------------------------------------- | | uuid | string | Your list UUID | | email | string | The email of subscriber (if unique identifier) | | phone\_number | string | The phone number of subscriber (if unique identifier) | | crypto\_wallet\_address | string | The crypto wallet address of subscriber (if unique identifier) | | other\_identifier\_value | string | The other identifier value of subscriber (if unique identifier) | | amount (required) | string | Amount of the Transaction | | transaction\_id | string | Transaction ID | | product\_id | string | Product ID | | lifetime\_spend | string | Total lifetime spend | | reward\_value | string | Set a reward value with the transaction | **Request Body (JSON Format)** {% tabs %} {% tab title="JSON" %} ```json { "transactions": [ { "email": "refloading@hi.com", "amount": 150, "product_id": "prod_0005", "transaction_id": "trans_0005", "reward_value": 15 }, { "email": "tremendousref3@hi.com", "amount": 500, "product_id": "prod_0006", "transaction_id": "trans_0006", "reward_value": 50 } ] } ``` {% endtab %} {% endtabs %} **Response** {% tabs %} {% tab title="200" %} ```json { "status": "in_progress", "message": "Transactions are being processed. It will take some time to complete." } ``` {% endtab %} {% endtabs %} ### Promote a subscriber `POST` `https://app.referralhero.com/api/v2/lists/:uuid/subscribers/:subscriber_id/promote` Promote a single subscriber. Read this article about what "promoting" means.\ **Note**: only verified subscribers can be promoted. Trying to promote a non-verified subscriber will return a `subscriber_not_found` error. #### Path Parameters | Name | Type | Description | | -------------- | ------ | ------------------------ | | uuid | string | Your list UUID | | subscriber\_id | string | The ID of the subscriber | {% tabs %} {% tab title="200 " %} ```yaml { "status": "ok", "data": { "response": "subscriber_promoted", < Subscriber object > }, "calls_left": 1000, "timestamp": 1487661494 } ``` {% endtab %} {% endtabs %} ### Trigger manual rewards `POST` `https://app.referralhero.com/api/v2/lists/:uuid/subscribers/:subscriber_id/unlock_promoted_reward` Used to trigger the Rewards for Promoted Winners or the One-Off Rewards #### Path Parameters | Name | Type | Description | | -------------- | ------ | ------------------------------ | | uuid | String | Your list UUID | | subscriber\_id | String | The ID of the subscriber | | reward\_id | String | The ID of the promotion reward | {% tabs %} {% tab title="200: OK " %} ```json { "response": "reward_unlocked", "reward": { "id": 203, "title": "Winner 2", "header": null, "description": "", "referrals": null, "image": "/missing.png", "label": "Winner Reward", "points": null, "category": "promoted_winners" } } ``` {% endtab %} {% endtabs %} ### Retrieve all subscribers by name `GET` `https://app.referralhero.com/api/v2/subscribers/search_by_name` Search across all campaigns to find subscribers by name and return a list of matching subscribers. #### Path Parameters | Name | Type | Description | | --------------- | ------ | -------------------------- | | name (required) | String | Name of the subscriber | | page | String | Page number. By default 1. | {% tabs %} {% tab title="200: OK " %} ```json { "status": "ok", "data": { "response": "subscribers_retrieved", "subscribers": [ { < Subscriber object > }, { < Subscriber object > }, ... ], "pagination": { "total_pages": 1, "current_page": 1, "per_page": 50, "total_objects": 10 } }, "calls_left": null, "timestamp": 1777469482 } ``` {% endtab %} {% endtabs %} ### Retrieve all subscribers from a list `GET` `https://app.referralhero.com/api/v2/lists/:uuid/subscribers` Get all the subscribers in a list. Results are paginated (max 50 results per page). #### Path Parameters | Name | Type | Description | | -------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | uuid | string | Your list UUID | | sort\_by | string | Sort subscribers by one attribute. Possible options are: `registration_desc`, `registration_asc`, `email_asc`, `email_desc`, `name_asc`, `name_desc`, `position_asc`, `position_desc` , `people_referred_asc`, `people_referred_desc`, `points_asc`, `points_desc` | | page | string | Page you want to jump to. By default 1. | | extra\_field | string | The extra field of the subscriber | | extra\_field\_2 | string | The extra field 2 of the subscriber | | option\_field | string | The option field of the subscriber | | stripe\_customer\_id | string | Stripe Customer ID | {% tabs %} {% tab title="200 " %} ```yaml { "status": "ok", "data": { "response": "subscribers_retrieved", "subscribers": [ { < Subscriber object > }, { < Subscriber object > }, ... ], "pagination": { "total_pages": 1, "current_page": 1, "per_page": 50, "total_objects": 14 } }, "calls_left": 1000, "timestamp": 1487675505 } ``` {% endtab %} {% endtabs %} ### Retrieve subscriber by ID `GET` `https://app.referralhero.com/api/v2/lists/:uuid/subscribers/:subscriber_id` Retrieve a single subscriber.\ **Note**: only verified subscribers can be retrieved. Trying to retrieve a non-verified subscriber will return a `subscriber_not_found` error. #### Path Parameters | Name | Type | Description | | -------------- | ------ | ------------------------ | | uuid | string | The list UUID | | subscriber\_id | string | The ID of the subscriber | {% tabs %} {% tab title="200 " %} ```yaml { "status": "ok", "data": { "response": "subscriber_retrieved", < Subscriber object > }, "calls_left": 1000, "timestamp": 1487676070 } ``` {% endtab %} {% endtabs %} ### Retrieve subscriber by email `GET` `https://app.referralhero.com/api/v2/lists/:uuid/subscribers/retrieve_by_email` Retrieve a single subscriber.\ **Note**: only verified subscribers can be retrieved. Trying to retrieve a non-verified subscriber will return a `subscriber_not_found` error. #### Path Parameters | Name | Type | Description | | ----- | ------ | ---------------------------- | | uuid | string | The list UUID | | email | string | The email of the subscriber. | {% tabs %} {% tab title="200 " %} ```yaml { "status": "ok", "data": { "response": "subscriber_retrieved", < Subscriber object > }, "calls_left": 1000, "timestamp": 1487676070 } ``` {% endtab %} {% endtabs %} ### Retrieve subscriber by MWR `GET` `https://app.referralhero.com/api/v2/lists/:uuid/subscribers/retrieve_by_mwr` Retrieve a single subscriber.\ **Note**: only verified subscribers can be retrieved. Trying to retrieve a non-verified subscriber will return a `subscriber_not_found` error. #### Path Parameters | Name | Type | Description | | ---- | ------ | ---------------------------- | | uuid | string | The list UUID | | mwr | string | The referrer's referral code | {% tabs %} {% tab title="200" %} ```json { "status": "ok", "data": { "response": "subscriber_retrieved", < Subscriber object > }, "calls_left": null, "timestamp": 1725032082 } ``` {% endtab %} {% endtabs %} ### Retrieve all referrals (pending, unconfirmed, confirmed) of a subscriber `GET` `https://app.referralhero.com/api/v2/lists/:uuid/subscribers/:subscriber_id/referred` Retrieve all referrals (pending, unconfirmed, confirmed) of a single subscriber. Results are paginated (max 50 results per page). #### Path Parameters
NameTypeDescription
uuidstringYour list UUID
subscriber_idstringThe ID of the subscriber.
pagestringPage you want to jump to. By default is 1.
sort_bystringSort subscribers by one attribute. Possible options are: registration_desc, registration_asc, email_asc, email_desc, name_asc, name_desc, position_asc, position_desc, people_referred_asc, people_referred_desc, points_asc, points_desc
{% tabs %} {% tab title="200 " %} ```json { "status": "ok", "data": { "response": "subscribers_retrieved", "subscribers": [ { < Subscriber object > }, { < Subscriber object > }, ... ], "pagination": { "total_pages": 1, "current_page": 1, "per_page": 50, "total_objects": 14 } }, "calls_left": 1000, "timestamp": 1487675505 } ``` {% endtab %} {% endtabs %} ### Retrieve all Level 2 referrals (pending, unconfirmed, confirmed) of a subscriber `GET` `https://app.referralhero.com/api/v2/lists/:uuid/subscribers/:subscriber_id/level_2_all_referrals` Retrieve all Level 2 referrals (pending, unconfirmed, confirmed) of a single subscriber. Results are paginated (max 50 results per page). #### Path Parameters | Name | Type | Description | | -------------- | ------ | ------------------------- | | uuid | string | Your list UUID | | subscriber\_id | string | The ID of the subscriber. | {% tabs %} {% tab title="200" %} ```json { "status": "ok", "data": { "response": "subscribers_retrieved", "subscribers": [ { < Subscriber object > , "pending_referrals": 0, "unconfirmed_referrals": 0, "people_referred": 0, "level_2_confirmed_referrals": 0, "level_3_confirmed_referrals": 0, "promoted": false, "promoted_at": null, "verified": true, "verified_at": 1723452705, "points": 0, "risk_level": 0, "host": "https://www.mywebiste.com/refer", "source": null, "device": null, "referral_link": "https://www.mywebiste.com/refer?mwr=eb134345", "created_at": 1723452705, "last_updated_at": 1723452705, "referral_status": "confirmed", "referral_status_at": 1723452705, "universal_link": "https://app.referralhero.com//MFxxxxxxxxx/universal_link?mwr=eb134b6d" } ], "pagination": { "total_pages": 1, "current_page": 1, "per_page": 50, "total_objects": 1 } }, "calls_left": null, "timestamp": 1723457099 } ``` {% endtab %} {% endtabs %} ### Retrieve all Level 3 referrals (pending, unconfirmed, confirmed) of a subscriber `GET` `https://app.referralhero.com/api/v2/lists/:uuid/subscribers/:subscriber_id/level_3_all_referrals` **Path Parameters** | Name | Type | Description | | -------------- | ------ | ------------------------- | | uuid | string | Your list UUID | | subscriber\_id | string | The ID of the subscriber. | {% tabs %} {% tab title="200" %} ```json { "status": "ok", "data": { "response": "subscribers_retrieved", "subscribers": [ { < Subscriber object > , "pending_referrals": 0, "unconfirmed_referrals": 0, "people_referred": 0, "level_2_confirmed_referrals": 0, "level_3_confirmed_referrals": 0, "promoted": false, "promoted_at": null, "verified": true, "verified_at": 1723452705, "points": 0, "risk_level": 0, "host": "https://www.mywebiste.com/refer", "source": null, "device": null, "referral_link": "https://www.mywebiste.com/refer?mwr=eb134ss4", "created_at": 1723452705, "last_updated_at": 1723452705, "referral_status": "confirmed", "referral_status_at": 1723452705, "universal_link": "https://app.referralhero.com//MFxxxxxxxxxx/universal_link?mwr=eb134b6d" } ], "pagination": { "total_pages": 1, "current_page": 1, "per_page": 50, "total_objects": 1 } }, "calls_left": null, "timestamp": 1723457099 } ``` {% endtab %} {% endtabs %} ### Retrieve all level 1 confirmed referrals of a subscriber `GET` `https://app.referralhero.com/api/v2/lists/:uuid/subscribers/:subscriber_id/level_1_referrals` Retrieve all level 1 confirmed referrals of a single subscriber. Results are paginated (max 50 results per page). #### Path Parameters
NameTypeDescription
uuidstringYour list UUID
subscriber_idstringThe ID of the subscriber.
pagestringPage you want to jump to. By default is 1.
sort_bystringSort subscribers by one attribute. Possible options are: registration_desc, registration_asc, email_asc, email_desc, name_asc, name_desc, position_asc, position_desc, people_referred_asc, people_referred_desc, points_asc, points_desc
{% tabs %} {% tab title="200 " %} ```yaml { "status": "ok", "data": { "response": "subscribers_retrieved", "subscribers": [ { < Subscriber object > }, { < Subscriber object > }, ... ], "pagination": { "total_pages": 1, "current_page": 1, "per_page": 50, "total_objects": 14 } }, "calls_left": 1000, "timestamp": 1487675505 } ``` {% endtab %} {% endtabs %} ### Retrieve all level 2 confirmed referrals of a subscriber `GET` `https://app.referralhero.com/api/v2/lists/:uuid/subscribers/:subscriber_id/level_2_referrals` Retrieve all level 2 confirmed referrals of a single subscriber. Results are paginated (max 50 results per page). #### Path Parameters
NameTypeDescription
uuidstringYour list UUID
subscriber_idstringThe ID of the subscriber.
pagestringPage you want to jump to. By default is 1.
sort_bystringSort subscribers by one attribute. Possible options are: registration_desc, registration_asc, email_asc, email_desc, name_asc, name_desc, position_asc, position_desc, people_referred_asc, people_referred_desc, points_asc, points_desc
{% tabs %} {% tab title="200 " %} ```json { "status": "ok", "data": { "response": "subscribers_retrieved", "subscribers": [ { < Subscriber object > }, { < Subscriber object > }, ... ], "pagination": { "total_pages": 1, "current_page": 1, "per_page": 50, "total_objects": 14 } }, "calls_left": 1000, "timestamp": 1487675505 } ``` {% endtab %} {% endtabs %} ### Retrieve all level 3 confirmed referrals of a subscriber `GET` `https://app.referralhero.com/api/v2/lists/:uuid/subscribers/:subscriber_id/level_3_referrals` Retrieve all level 3 confirmed referrals of a single subscriber. Results are paginated (max 50 results per page). #### Path Parameters
NameTypeDescription
uuidstringYour list UUID
subscriber_idstringThe ID of the subscriber.
pagestringPage you want to jump to. By default is 1.
sort_bystringSort subscribers by one attribute. Possible options are: registration_desc, registration_asc, email_asc, email_desc, name_asc, name_desc, position_asc, position_desc, people_referred_asc, people_referred_desc, points_asc, points_desc
{% tabs %} {% tab title="200 " %} ```json { "status": "ok", "data": { "response": "subscribers_retrieved", "subscribers": [ { < Subscriber object > }, { < Subscriber object > }, ... ], "pagination": { "total_pages": 1, "current_page": 1, "per_page": 50, "total_objects": 14 } }, "calls_left": 1000, "timestamp": 1487675505 } ``` {% endtab %} {% endtabs %} ### Retrieve all rewards for all subscribers `GET` `https://app.referralhero.com/api/v2/lists/:uuid/rewards` Retrieve a list of all rewards across all subscribers in a specified campaign. Results are paginated (maximum 50 results per page). #### Path Parameters | Name | Type | Description | | ----------------- | ------ | ---------------------------------------------------------------------- | | uuid | String | Your list UUID | | status (optional) | String | Status of the reward (i.e. sent, resent, canceled, pending or flagged) | | page | String | Page you want to jump to. By default is 1. | | per\_page | String | Number of results you want per page. By default is 10. | {% tabs %} {% tab title="200 " %} ````json { "status": "ok", "data": { "response": "rewards_retrieved", "rewards": [ { "id": 214, "name": "10% commission", "status": "sent", "referrals": 1, "created_at": 1729166882, "unlocked_date": 1752823036, "sent_date": 1752823044, "referral": "nishchay@referralhero.com", "value": 100.0, "total": "", "signup_type": null, "referrals_type": "confirmed", "recurring_count": null, "transaction_id": "pi_3SV7RlJb999K2d", "product_id": "price_1RBZEsJb999K2d", "coupon_code": null, "coupon_group": null, "image_url": null, "subscriber_email": "johndoe@gmail.com", "subscriber_id": "sub_64f9c36e25de" ``` }, ], "pagination": { "total_pages": 1, "current_page": 1, "per_page": 10, "total_objects": 1 } }, "calls_left": null, "timestamp": 1729186260 } ```` {% endtab %} {% endtabs %} ### Retrieve all rewards unlocked by a subscriber `GET` `https://app.referralhero.com/api/v2/lists/:uuid/subscribers/:subscriber_id/rewards` Get all rewards unlocked by the subscriber. Results are paginated (max 50 results per page). #### Path Parameters | Name | Type | Description | | ----------------- | ------ | ---------------------------------------------------------------------- | | uuid | String | Your list UUID | | subscriber\_id | String | The ID of the subscriber | | status (optional) | String | Status of the reward (i.e. sent, resent, canceled, pending or flagged) | {% tabs %} {% tab title="200 " %} ```json { "status": "ok", "data": { "response": "rewards_retrieved", "rewards": [ { "id": 214, "name": "10% commission", "status": "sent", "referrals": 1, "created_at": 1752217473, "unlocked_date": 1752823036, "sent_date": 1752823044, "referral": "nishchay@referralhero.com", "value": 100.0, "total": "", "signup_type": null, "referrals_type": "confirmed", "recurring_count": null, "transaction_id": "pi_3SV7RlJb999K2d", "product_id": "price_1RBZEsJb999K2d", "coupon_code": null, "coupon_group": null, "image_url": null }, ], "pagination": { "total_pages": 1, "current_page": 1, "per_page": 10, "total_objects": 1 } }, "calls_left": null, "timestamp": 1729186260 } ``` {% endtab %} {% endtabs %} ### Delete a subscriber `DELETE` `https://app.referralhero.com/api/v2/lists/:uuid/subscribers/:subscriber_id` Delete a single subscriber. #### Path Parameters | Name | Type | Description | | -------------- | ------ | ------------------------ | | uuid | string | The list UUID | | subscriber\_id | string | The ID of the subscriber | {% tabs %} {% tab title="200 " %} ```yaml { "status": "ok", "data": { "response": "subscriber_deleted", < Subscriber object > }, "calls_left": 1000, "timestamp": 1487661494 } ``` {% endtab %} {% endtabs %} ### Update reward status by reward\_id `POST` `https://app.referralhero.com/api/v2/lists/:uuid/subscribers/update_reward_status` Update status of an unlocked reward of a subscriber by reward\_id #### Path Parameters | Name | Type | Description | | ---------- | ------ | --------------------------------------------------------------------- | | uuid | String | Your list UUID | | reward\_id | String | ID of reward provided in GET all rewards unlocked by a subscriber API | | status | String | sent/resent/canceled | {% tabs %} {% tab title="200 " %} ```json { "status": "ok", "data": { "id": 794765, "name": "referral signup", "status": "confirmed", "referrals": null, "created_at": 1752217473, "unlocked_date": 1752823036, "sent_date": 1752823044, "referral": "", "value": null, "total": "", "signup_type": "referral", "referrals_type": null, "recurring_count": null, "coupon_code": "cdwtmnKz8P", "coupon_group": "10-off-new-355bed2b-d645-4b2f-88ed-40a813940243", "image_url": null }, "calls_left": null, "timestamp": 1753514108 } ``` {% endtab %} {% endtabs %} ### Create coupon group `POST` `https://app.referralhero.com/api/v2/lists/:uuid/coupon_groups` Add new coupon group #### Path Parameters | Name | Type | Description | | ------- | ------ | --------------------------------------- | | uuid | String | Your list UUID | | name | String | Coupon group name | | coupons | String | Array, e.g. \["ab23fg, fghg45, gh78wl"] | | active | String | True or false | {% tabs %} {% tab title="200 " %} ```json { "status": "ok", "data": { "id": "rh400", "name": "RH400", "active": true, "created_at": 1686563261, "coupons": [], "response": "coupon_group_created" }, "calls_left": null, "timestamp": 1686563261 } ``` {% endtab %} {% endtabs %} ### Create coupons `POST` `https://app.referralhero.com/api/v2/lists/:uuid/coupons` Add coupon(s) to a coupon group #### Path Parameters | Name | Type | Description | | ----------------- | ------ | ------------------------------------------ | | uuid | String | Your list UUID | | coupon\_group\_id | String | ID of coupon group | | coupons | String | Array, e.g. \["ab23fg", fghg45”, “gh78wl"] | {% tabs %} {% tab title="200 " %} ```json { "status": "ok", "data": { "id": "rh200", "name": "RH200", "active": true, "created_at": 1686563246, "coupons": [ { "code": "FCMPFI", "available": true, "sent_at": null, "email_id": null, "created_at": 1686563246 }, { "code": "U3EHFD", "available": true, "sent_at": null, "email_id": null, "created_at": 1686563246 }, { "code": "tvt4g45v", "available": true, "sent_at": null, "email_id": null, "created_at": 1686563246 }, { "code": "RFGH677", "available": true, "sent_at": null, "email_id": null, "created_at": 1686563246 }, { "code": "KMLFG767", "available": true, "sent_at": null, "email_id": null, "created_at": 1686563246 } ] }, "calls_left": null, "timestamp": 1686676359 } ``` {% endtab %} {% endtabs %} ### Retrieve all coupon groups `GET` `https://app.referralhero.com/api/v2/lists/:uuid/coupon_groups` Get all coupon groups of a campaign #### Path Parameters | Name | Type | Description | | ---- | ------ | -------------- | | uuid | String | Your list UUID | {% tabs %} {% tab title="200 " %} ```json { "status": "ok", "data": { "response": "coupon_groups_retrieved", "coupon_groups": [ { "id": "rh200", "name": "RH200", "active": true, "created_at": 1686563246, "coupons": [ { "code": "FCMPFI", "available": true, "sent_at": null, "email_id": null, "created_at": 1686563246 }, { "code": "U3EHFD", "available": true, "sent_at": null, "email_id": null, "created_at": 1686563246 } ] }, { "id": "rh400", "name": "RH400", "active": true, "created_at": 1686563261, "coupons": [] } ], "pagination": { "total_pages": 1, "current_page": 1, "per_page": 50, "total_objects": 2 } }, "calls_left": null, "timestamp": 1686563777 } ``` {% endtab %} {% endtabs %} ### Retrieve coupons `GET` `https://app.referralhero.com/api/v2/lists/:uuid/coupon_groups/:id` Get all coupons within a coupon group #### Path Parameters | Name | Type | Description | | ---- | ------ | ------------------ | | uuid | String | Your list UUID | | id | String | ID of coupon group | {% tabs %} {% tab title="200 " %} ```json { "status": "ok", "data": { "id": "rh200", "name": "RH200", "active": true, "created_at": 1686563246, "coupons": [] }, "calls_left": null, "timestamp": 1686563407 } ``` {% endtab %} {% endtabs %} ### Mark Referral as Unqualified `POST` `https://app.referralhero.com/api/v2/lists/:uuid/subscribers/:subscriber_id/unqualify` Mark a referral as Unqualified #### Path Parameters | Name | Type | Description | | -------------- | ------ | ------------------------ | | uuid | String | The list UUID | | subscriber\_id | String | The ID of the subscriber | {% tabs %} {% tab title="200 " %} ```ara { "status": "ok", "data": { "response": "subscriber_unqualified" < Subscriber object > }, "calls_left": null, "timestamp": 1775833694 } ``` {% endtab %} {% endtabs %} ### Mark Referral as Qualified `POST` `https://app.referralhero.com/api/v2/lists/:uuid/subscribers/:subscriber_id/qualify` Mark a referral as Qualified #### Path Parameters | Name | Type | Description | | -------------- | ------ | ------------------------ | | uuid | String | The list UUID | | subscriber\_id | String | The ID of the subscriber | {% tabs %} {% tab title="200 " %} ```ara { "status": "ok", "data": { "response": "subscriber_qualified" < Subscriber object > }, "calls_left": null, "timestamp": 1775833694 } ``` {% endtab %} {% endtabs %} # Endpoint Reference V2 ## Authentication All API requests must be authenticated using an API token. **Preferred (**Recommended) **:** Authorization: `Bearer YOUR_API_TOKEN` **Alternative :** X-API-Key: `YOUR_API_TOKEN` > Use X-API-Key only if your client cannot send the Authorization header. **Headers** | Name | Value | Description | | ------------- | ----------------------- | ------------------ | | Authorization | Bearer `YOUR_API_TOKEN` | (Preferred) | | X-API-Key | `YOUR_API_TOKEN` | Alternative option | {% hint style="info" %} You can find your api token by navigating to **ReferralHero dashboard > Account > API** {% endhint %} ## Lists Locations where you can find most of the required parameters: | Path Parameters | Location | | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | name | *ReferralHero dashboard > Campaign name* | | uuid |

ReferralHero dashboard > Campaign > Installation > Instructions

The 12-letter id that starts with ‘MF’ in the Tracking Code, e.g. Mxxxxxxxxxx

| #### Create a new list `POST` `https://app.referralhero.com/api/v2/lists` Create a new list/campaign in your account. **Path Parameters** | Name | Type | Description | | ------- | ------ | -------------------- | | website | string | Default Referral URL | | name | string | Your list name | {% tabs %} {% tab title="200 " %} ```yaml { "status": "ok", "data": { < List object > }, "calls_left": 1000, "timestamp": 1487659010 } ``` {% endtab %} {% endtabs %} #### Retrieve all lists `GET` `https://app.referralhero.com/api/v2/lists` Get all the lists/campaigns in your account. Results are paginated (10 results per page).\ Only active lists will be retrieved. **Path Parameters** | Name | Type | Description | | ---- | ------ | --------------------------------------- | | page | string | Page you want to jump to. By default 1. | {% tabs %} {% tab title="200 " %} ```yaml { "status": "ok", "data": { "response": "lists_retrieved", "lists": [ { < List object > }, { < List object > }, ... ], "pagination": { "total_pages": 7, "current_page": 1, "per_page": 10, "total_objects": 67 } }, "calls_left": 1000, "timestamp": 1487658324 } ``` {% endtab %} {% endtabs %} #### Get List Leaderboard `GET` `https://app.referralhero.com/api/v2/lists/:uuid/leaderboard` Retrieve leaderboard of the top 10-100 subscribers in a list. **Path Parameters** | Name | Type | Description | | ----- | ------ | ---------------------------------------------------------- | | uuid | string | Your list UUID | | count | string | Number (10-100) of subscribers returned in the leaderboard | {% tabs %} {% tab title="200 " %} ```yaml { "status": "ok", "data": { "ranking": [ { < Subscriber object > }, { < Subscriber object > }, ... ] }, "calls_left": 1000, "timestamp": 1487659347 } ``` {% endtab %} {% endtabs %} #### Get list rewards `GET` `https://app.referralhero.com/api/v2/lists/:uuid/bonuses` Retrieve list of rewards from a list. **Path Parameters** | Name | Type | Description | | ---- | ------ | -------------- | | uuid | string | Your list UUID | {% tabs %} {% tab title="200 " %} ```yaml { "status": "ok", "data": [ { < Reward object > }, { < Reward object > } ], "calls_left": 1000, "timestamp": 1487659708 } ``` {% endtab %} {% endtabs %} ### Subscribers Locations where you can find most of the required parameters: | Path Parameters | Location | | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | uuid |

ReferralHero dashboard > Campaign Overview> Edit Campaign > Launch > Instructions

The 12-letter id that starts with ‘MF’ in the Tracking Code, e.g. MF078d000987

| | email | The email of the subscriber | | domain | *ReferralHero dashboard > Campaign > Options > Default Referral Link* | | subscriber\_id | *ReferralHero dashboard > Campaign > Subscribers* | #### Add a subscriber `POST` `https://app.referralhero.com/api/v2/lists/:uuid/subscribers` **Path Parameters** | Name | Type | Description | | ------------------------ | ------- | ------------------------------------------------------------------------------------- | | uuid | string | The list uuid | | email | string | The email of subscriber (if unique identifier) | | phone\_number | string | The phone number of subscriber (if unique identifier) | | crypto\_wallet\_address | string | The wallet address of subscriber (if unique identifier) | | other\_identifier\_value | string | The other identifier value of subscriber (if unique identifier) | | name | string | The name of the subscriber | | status | string | Use 'custom\_event\_pending' to set the referral status to pending | | transaction\_id | string | The unique ID of the transaction. Useful when tracking referrals for purchases. | | conversion\_category | string | The type of subscriber. Useful for creating reports or segmenting subscribers. | | conversion\_value | number | The monetary value of the referral. | | device | string | The device used by the subscriber to sign up. Used for analytics. | | source | string | The source of the subscriber. Used for analytics. | | double\_optin | boolean | If set to `false` the subscriber will not received a confirmation email. | | points | integer | The number of points for the subscriber. It only works for "contest" campaigns. | | referrer | string | Set a referrer for the subscriber by providing the referrer's referral code or email. | | extra\_field | string | The extra field of the subscriber | | extra\_field\_2 | string | The extra field 2 of the subscriber | | domain | string | The URL for the referral link | | stripe\_customer\_id | string | Stripe Customer ID | | advocate\_name | string | Name of the advocate | | tags | array | Assign tags to subscribers | {% tabs %} {% tab title="200 " %} ```yaml { "status": "ok", "data": { "response": "subscriber_created", < Subscriber object > }, "calls_left": 1000, "timestamp": 1487661494 } ``` {% endtab %} {% endtabs %} {% hint style="info" %} **Note for Web Integrations:** When deciding between using our Javascript Web API or REST API to interact with ReferralHero, it is generally advisable to 'add a subscriber' using the Javascript Web API as you will take advantage of our powerful global tracking script and cookie. Once a subscriber is added to our database, you can manage that subscriber and campaign more freely using either the Javascript Web API or REST API. {% endhint %} #### Track referral conversion event `POST` `https://app.referralhero.com/api/v2/lists/:uuid/subscribers/track_referral_conversion_event` Use when your Campaign Goal is set to track two or three conversion events. **If the referrer is present** in the API request params, we will check the referral unique identifier in your campaign and, if found, the referral status will be updated and, if not found, we will create the referral and set the referral status. **If the referrer is not present** in the API request params, we will check the referral unique identifier in your campaign and, if found, the referral status will be updated and, if not found, the referral will not be created. **The Referral Status Is Set To:** Confirmed (if tracking two conversion events) Unconfirmed (if tracking three conversion events) \ **Note**: 1\. Your campaign Goal must be set up to track two or three conversion events otherwise, an error will return. 2\. If the referral is present in ReferralHero with pending status, a successful response `custom_event_completed` will return. 3\. If the referral unique identifier is not present in the ReferralHero, but the referrer unique identifier is present, a successful response `custom_event_completed` with the data of the new confirmed referral will return. 4\. If a referral exists but the referral status is not pending, the error `custom event is already completed` will return. 5\. If the referral unique identifier is not present in ReferralHero and the referrer is also not provided in the API, the error `referrer is invalid or not present` will return. 6\. If the referral status is unconfirmed or confirmed, the error `custom event is already completed` will return. **Path Parameters** | Name | Type | Description | | ------------------------ | ------ | -------------------------------------------------------------------- | | uuid | string | Your list UUID | | email | string | The email of subscriber (if unique identifier) | | phone\_number | string | The phone number of subscriber (if unique identifier) | | crypto\_wallet\_address | string | The crypto wallet address of subscriber (if unique identifier) | | other\_identifier\_value | string | The identifier value of subscriber (if unique identifier) | | referrer | string | The unique identifier of the referrer | | conversion\_value | string | Referral conversion value | | stripe\_customer\_id | string | Stripe Customer ID | | transaction\_id | string | Assign a transaction id to the conversion event | | product\_id | string | Product ID (normally used if rewards are based on specific products) | | tags | array | Assign tags to subscriber | {% tabs %} {% tab title="200 " %} ```yaml { "status": "ok", "data": { "response": "custom_event_completed", < Subscriber object > }, "calls_left": 1000, "timestamp": 1487661494 } ``` {% endtab %} {% endtabs %} #### Confirm referral by Subscriber ID `POST` `https://app.referralhero.com/api/v2/lists/:uuid/subscribers/:subscriber_id/confirm` Use when your Campaign Goal is set to track three conversion events and you want to confirm referrals when your third conversion event occurs (e.g: upgrade to a paid plan, end of trial, etc). **The Referral Status Is Set To:** Confirmed (if tracking three conversion events) **Note**: 1\. Your campaign Goal must be set up to track three conversion events otherwise, an error will return. 2\. Only verified referrals can be confirmed. Trying to confirm a non-verified referral will return a `subscriber_not_found` error. **Path Parameters** | Name | Type | Description | | -------------- | ------ | ------------------------ | | uuid | string | Your list UUID | | subscriber\_id | string | The ID of the subscriber | {% tabs %} {% tab title="200 " %} ```yaml { "status": "ok", "data": { "response": "subscriber_confirmed", < Subscriber object > }, "calls_left": 1000, "timestamp": 1487661494 } ``` {% endtab %} {% endtabs %} #### Confirm referral by Unique Identifier `POST` `https://app.referralhero.com/api/v2/lists/:uuid/subscribers/confirm` Use when your Campaign Goal is set to track three conversion events and you want to confirm referrals when your third conversion event occurs (e.g: upgrade to a paid plan, end of trial, etc). **The Referral Status Is Set To:** Confirmed (if tracking three conversion events) **Note**: 1\. Your campaign Goal must be set up to track three conversion events otherwise, an error will return. 2\. Only verified referrals can be confirmed. Trying to confirm a non-verified referral will return a `subscriber_not_found` error. **Path Parameters** | Name | Type | Description | | ------------------------ | ------ | --------------------------------------------------------------- | | uuid | String | Your list UUID | | email | String | The email of subscriber (if unique identifier) | | crypto\_wallet\_address | String | The wallet address of subscriber (if unique identifier) | | phone\_number | String | The phone number of subscriber (if unique identifier) | | other\_identifier\_value | String | The other identifier value of subscriber (if unique identifier) | {% tabs %} {% tab title="200 " %} ```json { "status": "ok", "data": { "response": "subscriber_confirmed", < Subscriber object > }, "calls_left": 1000, "timestamp": 1487661494 } ``` {% endtab %} {% endtabs %} #### Update a subscriber `POST` `https://app.referralhero.com/api/v2/lists/:uuid/subscribers/:subscriber_id` Update a single subscriber.\ Note: only verified subscribers can be updated. Trying to update a non-verified subscriber will return a subscriber\_not\_found error. **Path Parameters** | Name | Type | Description | | ------------------------ | ------ | ------------------------------------------------------------------------------ | | uuid | string | The list UUID | | name | string | The name of the subscriber | | email | string | The email of subscriber (if unique identifier) | | phone\_number | string | The phone number of subscriber (if unique identifier) | | crypto\_wallet\_address | string | The wallet address of subscriber (if unique identifier) | | other\_identifier\_value | string | The other identifier value of subscriber (if unique identifier) | | extra\_field | string | The extra field of the subscriber | | extra\_field\_2 | string | The extra field 2 of the subscriber | | points | string | The number of points of the subscriber. It only works for "contest" campaigns. | | subscriber\_id | string | The ID of the subscriber | | stripe\_customer\_id | string | Stripe Customer ID | | tags | array | Assign tags to subscribers | | address | string | The address of the subscriber. | | city | string | The city of the subscriber. | | country | string | The country of the subscriber. | {% tabs %} {% tab title="200 " %} ```yaml { "status": "ok", "data": { "response": "subscriber_updated", < Subscriber object > }, "calls_left": 1000, "timestamp": 1487661494 } ``` {% endtab %} {% endtabs %} #### Add points to a subscriber `POST` `https://app.referralhero.com/api/v2/lists/:uuid/subscribers/add_points` Add points to an existing subscriber for any reason.\ **Note**: Trying to add points to a non-existing subscriber will return a `subscriber_not_found` error. **Path Parameters** | Name | Type | Description | | ------------------------ | ------ | --------------------------------------------------------------- | | uuid | string | Your list UUID | | email | string | The email of subscriber (if unique identifier) | | phone\_number | string | The phone number of subscriber (if unique identifier) | | crypto\_wallet\_address | string | The crypto wallet address of subscriber (if unique identifier) | | other\_identifier\_value | string | The other identifier value of subscriber (if unique identifier) | | points | string | The number or points to add | {% tabs %} {% tab title="200 " %} ```yaml { "status": "ok", "data": { "response": "points_added", < Subscriber object > }, "calls_left": 1000, "timestamp": 1487661494 } ``` {% endtab %} {% endtabs %} #### Track Transactions (Single Transaction) `POST` `https://app.referralhero.com/api/v2/lists/:uuid/subscribers/add_transactions` This allows you to pass transaction data to ReferralHero. | Name | Type | Description | | ------------------------ | ------ | --------------------------------------------------------------- | | uuid | string | Your list UUID | | email | string | The email of subscriber (if unique identifier) | | phone\_number | string | The phone number of subscriber (if unique identifier) | | crypto\_wallet\_address | string | The crypto wallet address of subscriber (if unique identifier) | | other\_identifier\_value | string | The other identifier value of subscriber (if unique identifier) | | amount (required) | string | Amount of the transaction | | transaction\_id | string | Transaction ID | | product\_id | string | Product ID | | lifetime\_spend | string | Total lifetime spend | | reward\_value | string | Set a reward value with the transaction | **Response** {% tabs %} {% tab title="200" %} ```json { "status": "ok", "data": { "id": 592, "transaction_id": "MFa19e08789720240219142611", "transaction_time": "2024-02-19T14:26:11.000Z", "amount": 56665, "product_id": "12345", "response": "transaction_added" }, "calls_left": null, "timestamp": 1708352775 } ``` {% endtab %} {% endtabs %} #### Track Bulk Transactions `POST` `https://app.referralhero.com/api/v2/lists/:uuid/subscribers/add_bulk_transactions` This allows you to pass multiple transaction data to ReferralHero in bulk. Once processing is complete, the results will be emailed to the admin with a CSV file containing the transaction status. You can pass up to **500 transactions** at a time. | Name | Type | Description | | ------------------------ | ------ | --------------------------------------------------------------- | | uuid | string | Your list UUID | | email | string | The email of subscriber (if unique identifier) | | phone\_number | string | The phone number of subscriber (if unique identifier) | | crypto\_wallet\_address | string | The crypto wallet address of subscriber (if unique identifier) | | other\_identifier\_value | string | The other identifier value of subscriber (if unique identifier) | | amount (required) | string | Amount of the Transaction | | transaction\_id | string | Transaction ID | | product\_id | string | Product ID | | lifetime\_spend | string | Total lifetime spend | | reward\_value | string | Set a reward value with the transaction | **Request Body (JSON Format)** {% tabs %} {% tab title="JSON" %} ```json { "transactions": [ { "email": "refloading@hi.com", "amount": 150, "product_id": "prod_0005", "transaction_id": "trans_0005", "reward_value": 15 }, { "email": "tremendousref3@hi.com", "amount": 500, "product_id": "prod_0006", "transaction_id": "trans_0006", "reward_value": 50 } ] } ``` {% endtab %} {% endtabs %} **Response** {% tabs %} {% tab title="200" %} ```json { "status": "in_progress", "message": "Transactions are being processed. It will take some time to complete." } ``` {% endtab %} {% endtabs %} #### Promote a subscriber `POST` `https://app.referralhero.com/api/v2/lists/:uuid/subscribers/:subscriber_id/promote` Promote a single subscriber. Read this article about what "promoting" means.\ **Note**: only verified subscribers can be promoted. Trying to promote a non-verified subscriber will return a `subscriber_not_found` error. **Path Parameters** | Name | Type | Description | | -------------- | ------ | ------------------------ | | uuid | string | Your list UUID | | subscriber\_id | string | The ID of the subscriber | {% tabs %} {% tab title="200 " %} ```yaml { "status": "ok", "data": { "response": "subscriber_promoted", < Subscriber object > }, "calls_left": 1000, "timestamp": 1487661494 } ``` {% endtab %} {% endtabs %} #### Trigger manual rewards `POST` `https://app.referralhero.com/api/v2/lists/:uuid/subscribers/:subscriber_id/unlock_promoted_reward` Used to trigger the Rewards for Promoted Winners **Path Parameters** | Name | Type | Description | | -------------- | ------ | ------------------------------ | | uuid | String | Your list UUID | | subscriber\_id | String | The ID of the subscriber | | reward\_id | String | The ID of the promotion reward | {% tabs %} {% tab title="200 " %} ```json { "response": "reward_unlocked", "reward": { "id": 203, "title": "Winner 2", "header": null, "description": "", "referrals": null, "image": "/missing.png", "label": "Winner Reward", "points": null, "category": "promoted_winners" } } ``` {% endtab %} {% endtabs %} #### Retrieve all subscribers from a list `GET` `https://app.referralhero.com/api/v2/lists/:uuid/subscribers` Get all the subscribers in a list. Results are paginated (max 50 results per page). **Path Parameters** | Name | Type | Description | | -------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | uuid | string | Your list UUID | | sort\_by | string | Sort subscribers by one attribute. Possible options are: `registration_desc`, `registration_asc`, `email_asc`, `email_desc`, `name_asc`, `name_desc`, `position_asc`, `position_desc` , `people_referred_asc`, `people_referred_desc`, `points_asc`, `points_desc` | | page | string | Page you want to jump to. By default 1. | | extra\_field | string | The extra field of the subscriber | | extra\_field\_2 | string | The extra field 2 of the subscriber | | option\_field | string | The option field of the subscriber | | stripe\_customer\_id | string | Stripe Customer ID | {% tabs %} {% tab title="200 " %} ```yaml { "status": "ok", "data": { "response": "subscribers_retrieved", "subscribers": [ { < Subscriber object > }, { < Subscriber object > }, ... ], "pagination": { "total_pages": 1, "current_page": 1, "per_page": 50, "total_objects": 14 } }, "calls_left": 1000, "timestamp": 1487675505 } ``` {% endtab %} {% endtabs %} #### Retrieve subscriber by ID `GET` `https://app.referralhero.com/api/v2/lists/:uuid/subscribers/:subscriber_id` Retrieve a single subscriber.\ **Note**: only verified subscribers can be retrieved. Trying to retrieve a non-verified subscriber will return a `subscriber_not_found` error. **Path Parameters** | Name | Type | Description | | -------------- | ------ | ------------------------ | | uuid | string | The list UUID | | subscriber\_id | string | The ID of the subscriber | {% tabs %} {% tab title="200 " %} ```yaml { "status": "ok", "data": { "response": "subscriber_retrieved", < Subscriber object > }, "calls_left": 1000, "timestamp": 1487676070 } ``` {% endtab %} {% endtabs %} #### Retrieve subscriber by email `GET` `https://app.referralhero.com/api/v2/lists/:uuid/subscribers/retrieve_by_email` Retrieve a single subscriber.\ **Note**: only verified subscribers can be retrieved. Trying to retrieve a non-verified subscriber will return a `subscriber_not_found` error. **Path Parameters** | Name | Type | Description | | ----- | ------ | ---------------------------- | | uuid | string | The list UUID | | email | string | The email of the subscriber. | {% tabs %} {% tab title="200 " %} ```yaml { "status": "ok", "data": { "response": "subscriber_retrieved", < Subscriber object > }, "calls_left": 1000, "timestamp": 1487676070 } ``` {% endtab %} {% endtabs %} #### Retrieve subscriber by MWR `GET` `https://app.referralhero.com/api/v2/lists/:uuid/subscribers/retrieve_by_mwr` Retrieve a single subscriber.\ **Note**: only verified subscribers can be retrieved. Trying to retrieve a non-verified subscriber will return a `subscriber_not_found` error. **Path Parameters** | Name | Type | Description | | ---- | ------ | ---------------------------- | | uuid | string | The list UUID | | mwr | string | The referrer's referral code | {% tabs %} {% tab title="200" %} ```json { "status": "ok", "data": { "response": "subscriber_retrieved", < Subscriber object > }, "calls_left": null, "timestamp": 1725032082 } ``` {% endtab %} {% endtabs %} #### Retrieve all referrals (pending, unconfirmed, confirmed) of a subscriber `GET` `https://app.referralhero.com/api/v2/lists/:uuid/subscribers/:subscriber_id/referred` Retrieve all referrals (pending, unconfirmed, confirmed) of a single subscriber. Results are paginated (max 50 results per page). **Path Parameters**
NameTypeDescription
uuidstringYour list UUID
subscriber_idstringThe ID of the subscriber.
pagestringPage you want to jump to. By default is 1.
sort_bystringSort subscribers by one attribute. Possible options are: registration_desc, registration_asc, email_asc, email_desc, name_asc, name_desc, position_asc, position_desc, people_referred_asc, people_referred_desc, points_asc, points_desc
{% tabs %} {% tab title="200 " %} ```json { "status": "ok", "data": { "response": "subscribers_retrieved", "subscribers": [ { < Subscriber object > }, { < Subscriber object > }, ... ], "pagination": { "total_pages": 1, "current_page": 1, "per_page": 50, "total_objects": 14 } }, "calls_left": 1000, "timestamp": 1487675505 } ``` {% endtab %} {% endtabs %} #### Retrieve all Level 2 referrals (pending, unconfirmed, confirmed) of a subscriber `GET` `https://app.referralhero.com/api/v2/lists/:uuid/subscribers/:subscriber_id/level_2_all_referrals` Retrieve all Level 2 referrals (pending, unconfirmed, confirmed) of a single subscriber. Results are paginated (max 50 results per page). **Path Parameters** | Name | Type | Description | | -------------- | ------ | ------------------------- | | uuid | string | Your list UUID | | subscriber\_id | string | The ID of the subscriber. | {% tabs %} {% tab title="200" %} ```json { "status": "ok", "data": { "response": "subscribers_retrieved", "subscribers": [ { < Subscriber object > , "pending_referrals": 0, "unconfirmed_referrals": 0, "people_referred": 0, "level_2_confirmed_referrals": 0, "level_3_confirmed_referrals": 0, "promoted": false, "promoted_at": null, "verified": true, "verified_at": 1723452705, "points": 0, "risk_level": 0, "host": "https://www.mywebiste.com/refer", "source": null, "device": null, "referral_link": "https://www.mywebiste.com/refer?mwr=eb134345", "created_at": 1723452705, "last_updated_at": 1723452705, "referral_status": "confirmed", "referral_status_at": 1723452705, "universal_link": "https://app.referralhero.com//MFxxxxxxxxx/universal_link?mwr=eb134b6d" } ], "pagination": { "total_pages": 1, "current_page": 1, "per_page": 50, "total_objects": 1 } }, "calls_left": null, "timestamp": 1723457099 } ``` {% endtab %} {% endtabs %} #### Retrieve all Level 3 referrals (pending, unconfirmed, confirmed) of a subscriber `GET` `https://app.referralhero.com/api/v2/lists/:uuid/subscribers/:subscriber_id/level_3_all_referrals` **Path Parameters** | Name | Type | Description | | -------------- | ------ | ------------------------- | | uuid | string | Your list UUID | | subscriber\_id | string | The ID of the subscriber. | {% tabs %} {% tab title="200" %} ```json { "status": "ok", "data": { "response": "subscribers_retrieved", "subscribers": [ { < Subscriber object > , "pending_referrals": 0, "unconfirmed_referrals": 0, "people_referred": 0, "level_2_confirmed_referrals": 0, "level_3_confirmed_referrals": 0, "promoted": false, "promoted_at": null, "verified": true, "verified_at": 1723452705, "points": 0, "risk_level": 0, "host": "https://www.mywebiste.com/refer", "source": null, "device": null, "referral_link": "https://www.mywebiste.com/refer?mwr=eb134ss4", "created_at": 1723452705, "last_updated_at": 1723452705, "referral_status": "confirmed", "referral_status_at": 1723452705, "universal_link": "https://app.referralhero.com//MFxxxxxxxxxx/universal_link?mwr=eb134b6d" } ], "pagination": { "total_pages": 1, "current_page": 1, "per_page": 50, "total_objects": 1 } }, "calls_left": null, "timestamp": 1723457099 } ``` {% endtab %} {% endtabs %} #### Retrieve all level 1 confirmed referrals of a subscriber `GET` `https://app.referralhero.com/api/v2/lists/:uuid/subscribers/:subscriber_id/level_1_referrals` Retrieve all level 1 confirmed referrals of a single subscriber. Results are paginated (max 50 results per page). **Path Parameters**
NameTypeDescription
uuidstringYour list UUID
subscriber_idstringThe ID of the subscriber.
pagestringPage you want to jump to. By default is 1.
sort_bystringSort subscribers by one attribute. Possible options are: registration_desc, registration_asc, email_asc, email_desc, name_asc, name_desc, position_asc, position_desc, people_referred_asc, people_referred_desc, points_asc, points_desc
{% tabs %} {% tab title="200 " %} ```yaml { "status": "ok", "data": { "response": "subscribers_retrieved", "subscribers": [ { < Subscriber object > }, { < Subscriber object > }, ... ], "pagination": { "total_pages": 1, "current_page": 1, "per_page": 50, "total_objects": 14 } }, "calls_left": 1000, "timestamp": 1487675505 } ``` {% endtab %} {% endtabs %} #### Retrieve all level 2 confirmed referrals of a subscriber `GET` `https://app.referralhero.com/api/v2/lists/:uuid/subscribers/:subscriber_id/level_2_referrals` Retrieve all level 2 confirmed referrals of a single subscriber. Results are paginated (max 50 results per page). **Path Parameters**
NameTypeDescription
uuidstringYour list UUID
subscriber_idstringThe ID of the subscriber.
pagestringPage you want to jump to. By default is 1.
sort_bystringSort subscribers by one attribute. Possible options are: registration_desc, registration_asc, email_asc, email_desc, name_asc, name_desc, position_asc, position_desc, people_referred_asc, people_referred_desc, points_asc, points_desc
{% tabs %} {% tab title="200 " %} ```json { "status": "ok", "data": { "response": "subscribers_retrieved", "subscribers": [ { < Subscriber object > }, { < Subscriber object > }, ... ], "pagination": { "total_pages": 1, "current_page": 1, "per_page": 50, "total_objects": 14 } }, "calls_left": 1000, "timestamp": 1487675505 } ``` {% endtab %} {% endtabs %} #### Retrieve all level 3 confirmed referrals of a subscriber `GET` `https://app.referralhero.com/api/v2/lists/:uuid/subscribers/:subscriber_id/level_3_referrals` Retrieve all level 3 confirmed referrals of a single subscriber. Results are paginated (max 50 results per page). **Path Parameters**
NameTypeDescription
uuidstringYour list UUID
subscriber_idstringThe ID of the subscriber.
pagestringPage you want to jump to. By default is 1.
sort_bystringSort subscribers by one attribute. Possible options are: registration_desc, registration_asc, email_asc, email_desc, name_asc, name_desc, position_asc, position_desc, people_referred_asc, people_referred_desc, points_asc, points_desc
{% tabs %} {% tab title="200 " %} ```json { "status": "ok", "data": { "response": "subscribers_retrieved", "subscribers": [ { < Subscriber object > }, { < Subscriber object > }, ... ], "pagination": { "total_pages": 1, "current_page": 1, "per_page": 50, "total_objects": 14 } }, "calls_left": 1000, "timestamp": 1487675505 } ``` {% endtab %} {% endtabs %} ### Retrieve all rewards for all subscribers `GET` `https://app.referralhero.com/api/v2/lists/:uuid/rewards` Retrieve a list of all rewards across all subscribers in a specified campaign. Results are paginated (maximum 50 results per page). **Path Parameters** | Name | Type | Description | | ----------------- | ------ | ---------------------------------------------------------------------- | | uuid | String | Your list UUID | | status (optional) | String | Status of the reward (i.e. sent, resent, canceled, pending or flagged) | | page | String | Page you want to jump to. By default is 1. | | per\_page | String | Number of results you want per page. By default is 10. | {% tabs %} {% tab title="200 " %} { "status": "ok", "data": { "response": "rewards\_retrieved", "rewards": \[ { "id": 214, "name": "10% commission", "status": "sent", "referrals": 1, "created\_at": 1729166882, "unlocked\_date": 1752823036, "sent\_date": 1752823044, "referral": "", "value": 100.0, "total": "", "signup\_type": null, "referrals\_type": "confirmed", "recurring\_count": null, "coupon\_code": null, "coupon\_group": null, "image\_url": null, "subscriber\_email": "", "subscriber\_id": "sub\_64f9c36e25de" \`\`\` }, ], "pagination": { "total\_pages": 1, "current\_page": 1, "per\_page": 10, "total\_objects": 1 } }, "calls\_left": null, "timestamp": 1729186260 } Retrieve all rewards unlocked by a subscriber `GET` `https://app.referralhero.com/api/v2/lists/:uuid/subscribers/:subscriber_id/rewards` Get all rewards unlocked by the subscriber. Results are paginated (max 50 results per page). **Path Parameters** | Name | Type | Description | | ----------------- | ------ | ---------------------------------------------------------------------- | | uuid | String | Your list UUID | | subscriber\_id | String | The ID of the subscriber | | status (optional) | String | Status of the reward (i.e. sent, resent, canceled, pending or flagged) | {% tabs %} {% tab title="200: OK" %} ```json { "status": "ok", "data": { "response": "rewards_retrieved", "rewards": [ { "id": 214, "name": "10% commission", "status": "sent", "referrals": 1, "created_at": 1752217473, "unlocked_date": 1752823036, "sent_date": 1752823044, "referral": "nishchay@referralhero.com", "value": 100.0, "total": "", "signup_type": null, "referrals_type": "confirmed", "recurring_count": null, "coupon_code": null, "coupon_group": null, "image_url": null }, ], "pagination": { "total_pages": 1, "current_page": 1, "per_page": 10, "total_objects": 1 } }, "calls_left": null, "timestamp": 1729186260 } ``` {% endtab %} {% endtabs %} #### Delete a subscriber `DELETE` `https://app.referralhero.com/api/v2/lists/:uuid/subscribers/:subscriber_id` Delete a single subscriber. **Path Parameters** | Name | Type | Description | | -------------- | ------ | ------------------------ | | uuid | string | The list UUID | | subscriber\_id | string | The ID of the subscriber | {% tabs %} {% tab title="200: OK" %} ```json { "status": "ok", "data": { "response": "subscriber_deleted", < Subscriber object > }, "calls_left": 1000, "timestamp": 1487661494 } ``` {% endtab %} {% endtabs %} #### Update reward status by reward\_id `POST` `https://app.referralhero.com/api/v2/lists/:uuid/subscribers/update_reward_status` Update status of an unlocked reward of a subscriber by reward\_id **Path Parameters** | Name | Type | Description | | ---------- | ------ | --------------------------------------------------------------------- | | uuid | String | Your list UUID | | reward\_id | String | ID of reward provided in GET all rewards unlocked by a subscriber API | | status | String | sent/resent/canceled | {% tabs %} {% tab title="200: OK" %} ```json { "status": "ok", "data": { "id": 794765, "name": "referral signup", "status": "confirmed", "referrals": null, "created_at": 1752217473, "unlocked_date": 1752823036, "sent_date": 1752823044, "referral": "", "value": null, "total": "", "signup_type": "referral", "referrals_type": null, "recurring_count": null, "coupon_code": "cdwtmnKz8P", "coupon_group": "10-off-new-355bed2b-d645-4b2f-88ed-40a813940243", "image_url": null }, "calls_left": null, "timestamp": 1753514108 } ``` {% endtab %} {% endtabs %} #### Create coupon group `POST` `https://app.referralhero.com/api/v2/lists/:uuid/coupon_groups` Add new coupon group **Path Parameters** | Name | Type | Description | | ------- | ------ | --------------------------------------- | | uuid | String | Your list UUID | | name | String | Coupon group name | | coupons | String | Array, e.g. \["ab23fg, fghg45, gh78wl"] | | active | String | True or false | {% tabs %} {% tab title="200: OK" %} ```json { "status": "ok", "data": { "id": "rh400", "name": "RH400", "active": true, "created_at": 1686563261, "coupons": [], "response": "coupon_group_created" }, "calls_left": null, "timestamp": 1686563261 } ``` {% endtab %} {% endtabs %} #### Create coupons `POST` `https://app.referralhero.com/api/v2/lists/:uuid/coupons` Add coupon(s) to a coupon group **Path Parameters** | Name | Type | Description | | ----------------- | ------ | ------------------------------------------ | | uuid | String | Your list UUID | | coupon\_group\_id | String | ID of coupon group | | coupons | String | Array, e.g. \["ab23fg", fghg45”, “gh78wl"] | {% tabs %} {% tab title="200: OK " %} ```json { "status": "ok", "data": { "id": "rh200", "name": "RH200", "active": true, "created_at": 1686563246, "coupons": [ { "code": "FCMPFI", "available": true, "sent_at": null, "email_id": null, "created_at": 1686563246 }, { "code": "U3EHFD", "available": true, "sent_at": null, "email_id": null, "created_at": 1686563246 }, { "code": "tvt4g45v", "available": true, "sent_at": null, "email_id": null, "created_at": 1686563246 }, { "code": "RFGH677", "available": true, "sent_at": null, "email_id": null, "created_at": 1686563246 }, { "code": "KMLFG767", "available": true, "sent_at": null, "email_id": null, "created_at": 1686563246 } ] }, "calls_left": null, "timestamp": 1686676359 } ``` {% endtab %} {% endtabs %} #### Retrieve all coupon groups `GET` `https://app.referralhero.com/api/v2/lists/:uuid/coupon_groups` Get all coupon groups of a campaign **Path Parameters** | Name | Type | Description | | ---- | ------ | -------------- | | uuid | String | Your list UUID | {% tabs %} {% tab title="200: OK " %} ```json { "status": "ok", "data": { "response": "coupon_groups_retrieved", "coupon_groups": [ { "id": "rh200", "name": "RH200", "active": true, "created_at": 1686563246, "coupons": [ { "code": "FCMPFI", "available": true, "sent_at": null, "email_id": null, "created_at": 1686563246 }, { "code": "U3EHFD", "available": true, "sent_at": null, "email_id": null, "created_at": 1686563246 } ] }, { "id": "rh400", "name": "RH400", "active": true, "created_at": 1686563261, "coupons": [] } ], "pagination": { "total_pages": 1, "current_page": 1, "per_page": 50, "total_objects": 2 } }, "calls_left": null, "timestamp": 1686563777 } ``` {% endtab %} {% endtabs %} #### Retrieve coupons `GET` `https://app.referralhero.com/api/v2/lists/:uuid/coupon_groups/:id` Get all coupons within a coupon group **Path Parameters** | Name | Type | Description | | ---- | ------ | ------------------ | | uuid | String | Your list UUID | | id | String | ID of coupon group | {% tabs %} {% tab title="200: OK" %} ``` json { "status": "ok", "data": { "id": "rh200", "name": "RH200", "active": true, "created_at": 1686563246, "coupons": [] }, "calls_left": null, "timestamp": 1686563 ``` {% endtab %} {% endtabs %} # Endpoint Reference V1 ## Lists Locations where you can find most of the required parameters: | Path Parameters | Location | | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | api\_token | *ReferralHero dashboard > Account > API* | | name | *ReferralHero dashboard > Campaign name* | | uuid |

ReferralHero dashboard > Campaign > Installation > Instructions

The 12-letter id that starts with ‘MF’ in the Tracking Code, e.g. Mxxxxxxxxxx

| ### Create a new list `POST` `https://app.referralhero.com/api/v2/lists` Create a new list/campaign in your account. #### Path Parameters | Name | Type | Description | | ---------- | ------ | -------------------- | | website | string | Default Referral URL | | name | string | Your list name | | api\_token | string | Your API Token | {% tabs %} {% tab title="200 " %} ```yaml { "status": "ok", "data": { < List object > }, "calls_left": 1000, "timestamp": 1487659010 } ``` {% endtab %} {% endtabs %} ### Retrieve all lists `GET` `https://app.referralhero.com/api/v2/lists` Get all the lists/campaigns in your account. Results are paginated (10 results per page).\ Only active lists will be retrieved. #### Path Parameters | Name | Type | Description | | ---------- | ------ | --------------------------------------- | | api\_token | string | Your API Token. | | page | string | Page you want to jump to. By default 1. | {% tabs %} {% tab title="200 " %} ```yaml { "status": "ok", "data": { "response": "lists_retrieved", "lists": [ { < List object > }, { < List object > }, ... ], "pagination": { "total_pages": 7, "current_page": 1, "per_page": 10, "total_objects": 67 } }, "calls_left": 1000, "timestamp": 1487658324 } ``` {% endtab %} {% endtabs %} ### Get List Leaderboard `GET` `https://app.referralhero.com/api/v2/lists/:uuid/leaderboard` Retrieve leaderboard of the top 10-100 subscribers in a list. #### Path Parameters | Name | Type | Description | | ---------- | ------ | ---------------------------------------------------------- | | uuid | string | Your list UUID | | api\_token | string | Your API Token | | count | string | Number (10-100) of subscribers returned in the leaderboard | {% tabs %} {% tab title="200 " %} ```yaml { "status": "ok", "data": { "ranking": [ { < Subscriber object > }, { < Subscriber object > }, ... ] }, "calls_left": 1000, "timestamp": 1487659347 } ``` {% endtab %} {% endtabs %} ### Get list rewards `GET` `https://app.referralhero.com/api/v2/lists/:uuid/bonuses` Retrieve list of rewards from a list. #### Path Parameters | Name | Type | Description | | ---------- | ------ | -------------- | | uuid | string | Your list UUID | | api\_token | string | Your API Token | {% tabs %} {% tab title="200 " %} ```yaml { "status": "ok", "data": [ { < Reward object > }, { < Reward object > } ], "calls_left": 1000, "timestamp": 1487659708 } ``` {% endtab %} {% endtabs %} ## Subscribers Locations where you can find most of the required parameters: | Path Parameters | Location | | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | api\_token | *ReferralHero dashboard > Account > API* | | uuid |

ReferralHero dashboard > Campaign Overview> Edit Campaign > Launch > Instructions

The 12-letter id that starts with ‘MF’ in the Tracking Code, e.g. MF078d000987

| | email | The email of the subscriber | | domain | *ReferralHero dashboard > Campaign > Options > Default Referral Link* | | subscriber\_id | *ReferralHero dashboard > Campaign > Subscribers* | ### Add a subscriber `POST` `https://app.referralhero.com/api/v2/lists/:uuid/subscribers` #### Path Parameters | Name | Type | Description | | ------------------------ | ------- | ------------------------------------------------------------------------------------- | | api\_token | string | Your API Token | | uuid | string | The list uuid | | email | string | The email of subscriber (if unique identifier) | | phone\_number | string | The phone number of subscriber (if unique identifier) | | crypto\_wallet\_address | string | The wallet address of subscriber (if unique identifier) | | other\_identifier\_value | string | The other identifier value of subscriber (if unique identifier) | | name | string | The name of the subscriber | | status | string | Use 'custom\_event\_pending' to set the referral status to pending | | transaction\_id | string | The unique ID of the transaction. Useful when tracking referrals for purchases. | | conversion\_category | string | The type of subscriber. Useful for creating reports or segmenting subscribers. | | conversion\_value | number | The monetary value of the referral. | | device | string | The device used by the subscriber to sign up. Used for analytics. | | source | string | The source of the subscriber. Used for analytics. | | double\_optin | boolean | If set to `false` the subscriber will not received a confirmation email. | | points | integer | The number of points for the subscriber. It only works for "contest" campaigns. | | referrer | string | Set a referrer for the subscriber by providing the referrer's referral code or email. | | extra\_field | string | The extra field of the subscriber | | extra\_field\_2 | string | The extra field 2 of the subscriber | | domain | string | The URL for the referral link | | stripe\_customer\_id | string | Stripe Customer ID | | advocate\_name | string | Name of the advocate | | tags | array | Assign tags to subscribers | {% tabs %} {% tab title="200 " %} ```yaml { "status": "ok", "data": { "response": "subscriber_created", < Subscriber object > }, "calls_left": 1000, "timestamp": 1487661494 } ``` {% endtab %} {% endtabs %} {% hint style="info" %} **Note for Web Integrations:** When deciding between using our Javascript Web API or REST API to interact with ReferralHero, it is generally advisable to '[add a subscriber](/integrate/javascript-web-api/adding-a-subscriber-manually)' using the Javascript Web API as you will take advantage of our powerful global tracking script and cookie. Once a subscriber is added to our database, you can manage that subscriber and campaign more freely using either the Javascript Web API or REST API. {% endhint %} ### Track referral conversion event `POST` `https://app.referralhero.com/api/v2/lists/:uuid/subscribers/track_referral_conversion_event` Use when your Campaign Goal is set to track two or three conversion events. **If the referrer is present** in the API request params, we will check the referral unique identifier in your campaign and, if found, the referral status will be updated and, if not found, we will create the referral and set the referral status. **If the referrer is not present** in the API request params, we will check the referral unique identifier in your campaign and, if found, the referral status will be updated and, if not found, the referral will not be created. **The Referral Status Is Set To:** Confirmed (if tracking two conversion events) Unconfirmed (if tracking three conversion events) \ **Note**: 1\. Your campaign Goal must be set up to track two or three conversion events otherwise, an error will return. 2\. If the referral is present in ReferralHero with pending status, a successful response `custom_event_completed` will return. 3\. If the referral unique identifier is not present in the ReferralHero, but the referrer unique identifier is present, a successful response `custom_event_completed` with the data of the new confirmed referral will return. 4\. If a referral exists but the referral status is not pending, the error `custom event is already completed` will return. 5\. If the referral unique identifier is not present in ReferralHero and the referrer is also not provided in the API, the error `referrer is invalid or not present` will return. 6\. If the referral status is unconfirmed or confirmed, the error `custom event is already completed` will return. #### Path Parameters | Name | Type | Description | | ------------------------ | ------ | -------------------------------------------------------------------- | | api\_token | string | Your API Token | | uuid | string | Your list UUID | | email | string | The email of subscriber (if unique identifier) | | phone\_number | string | The phone number of subscriber (if unique identifier) | | crypto\_wallet\_address | string | The crypto wallet address of subscriber (if unique identifier) | | other\_identifier\_value | string | The identifier value of subscriber (if unique identifier) | | referrer | string | The unique identifier of the referrer | | conversion\_value | string | Referral conversion value | | stripe\_customer\_id | string | Stripe Customer ID | | transaction\_id | string | Assign a transaction id to the conversion event | | product\_id | string | Product ID (normally used if rewards are based on specific products) | | tags | array | Assign tags to subscriber | {% tabs %} {% tab title="200 " %} ```yaml { "status": "ok", "data": { "response": "custom_event_completed", < Subscriber object > }, "calls_left": 1000, "timestamp": 1487661494 } ``` {% endtab %} {% endtabs %} ### Confirm referral by Subscriber ID `POST` `https://app.referralhero.com/api/v2/lists/:uuid/subscribers/:subscriber_id/confirm` Use when your Campaign Goal is set to track three conversion events and you want to confirm referrals when your third conversion event occurs (e.g: upgrade to a paid plan, end of trial, etc). **The Referral Status Is Set To:** Confirmed (if tracking three conversion events) **Note**: 1\. Your campaign Goal must be set up to track three conversion events otherwise, an error will return. 2\. Only verified referrals can be confirmed. Trying to confirm a non-verified referral will return a `subscriber_not_found` error. #### Path Parameters | Name | Type | Description | | -------------- | ------ | ------------------------ | | api\_token | string | Your API Token | | uuid | string | Your list UUID | | subscriber\_id | string | The ID of the subscriber | {% tabs %} {% tab title="200 " %} ```yaml { "status": "ok", "data": { "response": "subscriber_confirmed", < Subscriber object > }, "calls_left": 1000, "timestamp": 1487661494 } ``` {% endtab %} {% endtabs %} ### Confirm referral by Unique Identifier `POST` `https://app.referralhero.com/api/v2/lists/:uuid/subscribers/confirm` Use when your Campaign Goal is set to track three conversion events and you want to confirm referrals when your third conversion event occurs (e.g: upgrade to a paid plan, end of trial, etc). **The Referral Status Is Set To:** Confirmed (if tracking three conversion events) **Note**: 1\. Your campaign Goal must be set up to track three conversion events otherwise, an error will return. 2\. Only verified referrals can be confirmed. Trying to confirm a non-verified referral will return a `subscriber_not_found` error. #### Path Parameters | Name | Type | Description | | ------------------------ | ------ | --------------------------------------------------------------- | | api\_token | String | Your API Token | | uuid | String | Your list UUID | | email | String | The email of subscriber (if unique identifier) | | crypto\_wallet\_address | String | The wallet address of subscriber (if unique identifier) | | phone\_number | String | The phone number of subscriber (if unique identifier) | | other\_identifier\_value | String | The other identifier value of subscriber (if unique identifier) | {% tabs %} {% tab title="200: OK " %} ```json { "status": "ok", "data": { "response": "subscriber_confirmed", < Subscriber object > }, "calls_left": 1000, "timestamp": 1487661494 } ``` {% endtab %} {% endtabs %} ### Update a subscriber `POST` `https://app.referralhero.com/api/v2/lists/:uuid/subscribers/:subscriber_id` Update a single subscriber.\ Note: only verified subscribers can be updated. Trying to update a non-verified subscriber will return a subscriber\_not\_found error. #### Path Parameters | Name | Type | Description | | ------------------------ | ------ | ------------------------------------------------------------------------------ | | api\_token | string | Your API Token | | uuid | string | The list UUID | | name | string | The name of the subscriber | | email | string | The email of subscriber (if unique identifier) | | phone\_number | string | The phone number of subscriber (if unique identifier) | | crypto\_wallet\_address | string | The wallet address of subscriber (if unique identifier) | | other\_identifier\_value | string | The other identifier value of subscriber (if unique identifier) | | extra\_field | string | The extra field of the subscriber | | extra\_field\_2 | string | The extra field 2 of the subscriber | | points | string | The number of points of the subscriber. It only works for "contest" campaigns. | | subscriber\_id | string | The ID of the subscriber | | stripe\_customer\_id | string | Stripe Customer ID | | tags | array | Assign tags to subscribers | | address | string | The address of the subscriber. | | city | string | The city of the subscriber. | | country | string | The country of the subscriber. | {% tabs %} {% tab title="200 " %} ```yaml { "status": "ok", "data": { "response": "subscriber_updated", < Subscriber object > }, "calls_left": 1000, "timestamp": 1487661494 } ``` {% endtab %} {% endtabs %} ### Add points to a subscriber `POST` `https://app.referralhero.com/api/v2/lists/:uuid/subscribers/add_points` Add points to an existing subscriber for any reason.\ **Note**: Trying to add points to a non-existing subscriber will return a `subscriber_not_found` error. #### Path Parameters | Name | Type | Description | | ------------------------ | ------ | --------------------------------------------------------------- | | api\_token | string | Your API Token | | uuid | string | Your list UUID | | email | string | The email of subscriber (if unique identifier) | | phone\_number | string | The phone number of subscriber (if unique identifier) | | crypto\_wallet\_address | string | The crypto wallet address of subscriber (if unique identifier) | | other\_identifier\_value | string | The other identifier value of subscriber (if unique identifier) | | points | string | The number or points to add | {% tabs %} {% tab title="200 " %} ```yaml { "status": "ok", "data": { "response": "points_added", < Subscriber object > }, "calls_left": 1000, "timestamp": 1487661494 } ``` {% endtab %} {% endtabs %} ### Track Transactions (Single Transaction) `POST` `https://app.referralhero.com/api/v2/lists/:uuid/subscribers/add_transactions` This allows you to pass transaction data to ReferralHero. | Name | Type | Description | | ------------------------ | ------ | --------------------------------------------------------------- | | api\_token | string | Your API Token | | uuid | string | Your list UUID | | email | string | The email of subscriber (if unique identifier) | | phone\_number | string | The phone number of subscriber (if unique identifier) | | crypto\_wallet\_address | string | The crypto wallet address of subscriber (if unique identifier) | | other\_identifier\_value | string | The other identifier value of subscriber (if unique identifier) | | amount (required) | string | Amount of the transaction | | transaction\_id | string | Transaction ID | | product\_id | string | Product ID | | lifetime\_spend | string | Total lifetime spend | | reward\_value | string | Set a reward value with the transaction | **Response** {% tabs %} {% tab title="200" %} ```json { "status": "ok", "data": { "id": 592, "transaction_id": "MFa19e08789720240219142611", "transaction_time": "2024-02-19T14:26:11.000Z", "amount": 56665, "product_id": "12345", "response": "transaction_added" }, "calls_left": null, "timestamp": 1708352775 } ``` {% endtab %} {% endtabs %} ### Track Bulk Transactions `POST` `https://app.referralhero.com/api/v2/lists/:uuid/subscribers/add_bulk_transactions` This allows you to pass multiple transaction data to ReferralHero in bulk. Once processing is complete, the results will be emailed to the admin with a CSV file containing the transaction status. You can pass up to **500 transactions** at a time. | Name | Type | Description | | ------------------------ | ------ | --------------------------------------------------------------- | | api\_token | string | Your API Token | | uuid | string | Your list UUID | | email | string | The email of subscriber (if unique identifier) | | phone\_number | string | The phone number of subscriber (if unique identifier) | | crypto\_wallet\_address | string | The crypto wallet address of subscriber (if unique identifier) | | other\_identifier\_value | string | The other identifier value of subscriber (if unique identifier) | | amount (required) | string | Amount of the Transaction | | transaction\_id | string | Transaction ID | | product\_id | string | Product ID | | lifetime\_spend | string | Total lifetime spend | | reward\_value | string | Set a reward value with the transaction | **Request Body (JSON Format)** {% tabs %} {% tab title="JSON" %} ```json { "transactions": [ { "email": "refloading@hi.com", "amount": 150, "product_id": "prod_0005", "transaction_id": "trans_0005", "reward_value": 15 }, { "email": "tremendousref3@hi.com", "amount": 500, "product_id": "prod_0006", "transaction_id": "trans_0006", "reward_value": 50 } ] } ``` {% endtab %} {% endtabs %} **Response** {% tabs %} {% tab title="200" %} ```json { "status": "in_progress", "message": "Transactions are being processed. It will take some time to complete." } ``` {% endtab %} {% endtabs %} ### Promote a subscriber `POST` `https://app.referralhero.com/api/v2/lists/:uuid/subscribers/:subscriber_id/promote` Promote a single subscriber. Read this article about what "promoting" means.\ **Note**: only verified subscribers can be promoted. Trying to promote a non-verified subscriber will return a `subscriber_not_found` error. #### Path Parameters | Name | Type | Description | | -------------- | ------ | ------------------------ | | api\_token | string | Your API Token | | uuid | string | Your list UUID | | subscriber\_id | string | The ID of the subscriber | {% tabs %} {% tab title="200 " %} ```yaml { "status": "ok", "data": { "response": "subscriber_promoted", < Subscriber object > }, "calls_left": 1000, "timestamp": 1487661494 } ``` {% endtab %} {% endtabs %} ### Trigger manual rewards `POST` `https://app.referralhero.com/api/v2/lists/:uuid/subscribers/:subscriber_id/unlock_promoted_reward` Used to trigger the Rewards for Promoted Winners #### Path Parameters | Name | Type | Description | | -------------- | ------ | ------------------------------ | | api\_token | String | Your API Token | | uuid | String | Your list UUID | | subscriber\_id | String | The ID of the subscriber | | reward\_id | String | The ID of the promotion reward | {% tabs %} {% tab title="200: OK " %} ```json { "response": "reward_unlocked", "reward": { "id": 203, "title": "Winner 2", "header": null, "description": "", "referrals": null, "image": "/missing.png", "label": "Winner Reward", "points": null, "category": "promoted_winners" } } ``` {% endtab %} {% endtabs %} ### Retrieve all subscribers from a list `GET` `https://app.referralhero.com/api/v2/lists/:uuid/subscribers` Get all the subscribers in a list. Results are paginated (max 50 results per page). #### Path Parameters | Name | Type | Description | | -------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | api\_token | string | Your API Token | | uuid | string | Your list UUID | | sort\_by | string | Sort subscribers by one attribute. Possible options are: `registration_desc`, `registration_asc`, `email_asc`, `email_desc`, `name_asc`, `name_desc`, `position_asc`, `position_desc` , `people_referred_asc`, `people_referred_desc`, `points_asc`, `points_desc` | | page | string | Page you want to jump to. By default 1. | | extra\_field | string | The extra field of the subscriber | | extra\_field\_2 | string | The extra field 2 of the subscriber | | option\_field | string | The option field of the subscriber | | stripe\_customer\_id | string | Stripe Customer ID | {% tabs %} {% tab title="200 " %} ```yaml { "status": "ok", "data": { "response": "subscribers_retrieved", "subscribers": [ { < Subscriber object > }, { < Subscriber object > }, ... ], "pagination": { "total_pages": 1, "current_page": 1, "per_page": 50, "total_objects": 14 } }, "calls_left": 1000, "timestamp": 1487675505 } ``` {% endtab %} {% endtabs %} ### Retrieve subscriber by ID `GET` `https://app.referralhero.com/api/v2/lists/:uuid/subscribers/:subscriber_id` Retrieve a single subscriber.\ **Note**: only verified subscribers can be retrieved. Trying to retrieve a non-verified subscriber will return a `subscriber_not_found` error. #### Path Parameters | Name | Type | Description | | -------------- | ------ | ------------------------ | | api\_token | string | Your API Token | | uuid | string | The list UUID | | subscriber\_id | string | The ID of the subscriber | {% tabs %} {% tab title="200 " %} ```yaml { "status": "ok", "data": { "response": "subscriber_retrieved", < Subscriber object > }, "calls_left": 1000, "timestamp": 1487676070 } ``` {% endtab %} {% endtabs %} ### Retrieve subscriber by email `GET` `https://app.referralhero.com/api/v2/lists/:uuid/subscribers/retrieve_by_email` Retrieve a single subscriber.\ **Note**: only verified subscribers can be retrieved. Trying to retrieve a non-verified subscriber will return a `subscriber_not_found` error. #### Path Parameters | Name | Type | Description | | ---------- | ------ | ---------------------------- | | api\_token | string | Your API Token | | uuid | string | The list UUID | | email | string | The email of the subscriber. | {% tabs %} {% tab title="200 " %} ```yaml { "status": "ok", "data": { "response": "subscriber_retrieved", < Subscriber object > }, "calls_left": 1000, "timestamp": 1487676070 } ``` {% endtab %} {% endtabs %} ### Retrieve subscriber by MWR `GET` `https://app.referralhero.com/api/v2/lists/:uuid/subscribers/retrieve_by_mwr` Retrieve a single subscriber.\ **Note**: only verified subscribers can be retrieved. Trying to retrieve a non-verified subscriber will return a `subscriber_not_found` error. #### Path Parameters | Name | Type | Description | | ---------- | ------ | ---------------------------- | | api\_token | string | Your API Token | | uuid | string | The list UUID | | mwr | string | The referrer's referral code | {% tabs %} {% tab title="200" %} ```json { "status": "ok", "data": { "response": "subscriber_retrieved", < Subscriber object > }, "calls_left": null, "timestamp": 1725032082 } ``` {% endtab %} {% endtabs %} ### Retrieve all referrals (pending, unconfirmed, confirmed) of a subscriber `GET` `https://app.referralhero.com/api/v2/lists/:uuid/subscribers/:subscriber_id/referred` Retrieve all referrals (pending, unconfirmed, confirmed) of a single subscriber. Results are paginated (max 50 results per page). #### Path Parameters
NameTypeDescription
api_tokenstringYour API Token
uuidstringYour list UUID
subscriber_idstringThe ID of the subscriber.
pagestringPage you want to jump to. By default is 1.
sort_bystringSort subscribers by one attribute. Possible options are: registration_desc, registration_asc, email_asc, email_desc, name_asc, name_desc, position_asc, position_desc, people_referred_asc, people_referred_desc, points_asc, points_desc
{% tabs %} {% tab title="200 " %} ```json { "status": "ok", "data": { "response": "subscribers_retrieved", "subscribers": [ { < Subscriber object > }, { < Subscriber object > }, ... ], "pagination": { "total_pages": 1, "current_page": 1, "per_page": 50, "total_objects": 14 } }, "calls_left": 1000, "timestamp": 1487675505 } ``` {% endtab %} {% endtabs %} ### Retrieve all Level 2 referrals (pending, unconfirmed, confirmed) of a subscriber `GET`[`https://app.referralhero.com/api/v2/lists/:uuid/subscribers/:subscriber_id/level_2_all_referrals`](https://app.referralhero.com/api/v2/lists/:uuid/subscribers/:subscriber_id/level_2_all_referrals) Retrieve all Level 2 referrals (pending, unconfirmed, confirmed) of a single subscriber. Results are paginated (max 50 results per page). #### Path Parameters | Name | Type | Description | | -------------- | ------ | ------------------------- | | api\_token | string | Your API Token | | uuid | string | Your list UUID | | subscriber\_id | string | The ID of the subscriber. | {% tabs %} {% tab title="200" %} ```json { "status": "ok", "data": { "response": "subscribers_retrieved", "subscribers": [ { < Subscriber object > , "pending_referrals": 0, "unconfirmed_referrals": 0, "people_referred": 0, "level_2_confirmed_referrals": 0, "level_3_confirmed_referrals": 0, "promoted": false, "promoted_at": null, "verified": true, "verified_at": 1723452705, "points": 0, "risk_level": 0, "host": "https://www.mywebiste.com/refer", "source": null, "device": null, "referral_link": "https://www.mywebiste.com/refer?mwr=eb134345", "created_at": 1723452705, "last_updated_at": 1723452705, "referral_status": "confirmed", "referral_status_at": 1723452705, "universal_link": "https://app.referralhero.com//MFxxxxxxxxx/universal_link?mwr=eb134b6d" } ], "pagination": { "total_pages": 1, "current_page": 1, "per_page": 50, "total_objects": 1 } }, "calls_left": null, "timestamp": 1723457099 } ``` {% endtab %} {% endtabs %} ### Retrieve all Level 3 referrals (pending, unconfirmed, confirmed) of a subscriber `GET` [`https://app.referralhero.com/api/v2/lists/:uuid/subscribers/:subscriber_id/level_3_all_referrals`](https://app.referralhero.com/api/v2/lists/:uuid/subscribers/:subscriber_id/level_3_all_referrals) **Path Parameters** | Name | Type | Description | | -------------- | ------ | ------------------------- | | api\_token | string | Your API Token | | uuid | string | Your list UUID | | subscriber\_id | string | The ID of the subscriber. | {% tabs %} {% tab title="200" %} ```json { "status": "ok", "data": { "response": "subscribers_retrieved", "subscribers": [ { < Subscriber object > , "pending_referrals": 0, "unconfirmed_referrals": 0, "people_referred": 0, "level_2_confirmed_referrals": 0, "level_3_confirmed_referrals": 0, "promoted": false, "promoted_at": null, "verified": true, "verified_at": 1723452705, "points": 0, "risk_level": 0, "host": "https://www.mywebiste.com/refer", "source": null, "device": null, "referral_link": "https://www.mywebiste.com/refer?mwr=eb134ss4", "created_at": 1723452705, "last_updated_at": 1723452705, "referral_status": "confirmed", "referral_status_at": 1723452705, "universal_link": "https://app.referralhero.com//MFxxxxxxxxxx/universal_link?mwr=eb134b6d" } ], "pagination": { "total_pages": 1, "current_page": 1, "per_page": 50, "total_objects": 1 } }, "calls_left": null, "timestamp": 1723457099 } ``` {% endtab %} {% endtabs %} ### Retrieve all level 1 confirmed referrals of a subscriber `GET`\ `https://app.referralhero.com/api/v2/lists/:uuid/subscribers/:subscriber_id/level_1_referrals` Retrieve all level 1 confirmed referrals of a single subscriber. Results are paginated (max 50 results per page). #### Path Parameters
NameTypeDescription
api_tokenstringYour API Token
uuidstringYour list UUID
subscriber_idstringThe ID of the subscriber.
pagestringPage you want to jump to. By default is 1.
sort_bystringSort subscribers by one attribute. Possible options are: registration_desc, registration_asc, email_asc, email_desc, name_asc, name_desc, position_asc, position_desc, people_referred_asc, people_referred_desc, points_asc, points_desc
{% tabs %} {% tab title="200 " %} ```yaml { "status": "ok", "data": { "response": "subscribers_retrieved", "subscribers": [ { < Subscriber object > }, { < Subscriber object > }, ... ], "pagination": { "total_pages": 1, "current_page": 1, "per_page": 50, "total_objects": 14 } }, "calls_left": 1000, "timestamp": 1487675505 } ``` {% endtab %} {% endtabs %} ### Retrieve all level 2 confirmed referrals of a subscriber `GET`\ `https://app.referralhero.com/api/v2/lists/:uuid/subscribers/:subscriber_id/level_2_referrals` Retrieve all level 2 confirmed referrals of a single subscriber. Results are paginated (max 50 results per page). #### Path Parameters
NameTypeDescription
api_tokenstringYour API Token
uuidstringYour list UUID
subscriber_idstringThe ID of the subscriber.
pagestringPage you want to jump to. By default is 1.
sort_bystringSort subscribers by one attribute. Possible options are: registration_desc, registration_asc, email_asc, email_desc, name_asc, name_desc, position_asc, position_desc, people_referred_asc, people_referred_desc, points_asc, points_desc
{% tabs %} {% tab title="200 " %} ```json { "status": "ok", "data": { "response": "subscribers_retrieved", "subscribers": [ { < Subscriber object > }, { < Subscriber object > }, ... ], "pagination": { "total_pages": 1, "current_page": 1, "per_page": 50, "total_objects": 14 } }, "calls_left": 1000, "timestamp": 1487675505 } ``` {% endtab %} {% endtabs %} ### Retrieve all level 3 confirmed referrals of a subscriber `GET`\ `https://app.referralhero.com/api/v2/lists/:uuid/subscribers/:subscriber_id/level_3_referrals` Retrieve all level 3 confirmed referrals of a single subscriber. Results are paginated (max 50 results per page). #### Path Parameters
NameTypeDescription
api_tokenstringYour API Token
uuidstringYour list UUID
subscriber_idstringThe ID of the subscriber.
pagestringPage you want to jump to. By default is 1.
sort_bystringSort subscribers by one attribute. Possible options are: registration_desc, registration_asc, email_asc, email_desc, name_asc, name_desc, position_asc, position_desc, people_referred_asc, people_referred_desc, points_asc, points_desc
{% tabs %} {% tab title="200 " %} ```json { "status": "ok", "data": { "response": "subscribers_retrieved", "subscribers": [ { < Subscriber object > }, { < Subscriber object > }, ... ], "pagination": { "total_pages": 1, "current_page": 1, "per_page": 50, "total_objects": 14 } }, "calls_left": 1000, "timestamp": 1487675505 } ``` {% endtab %} {% endtabs %} ### Retrieve all rewards for all subscribers `GET` `https://app.referralhero.com/api/v2/lists/:uuid/rewards` Retrieve a list of all rewards across all subscribers in a specified campaign. Results are paginated (maximum 50 results per page). #### Path Parameters | Name | Type | Description | | ----------------- | ------ | ---------------------------------------------------------------------- | | api\_token | String | Your API Token | | uuid | String | Your list UUID | | status (optional) | String | Status of the reward (i.e. sent, resent, canceled, pending or flagged) | | page | String | Page you want to jump to. By default is 1. | | per\_page | String | Number of results you want per page. By default is 10. | {% tabs %} {% tab title="200: OK " %} ````json { "status": "ok", "data": { "response": "rewards_retrieved", "rewards": [ { "id": 214, "name": "10% commission", "status": "sent", "referrals": 1, "created_at": 1729166882, "unlocked_date": 1752823036, "sent_date": 1752823044, "referral": "nishchay@referralhero.com", "value": 100.0, "total": "", "signup_type": null, "referrals_type": "confirmed", "recurring_count": null, "coupon_code": null, "coupon_group": null, "image_url": null, "subscriber_email": "johndoe@gmail.com", "subscriber_id": "sub_64f9c36e25de" ``` }, ], "pagination": { "total_pages": 1, "current_page": 1, "per_page": 10, "total_objects": 1 } }, "calls_left": null, "timestamp": 1729186260 } ```` {% endtab %} {% endtabs %} ### Retrieve all rewards unlocked by a subscriber `GET` `https://app.referralhero.com/api/v2/lists/:uuid/subscribers/:subscriber_id/rewards` Get all rewards unlocked by the subscriber. Results are paginated (max 50 results per page). #### Path Parameters | Name | Type | Description | | ----------------- | ------ | ---------------------------------------------------------------------- | | api\_token | String | Your API Token | | uuid | String | Your list UUID | | subscriber\_id | String | The ID of the subscriber | | status (optional) | String | Status of the reward (i.e. sent, resent, canceled, pending or flagged) | {% tabs %} {% tab title="200: OK " %} ```json { "status": "ok", "data": { "response": "rewards_retrieved", "rewards": [ { "id": 214, "name": "10% commission", "status": "sent", "referrals": 1, "created_at": 1752217473, "unlocked_date": 1752823036, "sent_date": 1752823044, "referral": "nishchay@referralhero.com", "value": 100.0, "total": "", "signup_type": null, "referrals_type": "confirmed", "recurring_count": null, "coupon_code": null, "coupon_group": null, "image_url": null }, ], "pagination": { "total_pages": 1, "current_page": 1, "per_page": 10, "total_objects": 1 } }, "calls_left": null, "timestamp": 1729186260 } ``` {% endtab %} {% endtabs %} ### Delete a subscriber `DELETE` `https://app.referralhero.com/api/v2/lists/:uuid/subscribers/:subscriber_id` Delete a single subscriber. #### Path Parameters | Name | Type | Description | | -------------- | ------ | ------------------------ | | api\_token | string | Your API Token | | uuid | string | The list UUID | | subscriber\_id | string | The ID of the subscriber | {% tabs %} {% tab title="200 " %} ```yaml { "status": "ok", "data": { "response": "subscriber_deleted", < Subscriber object > }, "calls_left": 1000, "timestamp": 1487661494 } ``` {% endtab %} {% endtabs %} ### Update reward status by reward\_id `POST` `https://app.referralhero.com/api/v2/lists/:uuid/subscribers/update_reward_status` Update status of an unlocked reward of a subscriber by reward\_id #### Path Parameters | Name | Type | Description | | ---------- | ------ | --------------------------------------------------------------------- | | api\_token | String | Your API Token | | uuid | String | Your list UUID | | reward\_id | String | ID of reward provided in GET all rewards unlocked by a subscriber API | | status | String | sent/resent/canceled | {% tabs %} {% tab title="200: OK " %} ```json { "status": "ok", "data": { "id": 794765, "name": "referral signup", "status": "confirmed", "referrals": null, "created_at": 1752217473, "unlocked_date": 1752823036, "sent_date": 1752823044, "referral": "", "value": null, "total": "", "signup_type": "referral", "referrals_type": null, "recurring_count": null, "coupon_code": "cdwtmnKz8P", "coupon_group": "10-off-new-355bed2b-d645-4b2f-88ed-40a813940243", "image_url": null }, "calls_left": null, "timestamp": 1753514108 } ``` {% endtab %} {% endtabs %} ### Create coupon group `POST` `https://app.referralhero.com/api/v2/lists/:uuid/coupon_groups` Add new coupon group #### Path Parameters | Name | Type | Description | | ---------- | ------ | --------------------------------------- | | api\_token | String | Your API Token | | uuid | String | Your list UUID | | name | String | Coupon group name | | coupons | String | Array, e.g. \["ab23fg, fghg45, gh78wl"] | | active | String | True or false | {% tabs %} {% tab title="200: OK " %} ```json { "status": "ok", "data": { "id": "rh400", "name": "RH400", "active": true, "created_at": 1686563261, "coupons": [], "response": "coupon_group_created" }, "calls_left": null, "timestamp": 1686563261 } ``` {% endtab %} {% endtabs %} ### Create coupons `POST` `https://app.referralhero.com/api/v2/lists/:uuid/coupons` Add coupon(s) to a coupon group #### Path Parameters | Name | Type | Description | | ----------------- | ------ | ------------------------------------------ | | api\_token | String | Your API Token | | uuid | String | Your list UUID | | coupon\_group\_id | String | ID of coupon group | | coupons | String | Array, e.g. \["ab23fg", fghg45”, “gh78wl"] | {% tabs %} {% tab title="200: OK " %} ```json { "status": "ok", "data": { "id": "rh200", "name": "RH200", "active": true, "created_at": 1686563246, "coupons": [ { "code": "FCMPFI", "available": true, "sent_at": null, "email_id": null, "created_at": 1686563246 }, { "code": "U3EHFD", "available": true, "sent_at": null, "email_id": null, "created_at": 1686563246 }, { "code": "tvt4g45v", "available": true, "sent_at": null, "email_id": null, "created_at": 1686563246 }, { "code": "RFGH677", "available": true, "sent_at": null, "email_id": null, "created_at": 1686563246 }, { "code": "KMLFG767", "available": true, "sent_at": null, "email_id": null, "created_at": 1686563246 } ] }, "calls_left": null, "timestamp": 1686676359 } ``` {% endtab %} {% endtabs %} ### Retrieve all coupon groups `GET` `https://app.referralhero.com/api/v2/lists/:uuid/coupon_groups` Get all coupon groups of a campaign #### Path Parameters | Name | Type | Description | | ---------- | ------ | -------------- | | api\_token | String | Your API Token | | uuid | String | Your list UUID | {% tabs %} {% tab title="200: OK " %} ```json { "status": "ok", "data": { "response": "coupon_groups_retrieved", "coupon_groups": [ { "id": "rh200", "name": "RH200", "active": true, "created_at": 1686563246, "coupons": [ { "code": "FCMPFI", "available": true, "sent_at": null, "email_id": null, "created_at": 1686563246 }, { "code": "U3EHFD", "available": true, "sent_at": null, "email_id": null, "created_at": 1686563246 } ] }, { "id": "rh400", "name": "RH400", "active": true, "created_at": 1686563261, "coupons": [] } ], "pagination": { "total_pages": 1, "current_page": 1, "per_page": 50, "total_objects": 2 } }, "calls_left": null, "timestamp": 1686563777 } ``` {% endtab %} {% endtabs %} ### Retrieve coupons `GET` `https://app.referralhero.com/api/v2/lists/:uuid/coupon_groups/:id` Get all coupons within a coupon group #### Path Parameters | Name | Type | Description | | ---------- | ------ | ------------------ | | api\_token | String | Your API Token | | uuid | String | Your list UUID | | id | String | ID of coupon group | {% tabs %} {% tab title="200: OK " %} ```json { "status": "ok", "data": { "id": "rh200", "name": "RH200", "active": true, "created_at": 1686563246, "coupons": [] }, "calls_left": null, "timestamp": 1686563407 } ``` {% endtab %} {% endtabs %} --- [Next Page](/llms-full.txt/1)