# HubSpot–Salesforce Native Integration: Data Sync Overview > Topic: The Data Sync capability of the official (Built by HubSpot) Salesforce connector > Scope: Covers only the HubSpot↔Salesforce native integration itself --- ## 1. Feature Overview HubSpot provides an official Salesforce integration app (the Salesforce connector, Built by HubSpot). Once installed and connected, it establishes **field-level data synchronization** between the two systems — mapping HubSpot objects and properties to Salesforce objects and fields so that data on both sides stays consistent. Core characteristics: - **Object-level mapping**: HubSpot Contacts / Companies / Deals correspond to Salesforce Leads / Contacts / Accounts / Opportunities. - **Field-level mapping**: Under each object, individual HubSpot properties ↔ Salesforce fields are connected (Field Mappings). - **Configurable sync rules**: Each field mapping is bound to a Sync Rule that determines the sync direction and which side wins on conflict. - **Near-real-time bidirectional sync**: A change on either side can sync to the other. The integration management UI is mainly divided into: **Overview**, **Feature discovery**, and **Data sync**. Data sync is further broken down per object into sub-pages such as Sync rules and Property mappings. --- ## 2. Object Sync Mapping HubSpot and Salesforce objects are not strictly one-to-one; the key difference lies in the contact/person object: | HubSpot Object | Salesforce Object | Relationship | |---|---|---| | **Contact** | **Lead or Contact** | HubSpot has only a single Contact object; Salesforce has both Lead and Contact. A given HubSpot Contact corresponds to exactly one of them at any moment | | **Company** | **Account** | One-to-one | | **Deal** | **Opportunity** | One-to-one | The integration can also sync Activities, and supports syncing custom objects (Sync custom object). --- ## 3. The Lead / Contact Duality of a Person This is the single most important concept to grasp in HubSpot–Salesforce sync. ### 3.1 One HubSpot Contact maps to exactly one Salesforce record A HubSpot Contact corresponds to **either** a Salesforce **Lead** **or** a Salesforce **Contact**, never both at the same time. Which one it is depends on the record's lifecycle state in Salesforce: | Situation | Salesforce record the HubSpot Contact maps to | |---|---| | HubSpot pushes the record to Salesforce for the first time (create) | Created as a **Lead** by default | | That Lead is **Converted** in Salesforce | After conversion it becomes a **Contact** (and generates an Account/Opportunity); from then on HubSpot changes sync to that Contact | | The record already exists as a Salesforce Contact | Syncs directly to the **Contact** | ### 3.2 How Salesforce identifies a record as a Lead vs. a Contact The first 3 characters of every Salesforce record ID (the Key Prefix) identify its object type: | Object | ID Prefix | |---|---| | Lead | `00Q` | | Contact | `003` | HubSpot stores, on its own side, the Salesforce record ID associated with the Contact, and uses the ID prefix to tell whether it currently maps to a Lead or a Contact. When a Lead is converted, Salesforce marks `IsConverted` on the original Lead and writes `ConvertedContactId`; HubSpot uses this to switch the sync association to the new Contact. ### 3.3 Mapping the same field across Lead / Contact Because Lead and Contact are two separate objects, a field with the same meaning may have a different field name on each: - For example, address: on a Salesforce **Lead** it is `City`, while on a **Contact** it is `MailingCity`. HubSpot creates **two mappings** for the same HubSpot property (e.g. `city`), pointing to the Lead field and the Contact field respectively, ensuring the value syncs whether the record is currently a Lead or a Contact. - If a field has the same API name on both Lead and Contact (e.g. an identically named custom field), then **a single mapping** covers both, and HubSpot automatically writes to the appropriate object based on the record's current identity. - A custom field built on only one of the objects will sync only while the record is in that identity. --- ## 4. Field Mappings ### 4.1 Concept A field mapping is a connection between a HubSpot property and a Salesforce field. **Any field or property that has no mapping is not included in the sync.** Each mapping carries a sync rule that governs when the field syncs and which side is the system of record. ### 4.2 Standard vs. Custom mappings - **Standard**: HubSpot's pre-built mappings for common fields (e.g. City, Employee Numbers), available out of the box. - **Custom**: Created manually by the user to map HubSpot custom properties to Salesforce custom fields (e.g. `Annual Revenue (SFDC)`, `Contact Lead Status`). ### 4.3 Information in the mapping list On Data sync → an object → Property mappings, the mapping list typically shows: - **HubSpot Property**: HubSpot property name + internal name + field type - **Salesforce Field**: Salesforce field name + API name + field type - **Sync Rule**: the sync rule for that mapping - **Status**: OK / Warning (e.g. when types do not fully match and need attention) - **Mapping Type**: Standard / Custom - **Last Modified / Create Date**: last modified / creation time The page supports: searching mappings, exporting field mappings (Export field mappings CSV), and adding a new mapping (Add new field mapping). ### 4.4 Fields that require "identity resolution": not every mapping is a verbatim value copy For ordinary fields (text, number, date, etc.), sync simply copies the value to the other side. But several kinds of **reference fields** use ID systems that are not interchangeable between the two platforms, so sync must first perform **identity resolution (ID resolution)** — find the corresponding entity on the other side and write a reference to it — rather than copying the raw ID across. **(1) Owner (record owner)** - Salesforce's `OwnerId` is a **Salesforce User reference** (the User object, ID prefix `005`); on the HubSpot side, the owner (Contact owner / Company owner / Deal owner) is a **HubSpot user**. The two user-ID systems are completely different. - Therefore syncing owner **is not an ID copy** but is done via a **user mapping**: the integration matches Salesforce Users to HubSpot users **by email address**, then resolves the record's owner to the corresponding user on the other side. - Precondition: the Salesforce user must exist in HubSpot as a (valid) user with the same email. **If no corresponding user is found, the owner cannot sync** (it is left blank or falls back to a default owner, depending on configuration). - Practical impact: owner sync depends on "users being aligned on both sides first." Adding new salespeople, deactivating users, changing email addresses, etc., all affect whether owner can be resolved correctly. **(2) Lookup / relationship fields** - For example, the Account a Contact is associated with (corresponding to HubSpot Contact ↔ Company), or the Account and Contacts an Opportunity is associated with (corresponding to Deal ↔ Company/Contacts). - These fields are essentially **relationships between records**, not ordinary values. What the integration syncs is the "relationship": it first resolves the related record to its already-synced counterpart on the other side, then creates/updates the association — rather than **copying the other side's record ID across as a string**. **(3) Picklist / enumeration values** - The set of allowed dropdown values may differ between the two sides; some scenarios require **option-value mapping** instead of a literal copy, otherwise a source value with no matching option on the other side produces a sync warning. > Summary: Reference fields such as Owner are "resolve the entity on the other side, then write a reference," while only ordinary fields are "verbatim value copies." When designing/troubleshooting owner-not-syncing issues, first check whether the **user mapping (email matching)** holds on both sides. --- ## 5. Sync Rules — The Core Each field mapping is bound to a sync rule that determines the field's sync direction and which side wins on conflict. There are four: | Sync Rule | Direction | System of Record (SoR) | Conflict / blank-value behavior | |---|---|---|---| | **Two-way** | HubSpot ↔ Salesforce | Both | A change on either side syncs to the other; on conflict the **most recently modified value wins** (last-write-wins) | | **Always use Salesforce** | Salesforce → HubSpot (one-way) | Salesforce | The Salesforce value **always overwrites** HubSpot, **even overwriting with a blank Salesforce value**; edits made in HubSpot are overwritten back on the next sync | | **Prefer Salesforce unless blank** | Primarily Salesforce → HubSpot; when Salesforce is blank, use the HubSpot value | Salesforce (when non-blank) | When Salesforce has a value it overwrites HubSpot; when Salesforce **is blank it does not overwrite**, falling back to HubSpot's value (which can also be back-filled to Salesforce) | | **Don't sync** | None | — | The field mapping exists but is disabled; data syncs in neither direction | ### Key points of each rule **Two-way** - Both sides can edit, changes sync to each other, and conflicts are resolved by last-modified time. - Suitable for fields that both sides maintain and that need to stay current. **Always use Salesforce** - Equivalent to one-way Salesforce → HubSpot; Salesforce is the absolute authority. - **Includes blank overwrites**: when the Salesforce field is blank, it also clears the corresponding HubSpot field. - Suitable for fields whose single source of truth is Salesforce. **Prefer Salesforce unless blank** - The only difference from "Always use Salesforce" is **blank handling**: when Salesforce is blank it **does not overwrite** HubSpot, thereby avoiding accidentally deleting existing HubSpot data with a blank value. - Suitable for fields that are primarily Salesforce-driven but where you want HubSpot to fill in the gaps. **Don't sync** - Temporarily stops syncing a field while retaining the mapping configuration; can be switched back to another rule at any time. > Sync rules are **field-level**: different fields of the same object can use different rules — e.g. Email uses Two-way while some status field uses "Always use Salesforce." The system applies each field's own system of record individually, rather than uniformly across the whole object. --- ## 6. Record Matching and Deduplication - When first establishing the association, HubSpot matches Salesforce Leads / Contacts primarily by **email**: if an existing record is hit, it associates with it; otherwise it creates a new record per the rules (a Lead by default). - Once the association is established, the Salesforce record ID serves as the stable anchor that maintains the correspondence. - The integration tries to avoid creating duplicate records; duplicate data on the Salesforce side must be handled according to Salesforce's own deduplication strategy. --- ## 7. Admission Control (Inclusion List / Selective Sync) - The integration supports mechanisms such as an **Inclusion List** to control which contacts/records participate in sync, rather than syncing all data indiscriminately. - Records that do not meet the admission criteria are not brought into the sync scope. - This helps sync only the target audience (e.g. a specific lifecycle stage or specific source), controlling data volume and quality. --- ## 8. Initial Sync and Ongoing Sync - **Initial sync**: After the integration is connected and mappings are configured, it performs a one-time alignment of existing data on both sides. - **Ongoing / Incremental sync**: Thereafter, whenever a record or field changes on either side, it syncs to the other side in near real time. - Sync runs automatically in the background with some processing latency (typically within a few minutes); it is not strictly real-time. --- ## 9. Sync Health and Monitoring - The integration provides views such as **Sync Health** for checking sync status and identifying records that failed to sync, along with reasons. - Common situations to watch for: field type mismatches (Status=Warning), required-field validation failures, insufficient permissions, unmatched records, etc. - Administrators can use this to troubleshoot and fix sync issues. --- ## 10. Summary The data sync of the HubSpot–Salesforce native integration is built around three layers of concepts: 1. **Object mapping**: Contacts↔Leads/Contacts, Companies↔Accounts, Deals↔Opportunities; the "one-of-two" correspondence between Contact and Lead/Contact is the most special part. 2. **Field mapping**: Connecting HubSpot properties and Salesforce fields field by field, split into Standard and Custom; what is not mapped is not synced. 3. **Sync rules**: Two-way, Always use Salesforce, Prefer Salesforce unless blank, Don't sync — controlling direction and conflict arbitration at the field level, where the only difference between the latter two is "whether a blank value overwrites." Combined with record matching, admission control, initial/ongoing sync, and sync-health monitoring, this delivers controllable, observable data consistency between the marketing side (HubSpot) and the sales side (Salesforce).