HubSpot Forms: Setting a Hidden Partner Link ID Field

This guide explains how to automatically set a hidden pio_plid field on a HubSpot embedded form using the Partner Link JavaScript API and the HubSpot Global Form Events API.

This guide assumes you have already installed the Partner Link script on your page. If you haven't, refer to the Partner Link installation guide first.

Prerequisites

• The Partner Link script is installed and initialized on your page

• A HubSpot custom property with the internal name pio_plid on a Lead or Deal object

• A HubSpot form with a hidden field mapped to the pio_plid property

• Your HubSpot Portal ID and Form ID

How It Works

When a HubSpot embedded form finishes rendering, it fires a global hs-form-event:on-ready event on the window object. You can listen for this event, retrieve the Partner Link ID (plid), and use HubSpot's setFieldValue API to populate the hidden field before the user submits.

Important: You must register the hs-form-event:on-ready listener before the HubSpot form embed script executes. If the form script loads first, the event will fire before your listener is attached and you'll miss it.

Step 1: Create the HubSpot Property

Before adding the hidden field to your form, you need a custom property in HubSpot to store the Partner Link ID.

1. In HubSpot, go to Settings > Properties

2. Select the Lead or Deal object (depending on your use case)

3. Click Create property

4. Set the following:

• Label: Partner Link ID (or similar)

• Internal name: pio_plid

• Field type: Single-line text

1. Save the property

Step 2: Add the Hidden Field to Your Form

1. Open your form in the HubSpot form editor

2. Add a Hidden field to the form

3. Map it to the pio_plid property you created in Step 1

4. Save the form

Once added, the hidden field will have a name attribute that includes the object type prefix and property name. The exact prefix depends on which object the property belongs to. You can find the full field name by inspecting the rendered form in your browser's dev tools:

<input type="hidden" name="0-1/pio_plid" value="" />

The prefix (0-1, 0-3, etc.) is assigned by HubSpot based on the object type. Use the full name value (including the prefix) when calling setFieldValue in the next step.

Step 3: Register the Event Listener

Add the following script to your page before the HubSpot form embed code. Replace YOUR_FORM_ID with your actual HubSpot form ID.

<script>
  window.addEventListener("hs-form-event:on-ready", function (event) {
    // Replace with your HubSpot form ID
    var FORM_ID = "YOUR_FORM_ID";

    // Only handle the target form (important if you have multiple forms on the page)
    if (event.detail.formId !== FORM_ID) return;

    // Retrieve the Partner Link ID
    var plid = window.partnerLinkLibrary
      ? window.partnerLinkLibrary.getPlid()
      : null;

    if (!plid) {
      console.log("[Partner.io] No plid found — visitor did not arrive via a partner link");
      return;
    }

    // Get the HubSpot form instance from the event
    var form = window.HubSpotFormsV4
      ? window.HubSpotFormsV4.getFormFromEvent(event)
      : null;

    if (!form) {
      console.log("[Partner.io] Could not get HubSpot form instance");
      return;
    }

    // Set the hidden field value
    form.setFieldValue("0-1/pio_plid", plid);
    console.log("[Partner.io] Set pio_plid to:", plid);
  });
</script>

What each API does

Step 4: Add the HubSpot Form Embed

Place the HubSpot form embed code after the event listener script from Step 3.

<script
  src="https://js-eu1.hsforms.net/forms/embed/YOUR_PORTAL_ID.js"
  defer
></script>
<div
  class="hs-form-frame"
  data-region="eu1"
  data-form-id="YOUR_FORM_ID"
  data-portal-id="YOUR_PORTAL_ID"
></div>

Note: The data-region and script URL domain depend on your HubSpot account region. Use eu1 / js-eu1.hsforms.net for EU accounts or na1 / js.hsforms.net for North American accounts.

Full Example

Here is a complete example showing the correct script ordering. The Partner Link script is assumed to be already loaded and initialized on the page (e.g. via your site-wide script installation or GTM).

<!-- 1. Register the form ready listener BEFORE the form embed -->
<script>
  window.addEventListener("hs-form-event:on-ready", function (event) {
    var FORM_ID = "6b4d7a54-38c2-442a-a4dd-55df9edb6dc0";

    if (event.detail.formId !== FORM_ID) return;

    var plid = window.partnerLinkLibrary
      ? window.partnerLinkLibrary.getPlid()
      : null;

    if (!plid) return;

    var form = window.HubSpotFormsV4
      ? window.HubSpotFormsV4.getFormFromEvent(event)
      : null;

    if (!form) return;

    form.setFieldValue("0-1/pio_plid", plid);
    console.log("[Partner.io] Set pio_plid to:", plid);
  });
</script>

<!-- 2. Load and render the HubSpot form -->
<script
  src="https://js-eu1.hsforms.net/forms/embed/145629153.js"
  defer
></script>
<div
  class="hs-form-frame"
  data-region="eu1"
  data-form-id="6b4d7a54-38c2-442a-a4dd-55df9edb6dc0"
  data-portal-id="145629153"
></div>

Finding Your Field Name

If your hidden field has a different property name, you can find the correct setFieldValue field name by:

1. Loading your page with the HubSpot form

2. Opening browser dev tools (F12)

3. Inspecting the hidden input element

4. The name attribute is the value you pass to setFieldValue

For example, if the input is:

<input type="hidden" name="0-1/my_custom_field" value="" />

Then use:

form.setFieldValue("0-1/my_custom_field", value);

Verifying the Integration

1. Visit your page with a plid parameter in the URL, e.g. https://yoursite.com/signup?plid=test-partner-123

2. Open your browser's developer console

3. You should see: [Partner.io] Set pio_plid to: test-partner-123

4. Submit the form and check the contact record in HubSpot — the pio_plid property should be populated

If you see No plid found, the visitor hasn't arrived via a partner link. This is expected for organic visitors.

Troubleshooting