HubSpot–Salesforce Integration Field Mapping Playbook

Successful RevOps teams treat the HubSpot–Salesforce (SFDC) connection as a governed data contract, not a switch you flip once. This playbook provides an end‑to‑end approach to designing and maintaining field mappings that keep marketing, sales, and success aligned without creating sync loops, broken reports, or a flood of duplicates. Use it to standardize how data flows, which system is the truth for each attribute, and how to evolve the schema safely as your go‑to‑market grows.

Who This Is For

Revenue leaders, operations managers, solution architects, and admins who need a durable pattern for mapping HubSpot objects and fields to Salesforce and back. If you’ve struggled with conflicting lifecycle statuses, inconsistent lead sources, multi‑touch attribution, or complex account hierarchies, this guide shows the canonical way to design, implement, and govern mappings while keeping reporting trustworthy.

What Good Looks Like

“Good” mapping is unambiguous, documented, and enforced by automation. In practice, that means:

One system of record per field, with clear write permissions and sync direction.
Lifecycle and funnel fields normalize to a single taxonomy across systems.
Picklists stay in lockstep; invalid values are blocked at the edge, not corrected later.
Sync rules prevent loops, race conditions, and accidental overwrites from workflows.

Core Objects and Scope

HubSpot natively syncs Contacts, Companies, Deals, Activities (limited), and some Custom Objects with Salesforce Leads, Contacts, Accounts, Opportunities, and custom entities. Before mapping, define scope:

Which objects will be bi‑directional vs. one‑way?
Do you migrate historical data or begin with “net new” only?
Will you unify to Leads first or route directly to Contacts/Accounts?
How will you map multi‑touch and campaign attribution data?

Make scope explicit in a one‑page Architecture Decision Record (ADR). The mapping you choose should follow from these answers.

Data Contract and Ownership Model

The single most important decision is system of record (SoR) by field. A reliable pattern is:

• Identity and governance fields (record owner, created date, record type) are owned by Salesforce. • Marketing engagement (first touch, last touch, original source, UTMs, subscription preferences) are owned by HubSpot. • Commercial data (forecast category, product line, pricing, stage probabilities) are owned by Salesforce. • Standardized firmographics (industry, employee band, country) are owned by Salesforce, with HubSpot allowed to enrich if mapping preserves master categories.

Document this as a “field ledger” that includes: field name, business definition, allowed values, SoR, sync direction (HS→SFDC, SFDC→HS, or bi‑directional), and conflict resolution policy.

Picklist Strategy and Normalization

Picklists are where integrity breaks. Normalize once, then propagate:

• Create a master value list in Salesforce for lifecycle stage, lead status, deal stage, industry, and region. Treat it as the taxonomy you publish from. • In HubSpot, mirror those values exactly; do not alias silently. If you must display friendly labels, keep the stored values identical. • For any value originating in HubSpot (e.g., content topic), ensure Salesforce has a compatible picklist or text field with validation rules that block unknown values.

Lifecycle and Funnel Alignment

Lifecycle (Subscriber → Lead → MQL → SQL → Opportunity → Customer → Evangelist) must align with Salesforce’s Lead Status and Opportunity stages. A proven approach:

• HubSpot calculates Lifecycle Stage and MQL Date based on engagement and fit scoring. • Salesforce governs Sales Accepted Lead (SAL) and SQL by converting Leads, creating Contacts and Opportunities. • HubSpot reads back SAL/SQL dates from Salesforce and locks the stage from moving backward.

This creates a crisp handoff that prevents “Stage ping‑pong.”

Identity, Matching, and Merge Rules

Identity rules drive mapping quality. Recommended baseline:

• Contacts: email is primary key; if missing, use Salesforce Contact ID as the bridge key and restrict HubSpot creation. • Companies: website domain is primary; backfill with SFDC Account ID for multi‑domain customers. • Leads: guardrails to avoid creating Leads for existing Contacts with the same email; HubSpot should append engagements to the Contact when possible.

Define merge precedence: Salesforce master merges win for Contacts and Accounts; HubSpot merges are allowed only for pre‑qualification records. Log merges and sync results for 90 days.

Mapping Patterns by Object

Contacts ↔ Leads/Contacts

• Contact Status (HubSpot) ↔ Lead Status (Salesforce) is one‑way from Salesforce after SAL; before SAL, HubSpot can promote status. • Lifecycle Stage (HubSpot) is HS→SFDC for Subscriber/Lead/MQL; becomes read‑only after SAL. • Original Source / UTMs (HubSpot) are HS→SFDC one‑way, immutable after first write.

Companies ↔ Accounts

• Account Tier (SFDC) is SFDC→HS; HubSpot uses it for routing and personalization. • Industry and Employee Range are SFDC→HS; allow HubSpot enrichment only if values map to master taxonomy.

Deals ↔ Opportunities

