RevOps Playbook: Field Mapping Between HubSpot and Salesforce

Field mapping is the integration’s contract. It determines which system owns each value, who can edit it, and how changes move between platforms without creating loops or silent data loss. This playbook provides a rigorous approach to defining, documenting, and maintaining field mappings across Contacts/Leads, Companies/Accounts, and Deals/Opportunities. It includes governance patterns that help your RevOps practice scale while keeping reporting consistent and automation predictable.

If you’ve ever experienced competing “lead status” fields, overwritten lifecycle stages, or mismatched pipeline stages between systems, the root cause is usually an unclear mapping contract. We will fix that by designing maps that are explicit, versioned, and testable. The goal is fewer surprises, faster reinforcement learning across teams, and more trustworthy dashboards.

Who This Is For

This playbook is for RevOps and Marketing Ops teams who administer HubSpot and Salesforce, and who are responsible for funnel reporting, pipeline handoffs, and attribution. We assume you can create and edit fields in both systems and that you can coordinate with IT or data engineering when advanced identity or backfills are needed.

Desired Outcomes

A versioned “Field Dictionary” stored in Git with owners, sync direction, value constraints, and tiebreakers.
Fewer sync errors and fewer manual corrections by sales and marketing users.
Lifecycle and pipeline reporting that is resilient to process changes.

Prerequisites

Documented funnel definitions (MQL, SAL, SQL) and a single authoritative lifecycle model.
Agreement on campaign, channel, and UTM taxonomies.
Clear ownership over account territories and person routing.

Core Principles

Field maps should reflect business intent first, then tool limitations. Keep these principles in mind:

One Owner Per Field

Every mapped field declares a single system-of-record. If bi-directional edits are required (e.g., title, phone), specify a tiebreaker such as “last modified wins” or “Salesforce wins.”

Validate Values at the Edge

Use picklists for categorical fields and normalize before sync. Reject invalid values at creation/update time, not after an error breaks reports.

Prefer Idempotent Writes

Structure workflows to write a field only if it will change the business state. Avoid flapping between values that trigger unwanted automations.

Contact/Lead Field Mapping

The person object is where most value drift happens, so design these fields with extra care.

Identity and Communication

Email (primary): single source-of-truth in HubSpot for inbound capture; mirrored to Salesforce on create and protected from unwanted overwrites.
Email Opt-Out: regulatory record-of-truth in HubSpot; mirrored to Salesforce for visibility.
Phone/Mobile: bi-directional with a tiebreaker; sales edits should not be lost.

Qualification and Lifecycle

Lifecycle Stage (HubSpot) ↔ Lead Status (Salesforce): define a mapping table aligned to your funnel. Only one side should drive changes; the other represents the same concept using local picklists.
Lead Source and UTM fields: mastered in HubSpot at first touch; mirrored to Salesforce as locked-down picklists.

Ownership

Contact/Lead Owner: assignment may originate from HubSpot automation or Salesforce territories. If both are in play, make Salesforce the tiebreaker and mirror owners back to HubSpot.

Company/Account Field Mapping

Align the company/account entity to avoid split engagement and routing mistakes.

Identity and Domain

Domain (Company Website): authoritative in HubSpot for inbound; validated and mirrored to Salesforce.
External Account ID: create a shared, immutable identifier for deterministic matching across tools and warehouses.

Firmographics and Segmentation

Industry, Employee Count, Revenue Band: mastered by enrichment + RevOps; mirrored with controlled picklists on both sides.
Account Owner: authoritative in Salesforce; mirrored back to HubSpot for routing and ABM programs.

Deal/Opportunity Field Mapping

Pipeline health depends on stage and forecast alignment.

Core Pipeline Fields

Stage, Amount, Close Date, Forecast Category: mastered in Salesforce; mirrored to HubSpot for attribution and marketing reporting.
Primary Campaign Association (Salesforce): required for attribution; sync back to HubSpot to complete multi-touch models.

Marketing Influence

Campaign Member Status and Influenced Campaigns: synced back into HubSpot for credible attribution across the buying committee.

Implementation Steps

Use a deliberate rollout to reduce risk and surface assumptions early.

Draft the Field Dictionary: list every mapped field with owner, direction, picklist values, and tiebreaker.
Validate with stakeholders: review lifecycle, routing, and pipeline teams.
Configure picklists and validation rules: enforce value integrity at create/update time.
Implement mappings in a sandbox: test bi-directional cases and error handling.
Migrate to production with read-only monitoring for a pilot team before full rollout.

Testing and Monitoring

Bake tests into your RevOps rhythm. For each field category, create QA records that exercise value changes from both systems. Monitor error logs, null spikes, and unexpected value drift weekly during rollout and monthly thereafter. Keep a “known issues” section in your repo and address them with small, atomic changes.

Change Management and Versioning

Treat mapping updates like application code. Require pull requests for every change, include justification and downstream impact, and tag releases when deployed. Maintain a rollback plan (e.g., revert a mapping file, disable an offending workflow) and simulate the rollback in sandbox at least once per quarter so the team stays fluent.

Anti-Patterns to Avoid

Bi-directional lifecycle fields without tiebreakers.
Free-text fields for categorical reporting (e.g., lead source) that undermine attribution.
Turning on routing automation before picklists and validations are locked.
Mapping the same concept to multiple fields with different names.

FAQ

How do we document the mapping without getting lost in spreadsheets?

Store a human-readable Field Dictionary (YAML/JSON + Markdown) in Git. Include owner, direction, allowed values, and tiebreaker. Link to this doc in both admins’ notes so it’s discoverable.

What if sales needs to correct enrichment values?

Let sales edits win for people fields that are regularly corrected (title, phone). For company firmographics, update only when empty or when the enrichment confidence is significantly higher than the current value.

Can we keep both Salesforce Lead and Contact in sync with HubSpot Contacts?

Yes, but document conversion rules. Decide whether HubSpot creates Salesforce Leads first or Contacts directly. Ensure email and external IDs keep identity consistent across conversions.

How do we prevent loops from workflows that read/write the same field?

Use idempotent updates: only write when values actually change. Add guard fields to short-circuit repetitive automations. Test reciprocal workflows together in sandbox before production.

What metrics indicate mapping success?

Low sync error rates, stable picklist distributions, reduced manual edits, accurate attribution fields on opportunities, and consistent lifecycle transitions across systems.