This guide outlines how you can create a referral program if you manage your customers through HubSpot CRM.
Here, we only cover
How to enroll existing customers in the referral program and assign them a referral link
How to automatically participate new users to the referral program
How to measure successful referrals only when a specific action (conversion) is performed.
This guide does not cover:
How to set up how your users interact with the referral program (Referral Widgets)- For this step please consult the Installation guidelines inside your template.
After this guide you’ll be able to send every user their referral link through a HubSpot email — showing their referral link and progress in a custom dedicated page inside your product requires a different guide depending on where that page is built.
This guide is relevant to you if you want to create a flow like this:
0. Prerequisites
You have a HubSpot account
You have created a Viral Loops Mileston or Altruistic referral campaign.
1. Enrolling existing customers in the referral program
This step concerns how your existing users get their referral code. As decided in the beginning of the campaign:
You want all existing users to get a referral code. Instead of asking them to opt in using the joining state widget.
Edit your Viral Loops Campaign and go to the Integrations step to select the HubSpot integration.
Inside the HubSpot Integration page click “Connect” and follow the instructions.
When you’ve completed the connection return to the Viral Loops Edit page to see this success message.
No participants have been added to the referral program yet! Please continue reading.
We have only established a safe connection between the two tools and created the proprietary User Properties inside HubSpot. Every user now will have this additional property group attached to them (empty for now).
To add your existing participants to the referral program and assign them a referral code, we need to import them to Viral Loops.
Ensure all your customers are in a static list—if not, please create a static list with all your existing customers.
Go to the Viral Loops dashboard of your referral campaign, navigate to the Participants section and click Import to select HubSpot as your import method.
Pick the static list with your current customers to enrol them in the referral program and give them a referral code.
This process might take several minutes. Once done, click OK and refresh the page to see your customers inside the Viral Loops dashboard.
Now, you can go to the same customers in your HubSpot account to see their referral program properties (referral link, number of referrals, etc.) added to their profiles. Should you have a large amount of contacts(>5000) please allow additional time for them to show up on the dashboard.
2. Participation of new leads and customers
When your campaign is live a lot of customers will come through customer referrals, but quite a few will also come on their own without a referral.
Since both types will be customers who might refer friends, you want them to automatically get a referral link, too — to become referral program participants.
Create a contact property for the referrer’s referral code.
First, we need a way to capture the referral code of their referrer, if they have one.
Go to Contacts > Actions > Edit Properties > Create Property.
Set the Object type to “Contact and the Group to the one created by Viral Loops in Step 1 above.
Set the label to “Referrer Code”. The Internal name must be “referrer_code”.
Add a hidden field in your lead capture form.
To use that property, we need to add it as a hidden field to the forms you use to capture potential customers.
Find that form and edit it. Then, add a hidden field for the “Referrer Code” (this will not be visible to customers).
Create the invitee page logic
When you set up your referral program inside Viral Loops, you set a URL. That URL determines where the referral link people share takes them when they click on it.
Find that page on HubSpot and open its editor.
The page should include the form you just created to capture potential customers.
Inside the page Editor, go to Settings > Advanced > Footer HTML and paste in this piece of code:
<script>
setTimeout(()=>{
const inputField = document.querySelector('input[name="referrer_code"]');
if (inputField) {
inputField.value = new URLSearchParams(window.location.search).get('referralCode');
console.log('Field found and set:', inputField.value);
} else {
console.log('Field not found. Current state of the DOM:', document.body.innerHTML);
}
}, 5000);
</script>
This code, checks if the visitor came through a referral link and if yes, it sets the referral code of their refer — so we can later reward the referrer if this lead converts to a customer.
To give every potential customer a referral link automatically and enroll them in the referral program, we need to create a HubSpot Workflow.
Go to Automations > Workflows > Create Workflow.
Pick a trigger that signifies a new potential customer has come through that form we just created or something similar. For this example, we’ll use a simple logic to trigger the workflow when someone submits the form we created.
Then, add a Custom Code action. (Do not worry; we’ll provide copy-paste-able code here so you don’t have to read or write any)
For Language, select Node.js from the dropdown.
Under Secrets, select “Add secret” and name it “vlCampaignId” and set the value to the campaign ID you can find at the installation step of your Viral Loops campaign.
Then, define the user properties we need to send to Viral Loops like in the image below.
Lastly, in the Code section, paste this:
<script>
const axios = require('axios');
exports.main = async (event, callback) => {
const { email, referrerCode } = event.inputFields;
const publicToken = process.env.vlCampaignId;
try {
const { data } = await axios.post('https://app.viral-loops.com/api/v3/campaign/participant', {
user: { email },
referrer: { referralCode: referrerCode }
publicToken: publicToken
}, {
headers: { 'accept': 'application/json', 'content-type': 'application/json' }
});
callback({ outputFields: { email, viralLoopsResponse: data } });
} catch (error) {
console.error('Error calling Viral Loops API:', error);
callback({ outputFields: { email, error: 'Failed to call Viral Loops API' } });
}
}
</script>
3. Conversion and closing the Viral Loop
Now it’s time to set up what makes a successful referral. In other words, what actions will close the referral loop.
For our example, we assume you only want to measure paying customers who came through referrals.
In other words, a customer will not get a reward unless the friends they invited also become a customer.
To do that, edit your Viral Loops campaign and click “I’ll do it myself” in the Installation step. There, scroll a little, and select
“A referral is complete when referred friends sign up and then make a conversion (API tracked).”
Next up, we need to create a HubSpot Workflow.
Go to Automations > Workflows > Create Workflow.
Pick a trigger that means that that contact has converted to a customer. This depends entirely on your business and goals — it can be a custom event when a salesperson marks a deal as closed or anything else.
For our example, we assume someone becomes a customer when a team member marks their Lead Status as “Connected”.
Also, to keep the data clean, ensure you add a second condition in the trigger to check if their Referrer Code is known — after all, we only care about informing Viral Loops of conversions that came through referrals.
Then, add a Custom Code action to inform Viral Loops that someone who came through a referral has converted.
For Language, select Node.js from the dropdown.
In Secrets, select the vlCampaignId you created in the previous step.
Under Property to include in code, create an “email” key with a value set to the contact’s email.
In the Code section, add copy and paste this in:
<script>
const axios = require('axios');
exports.main = async (event, callback) => {
const { email } = event.inputFields;
const viralLoopsToken = process.env.vlCampaignId;
const headers = { 'accept': 'application/json', 'content-type': 'application/json' };
try {
const response = await axios.post('https://app.viral-loops.com/api/v3/campaign/participant/convert', {
user: { email },
publicToken: viralLoopsToken
}, { headers });
callback({ outputFields: { email, conversionResponse: response.data } });
} catch (error) {
console.error('Error in Viral Loops conversion API call:', error);
callback({ outputFields: { email, error: 'Failed to make conversion API call' } });
}
};
</script>
Save the workflow, and you’re ready to go!