Salesforce HubSpot Integration: Setup, Sync Rules and What Breaks

The Salesforce HubSpot integration is HubSpot’s native connector that syncs contacts, companies, deals, tickets and activities with Salesforce leads, contacts, accounts, opportunities, cases and tasks, checking for changes about every 15 minutes. It needs a HubSpot Professional or Enterprise subscription, a Salesforce edition with API access, and a Salesforce admin to connect it.

The install wizard takes a few minutes. Most of the effort goes into deciding what should sync, in which direction, and what the Salesforce side will reject. This guide follows HubSpot’s and Salesforce’s own documentation, read on October 25, 2026, and links each rule to the page it came from.

What do you need before you connect HubSpot and Salesforce?

Check both sides before you click Install. Every requirement below comes from HubSpot’s install guide.

Requirement	What HubSpot’s documentation says
HubSpot subscription	Professional or Enterprise of Marketing Hub, Sales Hub, Service Hub, Data Hub, Content Hub or Smart CRM
HubSpot permission	Account Access
Salesforce edition	An edition with API access, or Salesforce Professional. Government Cloud works; Group Edition does not
Connecting user	A Salesforce system administrator
Salesforce profile permissions	API Enabled, View Setup and Configuration, Modify All on each object you sync, Download AppExchange Packages, and the Task Type field visible
Extra permissions	Modify Metadata for deal sync and the HubSpot Embed window; Customize Application to install HubSpot Embed
Connections	One Salesforce instance per HubSpot account

Two settings stop more first installs than anything else.

Login IP restrictions. HubSpot connects from dynamic IP addresses, so you cannot allowlist them. If “Enforce IP Restrictions on Every Request” is turned on in Salesforce, the integration cannot connect, according to HubSpot’s install guide.

The integration user. Whatever the connected Salesforce user can see is what HubSpot can sync. If that user has no access to leads, leads will not sync. Use a dedicated integration user rather than a person’s admin account, so the sync does not break when that person leaves. If you replace the user later, the new one needs permissions equal to or greater than the old one’s, in the same production org.

How do you install the HubSpot Salesforce integration?

The steps in HubSpot’s guide:

1. In HubSpot, open the Marketplace icon in the top navigation and choose HubSpot Marketplace.
2. Search for Salesforce and select the app.
3. Click Install. Tick the sandbox box if you are connecting a Salesforce sandbox.
4. Log in with your Salesforce admin credentials. Salesforce sends you back to HubSpot.
5. Work through the setup wizard: which objects sync, how contacts are created, and the field mappings.

Two points from the same guide are easy to miss. First, records do not sync when you finish setup; you import them or wait for a sync trigger. Second, the old Visualforce package is being deprecated, and HubSpot tells you to uninstall it and use HubSpot Embed instead. Admin guides written before 2025, such as Salesforce Ben’s 2023 walkthrough, still describe the Visualforce setup.

Connect a sandbox first if you have one. Turn on contacts only, check a few dozen records, then add companies and deals.

How do HubSpot objects map to Salesforce objects?

HubSpot object	Salesforce object	Notes
Contact	Lead and Contact	HubSpot holds one record per email address. Contact sync is on by default and cannot be turned off
Company	Account	Turn on object sync before you can map fields
Deal	Opportunity	Only deals in HubSpot pipelines mapped to an opportunity record type sync
Ticket	Case	Toggle under Data sync in the integration settings
Activities (emails, calls, meetings, notes)	Task	Synced from the Activities tab
Custom objects	Custom objects	Supported, configured per object

Sources: integration settings, property mapping and deal sync.

The contact settings shape everything downstream. You decide whether new HubSpot contacts become Salesforce leads or contacts. If you choose leads, HubSpot’s settings page advises turning off automatic company creation, or you will get duplicate companies. You can also limit which HubSpot contacts go to Salesforce with an inclusion list, a HubSpot segment. With no segment selected, every HubSpot contact syncs.

Which sync rule should each field use?

Each field mapping gets one of four rules. The definitions are from HubSpot’s property mapping guide.

Sync rule	What it does	Deletions	Use it for
Prefer Salesforce unless blank	HubSpot only writes to Salesforce when the Salesforce field is empty. A Salesforce value always overwrites HubSpot	A Salesforce deletion clears HubSpot	Fields sellers own but marketing may capture first, such as phone or job title
Always use Salesforce	HubSpot never writes to Salesforce	A Salesforce deletion clears HubSpot	Sales-owned fields: account tier, territory, contract dates
Two-way	The most recent value wins	Deletions sync both ways	Fields both teams edit and trust each other on, such as lead status
Don’t sync	Nothing passes either way	No effect	Fields that mean something different in each system

Deal mappings add two more rules, “Always use HubSpot” and “Use HubSpot unless blank”, and these only apply when the deal object syncs two ways, per HubSpot’s deal sync guide.

Four mapping rules cause most surprises:

• Owner is always two-way. Some accounts show “Prefer Salesforce unless blank” for owner, but HubSpot says it can only be mapped two-way, and the owner must match exactly in both systems.
• New mappings do not backfill. Existing values in a new mapping do not sync on their own. You run a manual or bulk resync, or a Salesforce import.
• Field types must match. A HubSpot dropdown maps to a Salesforce picklist, multiple checkboxes to a multipicklist, a number to a double or integer, a date picker to a date or datetime.
• The ceiling is 500 field mappings per object. A bulk resync of company mappings cannot cover more than 200,000 companies at once.

