The Definitive Guide to HubSpot & Salesforce Integration

The Salesforce integration is one of the most popular integrations in HubSpot’s App Marketplace. Salesforce has been around for several decades, and many sales teams rely on its data. As marketing and sales teams become more and more integrated, they are recognizing the need to resolve friction when they work in different systems. 

In many companies, the sales team uses Salesforce and the marketing team uses HubSpot. This separation can lead to siloed data, making it difficult to see how clients’ marketing and sales efforts are performing. With the Salesforce integration, both systems are connected so that users can access critical data from both systems.

Depending on your needs, a HubSpot and Salesforce integration will lead to:

• Better-aligned sales and marketing teams
• Improved reporting
• Successful performance of complex actions in both systems

This guide provides a basic breakdown of the HubSpot-Salesforce integration journey, starting with the prerequisites for integration, followed by the process for properly connecting the two systems, and finally common errors (and resolutions!) that occur during most integrations. 

Preparation is key to the success of your integration. During this stage, you are determining the rules of moving the data back and forth between the two systems.

You have two options:

• Sync everything between the two systems (the easiest option)
• Sync a subset of contacts between HubSpot to Salesforce

Ultimately, your three main data pools come from: 

• Companies (HubSpot) —> Accounts (Salesforce)
• Contacts (HubSpot) —> Contacts and Leads (Salesforce)
• Deals (HubSpot) —> Opportunities (Salesforce)

Rarely do two integrations look exactly alike, so the more clearly you can determine the rules of moving the data, the easier it will be. Keep in mind that errors will happen, regardless of how much you prepare; this is just part of the gig. We’ll get more into resolving those errors later on. 

1. Work with Your Team on an Integration Mapping Document

Before you do anything else, work on an integration mapping document with your sales and marketing teams who know the data best. Your ultimate rulebook of data movement, this document outlines:

• HubSpot properties and property types and Salesforce fields and field types to sync them to for Contacts, Companies, Deals, and Activities
• Whether data should sync both ways, not sync, prefer Salesforce unless blank, or always prefer Salesforce
• Custom objects and their fields in Salesforce that will sync one-way to HubSpot

The primary goal here is to fill out all of the fields and identify the sync settings for each before starting the migration. Additional rows should be added for any custom properties.

If you’re starting an integration mapping document from scratch, take a look at the one we use at SmartBug to get started! 

2. Create an Integration User (or Request a Salesforce Admin User from Your IT Team) 

As soon as you start working on the mapping document, request that your IT department create a Salesforce user specifically for the integration that has administrative access. (If you have administrative access to Salesforce, you can create the integration user yourself.) You might not believe it, but getting an integration user for Salesforce with admin access is often one of the longest tasks in the integration project.

The username (i.e., email address) of the integration user does not matter, but make sure that the mobile phone is yours so that you receive the verification code when setting up the integration.

We highly recommend not using a person’s Salesforce account as the integration user because the integration will break when the person leaves the company, changes their password, or moves departments. The integration user should be a dedicated account in Salesforce.

3. Conduct the Kick-Off Call(s) with Your Teams

Conducting a kick-off call (or calls) provides the opportunity for your marketing, sales, and sometimes even operations teams to get aligned. Your kick-off call should encourage discussion rather than simple yes or no responses, so expect this meeting to be anywhere between an hour and an hour and a half.

Make sure all relevant marketing and sales leaders and your Salesforce administrator are in attendance. You’ll get better, more direct answers in less time.

During the meeting, make sure to discuss:

• Goals. Clearly state the goal of the project and the benefits to both teams in integrating the data.
• Project timeline. After outlining a feasible timeline, determine if the deadline is hard and fast.
• Mapping document. This document does not need to be completed before the kickoff call. The call is a good opportunity to discuss questions and concerns about the document.
• Who will use what system. Though most marketing team members will not need a Salesforce login, we do recommend each sales team member have a HubSpot user account (you can give them a free marketing seat). This is so that they can see the Visualforce component in Salesforce with HubSpot contact activity.
• Where reporting occurs. Although sales reporting often happens in Salesforce and marketing reporting in HubSpot, if you are looking for attribution reporting, we recommend using HubSpot. This requires Opportunities to be synched with Deals in HubSpot.
• Leads and/or contacts. Determine if you will be synching both leads and contacts in Salesforce to HubSpot as well as if HubSpot should be creating new leads or contacts in Salesforce.
• External applications and integration. If you have any third-party software integrated with Salesforce (such as ZoomInfo or Drift), talk through whether this will automatically bring data to HubSpot or if you need to integrate it there as well.
• Whether all Salesforce contacts should be marketing contacts. This will depend on if you have room in your number of marketing contacts in your HubSpot subscription. Remember: Salesforce charges according to the number of users; HubSpot charges according to the number of marketing contacts. You can store extra contacts in HubSpot and mark them as non-marketing.
• Long-term support. Determine the point person for the integration after setup. This role might be you or your IT team (if your company has one). 

