How to Connect Salesforce to HubSpot: A Complete Integration Guide

Running Salesforce and HubSpot in parallel is one of the most common revenue stack architectures in B2B SaaS and mid-market companies. Sales lives in Salesforce — deep workflow customization, territory management, complex opportunity tracking. Marketing lives in HubSpot — email nurturing, attribution, content performance. The integration between them is the connective tissue that determines whether your revenue data is usable or a mess of conflicting records.

This guide covers the complete integration process: prerequisites, the native connector setup, field mapping decisions, the most common data sync failures, how to think about lifecycle stage and opportunity mapping, alternative integration approaches, and the strategic question of whether a dual-CRM architecture is actually right for your organization.

Before You Start: Prerequisites and Pre-Work

The setup steps for the native connector are straightforward. The failures happen before setup begins — in data state and permission configuration. Before touching the integration UI, verify all of the following.

Platform Requirements

HubSpot side: Professional or Enterprise on any Hub (Marketing, Sales, Service, or Operations). The native Salesforce connector is not available on HubSpot Starter. Operations Hub Professional ($720/month) or Enterprise ($2,000/month) unlocks additional sync capabilities including more custom field mappings and better custom object support.

Salesforce side: Professional, Enterprise, Performance, Unlimited, or Developer edition with API access enabled. Salesforce Essentials does not include API access and cannot support the native connector. Confirm API access is active in your Salesforce org before proceeding.

Create a Dedicated Salesforce Integration User

Do not use a named user's credentials to authenticate the integration. Create a dedicated Salesforce integration user — a service account — specifically for HubSpot's API access. This user account needs the following permissions:

• API Enabled — required for HubSpot to connect to the Salesforce API at all
• View Setup and Configuration — required for connector package installation
• Modify Metadata — required if you use the HubSpot Visualforce embed on Lead/Contact page layouts
• Full Read/Create/Edit/Delete on Leads, Contacts, Accounts, Opportunities, Tasks, Campaigns
• View All and Modify All on synced objects — required to bypass private sharing models so HubSpot can see all records, not just the ones the integration user owns
• Download AppExchange Packages and Customize Application — required for the managed package installation
• Password Never Expires — critical. If the integration user's password expires, the entire sync stops until credentials are updated in HubSpot's integration settings

Using a dedicated integration user also means that when a named employee leaves the organization, the sync does not break because their account was deprovisioned.

Clean Your Salesforce Data Before Connecting

The native connector deduplicates contacts and leads by email address. If your Salesforce org contains the same person as both a Lead and a Contact with different email addresses, the connector will not recognize them as duplicates. It will create two separate HubSpot contact records and sync both indefinitely.

Before enabling the sync, run a deduplication audit on your Salesforce contacts and leads. At minimum: identify contacts with no email address, leads with duplicate email addresses within the Leads object, and cases where the same person exists in both Leads and Contacts with different emails. The cost of a one-time data cleanup before integration is always lower than the cost of correcting a contaminated HubSpot contact database after the fact.

Step-by-Step: Setting Up the Native Connector

The integration setup begins and ends in HubSpot. You will complete steps in your Salesforce org at several points throughout the process, but HubSpot owns and drives the connector installation.

Step 1: Install the HubSpot Managed Package in Salesforce

In HubSpot, go to Settings → Integrations → Connected Apps and search for Salesforce. Click Connect Salesforce. HubSpot will prompt you to install its managed package in your Salesforce org via an AppExchange link. Log in with your Salesforce integration user credentials (not your personal admin credentials) and install the package for all users or specific profiles, depending on which Salesforce users you want to have visibility into the HubSpot Embed panel.

The managed package adds the HubSpot Intelligence tab and several custom fields to Salesforce Lead and Contact layouts. These fields carry HubSpot activity data — email opens, form submissions, marketing qualification scores — into Salesforce so sales reps see marketing engagement context without leaving their CRM.

Step 2: Authenticate the Connection

Back in HubSpot, complete the OAuth authentication flow using your Salesforce integration user credentials. HubSpot stores these credentials and uses them for every API call the sync makes. After authentication, HubSpot runs an initial connection check to verify API access and object permissions. If permission errors appear at this step, return to your integration user profile in Salesforce and add the missing permissions before proceeding.

Step 3: Configure Sync Direction and Object Scope

In HubSpot's Salesforce integration settings, you set the sync direction for each object type. The available options are bidirectional, HubSpot to Salesforce only, or Salesforce to HubSpot only. The default and most common configuration is bidirectional for Contacts/Leads and Opportunities/Deals, with activity sync enabled for Tasks.

Define the scope of which Salesforce records enter the sync. You have three options:

