Field Mapping and Sync Rules for HubSpot ↔ Salesforce: Prevent Duplicates, Preserve History

Published by Bles Software, a custom software and AI company based in Yehud-Monoson, Israel, building web apps, AI agents and API integrations for clients in Israel, the US, the UK and the EU.

Field mapping is where most HubSpot–Salesforce integrations drift. It’s tempting to mirror everything, only to discover that fields are ambiguous, picklists don’t match, duplicates multiply, and users lose trust when their notes are overwritten. This playbook defines a pragmatic, versioned mapping strategy that prevents duplicate creation, preserves history, and keeps reporting coherent across both systems.

Goals and non‑goals

Goals: Ensure each mapped field serves a routing, reporting, or compliance purpose; make sync directions explicit and auditable; and protect sales‑authored data from accidental overwrite. Non‑goals: mirroring every field, enabling ad‑hoc back‑and‑forth editing, or using mapping as a substitute for lifecycle and routing design.

A minimal canonical map to start

Begin with a “minimal viable map.” On people objects (Lead/Contact ↔ Contact in HubSpot), include identity (email, first/last name), ownership (owner, territory), lifecycle markers (MQL timestamp, SAL timestamp), marketing context (UTM original/latest, campaign key), and sales context (SAL acceptance flag, rejection reason). On companies/accounts, sync name, website domain, country/region, industry, employee band, and the owning business unit. On campaigns, sync a canonical key and membership status.

Avoid wide bi‑directional maps early. Every bi‑directional field is a risk. Favor one‑way by default and add bi‑directional fields only when a clear business need emerges and you’ve defined conflict resolution and auditability.

Documenting the map: a living specification

For each field, document:

Label and API names: both systems’ API names so engineers can validate logs and errors.

Purpose and owner: which team owns the field’s definition and who approves changes.

Source of truth and direction: HubSpot → Salesforce, Salesforce → HubSpot, or bidirectional.

Transformations: normalization (e.g., uppercase country codes), parsing (e.g., UTM breakdown), or enrichment rules.

Impact and dependencies: downstream reports, routing rules, or validation constraints.

Versioning: a change log entry with date, reason, and backfill plan.

Keep this specification in version control. Treat it like code. Review pull requests for field changes just as you would application logic.

Identity fields: email, external IDs, and merging

Use email as the marketing identity and introduce a stable external ID once a record is accepted in Salesforce. Sync the external ID back to HubSpot so every update carries lineage. For companies, normalize website domains (lowercase, strip prefixes) and maintain a domain alias table for conglomerates and rebrands.

Merging should preserve the oldest Salesforce Contact (or Account) as the survivor. HubSpot engagement can be rolled up by copying last‑touch marketing fields rather than brute‑force overwriting.

Picklists and enumerations: enforce parity

Picklist parity prevents sync errors and reporting drift. Align allowed values and labels. Maintain a master list in the repository and sync changes to both systems before changing automations. Don’t rely on “create new values” on the fly—this spawns zombie values that fragment reporting.

Timestamps and snapshots

Use dedicated timestamp fields for lifecycle and attribution snapshots. Snap MQL in HubSpot and SAL/SQL in Salesforce. For attribution, snapshot first‑touch and last‑touch at the moments of SAL and Opportunity creation. Never overwrite a snapshot; create new snapshots if business logic changes so analysts can reconstruct history.

Sync directions and conflict policy

Identity: Salesforce → HubSpot for name, title, phone once a record is sales‑owned. HubSpot → Salesforce for net‑new creation and marketing context. Bidirectional only when update discipline is high and you need in‑place edits from both sides.

Lifecycle: HubSpot → Salesforce for MQL; Salesforce → HubSpot for SAL/SQL. Timestamps are one‑way; status booleans are derived.

Attribution: HubSpot → Salesforce for UTMs and Campaign keys. Snapshots taken in Salesforce are not overwritten by later marketing activity.

Owner and territory: Salesforce → HubSpot. Lock owner after acceptance and avoid marketing overwrites.

Conflict policy: last‑writer‑wins is acceptable only on non‑critical fields. For critical fields (owner, status, account name), the system of record always wins and the other direction is blocked.

Error classes and recovery strategies

Three error classes cover 90% of issues:

Validation failures: picklist mismatches, missing required fields. Fix by aligning picklists and adding guardrails in HubSpot forms or workflows to populate missing fields before sync.

Permission and visibility errors: integration user lacks object/field access. Fix by granting least‑privilege access and testing in sandbox first.

Duplicate conflicts: matching rules deny creation. Fix by queuing for merge, then retrying, or by linking to the existing record via external ID lookup before sync.

Observability for the map

Measure:

Publish a weekly “map health” report. Use it to prioritize cleanups and to validate the impact of changes.

Backfills and replays

Every field change that impacts reporting requires a backfill plan. Execute backfills in small batches during off hours and monitor error rates closely. For attribution snapshots, create new snapshot fields rather than rewriting old ones. For ownership changes, avoid mass overwrites that reset SLAs; write surgical backfills that respect history.

Change management: requests, reviews, and releases

Create a simple request template: the field requested, the business question it answers, the reports it will affect, and the proposed sync direction. Require approvals from Marketing Ops and Sales Ops for lifecycle‑adjacent fields. Release changes on a schedule with a rollback plan defined.

Example starter map (conceptual)

People Email (HubSpot → Salesforce): create and update. First/Last Name (Salesforce → HubSpot after SAL): protect sales edits. Lifecycle: MQL Date (HubSpot → Salesforce), SAL Date (Salesforce → HubSpot), Recycle Reason (bidirectional only if identical codes exist). Owner/Territory (Salesforce → HubSpot): authoritative assignment. Attribution: Original/Landing UTMs (HubSpot → Salesforce), Last‑Touch UTM at SAL (HubSpot → Salesforce).

Companies/Accounts Name, Website (HubSpot create; Salesforce master post‑creation → HubSpot). Industry, Employees, Region (Salesforce → HubSpot once set).

Campaigns Campaign Key (HubSpot ↔ Salesforce): same key both sides. Membership Status (HubSpot → Salesforce): mapped to canonical picklist.

Governance and the cost of complexity

Every additional field increases maintenance cost. Resist pressure to sync “just in case.” Use reporting prototypes to validate that a field actually changes a decision before adding it to the map. Unused synced fields are a tax on performance and reliability.

FAQ

How many fields should we sync at launch?

Often 25–40 well‑chosen fields are enough for a robust first release. Expand deliberately with versioned changes and a weekly review cadence.

What’s the safest policy for names and titles?

Default to Salesforce → HubSpot after SAL to protect sales edits. If you need marketing edits, create separate “Marketing Title” or “Persona Title” fields to avoid stomping on what reps maintain.

How do we deal with picklist drift?

Maintain a master list in version control, sync it to both systems before enabling workflows, and disable free‑text or “create values on new data.” Periodically scan for rogue values and clean them.

Can we bidirectionally sync lead score?

You can, but it’s rarely useful. Use HubSpot scores for marketing workflows and expose them read‑only in Salesforce. If sales wants to contribute, add a separate “Sales Fit Score” field in Salesforce with a one‑way sync back to HubSpot for segmentation.

How should we treat attribution snapshots when logic changes?

Create new snapshot fields with a version suffix and deprecate the old ones. Don’t rewrite history—preserve the old snapshots for comparability.

More RevOps Playbooks from Bles Software