> ## Documentation Index
> Fetch the complete documentation index at: https://unify-19-preview.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# HubSpot integration guide

> Connect HubSpot to Unify.

export const PlanAvailability = ({plans}) => <aside aria-label="Plan availability" className="not-prose my-6 flex items-start gap-3 rounded-xl border border-zinc-200 bg-zinc-50 px-4 py-3 text-sm leading-6 text-zinc-700 dark:border-zinc-700 dark:bg-white/5 dark:text-zinc-300">
    <svg aria-hidden="true" width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" strokeLinejoin="round" className="mt-1 shrink-0">
      <path d="m12 3 9 5-9 5-9-5 9-5Z" />
      <path d="m3 12 9 5 9-5M3 16l9 5 9-5" />
    </svg>
    <span>Available only on {plans} plans.</span>
  </aside>;

export const ThemedImageFrame = ({lightSrc, darkSrc, alt, caption}) => <Frame caption={caption}>
    <img className="block w-full dark:hidden" src={lightSrc} alt={(alt ?? caption) ?? ""} />
    <img className="hidden w-full dark:block" src={darkSrc} alt={(alt ?? caption) ?? ""} />
  </Frame>;

## Overview

Unify connects to HubSpot to bring CRM data into your outreach workflows and keep
HubSpot updated with your team's activity:

* **Keep HubSpot up to date:** Sync companies, contacts, emails, and tasks from
  Unify to HubSpot.
* **Respect rules of engagement:** Use HubSpot data in exclusions to avoid
  contacting current customers or companies with open deals.
* **Automate outreach:** Use HubSpot properties to select the people and
  companies that enter your plays and sequences.
* **Work with your CRM in chat:** Find and review HubSpot records or create and
  update them when your workspace allows chat writes.

## How to connect

| Method | Use it for |
| - | - |
| **Workspace connection** | A shared connection for the team. Supports bidirectional syncs, CRM-based exclusions and automations, and HubSpot access in chat. |
| **User connection** | Each user connects their own HubSpot account. Chat and automatic sync rules can use that connection. |

<Tip>
  Use both when your team needs shared CRM data and wants chat or automatic
  updates to use each person's connection.
</Tip>