• All records: Every Salesforce contact, lead, and account syncs to HubSpot. This is appropriate if HubSpot is your marketing system of record and you want complete visibility across your installed base.
• Salesforce inclusion list: Only records in a specified Salesforce report or campaign sync to HubSpot. Use this when your Salesforce org contains historical or non-addressable records you do not want to contaminate your HubSpot database.
• HubSpot-originated records only: Only records that originated in HubSpot sync to Salesforce. This is rarely the right choice for a mature dual-CRM setup but is sometimes used during phased rollouts.

Step 4: Map Fields Between the Two Systems

Field mapping is where most integration configurations break down. HubSpot provides a visual field mapping interface in integration settings. Default mappings are pre-configured for the most common standard fields — First Name, Last Name, Email, Phone, Company, and key Opportunity fields. Review every default mapping before the sync goes live.

Key decisions to make at the field mapping stage:

• Sync direction per field: For each field mapping, you choose bidirectional, Salesforce to HubSpot only, or HubSpot to Salesforce only. Bidirectional is appropriate for fields where both teams write data. One-directional is appropriate for fields that only one team should own — for example, the Salesforce Opportunity Owner should typically flow to HubSpot read-only, not be overwritable from HubSpot.
• Conflict resolution: When both systems have a value for the same field and they differ, HubSpot needs to know which system wins. You configure this as either "most recently updated wins" or "always use [HubSpot/Salesforce] value." Be explicit about which system is the system of record for each field category — do not rely on defaults.
• Picklist alignment: If Salesforce and HubSpot use different dropdown values for the same conceptual field (Industry, Lead Source, Deal Stage), the sync will fail or create blank values for records where the values do not match. Audit your picklist values in both systems and align them before enabling the sync.
• Required fields in Salesforce: If a Salesforce field is required and the corresponding HubSpot record does not have a value, the sync will fail with a validation error. Either make the field not required in Salesforce, provide a default value, or ensure HubSpot always populates it before records are eligible to sync.

Step 5: Configure Lifecycle Stage and Lead Status Sync

This step requires specific attention because lifecycle stage and lead status do not map cleanly. In HubSpot's integration settings, enable Automatic lifecycle stage transitions. This setting tells HubSpot to update a contact's lifecycle stage based on actions that happen on associated Salesforce records — specifically, promoting a contact to Customer when their associated Salesforce opportunity is marked Closed/Won.

For this to work, you also need to enable Account sync (so Salesforce Accounts sync to HubSpot Companies) and optionally Lifecycle stage sync (so lifecycle stage changes apply to all contacts associated with the same company, not just the primary contact on the deal). The three settings work together; enabling only one of them produces partial behavior that is difficult to debug.

Step 6: Enable Opportunity-to-Deal Sync

In the Salesforce integration settings, navigate to the Opportunities section and enable sync. When active, Salesforce Opportunities sync to HubSpot Deals and vice versa. Key configuration decisions here:

• Decide which system owns pipeline stage values. The safest default is Salesforce-to-HubSpot only for Deal Stage, so that Salesforce remains the authoritative pipeline record and HubSpot reflects it.
• Map Close Date, Amount, and Owner fields explicitly. These are the fields most likely to have conflict resolution problems in a bidirectional setup.
• Be aware: HubSpot does not deduplicate deals against Salesforce opportunities. A new deal created in HubSpot will create a new opportunity in Salesforce. Establish a clear rule for which system originates deals to prevent phantom pipeline.

Step 7: Test in a Sandbox Before Going Live

If your Salesforce org has a sandbox environment, connect the integration to the sandbox first. Create test contact records in both systems, trigger updates, and verify that field values sync correctly in both directions. Pay specific attention to edge cases: a record created in HubSpot that has no match in Salesforce, a Salesforce lead that converts while the sync is active, and a contact with a missing required Salesforce field. Address each failure mode before connecting to production.

Step 8: Monitor the Sync Error Log

After going live, monitor the Salesforce integration sync error log in HubSpot (Settings → Integrations → Salesforce → Sync Errors) for the first two weeks. Common error categories include validation rule failures, permission errors on newly created record types, and duplicate detection conflicts. Most early errors are traceable to field mapping gaps or Salesforce validation rules that were not accounted for during pre-work. Address each error type systematically rather than ignoring low-volume errors — they typically indicate a class of record that will accumulate problems over time.

The Lifecycle Stage and Lead Status Mapping Problem

The most common source of RevOps confusion in a dual-CRM environment is the mismatch between HubSpot Lifecycle Stage and Salesforce Lead Status. Understanding the structural difference makes the mapping decision obvious.

