> ## 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.

# How bidirectional syncs work

> Understand HubSpot record syncs.

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 CrmWriteBehaviors = () => <table>
    <thead>
      <tr>
        <th>Write behavior</th>
        <th>Effect</th>
      </tr>
    </thead>
    <tbody>
      <tr>
        <td><strong>Do nothing</strong></td>
        <td>Does not write the mapped Unify value to the CRM field.</td>
      </tr>
      <tr>
        <td><strong>Fill if empty</strong></td>
        <td>Writes the value when creating a record or when the existing CRM field is empty.</td>
      </tr>
      <tr>
        <td><strong>Overwrite on manual edit</strong></td>
        <td>Replaces the CRM value when that Unify field is manually edited, including when its value is cleared. Otherwise, fills the CRM field only when it is empty.</td>
      </tr>
      <tr>
        <td><strong>Overwrite always</strong></td>
        <td>Replaces the CRM value with the available Unify value. Empty Unify values do not clear the CRM field.</td>
      </tr>
    </tbody>
  </table>;

export const CrmSyncRuleBehaviors = () => <table>
    <thead>
      <tr>
        <th>Sync rule</th>
        <th>Effect</th>
      </tr>
    </thead>
    <tbody>
      <tr>
        <td><strong>Do nothing</strong></td>
        <td>Skip the sync for this event.</td>
      </tr>
      <tr>
        <td><strong>Sync if already exists</strong></td>
        <td>Update a matching CRM record. Skip the sync if no match exists.</td>
      </tr>
      <tr>
        <td><strong>Sync if person exists</strong></td>
        <td>Sync the email only when its related person already exists in the CRM. Available for email events.</td>
      </tr>
      <tr>
        <td><strong>Sync</strong></td>
        <td>Update a matching CRM record or create one if no match exists.</td>
      </tr>
    </tbody>
  </table>;

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

<PlanAvailability plans="Business" />

Bidirectional syncs let you use HubSpot data in Unify and keep HubSpot up to date
with your team's activity. Use CRM data to [filter records](/tutorials/how-to-create-an-audience),
[apply exclusions](/tutorials/how-to-create-an-exclusion), and automate outreach,
then sync records and activity back to HubSpot.