4. Clear Space in Your Schedule

A typical integration takes about 20 hours, including a few hours of watching for extra sync errors after setup. However, these 20 hours are usually spread out over the course of a month or longer. In most cases, the integration takes longer than a month, but the pace of the project is based on how quickly you: 

• Finish the mapping document
• Obtain a Salesforce admin login for the integration user
• Resolve integration sync errors

Be sure to leave enough time to test the integration. You’ll want to do everything from “create a contact in HubSpot, make sure it’s a lead in Salesforce” type of testing to making sure any lead routing and automations are running correctly.

Before the integration begins, prepare yourself for a whole lot of errors at first. This is typical and shouldn’t cause a panic. No database is perfect and no database is 100 percent clean.

Finally, almost every decision made during the kick-off call can be changed or updated in the integration settings, so don’t feel as though anything is set in stone! 

As soon as you have completed the preliminary steps, it’s time to connect the two systems! 

Step One: Completing the HubSpot Install

In HubSpot, go to the App Marketplace and search for Salesforce. It should be the first result with the Salesforce cloud logo. After you click “Install app,” a new page will instruct you to begin the integration.

Step Two: Navigating Through the Integration Setup

The integration setup requires a series of small steps: 

• The first page will ask you to log into Salesforce. If you are testing in a sandbox environment (a copy of your organization’s data in a separate database that you can use for testing and training), you can check the box.
• After clicking “Allow” for the “Allow access” pop-up, start the app installation process. You will have to log in again.
• Click “Install for All Users.”
• Click “Yes, grant access to these third-party web sites” and then “Continue.”
• The installation process may take a few minutes.
• You can add the Visualforce component to the page layouts in Salesforce now, but it’s not a necessity for integration (you can also do this later).
• Before finishing the setup and syncing, you will get a chance to review the sync settings one last time.

Step Three: Choosing HubSpot Sync Settings

Once you have the app installed in HubSpot, you’ll need to go to the Sync Settings tab to update the HubSpot to Salesforce and Salesforce to HubSpot settings.

You get here by going to “Settings” -> “Integrations” -> “Connected Apps” -> “Salesforce.”

Here you can set:

• The inclusion list (defines which contacts in HubSpot should sync with Salesforce)
• Whether a new HubSpot contact gets created as a lead or contact in Salesforce
• If the state/country values are picklists or not
• If a new Salesforce contact/lead creates a new record in HubSpot
• If a contact’s lifecycle stage changes in Salesforce updates the lifecycle stage in HubSpot
• If needed, switch out or reconnect the integration user

Step Four: Identifying Mappings

You can identify your field mappings during the setup (step two above), or you can do it in the settings after the two systems are integrated.

All standard fields will be mapped automatically, but now you will want to pull out your Integration Mapping Document to ensure all fields’ sync rules are set up to match your document. You will also want to add any custom field mappings per your document.

Look for the following:

• Are all standard and custom fields identified in the Integration Mapping Document included for Contacts, Companies, and Deals?
• Are the sync rules correct?
• Is HubSpot showing a red error (issue) or yellow error (warning) on any of the mappings?

You will likely need to add a new mapping. To do so:

• Go to the tab where you want to add a new mapping (Contacts, Companies, or Deals).
• Click “Add new mapping.”
• Choose the HubSpot property you want to map (or create a property in the window).
  Choose the Salesforce field you want to map to.
• Choose the sync rule (2-way, don’t sync, prefer Salesforce, or always use Salesforce).
• Choose whether you want to sync the field now or gradually. If you’re close to hitting your API limit, choose gradually. Otherwise, it’s fine to sync now.
• Click “Save”!

Step Five: Importing Information

Once the integration is complete, you may want to see the Salesforce information immediately. (We all get impatient sometimes!) You can do so by going to “Import and Export” in HubSpot:

• Go to Settings.
• Click “Import & Export.”
• Click the “Go to import” button.
• Click the “Start an import” button.
• Select “Integrations,” then “Salesforce records,” then “Standard Objects.”
• From there, you can select specific objects or “everything.”

If you skip the above steps to force the data to import from Salesforce now, the Salesforce information will trickle in based on records being updated in Salesforce. 