The key consequence: when a Salesforce Lead converts to a Contact, the Lead object is deactivated and a new Contact (and optionally an Account and Opportunity) is created. In HubSpot, this same person exists as a single contact record throughout their entire lifecycle. The conversion event in Salesforce can create a duplicate in HubSpot if the converted Contact has even a slightly different email than the existing HubSpot record.

The recommended mapping approach is to treat HubSpot Lifecycle Stage as the marketing system's funnel signal and Salesforce Lead Status as the sales qualification signal, and connect them through workflow automation rather than direct field mapping. Specifically:

• HubSpot MQL status triggers a Salesforce Lead creation or status update via the sync
• Salesforce Lead Status "Qualified" or lead conversion triggers a HubSpot Lifecycle Stage update to SQL via the automatic transition setting
• Salesforce Opportunity Closed/Won triggers HubSpot Lifecycle Stage to Customer via the automatic transition setting

This approach avoids the trap of mapping HubSpot Lifecycle Stage directly to Salesforce Lead Status (which only exists pre-conversion) and instead uses Salesforce record state changes as the authoritative signal for HubSpot funnel progression.

Integration Approach Comparison

The native HubSpot-Salesforce connector is not the only way to connect the two systems. Three approaches are commonly used, each with a different operational profile.

Native Connector

The right default choice for the majority of B2B revenue teams. Covers standard objects, provides a visual mapping UI, installs the HubSpot Embed panel inside Salesforce so reps see marketing engagement data in context, and syncs every 15 minutes. Limitations: custom object sync is minimal, the underlying API version is relatively dated (v45), and true real-time sync is not available. For teams syncing under 100,000 records with standard object requirements, the native connector is sufficient and the right starting point.

Zapier

Event-driven and one-directional by design. A Zap fires when a trigger condition occurs in System A and creates or updates a record in System B — but changes subsequently made in System B do not automatically propagate back to System A without a second Zap in the opposite direction. In practice, this means Zapier-based Salesforce-HubSpot integrations degrade into eventually-inconsistent data rather than a synchronized view. Zapier is appropriate for specific lightweight automations (send a Slack notification when a Salesforce opportunity is created, add a HubSpot contact to a Salesforce campaign when they fill a form) but should not be the primary integration mechanism for a live dual-CRM environment.

Middleware Platforms

Platforms like Stacksync, Boomi, MuleSoft, and Workato provide near-real-time bidirectional sync, custom object support, complex transformation logic, and higher API throughput than the native connector. The cost is substantially higher than the native connector and requires RevOps or engineering resources to configure and maintain. The middleware path is justified when your revenue architecture requires custom object sync, you need sub-minute latency, your record volume exceeds 100,000 syncing contacts, or you have complex data transformation requirements (merging fields from multiple Salesforce objects into a single HubSpot property, for example).

Custom API Integration

Both Salesforce and HubSpot expose comprehensive REST APIs. A custom integration built against both APIs gives you complete control over sync behavior, field mapping, conflict resolution, and latency. The cost is ongoing engineering ownership — someone needs to maintain the integration when either platform updates its API, and someone needs to handle sync failures. This path is appropriate for organizations with dedicated RevOps engineering capacity and requirements that no off-the-shelf connector satisfies.

Common Data Sync Failures and How to Prevent Them

After the integration is live, several failure patterns recur consistently across organizations. Understanding them before they happen is more efficient than diagnosing them after they have contaminated months of data.

The Lead-Contact Duplicate Problem

Salesforce's data model separates people into two objects: Leads (pre-conversion) and Contacts (post-conversion). HubSpot treats all people as Contacts from the start. When the connector syncs, a person who exists as a Lead in Salesforce creates a HubSpot Contact. When that Lead converts in Salesforce and becomes a Contact, the connector creates a second HubSpot Contact for the same person if the email addresses differ even slightly, or if the converted Contact record is treated as a new record by the sync logic.

Prevention: Enforce email address standardization in Salesforce before enabling the sync. Consider setting up a Salesforce workflow rule that automatically populates the Contact email from the Lead email on conversion. Review HubSpot's duplicate management settings and configure duplicate detection rules that catch near-matches rather than exact matches only.

Phantom Deals from Bidirectional Opportunity Sync

When opportunity sync is bidirectional and both teams are creating records, you can end up with Salesforce opportunities that were created by the sync duplicating HubSpot deals that were themselves created by a previous sync. The connector does not deduplicate deals against opportunities — a new HubSpot deal will always create a new Salesforce opportunity, regardless of whether a matching opportunity already exists.

