> ## 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 Salesforce 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 Salesforce data in Unify and keep Salesforce 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 Salesforce.

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

## Syncing changes to Salesforce

### Sync rules

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

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

<CrmSyncRuleBehaviors />

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

<ThemedImageFrame lightSrc="/images/reference/integrations/salesforce/salesforce-sync-rule-options-light.png" darkSrc="/images/reference/integrations/salesforce/salesforce-sync-rule-options-dark.png" alt="Salesforce prospecting sync menu with Do nothing, Sync if already exists, and Sync options." />

Plays can also create or update records through a Salesforce 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-salesforce).

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

### Overwriting data

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

<CrmWriteBehaviors />

<ThemedImageFrame lightSrc="/images/reference/integrations/salesforce/salesforce-field-write-behavior-light.png" darkSrc="/images/reference/integrations/salesforce/salesforce-field-write-behavior-dark.png" alt="Salesforce write-behavior menu for Account Name, with Fill if empty selected and all four options visible." />

**Overwrite on manual edit** is available only for supported Unify fields.
Configured default values fill empty fields. See
[Field mappings](/reference/integrations/salesforce/field-mappings) for configuration.

Chat writes the values requested by the user, subject to the connected
Salesforce account's permissions. See
[Connection preferences](/reference/integrations/salesforce/connection-preferences)
for personal account selection.

### Duplicate prevention

Before creating a Salesforce 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 Salesforce duplicates.

### Supported objects

<AccordionGroup>
  <Accordion title="Accounts">
    Unify can sync an account alongside its contact, or when a Salesforce sync
    action runs within a play that is running on companies.

    If there is an existing account that matches the Unify company being written, it
    is selected for the update. Matches are determined based on the domain of the company
    website, using normalized domains. If there are no matches and the sync rule
    or action allows record creation, Unify creates an account.

    If multiple accounts match the Unify company, one is selected for the update.
  </Accordion>

  <Accordion title="Contacts">
    Unify writes Salesforce contacts when **Write people as** is set to
    **Contacts and accounts**. When **Leads** is selected and no matching lead
    exists, Unify can update an existing contact instead.

    Matches are determined based on email address. If no record matches, Unify
    can create a contact when **Contacts and accounts** is selected and the sync
    rule or action allows creation.

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

  <Accordion title="Leads">
    Unify writes Salesforce leads when **Write people as** is set to **Leads**.
    When **Contacts and accounts** is selected and no matching contact exists,
    Unify can update an existing lead instead.

    Matches are determined based on email address. If no record matches, Unify
    can create a lead when **Leads** is selected and the sync rule or action
    allows creation.

    If multiple leads match the Unify person, one is selected for the update.
  </Accordion>

  <Accordion title="Email messages">
    Email sync can write Salesforce email messages or tasks, according to the
    connection's settings. To write email message records, **Enhanced Email**
    must be enabled in Salesforce.

    Email sync looks for an existing record before creating one, using the
    message identifier when available. Mapped email activity values can also
    update an existing record, subject to the mapping behavior and Salesforce
    permissions.

    Enabled sync rules can write emails sent through Unify sequences or manual
    tasks, and replies to those emails. The corresponding person must already
    exist in Salesforce as a contact or lead, or the sync behavior must allow
    Unify to create the related record.

    Email messages can include mapped email activity fields such as subject,
    content, sent time, bounce status, click count, open timestamps, spam status,
    opt-out status, the enrolling play, and sequence name. These values are written
    only when the relevant event exists and the mapped Salesforce field is writable
    by the Salesforce account used for the write.
  </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 Salesforce. 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 the Salesforce Task object. 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 Salesforce before they are complete because email sending is
    controlled in Unify.

    Salesforce tasks are related to the corresponding Salesforce contact or
    lead. If the person does not already exist in Salesforce, Unify must sync
    the person to Salesforce before the task can be written. When there is an
    associated company and the person is a contact, Unify can also relate the
    task to the Salesforce account. When the person is a lead, Salesforce does
    not support the same account relationship on the task.

    Task sync uses the Task object mapping in
    [Field mappings](/reference/integrations/salesforce/field-mappings). Unify writes values
    such as subject, description, status, priority, task subtype, due date,
    owner, contact/lead relationship, and account relationship when available.
    When a task is deleted in Unify, Unify deletes the matching Salesforce task.
  </Accordion>
</AccordionGroup>

### Review sync results

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

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

## Syncing changes from Salesforce

### Records and fields

Changes to Salesforce accounts, contacts, leads, and opportunities update the corresponding
records in Unify. [Field mappings](/reference/integrations/salesforce/field-mappings)
pair Salesforce fields with Unify attributes and control which values sync.

Salesforce opportunities are read into Unify as opportunity records. They can be
associated with companies and people when the Salesforce opportunity has the
corresponding account or contact relationship.

Opportunity 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 Salesforce fields 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 Salesforce 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 Salesforce records
approximately every 15 minutes by default and synchronizes those changes.
Large batches of changes can take longer to process, delaying when they appear
in Unify.

### Task completion

Salesforce-to-Unify task sync is limited to completion updates. When a
non-email Salesforce task that was written by Unify is marked **Completed**
in Salesforce, Unify marks the corresponding task complete in Unify.

Completed Salesforce phone-call tasks created by supported dialer
integrations can also complete the matching open Unify phone-call task when
Unify can identify a single matching task for the same person. 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.