How does the Salesforce-HubSpot integration sync your data?

The integration links each HubSpot record to one Salesforce record and moves field values across that link. The settings you choose for each object decide which values move and in which direction. Those settings live on the Data sync tab of the Salesforce app, under Integrations and then Connected Apps in your HubSpot settings.

What the integration syncs and in which direction

HubSpot pairs each of its objects with a Salesforce object. The contact sync is on by default. You turn each other pair on in its own sync rules, as HubSpot’s integration settings article describes.

HubSpot object	Salesforce object	Direction
Contacts	Leads or contacts	Two-way
Companies	Accounts	Set in company sync rules
Deals	Opportunities	Set in deal sync rules
Tickets	Cases	Set in ticket sync rules
Engagements	Tasks	Set on the Activities tab
Custom objects	Custom objects	Turned on as a feature

A few defaults shape the first weeks after you connect.

• Records do not sync on install. You import them from Salesforce or let sync triggers move them over time.
• Deleting a HubSpot contact leaves the Salesforce lead or contact in place.
• Deleting a HubSpot company leaves the Salesforce account in place, and that rule cannot be edited.
• Without an inclusion segment, every HubSpot contact syncs to Salesforce.
• Selective sync filters which Salesforce accounts reach HubSpot, and multiple filters combine with AND logic.
• Salesforce opportunity updates can move a HubSpot lifecycle stage forward, and they never move it backward.

The connected user and the requirements

The integration acts as one Salesforce user, called the connected user. That user’s permissions decide what HubSpot can do in Salesforce. If the connected user cannot view leads, leads stay out of HubSpot, and HubSpot cannot create or update them either.

The person who connects needs these Salesforce settings, according to HubSpot’s setup article.

• A Salesforce edition with API access, or Salesforce Professional. Group Edition is unsupported.
• The system administrator role.
• The API Enabled and View Setup and Configuration permissions.
• Modify All on each object you plan to sync.
• The Download AppExchange Packages permission.
• Customize Application, which installs and updates the HubSpot Embed window.

On the HubSpot side, the connecting user needs Account Access permissions. The account needs a Professional or Enterprise subscription on a hub or on Smart CRM.

Native connector, middleware or a custom build

The native connector is HubSpot’s Salesforce app, installed from the HubSpot Marketplace. HubSpot designed it for ongoing syncing in both directions. For a one-time move of Salesforce data, HubSpot points to Smart Transfer instead. The two tools match records on different identifiers, so running both at once creates duplicates in both systems.

The native connector comes with limits you plan around.

• Each HubSpot account connects to one Salesforce instance. Several HubSpot accounts on one instance each need their own install.
• The integration spends API calls against a daily limit. One contact sync can take up to 4 calls per record.
• Salesforce login IP restrictions can block the connection. HubSpot uses dynamic addresses, so it recommends a network IP range in Salesforce.
• With several HubSpot accounts on one instance, HubSpot recommends the setting that stops automatic contact creation. The other choices let one account’s leads create contacts in another account.

We choose a native connector, third-party middleware or a custom build for each connection. Three criteria drive that choice.

Criterion	What we check
Data volume	Records and API calls per day
Sync frequency	How fresh each object must stay
Maintenance needs	Who updates the sync after launch

A custom build fits when a connection needs a schedule or logic the connector settings lack. For a commercial insurance agency on AMS360, we built a custom sync that moves quotes, policies and contacts into HubSpot every 20 minutes. Some of its objects sync both ways, and others update on triggers. On the Salesforce side, our integration team has built and repaired the Salesforce and HubSpot integration in several client environments.

Our integration projects typically fall in these ranges.

Scope	Typical timeline
Single integration with a well-documented API	1 to 3 weeks
Multi-platform integration build-out	4 to 8 weeks

Deciding which system owns each field

Field ownership names the system whose value wins for a mapped field. When both teams edit the same field, each sync can overwrite the other team’s work. Suppose, as an imagined case, your sales reps edit job titles in Salesforce while a marketing enrichment tool rewrites them in HubSpot. Each edit on one side becomes the next overwrite on the other.

