Partner Link JavaScript API

General Setup

Article for general setup guidance can be found here.

init(): Promise<void>

Description
Initializes the Partner Link script. It captures the Partner Link ID (plid) from the URL and records a click event (only if it's the first time).

⚠️ You typically don't need to call this manually. It's already called in the install snippet.

getPlid(): string | null

Description
Retrieves the current Partner Link ID from the URL or from local storage, if already stored.

⚠️ You typically don't need to call this manually. It's used internally by recordSignUpEvent and recordClickEvent when communicating with the API.

Returns The Partner Link ID as a string, or null if not found.

Use case Useful for debugging if you want to retrieve the current Partner Link ID that will be sent to the API.

recordSignUpEvent(signUpData: { label: string | null; value: string | null }[]): Promise<number>

Description
Records a sign-up event using an array of sign-up form data.

Parameters

• signUpData — an array of form fields with label and value keys

❓ What do I need to send?
😁 Pretty much anything! (Within reason, of course.)

🤖 Our AI automatically analyzes the fields you provide and maps them to the correct lead fields in your Partner.io account.

At a minimum, make sure to include:

• email

• name

We also recommend including:

• company

You don't need to use those exact field names — we'll figure it out.
You can even send values for your custom lead fields, and we'll match those too.

Returns
A Promise that resolves to the API status code.

Use case Use this method to manually track sign-ups when the form is submitted. This is useful if you want to handle form submissions yourself e.g. if you're using AJAX-style submissions or if you're not using GTM.

recordClickEvent(): Promise<number>

Description
Records a click event.

⚠️ You typically don't need to call this manually. It's called automatically when the script is initialized via init().

Returns
A Promise that resolves to the API status code.

Use case Use this method if you want to manually track clicks on a specific element (e.g., a button) instead of relying on the automatic click tracking.

getSignUpDataFromForm(formId: string): { label: string | null; value: string | null }[]

Description
Parses a form by ID and returns an array of its input values in the expected sign-up format.

Parameters

• formId — the DOM id of the form element

Returns
An array of { label, value } objects extracted from the form inputs.

Use case Use this method to extract form data before calling recordSignUpEvent. This is useful if you want to manually handle form submissions and send the data to the Partner API.

getSignUpDataFromFormElement(formElement: HTMLFormElement): { label: string | null; value: string | null }[]

Description
Parses a form element and returns an array of its input values in the expected sign-up format.

Parameters

• formElement — the HTML form element

Returns
An array of { label, value } objects extracted from the form inputs.

Use case Use this method to extract form data from a form element before calling recordSignUpEvent. This is useful if you want to manually handle form submissions and send the data to the Partner API.

resetClickState(): void

Description
Resets the click tracking state by removing the stored Partner Link ID.

Use case
Helpful for development or testing when simulating a new visitor.

enableDebugMode(): void

Description
Enables debug mode for the Partner Link script. This will log additional information to the console, which can be helpful for troubleshooting.

Use case
Use this method if you want to see detailed logs of the script's actions in the console.

disableDebugMode(): void

Description Disables debug mode for the Partner Link script. This will stop logging additional information to the console.

Use case Use this method if you want to turn off debug logging after enabling it.

Extracting Form Data

When tracking custom or AJAX forms, you'll need to extract the form data before sending it to Partner.io. We provide two methods for this:

Method 1: By Form ID

Use this when you know the form's ID:

const signUpData = window.partnerLinkLibrary.getSignUpDataFromForm('test-form');

Method 2: By Form Element

Use this when you already have a reference to the form DOM element:

const formElement = document.getElementById('your-form-id');
const signUpData = window.partnerLinkLibrary.getSignUpDataFromFormElement(formElement);

What Data Gets Extracted?

Both methods extract all input fields from the form and return them in this format:

[
  { label: 'email', value: '[email protected]' },
  { label: 'name', value: 'John Doe' },
  { label: 'company', value: 'Acme Inc' }
]

The label is taken from the input's name attribute, and the value is the current input value.

Examples

Example 1: Basic Manual Tracking

This is the simplest approach when you already have the form data in the correct format:

type SignUpData = {
    label: string | null;
    value: string | null;
}[];

const onSubmit = async (values: SignUpData) => {
    await window.partnerLinkLibrary?.recordSignUpEvent(values);
    // Continue with your form submission logic
};

Example 2: Complete AJAX Form Tracking

This is a complete example for tracking forms that use AJAX submission.

<script>
  document.addEventListener('DOMContentLoaded', function () {
    // Replace 'test-form' with your form's ID
    const form = document.getElementById('test-form');
    
    if (!form) return;

    form.addEventListener('submit', function () {
      if (!window.partnerLinkLibrary) return;
      
      const plid = window.partnerLinkLibrary.getPlid();
      if (!plid) return;
      
      const signUpData = window.partnerLinkLibrary.getSignUpDataFromFormElement(form);
      if (signUpData && signUpData.length > 0) {
        window.partnerLinkLibrary.recordSignUpEvent(signUpData);
      }
    });
  });
</script>

How to customize:

1. Replace form#test-form with your actual form selector

2. To find your form's selector, right-click the form and select "Inspect"

3. Look for the <form> tag's id or class attribute

4. Use form#id-name for IDs or form.class-name for classes

Common selectors:

• By ID: form#contact-form

• By class: form.signup-form

• By attribute: form[name="lead-form"]

Where to add this code:

Add this script to your website after the Partner Link library has loaded. Place it before the closing </body> tag, ensuring it comes after either:

• GTM: Your GTM container code

• Custom Install: Your Partner Link <script> tags

This ensures window.partnerLinkLibrary is available when the form tracking code runs.

💡 Platform-specific note: This pattern works for any AJAX-based form system including Webflow, Squarespace, custom JavaScript forms, and most modern form builders. Simply adjust the form selector to match your form's ID or class.

⚠️ Important: If you're using both GTM form submission triggers and this custom code, only one method should call recordSignUpEvent to avoid duplicate lead creation. Either use GTM's form submission trigger OR custom code, not both.

Tracking Embedded Forms

Sometimes the form you want to track is not controlled directly by you. For example, it might be an embedded form from a third-party service like HubSpot, Salesforce, or Zendesk. This presents challenges as the actual form element is often in an iframe and the default form submission behaviour is overridden. This makes submission events invisible to GTM and, as you're not handling the submission in your own code, you can't use the Partner Link JavaScript API to send the data to the Partner API.

Luckily, third party forms sometimes provide a way to hook into the submission lifecycle. If you can get a handle to the form data at submission time outside of the iframe (i.e. the same context the script is running in), you can still track the submission!

Here's an example of how to track HubSpot forms:

    <script
        charset="utf-8"
        type="text/javascript"
        src="//js.hsforms.net/forms/embed/v2.js"
    />
    <script>
        hbspt.forms.create({
            portalId: "<YOUR_PORTAL_ID>",
            formId: "<YOUR_FORM_ID>",
            onFormSubmit: function($form) {
                const data = window.partnerLinkLibrary.getSignUpDataFromFormElement($form);
                window.partnerLinkLibrary.recordSignUpEvent(data);
            }
        });
    </script>