Set up bidirectional HubSpot-Salesforce sync using HubSpot's native integration
Prerequisites
- HubSpot account on a paid plan (Starter, Professional, or Enterprise) with Super Admin access
- Salesforce account with API access (Enterprise or Unlimited edition, or Professional with the API add-on)
- Salesforce system administrator permissions including "Modify Metadata" and "Download AppExchange Packages"
- A field mapping plan — which HubSpot properties map to which Salesforce fields, and who wins on conflicts
Why HubSpot native?
The built-in HubSpot-Salesforce connector is the lowest-friction path to bidirectional sync. Everything is configured through a field-mapping UI — no code, no middleware, no API credentials to manage. You get per-field sync direction (Prefer Salesforce, Always use Salesforce, Prefer HubSpot, Two-way), email-based contact deduplication, inclusion lists to control which records sync, and a monitoring dashboard that surfaces errors and data quality issues.
The trade-offs are real. The integration polls on a 5-15 minute cycle, so changes are not instant. Custom object sync is limited to HubSpot Enterprise (up to 10 custom objects). There is no custom conflict resolution logic — you pick a direction per field, and that's it. You also cannot merge companies while the integration is active; HubSpot disables company merges to prevent sync corruption. For teams that need real-time sync, complex field transformations, or custom conflict resolution, the n8n approach gives you full programmatic control.
How it works
- Native connector installed from HubSpot's integration marketplace connects to your Salesforce org via OAuth
- Per-field sync direction lets you choose who wins for each mapped property: Prefer Salesforce (default), Always use Salesforce, Prefer HubSpot, or Two-way (last write wins)
- Email-based deduplication matches HubSpot contacts to Salesforce leads/contacts by email address — no duplicates created for matching records
- Inclusion lists filter which records sync, so you can exclude test data, unqualified leads, or inactive accounts
- Sync Health dashboard surfaces errors, failed records, and field mapping issues in real time
Step 1: Install the Salesforce integration
Navigate to Settings > Integrations > Connected Apps in HubSpot. Search for Salesforce and click Connect app.
HubSpot will prompt you to log in to your Salesforce org. Use an account with system administrator permissions — the integration needs access to create and modify metadata.
During the OAuth flow, Salesforce will list the permissions HubSpot is requesting. These include reading and writing to standard and custom objects, accessing metadata, and managing connected apps. Click Allow.
Once connected, HubSpot will begin an initial scan of your Salesforce schema — this takes 1-5 minutes depending on how many custom objects and fields your org has.
Create a dedicated Salesforce user for the HubSpot integration rather than connecting with a personal admin account. This prevents the integration from breaking when an employee leaves or changes their password. It also makes audit logs clearer — all sync activity is attributed to the integration user.
Step 2: Configure contact sync
Navigate to Settings > Integrations > Salesforce > Contact sync.
Set sync direction per field
HubSpot displays a table of mapped fields between HubSpot contact properties and Salesforce lead/contact fields. For each field, choose a sync direction:
| Direction | Behavior |
|---|---|
| Prefer Salesforce (default) | Salesforce value wins on initial sync; after that, whichever side was updated most recently wins |
| Always use Salesforce | Salesforce always overwrites HubSpot, regardless of timestamps |
| Prefer HubSpot | HubSpot value wins on initial sync; after that, most recent update wins |
| Two-way | Most recent update always wins based on timestamp comparison |
For most teams, the default "Prefer Salesforce" works well for fields that sales owns (job title, phone number, deal-related fields) while "Prefer HubSpot" works for fields that marketing owns (lead source, lifecycle stage, campaign data).
Map custom properties
Click Add new field mapping to map HubSpot custom properties to Salesforce custom fields. HubSpot will only show Salesforce fields that match the property type (text to text, number to number, etc.).
Set deduplication rules
The native integration deduplicates contacts by email address. When HubSpot encounters a Salesforce lead or contact with an email that already exists in HubSpot, it links the records instead of creating a duplicate.
The email-based dedup only works when both records have an email address. Contacts without emails — or with different email formats (john@acme.com vs j.doe@acme.com) — will create duplicates in the target system. Clean up email data in both systems before enabling the sync.
Step 3: Configure company/account sync
Navigate to Settings > Integrations > Salesforce > Company sync.
HubSpot companies map to Salesforce accounts. Enable company sync and configure the following:
Field mappings — Map company properties to account fields. Key mappings include:
| HubSpot Property | Salesforce Field | Recommended Direction |
|---|---|---|
| Company name | Account Name | Two-way |
| Company domain | Website | Two-way |
| Industry | Industry | Prefer Salesforce |
| Annual revenue | AnnualRevenue | Prefer Salesforce |
| Number of employees | NumberOfEmployees | Two-way |
Deduplication — Choose the field used to match companies to accounts. Domain name is the most reliable option. You can also use company name, but this is prone to mismatches (e.g., "Acme" vs "Acme Corp" vs "Acme Corporation").
Enabling contact sync does not automatically enable company sync. You must configure company sync in its own tab. If you skip this step, contacts will sync but their associated companies will not appear in Salesforce.
Step 4: Configure deal/opportunity sync
Navigate to Settings > Integrations > Salesforce > Deal sync.
HubSpot deals map to Salesforce opportunities. The most critical configuration here is the stage mapping table — HubSpot deal stages and Salesforce opportunity stages rarely have the same names, and unmapped stages cause deals to sync with a blank or default stage.
Create a stage mapping table
Map each HubSpot deal stage to its corresponding Salesforce opportunity stage:
| HubSpot Deal Stage | Salesforce Opportunity Stage |
|---|---|
| Appointment Scheduled | Discovery |
| Qualified to Buy | Qualification |
| Presentation Scheduled | Proposal/Price Quote |
| Decision Maker Bought-In | Negotiation/Review |
| Contract Sent | Negotiation/Review |
| Closed Won | Closed Won |
| Closed Lost | Closed Lost |
Adjust these mappings to match your actual pipeline stages. Every HubSpot stage must map to a Salesforce stage and vice versa.
Map deal fields
Key field mappings for deals/opportunities:
| HubSpot Property | Salesforce Field | Recommended Direction |
|---|---|---|
| Deal name | Opportunity Name | Two-way |
| Amount | Amount | Two-way |
| Close date | CloseDate | Two-way |
| Deal owner | Opportunity Owner | Prefer Salesforce |
| Pipeline | Record Type (optional) | Prefer HubSpot |
If a HubSpot deal stage has no corresponding Salesforce opportunity stage in the mapping table, the deal will sync to Salesforce with a blank or default stage. This can break validation rules and reporting. Map every stage in both directions before enabling deal sync.
Step 5: Set up inclusion lists
Inclusion lists control which records sync between systems. Without them, every contact, company, and deal in HubSpot syncs to Salesforce — including test records, unqualified leads, and inactive accounts.
Navigate to Settings > Integrations > Salesforce > Inclusion lists.
Create a HubSpot active list that defines your sync criteria. Common filters:
- Contacts: Lifecycle stage is any of Marketing Qualified Lead, Sales Qualified Lead, Opportunity, Customer (excludes raw leads and subscribers)
- Contacts: Email does not contain
@test.com,@example.com(excludes test records) - Companies: Company owner is known (excludes unassigned companies)
Set this list as the contact sync inclusion list. Only contacts that are members of this list will sync to Salesforce.
Begin with a restrictive inclusion list (e.g., only MQLs and beyond) and expand it once you've verified the sync is working correctly. It's much easier to add records to sync than to clean up duplicates created by an overly broad initial sync.
Step 6: Monitor sync health
Once the sync is running, navigate to Settings > Integrations > Salesforce > Sync Health to monitor its status.
The Sync Health dashboard shows:
- Sync status: Whether the integration is actively syncing or paused
- Records synced: Count of contacts, companies, and deals synced in each direction
- Sync errors: Records that failed to sync, with the specific error message (validation rule failures, required field missing, permission errors)
- Data quality issues: Field mapping conflicts, type mismatches, and truncated values
Review the Sync Health tab daily for the first week after enabling the integration. Most issues surface in the first 24-48 hours as the initial sync processes your historical data.
Common errors to watch for:
| Error | Cause | Fix |
|---|---|---|
| REQUIRED_FIELD_MISSING | Salesforce validation rule requires a field that HubSpot doesn't populate | Add the field to your mapping or set a default value in Salesforce |
| INVALID_FIELD | A mapped field was deleted or renamed in Salesforce | Update or remove the mapping in the Salesforce integration settings |
| DUPLICATE_VALUE | Salesforce unique field constraint violated | Deduplicate the conflicting records in Salesforce before re-syncing |
| INSUFFICIENT_ACCESS | Integration user lacks permission on the object or field | Grant the integration user's profile read/write access to the field |
Troubleshooting
Common questions
Can I sync custom objects between HubSpot and Salesforce?
Yes, but only on HubSpot Enterprise plans. You can sync up to 10 custom objects between the two systems. Starter and Professional plans are limited to standard objects: contacts, companies/accounts, deals/opportunities, and activities/tasks. If you need custom object sync without Enterprise, the n8n approach can handle it programmatically via both APIs.
What happens if I disable and re-enable the integration?
Existing field mappings and configuration are preserved. When you re-enable the integration, HubSpot re-syncs all records that changed while the integration was disabled. Depending on how many records changed and your total data volume, this catch-up sync can take several hours. Monitor the Sync Health dashboard during the re-sync to catch any new errors.
How do I prevent test records from syncing to Salesforce?
Use inclusion lists. Create a HubSpot active list that excludes contacts with specific properties — for example, email contains @test.com, lifecycle stage is Other, or a custom "Is Test Record" checkbox is true. Set this list as the sync inclusion list in Settings > Integrations > Salesforce > Inclusion lists. Only contacts that are members of the list will sync.
How long does the initial sync take?
It depends on data volume. Fewer than 10,000 records typically completes within 1-2 hours. Between 10,000 and 100,000 records can take 4-12 hours. Over 100,000 records may take 24-48 hours. HubSpot processes records in batches in the background — you can use both systems normally during the initial sync.
Cost
The native HubSpot-Salesforce integration is included with any paid HubSpot plan (Starter, Professional, or Enterprise) at no additional HubSpot charge. On the Salesforce side, API calls from the integration count toward your org's daily API limit — typically 15,000 to 100,000 calls per day depending on your Salesforce edition and number of licensed users. The sync uses approximately 1 API call per record per sync cycle, so a 10,000-record sync consumes roughly 10,000 API calls. Monitor your API usage in Setup > System Overview in Salesforce if you are on a Professional edition with limited API capacity.
Looking to scale your AI operations?
We build and optimize automation systems for mid-market businesses. Let's discuss the right approach for your team.