How do I set up the HubSpot Salesforce integration correctly?
The connector installs in minutes. Here are the five decisions to make before you turn it on, and the setup steps that follow.
Print it out and tick off each step as you go, or keep it open next to you while you work.
Table of contents
Admin access to HubSpot Professional or Enterprise and to a Salesforce edition with API access, plus a Salesforce sandbox.
The worst HubSpot Salesforce integration I've opened had 20,000 sync errors piled up over two years. Buried in them were about 200 form submissions from people asking to talk to sales, and none of them ever reached Salesforce. Installing the connector had taken minutes. What went wrong was everything that should have been decided first: which records cross in each direction, which system owns each field, and which activities a rep actually needs to see.
More often, the problem shows up in a leadership meeting. Marketing says it sent sales 45 leads last month, sales says it got 15, and both pulled their number straight out of their own system. When marketing digs in, most of the missing leads are sitting in sync errors, sometimes over something as small as HubSpot saying USA while Salesforce expects United States. Get the decisions right up front and both teams end up reporting the same number.
Configured for each other, HubSpot and Salesforce work like peanut butter and chocolate. Switched on without those agreements, they behave more like oil and water, sitting in the same jar and never mixing.
Below are the five decisions to make before you install the connector, the eight setup steps those decisions feed, and what to watch in the first two weeks after go-live.
If what you actually want is to leave Salesforce behind and run on HubSpot alone, that's a migration, and whether you should move from Salesforce to HubSpot is the better starting point.
Why the decisions come first
Left to its defaults, the connector syncs more than you'd expect. Once syncing starts, every HubSpot contact is eligible to reach Salesforce unless you build a segment that says otherwise, and HubSpot syncs contacts by default when the integration is turned on. Data will move either way. What you control is how much, in which direction, and who wins when two records disagree.
Skip those answers and the same failures show up. Marketing and sales keep different definitions of the same lifecycle stage, so the reporting never reconciles and leadership stops trusting either number. Inbound leads arrive late, or without the context that would have told a rep why to call, and duplicates multiply on both sides. People go back to exporting spreadsheets and reconciling by hand, which is the work the integration was supposed to end.
If you're still deciding whether to run both platforms at all, why companies run HubSpot and Salesforce together covers that question first.
When to set it up
Timing matters. Set up the integration before you change lifecycle stages, launch attribution reporting, build lead routing or territory assignment, or add new automations to either system. If one of those projects is already underway, pause it and integrate first. Each of them depends on where data lives, and redoing them after the sync moves that data costs more than waiting would have.
These are the signs you need the integration now:
- Someone exports leads from HubSpot and imports them into Salesforce by hand.
- Reps can't see which campaign or form a lead came from.
- Marketing and sales report different lead numbers for the same month.
A few things need fixing before you start. If the data is heavily duplicated or unstructured, clean it before the build, because the sync will copy every duplicate into the other system. If the teams can't commit to the alignment conversations, or there's no agreed sales process to build routing against, settle those first. And if you can't test safely in a sandbox, get one before you start. Each of these turns into rework once the sync is live, so clearing them is cheaper than working around them.
Choose your operating model
Before any configuration, decide which platform leads. Which one fits depends on who drives revenue today, how complex the sales process is, and how fast the team wants to iterate.
The table below lays out the three models, what each one means in practice, who it suits, and what it costs you.
Whichever you pick, write it down and tell both teams. Later, when the teams disagree about who owns a record or a field, the written model settles it.
The five decisions to make before you configure
Each of these decisions turns into a specific setting later, so answering them now means the setup steps become data entry instead of debate.
- At what point does a record move from HubSpot to Salesforce? A form submission, an MQL status, a lead score threshold. Your answer becomes the inclusion segment in step 3. A few questions settle it fast: where does marketing track campaign performance, where do your SDRs do their qualifying, and are you using the Lead object at all?
- Which system wins when contact information conflicts? If a rep updates a phone number in Salesforce and the same person submits a form in HubSpot with a different one, one of those values has to lose. Your answer sets the field-level sync rules in step 7.
- Which Salesforce fields should HubSpot never overwrite? Original Lead Source is a common one. Also step 7.
- Which activities does a rep actually need to see? Not every marketing touch earns a place on a Salesforce timeline. Your answer becomes the activity sync scope in step 8.
- What happens when a closed-lost lead re-engages in HubSpot? Back to the original owner, or reassigned? Your answer shapes both the inclusion segment and the routing rules in step 3.
Here's where each decision ends up in the setup:

