​
Overview

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:
  1. Create a customized form in HubSpot by following the instructions here.
  2. 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:

​
Step 2: Include the Cello Attribution Library

Add the Cello attribution script to your website’s <head> section or before the closing </body> tag: 
<script type="module" src="https://assets.cello.so/attribution/latest/cello-attribution.js" async></script>

​
Step 3: Add the Attribution Command Queue

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.

​
Step 3: Integrate with HubSpot Form Creation

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);
        });
    }
});

​
Test Your Implementation

​
1. Test Referral Code Capture

  1. Visit your page with a referral parameter: 
    https://yoursite.com/landing-page?ucc=test123&productId=yourproduct
  2. Open browser developer tools and check: 
    // Test if ucc is available
window.CelloAttribution('getUcc')
    Expected response: Promise {<fulfilled>: 'test123'}

​
2. Test Form Integration

  1. Open the page with the created form
  2. 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
  3. Enter some test data into the form. The result should look similar to the following
  4. Submit your HubSpot form
  5. 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
  6. The test was successful. You can now move ahead to the section on providing the required data to Cello.

​
Troubleshooting

​
Common Issues and Solutions

1. “getReferral is not supported” error
  • Make sure you’re using getUcc() instead of getReferral()
  • This is the correct method for the latest attribution library
2. Form fields not getting populated
  • Verify your form has a field with name="ucc"
  • Check that the field selector in querySelectorAll() matches your form
  • Ensure the onFormReady callback is executing
3. Referral code is undefined
  • Test with a URL containing the ucc parameter: ?ucc=test123
  • Check browser cookies for cello-referral
  • Verify the attribution script loaded properly
4. Script loading order issues
  • Always include the command queue script before any attribution calls
  • Use the async attribute on the attribution library script

​
HubSpot Scheduling Pages Integration

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.

​
How it works

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.

​
Setup Steps

The integration process for scheduling pages is identical to regular forms:
  1. Include the Cello Attribution Library (Steps 2-3 above remain the same)
  2. Set up the ucc property in your HubSpot contacts/companies
  3. Add a hidden ucc field to your scheduling page form
  4. Configure the scheduling page to populate the referral code

​
Adding ucc Field to Scheduling Pages

  1. Create or edit a scheduling page (HubSpot’s scheduling page guide)
  2. 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:

​
JavaScript Integration for Scheduling Pages

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 above
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
}

// 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>

​
Testing Your Scheduling Page Integration

  1. Visit your scheduling page with a referral parameter: 
    https://yoursite.com/book-demo?ucc=demo12345687
  2. Start the booking process and fill out the form
  3. Complete the booking
  4. Check the created contact in HubSpot - the ucc field should contain demo12345687

​
Key Differences from Regular Forms

  • 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.