Skip to content

Manage your Salesforce integration settings

Last updated: March 6, 2023

Available with any of the following subscriptions, except where noted:

Marketing Hub Professional, Enterprise
Sales Hub Professional, Enterprise
Service Hub Professional, Enterprise
Operations Hub Professional, Enterprise
CMS Hub Professional, Enterprise

Learn how to manage your Salesforce integration settings after installation. This includes allocating API calls, reviewing sync errors, and updating sync settings. 

To access your Salesforce integration settings:

  • In your HubSpot account, click the Marketplace icon marketplace in the main navigation bar. Under Manage, select Connected apps.
  • Click Salesforce

Manage API call use and review sync errors

On the Sync Health tab, you can view the number of API calls used by the integration in the last 24 hours, as well as all sync errors preventing data from syncing between the two systems. The API call limit for HubSpot should be set based on your Salesforce API call limit, as well as your current Salesforce API call usage.

To adjust the number of Salesforce API calls allocated to HubSpot:

  • Under Allocated to HubSpot, enter the number of API calls to allocate to the integration, then click Update.

The Sync errors section shows all sync errors that are preventing data from syncing between the two systems. View cards for each error type, with the number of current errors and impacted records for each. Click an error type card to see details of the errors in the right panel. Learn more about sync errors


Manage sync settings

On the Sync Settings tab, you can view which integration user is connected to Salesforce and set rules for how data should sync to and from HubSpot. 

To access your sync settings, click the Sync Settings tab. The How it works section outlines how the HubSpot-Salesforce integration works, including the sync direction between the two systems, sync frequency, and deduplication methods. 

Set rules for how data syncs from HubSpot to Salesforce

To configure the settings for how data syncs from HubSpot to Salesforce: 


  • Click the HubSpot –> Salesforce tab.
  • In the Limiting what syncs section, create or select an inclusion list to limit the contacts that sync from HubSpot to Salesforce. Contacts that are not in your inclusion list will not sync from HubSpot to Salesforce. Learn more about creating a Salesforce inclusion list.
  • In the Creating leads/contacts section, choose whether any new contacts created in HubSpot should be created as Salesforce leads or contacts. For existing contacts, HubSpot will update their existing contact record with new data.

    Please note: When Create a lead is selected in the Creating leads/contacts section, it is advised to turn off the setting to automatically create and associate companies with contacts in HubSpot. Salesforce leads do not have accounts, and the Salesforce integration uses associated contacts to deduplicate companies, not the domain. When a HubSpot contact is initially created as Salesforce lead with no account, as soon as you manually create an account or convert the lead to a contact in Salesforce, a duplicate company will be created in HubSpot.

    If you want the automatically create and associate companies with contacts setting turned on, it is strongly recommended to sync HubSpot contacts to Salesforce as contacts in order to avoid duplicates being created.

  • In the Matching state and country fields section, choose if default state and country values in HubSpot should be converted to pass validation for Salesforce's State and Country picklists.

    • Click the Tell us about your Salesforce state and country picklists dropdown menu and one of the following:
      • The picklist is disabled in Salesforce.
      • The picklist is enabled in Salesforce.
      • The picklist is enabled and customized in Salesforce.
    • Click the HubSpot will dropdown menu and select one of the following:
      • Match default Salesforce state/country values when syncing.
      • Sync HubSpot state/country values to Salesforce.

Set rules for how data syncs from Salesforce to HubSpot

To configure how data syncs from Salesforce to HubSpot:

  • Click the Salesforce -> HubSpot tab.
  • The Limiting what syncs section states only records with a valid email address can sync to HubSpot. To further limit which Salesforce records can be added to HubSpot, use Salesforce selective sync.
  • In the Updating leads section, decide what happens to contacts in HubSpot when a lead is created, updated, or deleted in Salesforce. 
    • Click the Create or update the contact dropdown menu to decide what happens in HubSpot when a Salesforce lead is created or updated: 
      • Do nothing in HubSpot: new or existing Salesforce leads/contacts that are updated will not automatically create HubSpot contacts.
      • Create or update the contact in HubSpot: new Salesforce leads/contacts created with a unique and valid email address will be created/updated HubSpot contacts.
  • Please note: if new Salesforce leads or contacts are set to create HubSpot contacts, a corresponding contact will be created or deduplicated in HubSpot when a Salesforce lead or contact is created, even if the HubSpot contact is not in the inclusion list. Further updates to the contact/lead from either HubSpot or Salesforce will not sync to the other platform.
  • Click the Delete the contact in HubSpot dropdown menu to decide what happens in HubSpot when a Salesforce lead is deleted:
    • Delete the contact in HubSpot: the contact record will be deleted. This setting does not work retroactively (i.e. it will not delete contacts in HubSpot that were already deleted in Salesforce before the setting is turned on). 
    • Do nothing in HubSpot: contacts will not be deleted in HubSpot when deleted in Salesforce. 
  • The settings above are automatically applied for contacts syncing from Salesforce. Clear the checkbox in the Updating contacts section to set different rules for contacts.


  • In the Adjusting lifecycle stage section, choose if actions taken on an associated Salesforce record will impact the lifecycle stage of the corresponding HubSpot contact.
    • Click the Update the contact's lifecycle stage in HubSpot dropdown menu to decide what happens when a contact's opportunity stage is update in Salesforce:
      • Update the contact's lifecycle stage in HubSpot: a Salesforce contact associated with an open opportunity will update the lifecycle stage of the corresponding HubSpot contact to Opportunity. If the opportunity is marked as Closed Won in Salesforce, the lifecycle stage of the corresponding HubSpot contact will change from Opportunity to Customer.
      • Do nothing: the contact's lifecycle stage in HubSpot will not be affected. 


Please note:

  • This setting will not move a HubSpot contact's lifecycle stage backwards. For example, if a HubSpot contact already has a lifecycle stage of Customer, they will not move back to Opportunity if their corresponding Salesforce contact is associated with an open opportunity.
  • The lifecycle stage of a HubSpot contact will not impact any corresponding Salesforce records. For example, setting the lifecycle stage of a HubSpot contact to Customer will not convert the corresponding Salesforce lead to a contact.
  • The Salesforce contact must be associated with the opportunity via contact roles. Custom relationship fields between Salesforce contacts and opportunities, as well as opportunities with no contact roles, will not trigger automatic lifecycle stage transitions.
  • If the companies Lifecycle stage sync setting is enabled, any other HubSpot contacts that are associated with the same company will also have their lifecycle stage updated.

Manage syncing of objects and activities

To manage how an object's data syncs between HubSpot and Salesforce:

  • Click the tab of the object you want to manage (e.g. the Contacts tab). 
  • To sync that object between HubSpot and Salesforce, click to toggle the Sync [Object] switch on
  • .You can also set up field mappings between HubSpot and Salesforce for the respective objects in the [Object] field mappings section. 

The following behavior is expected when syncing contacts, companies, and deals: 

HubSpot engagements (e.g., form submissions, email interactions, meetings, etc.) can be synced to Salesforce tasks. Click the Activities tab sync activities and tasks between HubSpot and Salesforce.

Was this article helpful?
This form is used for documentation feedback only. Learn how to get help with HubSpot.