Prevention: Establish a clear origination rule: either all deals are created in Salesforce and read in HubSpot, or all deals are created in HubSpot and pushed to Salesforce. Avoid a setup where both teams create revenue records independently in their respective systems.

Picklist Value Mismatches Silently Blanking Fields

If a Salesforce field contains a picklist value that does not exist in the mapped HubSpot property, the sync will either fail the record (generating a sync error) or import the record with a blank value in that field. Blank values are often worse than errors because they are invisible until you run a data audit. Mismatched Industry values, Lead Source values, and Deal Stage mappings are the most common sources of this problem.

Prevention: Before enabling the sync, export the full picklist values from every mapped field in both systems and align them. Either add missing values to the HubSpot property or the Salesforce field so every possible input value has a valid target.

API Limit Consumption in Shared Salesforce Orgs

Every sync operation between HubSpot and Salesforce consumes Salesforce API calls. On Salesforce Professional, the default API limit is 100,000 calls per 24-hour period — a figure that sounds large but can be consumed quickly when the HubSpot connector runs every 15 minutes against a large record set, especially during initial sync when all records are processed. Monitor your Salesforce API usage in Setup → System Overview after enabling the integration and confirm you are not approaching the daily limit. If you are, consider limiting initial sync scope or requesting an API limit increase from Salesforce.

When to Run Dual CRM vs. Consolidate

The strategic question behind the integration setup is whether a dual-CRM architecture is the right long-term choice for your organization, or whether you are building a bridge between two systems that should eventually become one.

The dual-CRM setup is architecturally justified when:

• Sales has deep Salesforce customization that is genuinely irreplaceable. Years of territory management rules, CPQ configuration, custom approval workflows, industry-specific compliance fields, and Salesforce-native integrations with ERP or billing systems represent real migration risk and cost. If the Salesforce configuration is the core operational layer for your sales team, the migration cost to HubSpot or any other CRM is not trivial.
• Marketing requires HubSpot's native content and attribution capabilities. HubSpot's email marketing, landing page builder, SEO tools, and attribution reporting are materially ahead of Salesforce Marketing Cloud for the majority of non-enterprise marketing teams in terms of implementation speed and operational simplicity. If marketing is the growth engine and marketing relies on HubSpot's native toolset, the case for running HubSpot in parallel is real.
• The two functions have explicitly different data access and ownership requirements. A regulated-industry company where sales data must stay within Salesforce for compliance reasons while marketing operates on a separate system is a legitimate architectural choice, not a workaround.

The dual-CRM setup is not justified when:

• It exists because marketing and sales cannot agree on a shared system. This is an organizational problem, not an architectural one. Two systems that both teams half-use will produce worse data quality than one system that both teams fully commit to.
• The integration is perpetually broken and nobody owns it. The integration requires ongoing ownership. If your RevOps function does not have someone who monitors sync errors, owns field mapping decisions, and understands both platforms' data models, the integration will drift into an unreliable state within six months.
• The total cost of maintaining two platforms plus the integration exceeds the migration cost. Salesforce's five-year total cost of ownership runs approximately 2.4× higher than HubSpot when accounting for implementation, licensing, and admin overhead. For organizations below $50M ARR without complex Salesforce customizations, consolidating to a single platform is often the lower-cost, lower-complexity choice.

Ongoing Maintenance: What Goes Wrong After Go-Live

A Salesforce-HubSpot integration is not a project with a completion date. It is an ongoing operational system that degrades without active ownership.

Monitor the sync error log weekly. HubSpot's sync error dashboard shows every record that failed to sync and the reason why. Errors are categorized by type — permission errors, validation failures, duplicate conflicts, API limit breaches — and each category has a distinct resolution approach. Teams that review the error log weekly catch issues before they accumulate; teams that check it quarterly often find hundreds of failed records that have created data quality gaps across both systems.

Audit field mappings when either platform updates. Salesforce and HubSpot both release regular updates that add new fields, change picklist values, or modify object structures. A field mapping that was correct at integration setup can break silently when either platform introduces a structural change. Build a quarterly field mapping review into your RevOps maintenance calendar.

Test the sync after any Salesforce configuration change. New validation rules, changed page layouts, modified sharing rules, and new required fields in Salesforce can all break sync behavior for specific record types. After any Salesforce admin makes a configuration change, run a test sync against a sample of records and check the error log before assuming the change had no integration impact.

Review the integration user's permissions after any Salesforce permission set changes. If your Salesforce admin restructures profiles or permission sets and inadvertently removes a permission from the integration user, the sync will fail for all records affected by that permission. The integration user should be on a dedicated permission set that is explicitly excluded from broad permission restructuring.

Frequently Asked Questions