This guide shows you how to capture referral codes (ucc) from visitors and automatically populate them into HubSpot forms when users submit lead generation or contact forms. This enables you to track which referrals lead to qualified leads and conversions.
Considerations when creating the ucc property in HubSpot
When creating a custom property in HubSpot, it is important that the internal name of the property is ucc. This sets up the property in either company or deal. The one to choose depends on your specific sales process and the corresponding HubSpot setup.These instructions describe creating the ucc property in the object type Company, group Company information. Often, it can make sense to create the ucc property in the Deal object type. A custom property can be created following the instructions of HubSpot here.
Step 1: Create a form with a hidden ucc field in HubSpot
To properly capture referral data, you need to add a ucc field to your HubSpot form:
Create a customized form in HubSpot by following the instructions here.
In your form, create a hidden field called ucc. This field automatically picks up the ucc from the link and feeds it into the create ucc property in HubSpot. The result should look like this:
Since HubSpot forms are loaded dynamically, include this script to handle race conditions between your code and the Cello library loading:
<script>window.CelloAttribution = window.CelloAttribution || function(t, ...o) { if ("getReferral" === t) throw new Error("getReferral is not supported in this context. Use getUcc instead."); let e, n; const i = new Promise((t, o) => { e = t, n = o }); return window.CelloAttributionCmd = window.CelloAttributionCmd || [], window.CelloAttributionCmd.push({ command: t, args: o, resolve: e, reject: n }), i}</script>
Important: This script must be added before any calls to window.CelloAttribution() to prevent race conditions.
When creating your HubSpot form, use the onFormReady callback to populate the referral code. Replace the placeholder values with your actual HubSpot configuration:
hbspt.forms.create({ region: "AAA", // Replace with your HubSpot region (e.g., "na1") portalId: "BBB", // Replace with your HubSpot Portal ID formId: "CCC", // Replace with your HubSpot Form ID onFormReady(form, ctx) { window.CelloAttribution('getUcc').then((celloUcc) => { console.log('Incoming Referral:', celloUcc); // Find all ucc fields and populate them document.querySelectorAll('input[name="ucc"]').forEach( el => { el.value = celloUcc; } ); }).catch((error) => { console.log('No referral code found or error occurred:', error); }); }});
Add ?ucc=demo12345687 to the link and reload the page. After the initialization of the config, this will be added automatically to the link by Cello
Enter some test data into the form. The result should look similar to the following
Submit your HubSpot form
HubSpot should now have created a new contact and a new company. In the new company, you should find the ucc property filled with the entered value demo12345687
The test was successful. You can now move ahead to the section on providing the required data to Cello.
You can also use the Cello attribution library with HubSpot scheduling pages to capture referral codes when prospects book meetings or demos. This is particularly useful for sales-led referral programs where referrals often lead to booked consultations or product demos.
HubSpot scheduling pages include built-in forms that collect contact information before allowing visitors to book meetings. You can integrate Cello attribution with these forms using the same approach as regular HubSpot forms.
In the “Form” section, add the created ucc parameter to the form. You can’t hide this field on a scheduling page. This field automatically picks up the ucc parameter from the link and feeds it into the created ucc property in HubSpot. The result should look like this:
Since scheduling pages are embedded HubSpot components, you’ll add the same integration code to the page where your scheduling page is embedded:
<!-- On the page containing your scheduling page --><script>// Same attribution command queue as abovewindow.CelloAttribution = window.CelloAttribution || function(t, ...o) { if ("getReferral" === t) throw new Error("getReferral is not supported in this context. Use getUcc instead."); let e, n; const i = new Promise((t, o) => { e = t, n = o }); return window.CelloAttributionCmd = window.CelloAttributionCmd || [], window.CelloAttributionCmd.push({ command: t, args: o, resolve: e, reject: n }), i}// Wait for scheduling page to load, then populate `ucc`document.addEventListener('DOMContentLoaded', function() { // Use MutationObserver to detect when scheduling form is loaded const observer = new MutationObserver(function(mutations) { mutations.forEach(function(mutation) { if (mutation.type === 'childList') { const uccField = document.querySelector('input[name="ucc"]'); if (uccField && !uccField.value) { window.CelloAttribution('getUcc').then((celloUcc) => { if (celloUcc) { uccField.value = celloUcc; console.log('ucc populated in scheduling form:', celloUcc); } }).catch((error) => { console.log('No referral code available:', error); }); } } }); }); // Start observing observer.observe(document.body, { childList: true, subtree: true });});</script>
Timing: Scheduling pages load asynchronously, so we use MutationObserver to detect when the form is ready
Form structure: Scheduling page forms are embedded HubSpot components with specific styling
Optional field: Make the ucc field optional since not all meeting bookings will come from referrals
Meeting context: The referral code will be associated with the contact and any resulting deals from the meeting
For sales-led businesses: Integrating referral tracking with scheduling pages is crucial for tracking which referrals lead to qualified sales conversations and ultimately closed deals.
Was this page helpful?
⌘I
Assistant
Responses are generated using AI and may contain mistakes.