We wish this wasn’t the case, but errors are very common in a HubSpot and Salesforce integration. You might as well consider them part of the process.

Luckily, as common as they are, errors are relatively easy to fix. In our experience, here are some of the most common errors that you can expect to see:

1. Associations

Association errors happen when a record in Salesforce is associated with another record (usually a contact or company) that is not in HubSpot. This most commonly occurs when you are using selective sync and the opportunity in Salesforce is associated with a contact that isn’t part of the sync and thus is not in HubSpot. Then the opportunity (i.e., deal in HubSpot) won’t sync at all.

The easiest way to fix this is to import all records and then try to resync. 

2. Custom Code

A custom code error is usually caused by a Salesforce validation rule, automation, or flow preventing the sync.

To fix validation rule errors, you should: 

• Update the HubSpot record to fit within those rules (best solution).
• Update the Salesforce validation rules to ignore the integration user (not recommended because the data will be less clean).
• Update the HubSpot inclusion list to exclude records with missing information (not recommended if those contacts should sync otherwise).

To fix automation or flow errors, click into the Custom Code error to find the details to send to your Salesforce Admin to fix.

3. Duplicates

Although HubSpot automatically de-duplicates based on email, Salesforce does not, which means if duplicate emails are found in Salesforce, HubSpot will show this error.

To fix the error:

• Merge the records in Salesforce.
• Change the emails in Salesforce.
• Separate out contacts in HubSpot.

4. Permissions

Permission errors often occur because the Salesforce integration user does not have the necessary access to view, edit, or create a record. This will most likely happen for any selective sync integration users or a user who does not have full admin rights in Salesforce.

To fix the error, update the Salesforce permissions or field access.

This error can also occur when there is a reference field issue (called a lookup field) in Salesforce. This happens when a lookup field in Salesforce is deleted, any of the children are deleted, or if there are limited permissions around that lookup object but not the actual record itself.

Update the property type in HubSpot to be a drop-down select.

5. Picklists

A picklist error occurs when the picklist values between the two systems do not match or the Salesforce record owner is either not in HubSpot or they are inactive.

To fix this error:

• For non-matching values, update either the HubSpot property or the Salesforce field to have the missing values.
• For Salesforce owners, either import active Salesforce users into HubSpot as free marketing users or reassign the records in Salesforce to active users.

6. Field Mappings

Field mapping errors occur because the property/field mappings are not compatible or the property/field no longer exists.

For field mapping sync settings, HubSpot color codes the status of the sync:

• Green means you’re good to go!
• Orange is most likely warning you that a property is mapped to multiple fields. Sometimes this is intentional, such as mapping the address in HubSpot to both the shipping and billing address fields in Salesforce. This warning also indicates a missing drop-down value for you to fix.
• Red is an issue and usually means that either the integration user is missing the correct permissions or the field is deleted in Salesforce.

To fix the error:

• Update the property/field type to a more compatible format.
• Re-map the property/field to another property/field.
• Delete the property/field mapping.

7. Property Values

Property value errors occur because the property value is not valid. This often occurs when an email address in Salesforce is invalid, usually because of a typo in an email address. 

To fix this error: 

• Update the email address in Salesforce. 

8. Other Sync Errors

Other sync errors are much harder to diagnose. Luckily, HubSpot will usually list a reason for an error. If the error isn’t listed, try Google to see if someone out there has an answer, wait out the error (as long as it doesn’t affect real data), or loop in your IT team for help.

9. Visualforce Issues

A common complaint you might get is that sales team members can’t see the Visualforce component with HubSpot data or they can’t see any data in the component on the contact record.

To troubleshoot: 

• Check the users’ browsers to see if they have cleared their cookies. If they’re using Chrome or Edge, it could be an extension on their browser that’s blocking the Visualforce component. Safari sometimes has more issues than the other two browsers, so switching to Chrome or Edge may be the answer.
• Make sure that they are clicking “Remember Me” when logging into HubSpot. Users have to be logged into both platforms to see the data.
• If your Salesforce users are not also HubSpot users, you can import active Salesforce users into HubSpot so they can see the component. They need a minimum of “Contacts View Access” in HubSpot.
• Have your Salesforce Admin ensure that those team member profiles in Salesforce have access to the HubSpot app. (When starting the app installation, did you accidentally install for select profiles instead of all users?)

As you’ve read, integrating HubSpot and Salesforce is a process that requires patience, curiosity, and very clear lines of communication. Although no integration will ever look the same as another, you can follow this process to ensure you reduce as much friction as possible.