<Note>
  HubSpot app permissions can give Unify access beyond the connected user's
  record permissions. See [When to require user connections](/reference/integrations/hubspot/connection-preferences#when-to-require-user-connections)
  for details.
</Note>

## Prerequisites

To authorize Unify, you need **Super Admin** or **HubSpot Marketplace Access** in
HubSpot.

## Setup

<Tabs>
  <Tab title="Workspace connection">
    <PlanAvailability plans="Business" />

    You need permission to manage the HubSpot integration in Unify to set up the
    workspace connection and change its settings.

    <Steps titleSize="h3">
      <Step title="Connect HubSpot">
        Open [Settings → HubSpot](https://app.unifygtm.com/dashboard/settings/integrations/hubspot)
        and click **Set up HubSpot**. If a personal connection already exists,
        open the connection selector and choose **Add workspace connection**.

        Sign in to HubSpot, select the account your team uses, and authorize
        Unify. When you return, the page shows an active **Workspace connection**.
        Open its three-dot menu and select **Details** to check the connected
        email and **HubSpot account ID**.

        <ThemedImageFrame lightSrc="/images/reference/integrations/hubspot/hubspot-workspace-status-light.png" darkSrc="/images/reference/integrations/hubspot/hubspot-workspace-status-dark.png" alt="HubSpot workspace connection marked active and healthy." />
      </Step>

      <Step title="Review field mappings">
        Field mappings pair Unify attributes with HubSpot properties and control
        how values are read and written. Mappings are shared by connections to
        the same HubSpot account within your Unify workspace.

        Under **Field mappings**, click **Edit mapping** for the records you want
        to sync. Review the mapped properties and choose how Unify should handle
        existing values, then click **Save**. For example, **Fill if empty**
        preserves an existing HubSpot value, while **Overwrite always** replaces
        it with the available Unify value.

        <ThemedImageFrame lightSrc="/images/reference/integrations/hubspot/hubspot-field-write-behavior-light.png" darkSrc="/images/reference/integrations/hubspot/hubspot-field-write-behavior-dark.png" alt="HubSpot field mappings with the write-behavior menu open for Company name." />

        See [Field mappings](/reference/integrations/hubspot/field-mappings) for
        the available options and [Default values](/reference/integrations/hubspot/default-values)
        to populate empty properties during sync.
      </Step>

      <Step title="Review sync rules">
        Open **Sync rules**. Choose which actions in
        Unify should update HubSpot, such as prospecting a person, sending an
        email, or creating a task.

        For prospecting, **Sync if already exists** allows updates to matching
        HubSpot records, while **Sync** also allows new records. Choose
        **Do nothing** for events you want to leave disabled, then click **Save**.

        <ThemedImageFrame lightSrc="/images/reference/integrations/hubspot/hubspot-sync-rule-choices-light.png" darkSrc="/images/reference/integrations/hubspot/hubspot-sync-rule-choices-dark.png" alt="HubSpot prospecting sync menu with Do nothing, Sync if already exists, and Sync options; Do nothing is selected." caption="Choose whether prospecting can create new CRM records or only update existing ones." />
      </Step>

      <Step title="Enable syncs">
        Turn on **Bidirectional syncs** once your mappings and sync rules are
        ready. Unify starts an initial sync of HubSpot data and synchronizes changes
        according to your configuration.

        See [Bidirectional syncs](/reference/integrations/hubspot/bidirectional-syncs)
        for sync behavior and timing.
      </Step>
    </Steps>
  </Tab>

  <Tab title="User connection">
    <PlanAvailability plans="Pro and Business" />

    Your workspace must allow personal HubSpot connections. To use your
    connection for workspace sync rules, choose the same HubSpot account as the
    workspace connection.

    <Steps titleSize="h3">
      <Step title="Connect your account">
        Open [Settings → HubSpot](https://app.unifygtm.com/dashboard/settings/integrations/hubspot)
        and click **Connect HubSpot**. If a connection is already shown, open the
        connection selector and choose **Add personal connection**.

        Sign in with your own HubSpot login and authorize Unify. Choose the
        HubSpot account you want to use and approve the requested app access.
      </Step>

      <Step title="Confirm your connection">
        Confirm that the connection is labeled **User connection**. Open its
        three-dot menu and select **Details** to check the connected email and
        **HubSpot account ID**.

        <ThemedImageFrame lightSrc="/images/reference/integrations/hubspot/hubspot-user-connection-light.png" darkSrc="/images/reference/integrations/hubspot/hubspot-user-connection-dark.png" alt="HubSpot user connection marked active and healthy." />

        Your workspace's connection preferences determine when chat and
        automatic sync rules use your personal connection. Ask your
        administrator if you need those preferences changed.
      </Step>
    </Steps>
  </Tab>
</Tabs>

To require each user's HubSpot authorization, see
[When to require user connections](/reference/integrations/hubspot/connection-preferences#when-to-require-user-connections).

## Troubleshooting

<AccordionGroup>
  <Accordion title="Why can't I add a personal connection?">
    Ask someone who manages the integration to check **Allow users to set up
    personal HubSpot connections** in **Workspace settings**. Each user can have
    one personal CRM connection at a time; check whether you already have one.
  </Accordion>

  <Accordion title="How do I reauthorize or change the connected account?">
    If the connection shows **Needs reauthorization** or **Missing permissions**,
    click **Reauthorize** and complete HubSpot authorization again. To use a
    different login, open the connection's three-dot menu and choose
    **Change user**. Review **Details** afterward.
  </Accordion>

  <Accordion title="Why did a sync fail?">
    Open the failed attempt in **Sync log** and review the error and selected
    connection. Correct the connection, property, or record issue, then choose
    **Retry sync** if available. Retrying requires permission to manage the HubSpot integration.
  </Accordion>

  <Accordion title="What happens when I disconnect a connection?">
    Disconnecting a workspace connection stops automated actions that require it
    and can disable dependent engagement policies. Disconnecting a personal
    connection removes that user's authorization. Review the consequences shown
    in the confirmation dialog before choosing **Disconnect**.
  </Accordion>
</AccordionGroup>

## Additional HubSpot resources

<CardGroup cols={2}>
  <Card icon="arrow-right-arrow-left" title="Field mappings" href="/reference/integrations/hubspot/field-mappings">
    Choose which HubSpot properties Unify reads and writes.
  </Card>

  <Card icon="pen-to-square" title="Default values" href="/reference/integrations/hubspot/default-values">
    Populate empty HubSpot properties during sync.
  </Card>

  <Card icon="arrows-rotate" title="Bidirectional syncs" href="/reference/integrations/hubspot/bidirectional-syncs">
    Understand sync timing, supported records, and matching behavior.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.