HubSpot

HubSpot is a leading CRM and marketing automation platform. Its forms can be embedded on your website in two ways, and AttributionHub handles both automatically:

1. Native forms — HubSpot forms rendered as standard HTML form elements (.hbspt-form) in the page DOM. These are handled by the standard forms handler, just like Gravity Forms or any other HTML form.
2. Iframe embeds — HubSpot forms loaded via <script> tags that render inside cross-origin iframes (hsforms.com / hubspot.com). These are handled by a dedicated handler that injects attribution data as URL parameters on the iframe source.

You do not need to know which mode your forms use. AttributionHub detects both automatically and populates them with the right approach.

Prerequisites

Before you begin, make sure:

• The AttributionHub tracking script is installed on your site (see Installation)
• You have a HubSpot account with access to create or edit forms
• You have access to create custom contact properties in HubSpot

Step 1: Create Custom Properties in HubSpot

HubSpot uses “properties” to store data on contacts. You need to create custom properties so that attribution values have somewhere to land when a form is submitted.

1. In HubSpot, go to Settings (gear icon in the top navigation)
2. Navigate to Data Management > Properties
3. Click Create property
4. For each attribution field you want to track:
   • Set the Object type to Contact
   • Set the Group to a new group like “Attribution Data” (or use an existing group)
   • Set the Label to something descriptive (e.g., “Attribution Channel - Latest”)
   • Set the Internal name to match the AttributionHub field name (e.g., ah_lt_channel)
   • Set the Field type to Single-line text
5. Click Create and repeat for each field

We recommend creating properties for at least the core fields listed in the Recommended Hidden Fields section below.

Step 2: Add Hidden Fields to Your Form

1. In HubSpot, go to Marketing > Forms
2. Open the form you want to add attribution tracking to, or create a new form
3. In the form editor, drag each of your new attribution properties into the form as fields
4. For each field you added:
   • Click on the field in the form editor
   • Toggle the Make this field hidden switch to on
   • Leave the Default value empty — AttributionHub will fill it in
5. Click Update (or Publish) to save your form

Step 3: Embed the Form on Your Page

Use whichever HubSpot embed method your site already uses. AttributionHub supports both:

Script embed (iframe mode):

<script
  charset="utf-8"
  type="text/javascript"
  src="//js.hsforms.net/forms/embed/v2.js"
></script>
<script>
  hbspt.forms.create({
    region: "na1",
    portalId: "YOUR_PORTAL_ID",
    formId: "YOUR_FORM_ID",
  });
</script>

HTML embed (native mode): If your CMS or page builder renders the HubSpot form directly as HTML, the standard forms handler will pick it up automatically.

No changes to your embed code are needed. AttributionHub detects HubSpot forms by looking for:

• iframe[src*="forms.hubspot.com"]
• .hs-form-iframe
• .hbspt-form

Step 4: Test the Integration

1. Visit a page on your site that contains the HubSpot form
2. Open your browser’s DevTools (F12)
3. For iframe embeds: inspect the iframe element and check that its src URL now includes attribution parameters (e.g., ?ah_lt_channel=Organic+Search&ah_lt_source=Google)
4. For native forms: inspect the hidden <input> elements inside the form and check that they have attribution values populated
5. Submit a test form entry
6. In HubSpot, go to CRM > Contacts and find the test submission. The attribution properties should contain values

For a full testing walkthrough, see Verify It Works.

How It Works

Native Forms (.hbspt-form)

When HubSpot renders a form as standard HTML elements in the page DOM, AttributionHub’s standard forms handler detects it like any other HTML form. It finds hidden fields whose name attributes match your field mapping and sets their values.

Iframe Embeds

When HubSpot renders a form inside a cross-origin iframe, AttributionHub cannot access the form fields directly. Instead, the dedicated HubSpot handler:

1. Detects HubSpot iframes on the page
2. Reads your attribution data from localStorage
3. Appends field values as URL search parameters on the iframe src
4. HubSpot reads these parameters and fills the corresponding hidden fields inside the iframe

This all happens automatically. You just need to make sure that HubSpot properties exist with the correct internal names.

Recommended Hidden Fields

The table below lists the most commonly used fields. For the complete field catalog, see Field Reference.

Core Attribution Fields (Latest Touch)

These fields capture details about the visitor’s most recent traffic source:

Core Attribution Fields (First Touch)

First-touch fields record the very first traffic source that brought the visitor to your site. These values are locked permanently once set:

Global Fields

For additional fields including latest-non-direct touch (ah_lnd_*), drill-down fields, raw UTM parameters, and ad click IDs, see the full Field Reference.

Custom Field Mapping

If your HubSpot properties use different internal names, you can map AttributionHub’s internal fields to your property names using fieldMapping:

<script>
  window.attrhub = {
    settings: {
      fieldMapping: {
        "latest.attribution.channelGroup": "attribution_channel",
        "latest.attribution.source": "attribution_source",
        "latest.attribution.campaign": "attribution_campaign",
      },
    },
  };
</script>

With this configuration, AttributionHub will populate properties named attribution_channel, attribution_source, and attribution_campaign. See Configuration for the full mapping reference.

Tips

• HubSpot workflows — Use the attribution properties in HubSpot workflows to route leads based on their traffic source. For example, send leads from Paid Search to your sales team and leads from Organic Search to a nurture sequence.
• HubSpot reports — Create custom reports using the attribution properties to see which channels generate the most leads and highest-quality contacts.
• Multiple forms on one page — AttributionHub detects and populates all HubSpot forms on the page, whether they are native or iframe embeds.
• HubSpot landing pages — If you use HubSpot’s built-in landing pages, add the AttributionHub script to the page’s custom HTML section. The form on the landing page will be populated automatically.
• Existing contacts — When an existing contact submits a form, HubSpot updates their properties. First-touch attribution values will remain as originally captured by AttributionHub; latest-touch values will be updated with the new submission data.

Troubleshooting

Properties are empty after form submission

1. Verify that the HubSpot property internal names exactly match the AttributionHub field names (or your custom field mapping). Internal names are case-sensitive.
2. Check that the properties are added as hidden fields in the form editor, not just created as properties.
3. For iframe embeds, inspect the iframe src in DevTools to confirm that attribution parameters are being appended.
4. Enable logging (enableLogging: true in settings) and check the browser Console for population messages.

Form loads slowly or attribution is missing

HubSpot’s script-based embed can take a moment to load. AttributionHub includes a retry mechanism (~500 ms) and a MutationObserver that watches for dynamically inserted elements, so most timing issues are handled automatically. If the form consistently loads after several seconds, check HubSpot’s script placement — loading it in the <head> can improve timing.

Iframe not detected

Make sure the iframe src contains forms.hubspot.com or hsforms.com. If HubSpot uses a custom domain for your portal, you can help AttributionHub detect it by adding data-attrhub-hubspot as an attribute on the iframe element.