HubSpot’s setup article asks you to plan which records sync, how fields map and how record ownership works before you connect. The settings give you these controls.

• Field mapping sync rules. The company sync adds an Always use HubSpot rule, which sends a field’s value from HubSpot to Salesforce.
• Object direction. A one-way object rule overrides the field rules in that direction.
• A sync conflict rule for companies. It picks the source for matched records on their first sync and has no effect afterward.
• State and country handling. You choose whether HubSpot converts its default values to pass Salesforce picklist validation.

Leads, contacts and duplicate companies

You choose whether a new HubSpot contact creates a Salesforce contact or a Salesforce lead. Salesforce leads carry no account. The integration deduplicates companies through associated contacts instead of the domain. A contact that starts as a lead produces a duplicate HubSpot company once someone converts it or creates its account in Salesforce. HubSpot advises syncing contacts as Salesforce contacts when automatic company creation stays on.

A short worksheet settles ownership before any mapping goes live.

1. List every mapped field on each synced object.
2. Name the team that edits each field day to day.
3. Make that team’s system the owner of the field.
4. Set the sync rule that matches the owner.
5. Record the decision in your integration documentation.

What happens when a record fails to sync

A sync error stops a record’s data from moving between the systems. The Sync Health tab in the Salesforce app shows the API calls used in the last 24 hours and each current error. Errors group into cards by type, and each card counts current errors and affected records. Clicking a card opens the details in a side panel.

HubSpot’s articles point to these causes.

• Connected user permissions. A missing permission blocks syncing on that object.
• API call allocation. HubSpot advises setting it from your Salesforce limit and your current usage.
• Field mappings after an org change. A Salesforce field with a different internal name in the new org produces sync errors until you remap it.
• State and country values. Values that skip conversion can fail Salesforce picklist validation.
• IP restrictions. The Enforce IP Restrictions on Every Request setting stops the integration from connecting.

Gaps that come from the settings

Some gaps come from settings working as designed.

• A Salesforce lead can create a HubSpot contact outside the inclusion segment. Later updates to that pair stop syncing in both directions.
• Lifecycle stage updates depend on contact roles on the opportunity. Custom relationship fields trigger no stage change.
• A company merge in HubSpot leaves the matching Salesforce accounts unmerged.
• A move to a new Salesforce production org keeps the links between contacts and leads. The company and deal links are lost.

Our new builds start after an audit that checks your current integrations for gaps, errors and silent failures. A Salesforce org move also turns the integration off for about an hour, so plan that work outside your busiest sync window.

How to test the sync before go-live

HubSpot’s install flow has a checkbox for connecting a Salesforce sandbox. HubSpot also recommends testing the New Company Sync in a developer test account or sandbox first, because you cannot return to the standard company sync once it is on. We validate every integration’s data flow in a staging environment before go-live.

A test plan for the sandbox covers each rule you set.

1. Connect the sandbox with a user whose permissions match the connected user in production.
2. Load sample records for each object pair you plan to sync.
3. Edit an owned field on each side and confirm the owner’s value wins.
4. Create a HubSpot contact and check whether Salesforce receives a lead or a contact.
5. Convert a test lead and check HubSpot for a duplicate company.
6. Delete test records on each side and confirm the deletion rules.
7. Read the Sync Health tab for errors and the API calls used.

Turning on the company sync raises Salesforce API usage for a while as it indexes records. Usage returns to normal once indexing finishes, so measure your API budget after that point.

HubSpot’s setup article does not say how many API calls other objects use per record. The setup article gives a figure for contacts alone and notes that the count varies. Production volume can exceed your sandbox sample, so watch Sync Health through the first weeks after go-live.

Our team’s HubSpot certifications include the Salesforce Integration Certification. HubSpot has also awarded us its Custom Integration accreditation, and our credentials page lists both.