HubSpot Salesforce Integration: Object Mapping, Sync Design Patterns and Antipatterns
HubSpot Salesforce integration explained: how the objects pair, what the four sync rules do, how the inclusion segment gates both directions, and the API cost.
Paul Maxwell, PhD
AUTHOR
GET WEEKLY REVOPS INSIGHTS
No spam. Unsubscribe anytime.
A sales representative edits a lead in Salesforce, and the matching HubSpot contact never changes. Marketing keeps nurturing a person whom sales has disqualified, and a lead score reaches Salesforce a day late after every rescoring run. The sync error queue can stay empty throughout, because the HubSpot Salesforce integration did exactly what its settings said, and those settings were chosen one screen at a time.
This article explains how HubSpot's native connector decides which records sync, which value wins on each field, who owns each record, and what the sync costs in Salesforce API calls. It starts with the object pairs, then record scope, where the inclusion segment behaves differently from its description. Sync rules, the Lead object and ownership follow, then a sample API budget, a verified configuration procedure, the reported issues, the business case and the limits of the evidence.
The connector is HubSpot's own Salesforce integration, installed from the HubSpot Marketplace on Professional and Enterprise subscriptions, according to its installation documentation. The inclusion segment is an active HubSpot segment whose members are the contacts eligible to sync. A sync rule is the per-field setting that decides which system's value is written when the two disagree. The connected user is the Salesforce user the connector runs as, and its permissions bound everything the connector can read or write.
Object Pairs and Record Matching
The connector pairs each HubSpot object with one Salesforce object, and each pair has its own matching rule. Contact sync cannot be turned off. Companies, deals and tickets each have a toggle under Settings > Integrations > Connected Apps > Salesforce > Data sync, as the integration settings documentation describes.
| HubSpot | Salesforce | Pairing rule, as documented |
|---|---|---|
| HubSpotContact | SalesforceLead or contact | Pairing rule, as documentedMatched on email address; sync cannot be turned off |
| HubSpotCompany | SalesforceAccount | Pairing rule, as documentedThe Account ID of a previously synced contact, or, under the new company sync, an exact match on the deduplication field; a similar name never matches |
| HubSpotDeal | SalesforceOpportunity | Pairing rule, as documentedOnly deals in Salesforce-synced pipelines, which are named Salesforce - [record type ID]; the Sales Hub tier sets how many pipelines can sync |
| HubSpotTicket | SalesforceCase | Pairing rule, as documentedPaired once ticket sync is turned on |
| HubSpotActivity | SalesforceTask | Pairing rule, as documentedOne contact association per activity; a second contact returns an association error |
Nothing syncs at installation: records arrive by import or as sync triggers fire, and HubSpot checks both systems for changes approximately every 15 minutes, according to its sync trigger documentation.
Several documented behaviours are worth settling before any field is mapped. Deleting a Salesforce opportunity deletes the synced HubSpot deal but not the reverse. Currency amounts sync as bare numbers with no exchange rate, according to the opportunity sync documentation. Company sync must also be on, with accounts imported, before opportunity sync starts. A HubSpot company creates a Salesforce account only under listed conditions, and never when every associated contact syncs as a Salesforce lead, per the account sync documentation.
Record Scope: Inclusion Segments and the Connected User
HubSpot's settings documentation, and the section on HubSpot contacts in its lead and contact sync documentation, describe the inclusion segment as a filter on what HubSpot sends: only members sync to Salesforce, and with no segment every contact syncs. The inclusion segment documentation states a wider effect: records outside the segment do not sync in either direction. Creation from Salesforce is the principal exception: a lead or contact created there still creates a HubSpot contact, or pairs with an existing one, when the HubSpot contact creation setting allows it. Further updates from either side then stop until the contact meets the criteria. Email opt-out sits inside the same boundary: per the lead and contact sync documentation, a contact that is not syncing passes its opt-out status in neither direction until it first syncs.
The finding this article rests on follows, and any sandbox can check it. A segment written to keep unqualified contacts out of Salesforce also stops edits to unqualified leads that sales created in Salesforce from reaching HubSpot. A criterion such as a lifecycle stage of marketing qualified lead or later leaves every earlier-stage lead that sales entered directly unchanged in HubSpot after its creation, until it qualifies.
The repair lives in the segment criteria, not in the sync rules. A segment defined as the qualification criteria, or Salesforce Lead ID is known, or Salesforce Contact ID is known, keeps every record already in Salesforce paired. HubSpot-only contacts still cross on qualification alone. The integration maintains both ID properties itself, and the sync error documentation warns against mapping them for that reason. HubSpot does not describe this pattern, so the last step of the procedure below tests it.
The second control is set in Salesforce. Per the installation documentation, a connected user who cannot view the lead object means leads neither sync to HubSpot nor accept writes from it. Field permissions govern writes the same way: a field the connected user cannot edit returns a Salesforce field permission error, per the sync error documentation.
Two further behaviours bound the segment. The first sync of a record that HubSpot knows only by its Salesforce ID can write mapped fields before membership is evaluated. Selecting a segment also moves nothing until a trigger fires or the segment is resynced by hand. A manual segment resync requires Marketing Hub Professional or Enterprise and needs three API calls per member available, per the sync trigger documentation.
Sync Rules and Field Ownership
Every mapping carries one of four sync rules, which the field mapping documentation names from Salesforce's side of the connection.
| Sync rule | HubSpot value to Salesforce | Salesforce value to HubSpot |
|---|---|---|
| Sync rulePrefer Salesforce unless blank | HubSpot value to SalesforceOnly while the Salesforce field is empty | Salesforce value to HubSpotOverwrites HubSpot whenever present; a Salesforce deletion clears HubSpot |
| Sync ruleAlways use Salesforce | HubSpot value to SalesforceNever, even into an empty field | Salesforce value to HubSpotOverwrites HubSpot whenever present; a Salesforce deletion clears HubSpot |
| Sync ruleTwo-way | HubSpot value to SalesforceThe latest write from either side wins; deletions pass | Salesforce value to HubSpotThe latest write from either side wins; deletions pass |
| Sync ruleDon't sync | HubSpot value to SalesforceNever | Salesforce value to HubSpotNever; deletions do not pass |
No rule makes HubSpot authoritative. Two rules let Salesforce's value win whenever one exists, one stops the sync, and only Two-way carries a HubSpot edit onto a populated Salesforce field. A field that marketing owns is therefore protected only in Salesforce: map it Two-way, use field-level security to make it read-only on every profile, and grant edit access to the connected user alone through a permission set. The System Administrator profile has to be read-only too, because HubSpot requires the connected user to be an administrator and every other administrator shares that profile. Salesforce itself recommends permission sets over profiles for field permissions. A field that sales owns needs no Salesforce configuration, because under Always use Salesforce a HubSpot edit never leaves HubSpot, and the Salesforce value, where one exists, overwrites it when the record next syncs.
Owner is the documented exception in the field mapping documentation: HubSpot may display Prefer Salesforce unless blank against it, but owner syncs two-way only and must match exactly. Property types must be compatible, and Salesforce reference fields arrive as 18-digit record IDs rather than labels. Mapping one HubSpot property to two Salesforce fields can start a sync loop. The mappings export as CSV from the Property mappings screen, which gives the ownership design a written record.
The Lead Object and Contact Creation
Salesforce keeps an unqualified person on a lead record and, at qualification, converts it into a contact on a new or existing account, optionally creating an opportunity, as its lead conversion documentation describes. HubSpot records the same progression as a lifecycle stage on one contact, a property distinguished from lead status in lifecycle stage against lead status. One connector setting reconciles the two models: whether a HubSpot contact creates a Salesforce contact or a Salesforce lead.
The choice has a documented side effect on companies. Where contacts sync as leads, the integration settings documentation advises turning off automatic company creation, because leads have no accounts and the integration deduplicates companies through contacts rather than by domain. With the setting left on, converting such a lead in Salesforce creates a duplicate HubSpot company. Leads suit an org that qualifies in Salesforce, with assignment rules and a conversion step that sales performs. Contacts suit an org that qualifies in HubSpot and sends Salesforce only people worth an account.
Lifecycle stage can follow the opportunity when the automatic lifecycle stage setting is on, as the opportunity sync documentation describes. An opportunity stage change moves the HubSpot contact forward and never backwards, and only through contact roles, while a HubSpot lifecycle change never converts the Salesforce lead.
Record Ownership and the Integration User
Any Salesforce owner can sync into HubSpot. A HubSpot owner reaches Salesforce only when it matches an active Salesforce user's name and email address, and otherwise the Owner ID resets to its last Salesforce value, per the field mapping documentation. Salesforce requires an owner on every record, so an unassigned HubSpot record that creates a Salesforce record is assigned to the connected user. New leads are the documented exception: a HubSpot contact with no matching owner that creates a lead is routed by Salesforce lead assignment rules instead. A user created for the connector alone therefore doubles as a diagnostic, because a Salesforce report filtered on that owner lists every record the connector created without an owner that no assignment rule claimed.
Salesforce API Call Budget on Sample Data
The connector spends from an API budget that the whole Salesforce org shares. Salesforce's developer documentation, API Request Limits and Allocations, sets the Enterprise Edition limit at 100,000 calls plus 1,000 per Salesforce licence per 24-hour period, before any purchased add-ons. The limit is enforced against every API call made to the org, not per user, and the System Overview page in Setup reports its use. In HubSpot, the Sync Health tab shows the connector's use over the last 24 hours and an Allocated to HubSpot field that caps it, as the sync error documentation shows. The installation documentation states that one contact sync can take up to four calls.
The figures below are sample data for an illustrative org, not a client: Salesforce Enterprise Edition with 60 licences, 48,000 HubSpot contacts and an inclusion segment of 9,000.
| Quantity | Derivation | Calls |
|---|---|---|
| QuantitySalesforce limit | Derivation100,000 + 60 × 1,000 | Calls160,000 |
| QuantityAll API use, last 24 hours | DerivationSystem Overview in Salesforce Setup | Calls96,000 |
| QuantityThe connector's use, last 24 hours | DerivationSync Health in HubSpot | Calls22,000 |
| QuantityEvery other consumer | Derivation96,000 − 22,000 | Calls74,000 |
| QuantityAllocated to HubSpot | DerivationChosen | Calls60,000 |
| QuantityMargin for other consumers' peaks | Derivation160,000 − 74,000 − 60,000 | Calls26,000 |
Marketing then rebuilds its lead score, which is mapped Two-way to a Salesforce field, and the rescore changes the score on every contact. With no inclusion segment all 48,000 contacts are eligible, and at the four-call ceiling the change needs 192,000 calls, which is 3.2 days of the entire allocation. Inside the segment, 9,000 members need 36,000 calls, or 0.6 of a day, and a manual resync of the segment needs 27,000 calls available.
The segment is therefore an API control as well as a scope control. A mapped field that changes in bulk, as a lead score does, costs calls for every in-scope contact on every change, so the case for mapping it rests on the other system acting on it. The four-call figure is a ceiling that HubSpot says can vary, so the example measures capacity rather than traffic.
HubSpot Salesforce Integration Guide: Configuration Order and Verification
- Confirm a Professional or Enterprise HubSpot edition, a Salesforce edition with API access or Salesforce Professional, and a connected user who is a system administrator holding the permissions HubSpot lists, including API Enabled, View Setup and Configuration, and Modify All on each synced object.
- Read the API budget from System Overview in Salesforce Setup, and derive the allocation as in the sample table.
- Install against a sandbox first: open the HubSpot Marketplace, search for Salesforce, click Install, and select Yes, this will connect to a sandbox.
- Build the inclusion segment as an active segment, including the Salesforce ID clause, and select it under Data sync > Contacts > Sync rules > Limiting what syncs.
- On the same screen, choose lead or contact creation, contact creation in HubSpot, deletion and lifecycle behaviour; if leads are chosen, turn off automatic company creation.
- Write the mappings under Property mappings, one owning system per field, and export them as CSV.
- Enter the allocation under Allocated to HubSpot on Sync Health, then turn on error notifications at the Daily frequency and name the person who reads them.
- Turn on company sync and import accounts before turning on deal sync.
- Verify with four sandbox records, allowing one 15-minute check cycle after each change. A HubSpot contact meeting the segment appears in Salesforce as the chosen object. A Two-way field edited in Salesforce reaches HubSpot. A field mapped Always use Salesforce, edited in HubSpot, does not reach Salesforce. A lead created in Salesforce below the qualification criteria, then edited there, shows the edit in HubSpot; if it does not, the segment is gating the pairing. Finish by comparing the use on Sync Health with step 2.
HubSpot Salesforce Integration Issues and Their Mechanisms
A HubSpot edit reverts to its earlier value. The mapping uses a Salesforce-first rule while Salesforce holds a value, or, for owner, the HubSpot user matches no active Salesforce user by name and email. The fix lives in the rule or the user record.
Salesforce edits to a lead never reach HubSpot. The contact sits outside the inclusion segment, so it was created once from Salesforce and its updates then stopped. The fix belongs in the segment's criteria.
Duplicate companies appear in HubSpot after sales converts leads. Contacts sync as Salesforce leads while automatic company creation is on, and the integration deduplicates companies through contacts rather than domain. The fix is to sync contacts as contacts or turn company creation off; existing duplicates need the cleanup described in HubSpot duplicate management.
A newly mapped field shows stale values or overwrites newer HubSpot ones. A new mapping moves no existing values until a resync or a Salesforce import, and a record with no sync history on the field takes Salesforce's value as its baseline at first sync. The fix is to choose the rule before running a deliberate resync.
Records fail with a custom code or picklist error. A Salesforce validation rule, flow or automation rejected the write, or a HubSpot option's internal value matches no Salesforce picklist value. The sync error documentation places the first fix with the Salesforce administrator and the second in aligned internal names.
A deal never becomes an opportunity, or an opportunity never becomes a deal. The deal sits in a pipeline that is not Salesforce-synced, the opportunity's stage is inactive or absent from the HubSpot pipeline, or opportunities lack a record type while record types are enabled. The sync error documentation lists the last two as picklist errors, and the fix lives in the Salesforce stage values or record types.
Updates lag behind a bulk change. The change has consumed the allocation, which Sync Health shows as calls used against calls allocated. The durable fix is a smaller segment or fewer mapped fields.
The Business Case for Running Both Platforms
What the connector buys is a joined record without a migration. Sales keeps the Salesforce process it is forecast through, marketing keeps HubSpot's automation, and opportunity outcomes reach the HubSpot contact.
What it costs is a permanent reconciliation surface: API calls from a shared budget, administrators fluent in both systems, and an error queue with a named owner. The segment, the rules and the ownership design need revisiting whenever either system adds a field, a validation rule or a pipeline, a discipline set out in HubSpot integration architecture.
The case is strongest where Salesforce holds a sales process that sales will not leave, and the population crossing is a qualified subset with few Two-way fields. It is weakest where the same people work in both systems every day, or where the connector was installed as a bridge during a migration that never finished. A manufacturer that kept both platforms, with a written conflict policy for each field, is described in the illustrative HubSpot Salesforce integration case study.
The firm is a HubSpot Solutions Partner, with an interest in where a two-CRM estate settles. The axes on which an alternative to the native connector wins are therefore taken from the documentation. The connector links one Salesforce instance to each HubSpot account, so two Salesforce orgs need middleware or a custom build. It syncs currency amounts without conversion, and selective sync, its filter on records arriving from Salesforce, does not cover leads or contacts. Whether to keep both platforms at all is examined in HubSpot against Salesforce on record access and data model.
Boundaries of the Evidence
This covers the native connector in its standard configuration, not the separate Salesforce Selective Sync setup, the updated deal sync, custom object sync, the HubSpot Embed window, or middleware. Moving records permanently between the platforms is a migration, sequenced in the CRM data migration method.
Settings, paths, limits and behaviour are as documented in September 2026, and the vendor documentation governs as the product changes. Every behavioural claim here is documented behaviour, not a measurement in a live org. The API figures apply a documented formula and ceilings to sample data, and HubSpot does not document how a backlog is worked once the allocation is spent. The segment design and the field-level security pattern are inferences from the two vendors' documentation, not described by HubSpot, and nothing here measures how frequently any listed issue occurs.
Frequently Asked Questions
Which subscriptions does a HubSpot and Salesforce integration require?
A Professional or Enterprise edition of a HubSpot hub or Smart CRM, and a Salesforce edition with API access or Salesforce Professional; Group Edition is not supported.
Does the Salesforce integration with HubSpot sync leads?
Salesforce leads and contacts both sync to HubSpot contacts, and one setting decides whether a HubSpot contact creates a Salesforce lead or a Salesforce contact.
Which screen holds the Salesforce integration HubSpot settings?
Under Settings > Integrations > Connected Apps > Salesforce, where the Data sync tab holds sync rules and mappings and Sync Health holds API use and errors.
Which HubSpot Salesforce integration best practices carry the design?
An inclusion segment that keeps every already-paired record in scope, one owning system per field expressed through its sync rule, and an API allocation derived from the org's measured use.
Is there a Salesforce HubSpot integration guide from HubSpot itself?
HubSpot documents the connector across several articles, beginning with Connect HubSpot and Salesforce; the procedure above orders those steps and adds verification.
Is the Salesforce and HubSpot integration expensive in API calls?
It can be: HubSpot documents up to four calls per contact sync and three per member for a segment resync, all drawn from the org's shared daily limit.
Salesforce HubSpot integration and challenges: which are structural?
Two are structural rather than configurational: no sync rule makes HubSpot authoritative over a populated Salesforce field, and the inclusion segment gates updates in both directions.
In Summary
The HubSpot Salesforce integration pairs contacts with leads or contacts, companies with accounts, deals with opportunities and tickets with cases, resolving each mapped field through one of four sync rules. Only Two-way carries a HubSpot edit onto a populated Salesforce field, so a HubSpot-owned field is protected by Salesforce field-level security or not at all.
Record scope is set in two systems. The connected user's permissions bound both directions, and the inclusion segment, described as a filter on what HubSpot sends, gates updates and email opt-out in both directions for any contact outside it. It also caps what a bulk change costs: in the sample org, one rescoring run took 3.2 days of the allocation without a segment and 0.6 of a day with one.
The change to make before production is in the segment definition. Write it as the qualification criteria or a known Salesforce Lead ID or Contact ID, then create a lead in the Salesforce sandbox, edit it, and confirm the edit reaches HubSpot. A connector that passes that test has its scope set on purpose, not by the first criteria typed into a segment.