Write the mapping down before you build it: one row per field, with the owner team, the rule and the reason. That sheet is what you will check when a value changes and nobody knows why.

How often does HubSpot sync with Salesforce?

About every 15 minutes, HubSpot checks both systems for new or changed records and syncs what your settings allow, according to its sync triggers page. Some events push a record sooner:

• a form submission, or sales and marketing email sends, opens and clicks (if activity sync is on)
• meetings, calls, notes and tasks logged on a contact (if activity sync is on)
• a property change in HubSpot or a field change in Salesforce, subject to the mapping rule
• a new lead or contact in Salesforce, or a new contact in HubSpot
• an ownership change in either system
• a lifecycle stage change, if automatic lifecycle stage updates are on

Three things do not trigger a sync: updating a Salesforce formula field, changing a field on another record that a formula reads, and removing a lead or contact from an active Salesforce campaign. If a lead score lives in a Salesforce formula field, HubSpot will only see the new value the next time something else on that record changes.

How many Salesforce API calls will the integration use?

Up to four calls per contact. HubSpot’s install guide says a single contact sync “can take up to four API calls per record, but this number can vary.” Every Salesforce org has one shared daily allowance. Salesforce’s API limits documentation sets it for Enterprise and API-enabled Professional orgs at 100,000 calls per 24 hours, plus 1,000 per Salesforce license, plus any API add-ons you buy. Unlimited and Performance orgs get the same 100,000 base plus 5,000 per Salesforce license.

In HubSpot, the Sync Health tab shows the calls used in the last 24 hours, and the “Allocated to HubSpot” field caps how many HubSpot may use. Every other tool connected to Salesforce, such as your routing, enrichment and billing tools, draws on the same allowance.

An illustrative API budget

Illustrative, not a benchmark. The company is fictional.

Northcape Freight runs Salesforce Enterprise with 40 licenses, so its daily allowance is 100,000 + 40 x 1,000 = 140,000 calls. Its routing and enrichment tools already use about 50,000 a day. The marketing team wants to sync a 30,000-contact HubSpot database on launch day.

Item	Calls
Daily allowance	140,000
Used by other tools	50,000
Left for HubSpot	90,000
Initial sync of 30,000 contacts at up to 4 calls each	up to 120,000

At the worst case, the first sync needs more than a full day of what is left. The fix is to cap “Allocated to HubSpot” at about 80,000, so the other tools keep working, and to sync the database in batches over two days using an inclusion list.

What breaks in a HubSpot Salesforce sync?

HubSpot groups sync errors by type in the integration settings. These are the common causes listed on its sync errors page, with the fix.

Error type	Usual cause	Fix
Custom code	A Salesforce validation rule, flow or other automation rejects the update	A Salesforce admin adjusts the rule or flow, or exempts the integration user
Picklists	Values differ between systems, the picklist is restricted to its value set, or the record owner is an inactive Salesforce user	Match the option names to HubSpot’s values or lift the restriction; reassign records owned by inactive users
Property values	”String too long”, invalid email, missing required country or value	Fix the data or raise the Salesforce field length
Duplicates	”Email already in use” or a Salesforce duplicate rule blocks the record	Merge the records or adjust the matching rule
Permissions	The integration user cannot read or edit a field or object	Grant Read and Edit on the field
Associations	Linked accounts have not synced yet, or an activity has more than one contact	Import accounts first; keep one contact per activity
Duplicate id specified	Lead ID or Contact ID added to a custom mapping	Remove the ID fields from custom mappings

After you fix a cause, select the errors and click Resync. HubSpot resyncs up to 100 errors at a time. If records stall because HubSpot has used its share of API calls, raise “Allocated to HubSpot” on the Sync Health tab or sync in smaller batches.

Beyond error cards, four behaviors cause quiet damage, because nothing shows as an error:

• Deletions are one way for contacts. Deleting a Salesforce lead or contact can delete the HubSpot contact if you allow it. Deleting a HubSpot contact never deletes the Salesforce record. For deals, deleting a HubSpot deal never deletes the Salesforce opportunity.
• The inclusion list leaks in one direction. New Salesforce leads or contacts create HubSpot contacts even when they fall outside your segment, and their later updates then do not sync.
• Lifecycle stages only move forward. If HubSpot updates lifecycle stage from opportunity stage, the stage never goes backward, and the Salesforce contact needs a contact role on the opportunity.
• Switching Salesforce orgs loses links. Moving to a new production org keeps contact links but loses the links between HubSpot companies and Salesforce accounts, and between deals and opportunities, according to the install guide.

What should you check before you turn the sync on?

1. Clean duplicates in both systems. HubSpot matches on email, and Salesforce duplicate rules will block records. Our data hygiene entry covers the routine.
2. List the picklists that sync and compare internal values line by line, including countries and states.
3. Find every validation rule and flow that could reject an update from the integration user.
4. Decide leads or contacts for new HubSpot records, and set company creation to match.
5. Write the mapping sheet: field, owner, rule, reason.
6. Set the API allocation with the numbers above, before the first import.
7. Name an owner for sync errors who checks the error cards every week.

Where Growigami fits

Our CRM and routing service runs inside the CRM you already have, HubSpot, Salesforce or both. Each week we merge duplicates and fill fields, keep routing current as territories change, and fix a broken form or sync within one business day. If you are still choosing a CRM, start with our HubSpot vs Salesforce entry. For what happens after a synced lead lands with the right seller, see our guide to lead routing software.