Enable **Bidirectional syncs** after configuring your mappings and sync rules.
Follow the [HubSpot integration guide](/reference/integrations/hubspot/overview#setup)
for setup instructions.

## Syncing changes to HubSpot

### Sync rules

Sync rules determine which actions in Unify create or update HubSpot records.
You can configure rules for prospecting a person, enrolling them in a sequence,
email activity, task activity, and logged call outcomes.

In [Settings → HubSpot](https://app.unifygtm.com/dashboard/settings/integrations/hubspot),
open **Sync rules**. Choose a behavior for each event:

<CrmSyncRuleBehaviors />

For example, use **Sync if already exists** for prospecting to update people
already in HubSpot. Choose **Sync** to also create records for new prospects.
Click **Save** after changing your rules.

<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." />

Plays can also create or update records through a HubSpot sync action. These
explicit actions use the workspace connection and run according to the play,
independently of automatic sync rules. Bidirectional syncs must be enabled.
See the [play action reference](/reference/plays/actions#sync-to-hubspot).

When automatic writes use personal connections, the account depends on the
triggering action. See [How Unify uses the connections](/reference/integrations/hubspot/connection-preferences#how-unify-uses-the-connections).

### Overwriting data

Mapped sync writes use the write behavior selected for each property. Review
these settings before enabling writes: some behaviors replace existing HubSpot
values.

<CrmWriteBehaviors />

<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 write-behavior menu for Company name, with Fill if empty selected and all four options visible." />

**Overwrite on manual edit** is available only for fields that support it.
Configured default values fill empty properties. Explicit property values set
by a sync action can override mapped values. Chat writes the requested values
using the permissions granted to the Unify app in HubSpot.

### Duplicate prevention

Before creating a HubSpot record, Unify looks for an existing match. It updates
the matched record according to your field mappings. If there is no match, Unify
creates a record when the sync allows creation. Matching rules vary by object,
as described below. Unify does not merge existing HubSpot duplicates.

### Supported objects

<AccordionGroup>
  <Accordion title="Contacts">
    If there is an existing contact that matches the Unify person being written, it
    is selected for the update. Matches are determined based on email address. If
    there are no matches, Unify can create a new contact when the sync permits
    creation and includes an email value.

    If there are multiple contacts that match the Unify person, only one is
    selected for the update.
  </Accordion>

  <Accordion title="Companies">
    Unify can sync a company alongside its contact, or when a HubSpot sync action
    runs within a play that is running on companies.

    If there is an existing company that matches the Unify company being written, it
    is selected for the update. Matches are determined based on the company domain.
    If there are no matches, Unify can create a new company when the sync permits
    creation and includes a domain value.

    If there are multiple companies that match the Unify company, only one is
    selected for the update.
  </Accordion>

  <Accordion title="Email messages">
    Enabled sync rules can write emails sent through Unify sequences or manual
    tasks, and replies to those emails. Unify looks for an existing email activity
    before creating one and can update a match. The corresponding person must
    already exist in HubSpot as a contact, or the sync behavior must allow Unify
    to create the related contact.
  </Accordion>

  <Accordion title="Calls">
    When a call outcome is logged and its sync rule allows writing, Unify writes
    the call using the Phone call mapping. The activity is linked to the matched
    person in HubSpot. Available notes, disposition, duration, recording, and
    transcript data can accompany the call.

    See [Syncing calls to your CRM](/reference/dialer/crm-sync) for provider
    differences and troubleshooting.
  </Accordion>

  <Accordion title="Tasks">
    Unify writes eligible Unify tasks to HubSpot as HubSpot tasks. This includes
    ready or completed non-email tasks, such as phone-call and action-item tasks,
    and completed email or reply tasks. Unify does not write email tasks to
    HubSpot before they are complete because completing an email task in HubSpot
    can imply that the email has been sent, while email sending is controlled in
    Unify.

    HubSpot tasks are associated with the corresponding HubSpot contact. If the
    corresponding person does not already exist as a HubSpot contact, Unify must
    sync the person to HubSpot before the task can be written.

    Task sync uses the Task object mapping in
    [Field mappings](/reference/integrations/hubspot/field-mappings). Unify writes values such as the task subject, body, task type,
    status, priority, timestamp, and owner. When a task is deleted in Unify,
    Unify archives the matching task in HubSpot.
  </Accordion>
</AccordionGroup>

### Review sync results

Review all writes, including manual and chat writes, in **Sync log**. Select an
attempt to see the result and connection used. Open a record under **Details** to see its
written values and HubSpot record ID.

<ThemedImageFrame lightSrc="/images/reference/integrations/hubspot/hubspot-contact-sync-result-light.png" darkSrc="/images/reference/integrations/hubspot/hubspot-contact-sync-result-dark.png" alt="HubSpot sync details showing Alex Morgan created as a related contact." caption="This task sync also created the related HubSpot contact." />

## Syncing changes from HubSpot

### Records and fields

Changes to HubSpot companies, contacts, and deals update the corresponding
records in Unify. [Field mappings](/reference/integrations/hubspot/field-mappings)
pair HubSpot properties with Unify attributes and control which values sync.

HubSpot deals are read into Unify as opportunity records. They can be associated
with companies and people when the HubSpot deal has the corresponding company or
contact association.

Deal data is primarily CRM-owned. Unify uses it for record context, filters, and
exclusions, such as excluding companies with open opportunities from outbound
plays.

When you change how HubSpot properties map into Unify, Unify reprocesses existing
records for the affected object in the background alongside regular syncs. The
mapped values update in Unify as this work progresses.

### Initial sync

When you first enable bidirectional syncs, Unify performs an initial sync of
your existing HubSpot data. This can take several hours. For an exceptionally
large CRM with tens of millions of records, it can take a couple of days.

### Ongoing changes

After the initial sync, Unify checks for new and updated HubSpot records
approximately every 15 minutes and synchronizes those changes.
Large batches of changes can take longer to process, delaying when they appear
in Unify.

HubSpot record associations, such as the link between a contact and its company,
are also refreshed by a daily sync.

### Task completion

HubSpot-to-Unify task sync is limited to completion updates. When a
non-email HubSpot task that was written by Unify is marked complete in
HubSpot, Unify marks the corresponding task complete in Unify. Email tasks
are excluded from this completion sync.

### Missing records or values

<AccordionGroup>
  <Accordion title="Why hasn't a CRM record appeared in Unify?">
    Confirm that the workspace connection is active and bidirectional syncs are
    enabled. Allow the initial sync or a large batch of changes to finish.

    A company needs a valid domain and a person needs a valid email through the
    incoming mapping. Check those values on the CRM record and review the
    corresponding mapping. Also confirm that the connected account can read the
    record and its required fields.
  </Accordion>

  <Accordion title="Why is a field missing or different?">
    Check the field mapping and its read behavior. **Do nothing** leaves the
    Unify attribute unchanged; **Fill if empty** preserves a value already in
    Unify. A mapping change starts background reprocessing, so existing records
    may update gradually.

    For an unavailable field, review its type and the connected account's access
    with your CRM administrator. If the record still differs after syncs have
    caught up, contact support with the CRM record ID, field name, expected value,
    and time of the change.
  </Accordion>
</AccordionGroup>


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