In 300+ CRM audits, the integrations we end up rebuilding are almost always the ones that skipped these five calls before install.
Before you start
The setup can't finish if any of these are missing, so confirm each one before step 1.
Platform requirements
- HubSpot: Professional or Enterprise of Marketing Hub, Sales Hub, Service Hub, Data Hub, Content Hub or Smart CRM.
- Salesforce: an edition with API access, or Salesforce Professional. Government Cloud works, Group Edition doesn't.
- People and access: a Salesforce system administrator to run the install, a dedicated integration user (step 1), and a sandbox to test in.
- One instance: each HubSpot account connects to only one Salesforce instance.
Two Salesforce settings to check
- IP restrictions: HubSpot connects from changing IP addresses, so you can't allowlist it. Ask your Salesforce admin to turn off Enforce IP Restrictions on Every Request before you install, or the integration won't connect. If you still need to restrict logins, HubSpot recommends setting up a network IP range in Salesforce.
- Smart Transfer: if you moved Salesforce data into HubSpot with Smart Transfer, turn it off before you switch the integration on. Running both at once creates duplicate records in both systems.
Salesforce API budget
- Daily limit: know your Salesforce API limit and how much of it your other connected tools already use.
- Cost per contact: one contact sync can take up to four API calls, and the number varies.
- Allocation: after install, set HubSpot's share in the Sync Health tab under Allocated to HubSpot.
Salesforce validation rules
Validation rules are written for people typing data in. When the integration hits one, the record doesn't save, and the error usually lands in the custom code category on the Sync Errors page.
- Audit: check every validation rule and required field on the objects you'll sync, especially Leads and Contacts.
- Bypass: add a condition that lets the integration user through, before the build starts.
- Required fields that should stay: make them required on the HubSpot form too, or fill them with a HubSpot workflow. If Salesforce requires State and Country, for example, a workflow can copy the values HubSpot gets from the visitor's IP address.
Data
- Duplicates: check your duplicate rate and clear them before the build. The CRM deduplication playbook covers the cleanup.
- Field values: standardize them across both systems.
- Required fields: confirm which ones are actually filled on contact and company records.
Team agreements
- Definitions: sales, marketing and RevOps agree on lifecycle stages, lead statuses, qualification criteria and handoff rules before anyone configures anything.
- Source of truth: everyone agrees which system owns each major object.
- Field-mapping spreadsheet: every object, every field that syncs, its direction and its conflict rule.
- Lead management process: written down, because the inclusion segment and routing rules are built from it.
Here's what a few rows of that spreadsheet can look like:
With the decisions made and the prerequisites checked, the setup itself comes down to eight steps. Work them in order, because each one depends on the one before it, and the install sits at step 2 instead of step 1 on purpose.
Step 1: Create the integration user
When this step is done, the user sees the records you expect and nothing more, and every change the sync makes in Salesforce shows its name.
Use a dedicated Salesforce user for the connection instead of a person's login, so the sync doesn't break when that person leaves or their password expires.
- Profile: give the user its own profile, so you can tune its access without touching anyone else's.
- Permissions: API Enabled, View Setup and Configuration, Download AppExchange Packages, Customize Application, and Modify All on every object you sync. Add Modify Metadata if you want the HubSpot Embed window or deal sync.
- Task Type field: set it to visible on the profile.
- Password: set it to never expire.
- Sharing rules: these decide which Salesforce records reach HubSpot, so criteria-based sharing rules can keep whole categories of record from syncing.
Setting up a dedicated Salesforce integration user goes through the permission set in detail.
Step 2: Install the connector
When this step is done, you have an authenticated connection and nothing has synced yet.
- Find the app: in HubSpot, click the Marketplace icon in the top navigation, search for the Salesforce app and install it.
- Start in the sandbox: select the sandbox checkbox before you continue.
- Log in as the integration user: use its credentials, never your own.
Records don't sync automatically after install. They move when you import them or a sync is triggered, which gives you time to finish the remaining steps before any data crosses.
Here's what the integration syncs:
- Leads and contacts: sync to HubSpot contacts.
- Accounts: sync to HubSpot companies.
- Opportunities: sync to HubSpot deals.
- Cases: sync to HubSpot tickets.
- Custom objects: Enterprise only, and the object has to exist in HubSpot first. You set the direction per field mapping and per association, and one custom object can't sync to both Salesforce contacts and leads.
- Campaigns: don't sync, because HubSpot campaigns do a different job. How HubSpot and Salesforce campaigns work together covers why.
Step 3: Build the inclusion segment
When this step is done, only the HubSpot records that meet your criteria can reach Salesforce.
The inclusion segment decides which HubSpot contacts are eligible to reach Salesforce. HubSpot's docs call it an inclusion segment, and the setting inside the integration still says Inclusion List. They're the same thing. The setting itself takes about two seconds: build the segment, then select it. The thinking behind it is the part that takes time.
- Build it from decision 1: create an active segment whose criteria match the records you decided should cross. The setup I use most often is anything at MQL or beyond. Syncing everything except junk is a fine way to do it, and it makes HubSpot the dumping ground for bad contacts, but I'm less convinced it's the better option.
- Select it: pick it in the Limiting what syncs section of your Salesforce sync settings. Without one, every HubSpot contact syncs, which can work if you plan for it.
- Selecting it doesn't push anyone right away: a contact syncs only when something triggers it, such as being added to the segment.
- Salesforce-created records skip it: if new Salesforce leads or contacts are set to create HubSpot contacts, those get created whether or not they meet your criteria.
Skipping the segment isn't wrong, as long as you plan for it. Every contact then exists in both systems, which makes Salesforce campaigns easier to track and means you clean one database instead of two. The tradeoff is junk in both systems, which you pay Salesforce storage for, and you need clear routing so a new contact doesn't land on a rep just because it was created. If you go that way, I strongly recommend syncing as contacts, not leads.
Managing the HubSpot Salesforce inclusion list covers the edge cases.
Test it in the sandbox: create one record that matches and one that doesn't, then trigger a sync.
Step 4: Decide whether HubSpot creates leads or contacts
When this step is done, you've picked one object before go-live, because changing it later means correcting data.
In the contact sync rules, choose whether a new HubSpot contact creates or updates a Salesforce contact or a Salesforce lead.
The word lead also means different things in each system. In HubSpot it's a sub-object of a contact that tracks qualification. In Salesforce it's its own record that converts into a contact, an account and an opportunity.
For most B2B teams with a defined TAM and ICP, we recommend contacts, accounts and opportunities, and skipping the Lead object. It removes a conversion step and a whole category of duplicate. Whether you need both Salesforce leads and contacts makes the full case.
There's also a technical reason:
- Leads have no account: HubSpot matches companies through their associated contacts rather than by domain, so a lead gives it nothing to match on.
- Leads plus auto-created companies make duplicates: when someone converts the lead or adds an account in Salesforce, HubSpot ends up with a second company.
- The rule: if you sync leads, turn off auto-create companies. If you want auto-create companies on, sync contacts.
Step 5: Match company and deal sync to your model
When this step is done, only one system is creating accounts.
- If Salesforce owns accounts: turn off HubSpot's setting to automatically create and associate companies with contacts. With leads selected in step 4, this is required.
- Company and deal sync: turn them on if your model calls for them. Their field mappings can't be set up until object sync is on, which matters in step 7.
Step 6: Set the deletion policy
When this step is done, deletion works the way you intend in both directions.
Deletions don't work the same way in each direction:
- Salesforce to HubSpot: you choose what happens in HubSpot when a Salesforce contact or lead is deleted, either Delete the contact or Do nothing.
- HubSpot to Salesforce: deleting a HubSpot contact never deletes the Salesforce lead or contact.
When a contact is deleted in Salesforce, I'd recommend removing it from HubSpot too, by choosing Delete the contact, especially when Salesforce is your system of record.
Step 7: Map fields and choose a sync rule for each one
When this step is done, every field that syncs has a named winner.
Work from your field-mapping spreadsheet and record the HubSpot property, the Salesforce field and the sync rule for each mapping. This is where decisions 2 and 3 turn into settings.
The standard field mapping has four sync rules:
- Prefer Salesforce unless blank: Salesforce's value wins unless it's empty.
- Always use Salesforce: use it for the fields HubSpot should never overwrite. For a second guardrail, add a Salesforce validation rule that blocks the integration user from editing those fields.
- Two-way: the most recent update in either system wins.
- Don't sync: also how you stop a standard mapping, since standard mappings can't be deleted.
Rules can differ by object. Custom object mappings, for example, also offer Always use HubSpot, so check the dropdown on each mapping before you plan around a rule.
These mechanics cause most of the sync errors that show up later:
- Field types: a HubSpot dropdown maps to a Salesforce picklist or reference field, multiple checkboxes to a multipicklist, a number to a double or int.
- One property, one field: don't map a HubSpot property to several Salesforce fields or overlap a standard mapping. Duplicate mappings can overwrite values or create sync loops.
- Reference fields: these arrive in HubSpot as 18-digit record IDs instead of labels. Map them to a HubSpot dropdown property if you need them for segments or reports.
- Picklists: standardize the values in both systems before you map, so the same value doesn't arrive under two spellings. When a picklist changes in Salesforce later, update HubSpot to match.
- Limit: 500 field mappings per object, far more than you should need.
Review every default mapping the connector set up, too. A default sync rule moves data just like one you chose, and mapping only the fields you use covers how to decide what earns a place.
One more setting belongs in this step: it lets a Salesforce opportunity stage change update the HubSpot contact's lifecycle stage. For a contact to reach Customer when an opportunity closes, four things need to be true: account sync, Automatic lifecycle stage transitions and Lifecycle stage sync are all on, and a contact on the account is linked to the opportunity through contact roles. Here's how that chain works:

Contact roles are the part teams miss. An opportunity with an account but no linked contacts won't move anybody's lifecycle stage. The setting also never moves a stage backwards, and a HubSpot lifecycle stage never changes anything in Salesforce, so marking someone Customer in HubSpot won't convert a Salesforce lead.
Step 8: Configure activity sync
When this step is done, reps see the activities that help them and none of the ones that don't.
There are two activity syncs, both in the Activities tab of the integration settings. Check which ones are turned on before you change anything.
Here's how the two compare:

What to sync:
- Sync: core sales activity a rep would act on, like booked meetings, sales emails and calls.
- Skip: marketing email opens, clicks and sends. They sync through an API that doesn't deduplicate, so one contact opening one email five times creates five Salesforce tasks, and forwarded emails add more under the original contact. Salesforce storage is expensive to clean up once it's full.
How far back the Timeline sync reaches:
- Sales activity: sales emails, tasks, meetings, notes and content views sync only after the contact syncs. Nothing earlier is backfilled.
- Marketing email events: only those within 30 days of the contact's sync date.
- Form submissions: only those within one year of the contact's sync date.
Two settings make activity sync fail without an obvious error, so check them before go-live:
- Task Status picklist: its API names have to match what the HubSpot connector expects.
- Task Type field: it has to be visible to the integration user's profile.
How the HubSpot Salesforce activity sync works now walks through the configuration.
Test it before you go live
Run two rounds of user testing in the sandbox before anything touches production. In the first, department heads verify that fields map where they should, that lifecycle transitions fire correctly, and that routing sends records to the right owner. In the second, actual reps run real scenarios: create a lead, move a deal, log a call. The second round is the one that finds edge cases, because leadership tests the process as designed and reps test it as lived.
Back up data in both systems right before the production push.
During testing, you'll often need a record to sync right away. To push it through, update any mapped field. On my team, we add a Force sync to HubSpot checkbox in Salesforce for exactly this.
For the first two weeks after go-live, check the Sync Errors page in HubSpot daily. It groups errors by type with a count of affected records, so you can tell a single bad mapping apart from something systemic. On a healthy integration, I see a handful of new errors every two weeks, nothing crazy, and most are older records being updated, with few new leads stuck on the way to sales. If a record isn't syncing and nothing in the interface explains why, HubSpot support can check it from their side.
After go-live
Once errors pile up, fixing them has a side effect that surprises people. When you fix a sync error that's been blocking records for weeks, everything stuck behind it syncs at once. We call it a dam break. Tell sales before you fix it and check your routing rules first, so reps don't open Salesforce to hundreds of new leads and conclude the system is broken again.
After that, settle into a regular review cadence.
- Daily and weekly: review and resolve sync errors. On my team, one person clears them every week.
- Monthly: validate field mappings, collect user feedback and review adoption. This is also when to delete or archive what's broken, including unused HubSpot workflows and Salesforce flows, contacts with invalid email addresses, and contacts with no associated company or account.
- Quarterly: a full sync audit covering field mappings, user behavior and data quality trends.
- Annually: review the architecture against how the business sells now.
The HubSpot Salesforce sync errors diagnostic playbook covers each error type and its fix, which is the reference you'll want open during those daily reviews.
When the native connector is not enough
The native connector handles most dual-stack setups well. It gets strained when the Salesforce org runs heavy custom objects and automation the sync was never built around, when compliance requires record-level control the connector can't express, or when data needs reshaping on its way between systems instead of copying field to field. When to build a custom HubSpot Salesforce integration covers how to tell the difference and what the alternatives actually cost to maintain.
Frequently asked questions
Can you use HubSpot with Salesforce?
Yes. HubSpot has a native Salesforce integration that syncs contacts, companies, deals, tickets and activities between the two platforms on Professional and Enterprise subscriptions. Treat the connector as a starting point. Without an inclusion segment, a named source of truth for each field, and a deliberate activity sync scope, sync errors and conflicting records build up quietly.
Which HubSpot plan integrates with Salesforce?
You need Professional or Enterprise of Marketing Hub, Sales Hub, Service Hub, Data Hub, Content Hub or Smart CRM. On the Salesforce side you need an edition with API access, or Salesforce Professional. Group Edition is not supported.
How often does HubSpot sync with Salesforce?
Records move when something triggers them to sync, and specific actions do that: a form submission, an email send, open or click, a booked meeting, a call, a property value change, a new Salesforce lead or contact. HubSpot also checks for new or updated information across both accounts approximately every 15 minutes and triggers a sync if your configuration calls for one. For high-intent leads where response time decides the outcome, the fix is usually changing what triggers the sync.
What is the most common cause of HubSpot Salesforce sync errors?
The causes we see most often are duplicate records, mismatched field types between a HubSpot property and its Salesforce field, Salesforce validation rules and required fields blocking record creation, conflicts with third-party tools writing to the same records, and misconfigured automation in either system. Salesforce Flows and Apex triggers raise the chance of a silent break, which is why the error page gets checked on a schedule.
Can you integrate two HubSpot accounts with one Salesforce account?
Yes, with care. You install and set up the integration separately in each HubSpot account, and each HubSpot account can connect to only one Salesforce instance. Use selective sync in Salesforce so each HubSpot account only sees the records it should.
What to do next
If you're about to install, work backwards from this page. Answer the five decisions, finish the field-mapping spreadsheet, audit your validation rules, then install into a sandbox. The install is the easy part, and doing it last costs you nothing.
It's rare to find one person who knows both systems well, and the integration lives in the gap between them. Getting it right takes people who know what a new Salesforce automation does to a HubSpot campaign, and how a new HubSpot form field changes lead assignment in Salesforce. That's the work we do on both sides, so both teams end up reporting the same number.