• Deal Stage (HubSpot) mirrors Opportunity Stage (SFDC); Salesforce is the SoR post‑creation. • Forecast Category, Amount, Close Date, Probability are SFDC→HS. • Marketing Influence fields (first/last touch campaign, assisted touch count) are HS→SFDC.

Preventing Sync Loops and Overwrites

Loops happen when both systems write the same field on update. To avoid:

Make every field either authoritative in HS or SFDC, not both.
Apply update windows: for example, HubSpot is allowed to write Lead Status only until SAL.
Use field‑level validation in Salesforce to block unrecognized values and retrograde statuses.
In HubSpot, add workflow guards that check a “Locked by Salesforce” boolean before writing.

Change Management and Versioning

Treat mapping as code:

• Store the field ledger in version control with ADRs. • Propose changes through a weekly RevOps change board. • Pilot in a sandbox: replicate core sync, run a week of shadow logging, and compare reports. • Release with a migration plan for values and backfills; never flip picklists without a translation script.

Validation, Reconciliation, and Audits

You cannot govern what you cannot see. Build a lightweight audit routine:

Daily: counts of created/updated Contacts, Leads, Companies, and Opportunities on both sides, plus error buckets.
Weekly: sample a cohort of 100 matched records; compare top 20 mapped fields and log mismatches.
Monthly: reconcile funnel counts (MQLs, SALs, SQLs, opportunities created) across systems and investigate drift >3%.

Example Mapping Ledger (Narrative)

To make the ledger tangible, imagine these entries described in prose:

• Email (HubSpot Contact) is the primary contact key; HS→SFDC on create; immutable once set. Salesforce can’t overwrite. • Lead Source (HubSpot Original Source) is HS→SFDC one‑way; allowed values are paid_search, organic_search, direct, referral, paid_social, email, event, other. • Lifecycle Stage is HS→SFDC until SAL; once Lead Status ∈ {Working, Qualified}, SFDC→HS to prevent regression. • Opportunity Stage is SFDC→HS only; HubSpot reads but never writes post‑creation.

Rollout Plan

Plan your rollout in three waves:

Baseline: freeze picklists, publish the ledger, lock fields with conflicting writes.
Pilot: enable scoped bi‑directional sync for Contacts and Companies; keep Deals/Opportunities read‑only to HubSpot.
Full: expand to Deals and attribution writes; enable automated audits and error routing to RevOps Slack.

Risks and Mitigations

Duplicate creation on form fill: block if email exists in Salesforce; append as activity.
Attribution drift: lock original source fields; only calculate once per contact.
Unbounded picklist growth: restrict values; require change board approvals.
Sync thrash from workflows: add “Locked by Salesforce” flags and time‑boxed write windows.

KPIs and Reporting

Measure what the mapping enables, not just the mapping itself. Track time to SAL from MQL, SQL acceptance rate, opportunity creation rate, influenced revenue by channel, and field mismatch rate under 1%. Use a “Funnel Parity” report: if HubSpot and Salesforce disagree by more than 3% on any funnel count, raise an alert and investigate mapping drift.

Operating Model and RACI

Assign clear responsibilities: RevOps owns the ledger and audits; Marketing Ops owns UTMs and attribution logic; Sales Ops owns Lead Status and Opportunity stages; Data Engineering supports transformations and backfills; Security reviews PII handling and consent sync. Publish a 2‑page RACI and keep it close to the ledger.

FAQ

Should we sync Leads or only Contacts?

If your sales motion relies on Leads in Salesforce, sync both. Otherwise, prefer Contact‑only models to reduce conversion noise. The key is to publish explicit conversion rules and prevent duplicate Contact creation during Lead conversion.

Can Lifecycle Stage ever move backward?

Not automatically. Lock stages from regressing. If you need to correct a bad stage, apply a one‑time administrative backfill with a note in the ledger and a timestamp.

How do we handle multi‑domain accounts?

Use Salesforce as the company SoR and allow multiple website domains to roll up to the same Account via a related list. In HubSpot, maintain a canonical “Account GUID” from Salesforce to avoid accidental company splits.

What’s the safest way to add a new picklist value?

Add to Salesforce first, publish to the ledger, then mirror in HubSpot. Deploy a translation step for historic data if you’re consolidating values.

How do we stop marketing workflows from overwriting sales statuses?

Gate HubSpot writes behind a boolean such as “Locked by Salesforce.” After SAL, prevent HubSpot from updating status or lifecycle fields and enforce the lock with if/then guards.

Where should attribution fields live?

Calculate first/last touch and assisted touch counts in HubSpot. Write immutable first‑touch and last‑touch fields to Salesforce once, then keep them read‑only.

What about custom objects?

Treat each custom object like a small domain: publish a sub‑ledger that defines keys, parent relationships, and allowed writes. Pilot in a sandbox and add to the main ledger only after a clean audit.