Partner Referral Links

    Get started with partner referral links and converting sign ups into leads

    Table of Contents

    🔗 What Are Partner Referral Links?

    Partner referral links are a powerful tool that allows you to track and manage leads generated through your partner network. You can create multiple links in the app and name them to organize them into campaigns, hint to the partner where they should be shared, or describe where they go (e.g., Facebook - Pricing Page, Spring Campaign - Landing Page, etc.).

    Your partner reps share these links with their audience. When someone clicks on a link, it redirects them to your website. If the user signs up, a lead is created in your Partner.io account, and the partner rep who shared the link is credited with the lead.

    ⚙️ How Do They Work?

    When you create a partner referral link, each partner rep gets their own unique copy of that link. Each copy includes a unique Partner Link ID (plid) appended to it, like so:

    https://app.partner.io/signup?plid=1234567890

    📜 The Partner Link Script

    To track clicks and sign-ups, you need to add a small JavaScript snippet — the partner link script — to your website. Here's how it works:

    1. Captures the Partner Link ID: The script reads the plid from the URL when the user lands on the page.
    2. Stores the plid in the Browser: It saves the plid using localStorage, allowing it to persist across pages and even after the browser is closed and reopened.
    3. Tracks the Click: The script sends a click event to the Partner API when it initially captures the Partner Link ID.
    4. Intercepts Form Submissions: When a user submits a sign-up form, the script automatically captures the form data and sends it — along with the Partner Link ID — to the Partner API to create a lead. Including the plid allows us to attribute the lead to the exact referral link that drove the conversion.

    🧠 Key Concepts To Understand

    • Each link is unique: The Partner Link ID is tied to the specific referral link, not the partner rep directly.
    • Click and sign-up attribution: Events like clicks and sign-ups are attributed to the partner link, and the resulting lead is attributed to the partner rep who owns that link.
    • Persistence across pages: Since the Partner Link ID is stored in localStorage, it follows the user as they browse your site — meaning the sign-up form doesn't need to be on the same page the user originally landed on.
    • Script placement is important:
      ✅ The partner link script must be present on the page that the referral link directs to (so it can capture the plid).
      ✅ It must also be present on any page where sign-up forms exist (so it can intercept form submissions).

    To create a partner referral link, navigate to the Partner Toolkit section of the app and select Partner Referral Links. Click on the Create Link button and fill in the required fields, including the name of the link and where it goes.

    📝 Naming Your Links

    When naming your links, consider the following:

    • Descriptive: Use a name that describes the purpose of the link, maybe where it should be shared and where it directs (e.g., Facebook - Pricing Page).
    • Organized: Use a naming convention that helps you group similar links together (e.g., Spring Campaign - Landing Page).
    • Unique: Ensure that each link has a unique name to avoid confusion.

    To delete a link, go to the Partner Referral Links section of the app and select the link you want to remove. Click the actions menu (three dots) next to the link and choose Delete. Confirm the deletion when prompted.

    If the link has no clicks or leads associated with it, it will be permanently removed from your account. If it does have associated data, it will be deactivated instead — this ensures no data is lost.

    The same behavior applies to partner rep copies of the link:

    • If a partner rep's copy has no conversion data, it will be removed.
    • If it has associated clicks or leads, it will be deactivated but remain visible for historical reference.

    🧱 Installing the Partner Link Script

    There are a few different ways to install the Partner Link script on your website. The method you choose will depend on your website's setup and your preferences.

    Install MethodWhen to Use
    Google Tag ManagerUse this method if you're using Google Tag Manager (GTM) and want a quick, no-code setup. This is the recommended option for most users.
    Google Tag Manager (Legacy)This is our legacy GTM installation method. While still supported, it's not recommended for new users. If you're currently using this method, we recommend switching to GTM v2.
    Custom InstallUse this method if you're not using GTM and prefer to install the script directly on your site. This option requires some coding knowledge, as you'll need to manually update your website's code. It's also ideal if you want more fine-grained control over when events are recorded.

    Method 1: Google Tag Manager

    This guide assumes that you already have Google Tag manager up and running but if not heres an extensive guide on how to get started.

    Google Tag Manager (GTM) allows you to manage and deploy marketing tags (like tracking codes or scripts) on your website without needing to modify the source code directly. Below is a step-by-step guide on how to set up the Partner Link Tag using GTM.

    Create the Tag

    1. Go to Google Tag Manager

    Navigate to Google Tag Manager.

    2. Create a GTM Account

    If you don't already have an account, click Create Account. GTM allows you to create containers to organize your tags for different websites or web apps.

    • What is a GTM Container? A container is a place where you store all your tags, triggers, and variables for a specific website or app. Each GTM container corresponds to a different website or web application that you're tracking.

    3. Create a Container

    After creating an account, you'll be prompted to create a container. The container will hold all the tags for your website or web app.

    • Container Setup:
      • Enter a name for the container (typically your website's name).
      • Choose Web as the platform if you're setting it up for a website.
      • Click Create.

    4. Add a New Tag

    Once you have your container set up, the next step is to add a new tag:

    1. Click on “Add a New Tag”.
    2. You'll be taken to the Tag Configuration screen.

    5. Configure the Tag

    1. Click the Tag Configuration Box to choose the type of tag you want to create.

    2. Choose Custom HTML as the tag type.

      • Why Custom HTML? The Custom HTML tag allows you to insert any custom JavaScript or HTML into your website, such as the Partner Link script.

    3. Copy and Paste the HTML into the Tag Configuration Box

    <script src="https://widget.partner.io/partnerLink.js"></script>
<script>
  window.partnerLinkLibrary.init({{Form Element}});
</script>

    6. Set Up the Trigger

    1. Click the Triggering Box to select a trigger for when the tag should fire.

    2. Choose the All Pages Page View Trigger. This trigger ensures the script fires on all pages where it's included, which is necessary for tracking clicks.

      • What is a Trigger? A Trigger determines when and where a tag will fire. The Page View Trigger means that the tag will fire whenever a page is viewed.

    3. Click the Plus Icon in the top-right of the Triggering section to add a new trigger.

    4. Click the Plus Icon in the Choose a Trigger section to create a new trigger.

    5. Click the Trigger Configuration Box and select Form Submission as the trigger type.

      • Why Form Submission Trigger? This trigger allows you to track form submissions, so the script will capture the form data and send it to the Partner API when it's submitted.

    6. Configure Trigger Settings:

    • Check “Wait for Tags” and Check “Check Validation”.

    GTM will show a warning:
    You have selected Wait for Tags or Check Validation. We recommend enabling this trigger only on the pages where you need it and testing your changes before publishing.

    This is expected — it's just a reminder to properly scope your trigger.

    🔒 Step 1: Add Page Path Condition (before selecting "Some Forms")

    In the section titled "Enable this trigger when all of these conditions are true", you'll see:

    • Variable: Page Path
    • Operator: contains
    • Value: /your-page

    Add one row per page you want to track forms on (e.g., /contact, /signup, /quote).

    This ensures the trigger is only active on the pages you care about.

    ✏️ Step 2: Select “Some Forms” and Re-add Conditions

    Now scroll to the section labeled:

    Fire this trigger when an Event occurs and all of these conditions are true

    1. Select Some Forms (instead of All Forms).
    2. Add the same Page Path conditions here again:
      • Page Path → contains → /your-page
      • Add multiple conditions as needed.

    💡 Why repeat it?
    GTM separates form events from page scoping, and both areas need conditions to ensure accurate and restricted triggering.

    It should look something like this:

    1. Name your trigger, e.g. Form Submission, and click Save.

    7. Name the Tag

    Once you've configured the tag and trigger, give the tag an appropriate name (e.g., Partner Link Tag), and click Save.

    Adding the Form Element Variable

    To complete the setup, you need to add the Form Element variable. This makes the form that was submitted available to the Partner Link script as a variable in GTM.

    Why this is important

    The script uses {{Form Element}} to access the form DOM node in real time when it's submitted. Without enabling this built-in variable, GTM won't be able to pass the form reference to the script, and tracking will not work.

    Steps to Enable the Form Element Variable

    1. In the left sidebar of GTM, click Variables.
    2. Click the Configure button in the top-right of the Built-In Variables section.
    3. In the checklist that appears, scroll down to the Forms section.
    4. Check the box next to Form Element.

    You should now see Form Element listed as an available built-in variable.

    Publish the Container

    Once everything is configured, publish your changes to make the container live.

    1. In the top-right corner of GTM, click Submit.
    2. Add a version name (e.g. Add Partner Link Tracking) and an optional description.
    3. Click Publish.

    This will allow you to install the container on your website.

    Load the Script

    The tag — which includes the script — will be loaded on all pages where the GTM container is installed. To install the GTM container, you need to add the GTM code snippet to your website. Follow this guide for detailed instructions on how to do this.

    Make sure the container is installed on:

    • All pages where the referral link directs to.
    • All pages where you want to track sign-ups.

    Summary

    • You've created a Custom HTML tag with the Partner Link script.
    • You've set up two triggers:
      • One for All Pages (to capture link clicks).
      • One for Form Submissions (scoped to specific pages).
    • You've added the Form Element variable to pass the form DOM node to the script.
    • You've published the container to activate tracking.
    • And finally, you've added the GTM container code to your website 😎

    You're now ready to start tracking clicks and sign-ups through your Partner Link setup using GTM!

    ⚠️ Important
    If you're using standard HTML forms with an action attribute, a POST method, and a page reload on submit, this setup will work seamlessly. These types of form submissions can be automatically tracked by GTM.

    However, if you're submitting forms via AJAX or JavaScript (e.g., using fetch), the GTM form submission event will not fire. In this case, you'll need to manually send the sign-up data using the Partner Link JavaScript API.

    You can still use the GTM install method as described above. A manual install is only required when you're not using GTM. You'll just need to add some custom code to your form submission logic and call the recordSignUpEvent method from the Partner Link API to send the sign-up data.

    For a detailed example of how to track AJAX-style form submissions see here.

    Method 2: Google Tag Manager (Legacy)

    This method is the legacy version of the Google Tag Manager installation. While it is still supported, we recommend using the newer GTM v2 method for all new implementations.

    The GTM configuration is identical to the new method — the only difference is that this version uses the legacy script, which comes with more limitations.

    <script>var partnerLinkId=new URLSearchParams(new URL({{Page URL}}).search).get("plid"),partnerLinkIdCookie=(document.cookie.match(/partner_link_id=([^;]*)/)||[null,null])[1];if(partnerLinkId&&(!partnerLinkIdCookie||partnerLinkId!==partnerLinkIdCookie)){document.cookie="partner_link_id="+partnerLinkId+"; Max-Age=2592000; SameSite=None; Secure; path=/",partnerLinkIdCookie=partnerLinkId;var setPartnerLinkIdCookie=!0}var signUpData=(window.dataLayer||[]).length&&"gtm.formSubmit"===window.dataLayer[window.dataLayer.length-1].event&&{{Form Element}}?Array.prototype.map.call({{Form Element}}.querySelectorAll("input"),(function(e,n){return{label:e.name||null,value:e.value}})):null;(setPartnerLinkIdCookie||(partnerLinkIdCookie||partnerLinkId)&&signUpData)&&fetch("http://api.partner.local:8000/tracking/partner-links",{method:"POST",headers:{"Content-Type":"application/json",Accept:"application/json"},body:JSON.stringify({partner_link_id:partnerLinkIdCookie||partnerLinkId,sign_up_data:signUpData,click_event:!!setPartnerLinkIdCookie})}).then((function(e){return e.json()})).catch((function(e){console.error("Error:",e)}));</script>

    Note: The legacy script only supports traditional (non-AJAX) form submissions. If you're submitting forms via AJAX or JavaScript (e.g., using fetch), you'll need to use the newer GTM v2 method instead.

    The legacy script also relies on cookies to persist the Partner Link ID in the browser. This is less reliable, as many modern browsers restrict third-party scripts from setting cookies.

    Additionally, it does not support the Partner Link JavaScript API, so it's recommended only if you're maintaining an older integration.

    Method 3: Custom Install

    This method is for users who prefer to install the Partner Link script directly on their website without using Google Tag Manager (GTM).

    ⚠️ This setup requires some coding knowledge, as you'll need to manually update your website's HTML and handle form tracking yourself.

    You'll need to include the Partner Link script and initialize it manually.

    <script src="https://widget.partner.io/partnerLink.js"></script>
<script>
  window.partnerLinkLibrary.init();
</script>

    2. Add the Script to Your Website

    • Insert the script just before the closing </body> tag on your website.
    • Include it on every page which is the destination of a partner referral link.
    • Include it on every page where you want to track sign-ups.
    • This ensures the Partner Link JavaScript API is available wherever it's needed.

    3. Hook into Form Submissions

    Unlike the GTM setup — which automatically tracks form submissions — the custom install requires you to manually call the API when a form is submitted.

    You'll use the Partner Link JavaScript API to send sign-up events to the Partner API in your form submission handler.

    Example:

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

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

    See another example and the API documentation for recordSignUpEvent.

    🧪 Testing the Partner Link Script

    Partner.io will automatically check whether the Partner Link script is present on the destination page of each referral link. You can view the status of the script for every link inside the Partner Referral Links section of the app.

    You can also manually verify that the script is loaded using your browser's Developer Console:

    How to Check Manually

    1. Open the Developer Console (usually by pressing F12 or Ctrl + Shift + I).
    2. Go to the Console tab.
    3. Type window.partnerLinkLibrary and press Enter.
    4. If the script is installed on the page, you should see an object with various methods and properties.

    📚 The Partner Link JavaScript API

    These methods are available on the global window.partnerLinkLibrary object. Most are intended for use in custom (non-GTM) setups.

    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.

    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.

    Example: Tracking AJAX-Style Form Submissions

    This example shows how to track AJAX-style form submissions using the Partner Link JavaScript API. It is useful if your forms are submitted via JavaScript (e.g., using fetch) or if you're not using Google Tag Manager.

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

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

    Or using the getSignUpDataFromForm method to extract form data:

        const handlePartnerLead = async () => {
        const formId = 'your-form-id';
        const signUpData = window.partnerLinkLibrary?.getSignUpDataFromForm(formId);
        if (!signUpData) {
            return;
        }
        await window.partnerLinkLibrary?.recordSignUpEvent(signUpData);
    }

    const onSubmit = async (values: any) => {
        await handlePartnerLead();
        // Continue with your form submission logic
    };

    🎯 Troubleshooting

    My form submissions are not being tracked

    The click event is not being recorded

    The script is not being injected by Google Tag Manager

    • Make sure you have published the GTM container after adding the tag.
    • Turn off any ad blockers or browser extensions that might interfere with GTM.
    • Some browsers e.g. Brave block GTM by default. You may need to turn shields off for your site.