# Integrate with HubSpot for Advocate

This guide covers the HubSpot integration for Advocate programs, supporting standard HubSpot objects: Deals, Companies, and Contacts.

## Prerequisites

Use this guide to help you set up HubSpot integration for Advocate when:

* You already have a Performance or Creator program.
* You have [cross-program tracking](https://help.impact.com/en/support/solutions/articles/48001235079-enable-cross-program-tracking) enabled between your Advocate and Performance programs, and use an existing performance conversion event shared with Advocate.
* You're adding a new Advocate program from the in-app prompt and checklist.

{% hint style="warning" %}
**Important architectural limitation:** The HubSpot integration is limited to connecting with only one Advocate Program ID per HubSpot instance. This one-to-one mapping is mandatory to ensure accurate data sync and program property visibility on contact records.
{% endhint %}

{% stepper %}
{% step %}

### Connect and configure HubSpot

<details>

<summary>Initial integration setup</summary>

If you are setting up your HubSpot integration for the first time, you must complete the following steps.

***

#### Connect and configure the HubSpot integration

Advocate adds special settings to your impact.com HubSpot integration. If you haven't set up the integration yet, follow our [Integrate with HubSpot](https://integrations.impact.com/impact-brand/docs/integrate-with-hubspot) guide to do the following. Then, return to this section for Advocate-specific setup steps.

1. [Install and connect](https://integrations.impact.com/impact-brand/docs/integrate-with-hubspot#install--connect-impactcom-in-hubspot) the impact.com app in HubSpot.
   * On the *Settings* page in the connector, make sure you toggle on Advocate Program opt-in.
2. Enable [event triggers](https://integrations.impact.com/impact-brand/docs/integrate-with-hubspot#enable-event-triggers). Configure [field mappings](https://integrations.impact.com/impact-brand/docs/integrate-with-hubspot#configure-field-mappings).
   1. For Advocate, you must set up a few specific field mappings for the Deals object.
   2. You must pass the ClickId field on the conversion so it maps to your participants.
   3. In most cases, it's not required to map fields for either the Contact or Company objects. If your specific implementation requires mappings from either of these, a custom set of mappings will be provided to you by your impact.com-assigned Implementation Engineer.

| impact.com Mapping                                                                                                                                                                                         | HubSpot Mapping              | Required?   |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------- | ----------- |
| `EventDate`                                                                                                                                                                                                | lastmodifieddate             | Yes         |
| `CustomerId`                                                                                                                                                                                               | hs\_object\_id               | Yes         |
| `CustomerEmail`                                                                                                                                                                                            | email                        | No          |
| <p><code>OrderId</code><br>This is the default field used by impact.com to uniquely identify each conversion event. However, you can select another field to use instead.</p>                              | deal\_\[stage]\_id           | Yes         |
| <p><code>EventTypeCode</code><br>This is the default field used by impact.com to determine which program rule to trigger for a conversion event. However, you can select another field to use instead.</p> | deal\_\[deal stage]          | Yes         |
| `OrderSubTotal`                                                                                                                                                                                            | amount                       | Recommended |
| `Date3`                                                                                                                                                                                                    | closedate                    | Recommended |
| `Text2`                                                                                                                                                                                                    | hs\_deal\_stage\_probability | Recommended |

***

#### Configure HubSpot for Advocate

If you already have impact.com and HubSpot connected, you can [reopen the connector](https://hubspot-integration.impact.com/) to configure Advocate for HubSpot.

{% hint style="warning" %}
**Important:** We use this single connected Advocate program as the source of information when creating these new contact properties in HubSpot: Referral Code, Share Link, Message Links, Referred-by Code, Advocate User and Account ID, and Referral Cookie.
{% endhint %}

</details>
{% endstep %}

{% step %}

### Review your Microsite

Use microsites to give your customer advocates an easy way to interact with your Advocate program and start sharing.

You’ll need to:

1. [Customize the appearance of your microsite](https://help.impact.com/brand/what-would-you-like-to-learn-about/advocate-program/manage-advocate-participant-experiences/microsite-experiences/customize-microsite-layouts-and-pages).
2. Share the microsite URL with your Advocates when you launch the program.
   {% endstep %}

{% step %}

### Set up your cash rewards

Your customer advocate can be rewarded with cash payouts. Confirm that your impact.com account is [adequately funded](https://help.impact.com/en/support/solutions/articles/48001235908-deposit-funds-into-your-account).
{% endstep %}

{% step %}

### Test the integration

We recommend testing the integration to ensure it’s working as intended.

| Test                                                                                                                                                                                                                                                                                  | Purpose                                                                                                                 |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| <p>Create a deal with one of the new HubSpot contacts and change its status to <code>Closed Won</code>.<br>Use if you set up your program rules to perform an action when a deal’s status changes. If you used another status other than <code>Closed Won</code>, test with that.</p> | Confirm that program rules trigger correctly when a deal’s status changes. This should create and convert the referral. |

Congratulations! You’ve successfully navigated the technical setup. Your Advocate program is now integrated with HubSpot. To start seeing results and getting your Advocates engaged, make sure to share your unique microsite link across your marketing channels.
{% endstep %}
{% endstepper %}

## Optional enhancements

<details>

<summary>Upgrade your integration</summary>

For users already utilizing the [HubSpot integration](https://integrations.impact.com/impact-brand/docs/integrate-with-hubspot) for Performance and Creator programs, these Advocate-specific configurations are optional. You don’t need to make any immediate changes to your existing integration to launch your Advocate program; however, we recommend revisiting these enhancements once you’ve completed the initial setup steps above to ensure your integration is fully optimized.

Key benefits of activating the Advocate-specific integration include:

* Bi-directional data syncing: After setup, HubSpot can send referral tracking, deal stage, and contact information directly to impact.com. Important Advocate program properties like referral codes, share links, and more will be visible on contact records.
* Lead and Contact enrichment: Set up a HubSpot lead capture form that sends referral data to your Advocate program.

***

#### Manage your data sharing rules

This step takes place within the [HubSpot to impact.com connector](https://hubspot-integration.impact.com/login).

1. Choose which data is shared between impact.com and HubSpot when a new contact or participant is created.

| Action                                     | When                                                                              |
| ------------------------------------------ | --------------------------------------------------------------------------------- |
| Create contacts in HubSpot                 | An Advocate participant is created. An existing, unmapped participant is updated. |
| Create Advocate participants in impact.com | A HubSpot contact is created. An existing, unmapped contact is updated.           |

2. Refer to HubSpot's documentation to learn how to [customize the properties shown on records](https://knowledge.hubspot.com/object-settings/customize-properties-in-record-sections).
3. There are other, non-adjustable rules for deleting and updating participant and contact records. You can return to this screen to review them, or refer to [HubSpot & Advocate Data Mapping Explained](https://integrations.impact.com/impact-brand/docs/hubspot-for-advocate-integration-behaviors#sharing-rules) for more details.
4. Update the contact record layout in HubSpot to show participants' Advocate data.
5. Review your selections and choose whether to sync all Advocate participant data to HubSpot after setup.
6. Select **Finish**.

{% hint style="success" %}
**Note:** The initial data sync does not transfer your HubSpot contact records to impact.com. If you’d like to import them after setting up the integration, then make sure you [sync your HubSpot data](https://integrations.impact.com/impact-brand/docs/integrate-with-hubspot-for-advocate#step-3-sync-hubspot-data).
{% endhint %}

***

#### Register Referred Leads

1. Create a new hidden field on your HubSpot form for the impact\_referredby\_code Contact Property.
2. Load the function below alongside your HubSpot lead form.
   * This function will break down the referral cookie and ensure the referred by code is submitted along with the rest of the customer’s information to HubSpot.
3. Replace ProgramID with your Advocate Program ID.

{% hint style="success" %}
**Note:** This function requires the Universal Tracking Tag to be loaded for all transactions.
{% endhint %}

```javascript
<script>
  document.addEventListener("DOMContentLoaded", function() {
    // Delay function to ensure HubSpot form fields are fully rendered
    setTimeout(function () {
      window.impactOnReady = function () {
        // Retrieve the DOM element you want to auto-fill the referral code into
        const elements = document.getElementsByName("impact_referredby_code");
        if (elements.length > 0) {
          const element = elements[0];
          // Retrieve referral information from the cookie and set on element
          impact.api().referralCookie()
            .then(function (response) {
              const referralCode = response.codes['PROGRAMID'];
              if (referralCode) {
                element.value = referralCode;
              }
            })
            .catch(function (error) {
              console.error("Error retrieving referral cookie:", error);
            });
        } else {
          console.error("No element found with name 'impact_referredby_code'");
        }
      }
      // Call the impactOnReady function
      if (typeof impact !== 'undefined') {
        window.impactOnReady();
      } else {
        console.error("Impact object not found.");
      }
    }, 1000) // 1-second delay to ensure HubSpot form fields are rendered
  });
</script>
```

***

#### Sync HubSpot data

Optionally, you can bulk import data into HubSpot to ensure your Advocate program’s participants are synced with your HubSpot leads and contacts.

1. Export your contacts from HubSpot as a .CSV file.
2. Adjust the .CSV file to match the accepted bulk import format.
   1. Make sure that the name of the email column in the import file is *email*. We use this field to map HubSpot contacts with Advocate participants.
   2. Learn more about [bulk imports](https://help.impact.com/en/support/solutions/articles/155000000869) and [download a sample CSV file](https://assets.ctfassets.net/s68ib1kj8k5n/7LOYwhDlsI22uuaIMaWImE/71cefe860edc71c0968c8065e1d6e953/sample-user-upload.csv).
3. In your impact.com account, from the left navigation menu, select **Participants**.
4. At the top-right corner of the page, select **Import users**.
5. Upload the .CSV file.
   * To avoid errors, check that the .CSV file you’ve prepared follows the accepted import format. Reach out to our support team if you have questions.

</details>

#### **What’s Next**

Finally, test your integration to make sure that participants are being correctly registered in impact.com and rewarded for successful referrals.

* [End-to-End Testing](https://integrations.impact.com/impact-brand/docs/end-to-end-testing-for-advocate)

<br>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://integrations.impact.com/integration-guides/for-brands/advocate/advocate-plugin-integration/integrate-with-hubspot-for-advocate.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.