Connect and use HubSpot data sync

With HubSpot data sync, you can create a one-way or two-way sync between HubSpot and your other apps to unite all of your customer data in one platform. Review which apps use data sync here. 

Below, learn how data sync works and how to connect an app, turn on data sync, resync records, and more.

How data sync works

When a sync is activated, data sync creates an internal index of all records in an object. It then uses that index to compare and monitor record changes to see how their state (syncing, failing, or excluded) should change as the record properties are updated. This means that the internal data sync index continually compares its database (either HubSpot or the connected app) and can recover any dropped or errored API call or endpoint.

When a record is updated, the sync engine examines the entire record against the copy it has and updates its copy to match the real record. This allows it to recover any missed or failed updates. Data sync might take some time to index all records when initiated, but will ensure a smoother and healthier sync experience. 

Sync principles

A data sync will always be between two apps, one being HubSpot. Every sync has two main phases, independent of the object syncing:

• The initial sync: starts when a sync is activated or when saved. All existing records in both apps are passed through the sync engine to index, and if applicable, sync them.
• The incremental sync: when all records are indexed they are scanned for updates and new records. Indexed records that have changed since the last time they were checked are passed through the sync engine.

Initial sync

For a two-way sync, the initial sync consists of:

• Index HubSpot: the HubSpot records are scanned and the ID of the record and its matching identifiers are stored (by default this is the email for contacts, and name and/or domain for companies). The index is kept up to date throughout the entire syncing process going forward. Read more on how matching works. 
• Index the other app, and sync: the records from the other app are scanned and synced. For every resource that is fetched, a check is made to see if there's any matching identifier (e.g., email address for contacts) in the index table of HubSpot. If there is, the records are matched and both records are passed through the sync engine together. If there isn't a match, the record will go through the sync engine on its own. When the sync engine matches records, it combines all the information it has (the records' field values, the filters, field mappings, sync history, etc.) and based on that, it builds the next action (request changes to the resources, do nothing, log an error, etc.)

Please note: the first record returned by the app's API will be syncable, the next one will be considered a duplicate.

• Sync HubSpot: the HubSpot records are scanned again to check if they need to be synced. This step will result in the syncing of existing records in HubSpot, not in the other app.

Incremental sync

The incremental sync constantly scans for updates in HubSpot and the other app (based on the sync direction) and waits to be triggered. HubSpot checks if there are changes every five minutes. The other app, or its API, uses webhooks to alert of any changes.

Connect an app

Before you begin

• You must be a Super Admin or have App Marketplace permissions in your HubSpot account.
• There may be other permissions required for the specific app you're connecting to your HubSpot account.

Connecting the app

There are two ways to search for and connect to an app. You can do so via the App Marketplace, or through the imports page. 

1. In your HubSpot account, click the Marketplace icon marketplace in the top navigation bar, then select App Marketplace.
2. In the search bar, enter the app name, then click the search result. 
3. In the top right, click Install app.
4. In the dialog box, click Next, then log in to your app account.
5. Review the requested access permissions, then click Allow. You'll be redirected back to the app page in your HubSpot settings.

If you're setting up a sync from the imports page:

1. Click Import in the top right of any object home page, or access your import settings:

• • In your HubSpot account, click the settings settings icon in the top navigation bar.
  • In the left sidebar menu, navigate to Import & Export.
  • Click Go to import.

2. Click Set up a sync. 

3. In the right panel, enter the app name, then click the search result. 
4. Click Install app. 
5. You'll be redirected to the app's listing page to continue with the connection steps. 

It's possible to connect more than one instance of the same third-party app to HubSpot. For example, if you're managing two Microsoft Dynamics accounts, you can connect and sync data from both accounts with one HubSpot account. To connect an additional account:

1. In your HubSpot account, click the settings settings icon in the top navigation bar. In the left sidebar menu, navigate to Integrations > Connected Apps.
2. Click the name of the app. 
3. Click Actions > Manage accounts. 
4. In the right panel, click Connect another account. 
5. Proceed with the steps to connect the app to HubSpot. 

Turn on data sync

After connecting the app, you will need to configure your app settings and turn the sync on to begin syncing data between the two integrations. 

1. In your HubSpot account, click the settings settings icon in the top navigation bar. In the left sidebar menu, navigate to Integrations > Connected Apps.
2. Click the app.
3. Click Set up your sync.
4. On the Select the data you want to sync page, select the object to sync to, or from in the app, and the object you want to sync to or from in HubSpot.
5. Click the arrows dropdown menu, and select whether the sync is bi-directional or one way between the app and HubSpot, or vice versa. 

To turn off a mapping, click to turn the toggle off. 

To set up a custom field mapping:

1. Click Add a mapping. 
2. Use the dropdown menus to select the third-party app and the HubSpot property you want to map.
3. Click success Update.

4. To turn off custom mappings, click to toggle the switch off. 

Learn more about specific rules and considerations for data sync field mappings. 

Set up your sync rules

On the Limit screen, configure how you want to sync records from HubSpot to your third-party app, and vice versa.

If you're configuring a deal sync, you'll be prompted to map your deal pipelines and stages between HubSpot and your third-party app. Only deals in the mapped deal stages will sync. 

1. In the Map your deal pipelines and stages section, click the Choose a HubSpot pipeline dropdown menu to choose which HubSpot deal pipeline you want to sync with your third-party app.
2. Click Auto-map to automatically map HubSpot deal stages with your third-party app’s deal stages. The sync does a simple text search and attempts to map similar-sounding stages.
3. To map an additional pipeline, click Map another pipeline.

If you’re unable to view deal stages from your other app in HubSpot, it is because of the following reasons:

• The connected user account doesn't have the correct permissions to view the deal stages.
• Data sync maps HubSpot deal stages with pipeline stages in your other app. If you have a non-standard sales process that doesn't rely on deal/opportunity stages, you won't be able to sync data using HubSpot data sync.

If you're configuring a contact sync, by default, HubSpot will only sync contacts that have a valid email address. To also sync contacts without an email address, in the Duplicate reduction section, clear the Only sync contacts with an email address checkbox.

Learn more about matching records.

Please note: when an app has both a company name and company domain field, HubSpot will match two records if they have the same company name but a different domain, and vice versa.

In the Filters section, choose criteria to limit which records will sync from HubSpot to your third-party app, and vice versa:

1. Click Edit.
2. In the right panel, select the property to limit records syncing from HubSpot to your third-party app, and vice versa.
3. Click Done. 

Please note: the Filters section only limits which records initially sync between HubSpot and the third-party app. Once records sync, they will continue to sync data back and forth based on the property mapping set up.

Associate records

HubSpot attempts to maintain the same associations between records (e.g., companies associated with contacts, or deals associated with companies) when syncing with the original app you connected, whenever possible. Learn more about association mapping with data sync.

Please note: in most cases, data sync can only automatically associate invoices to contacts. Invoices must be manually associated to company records in HubSpot. 

Review rules and start the sync

In the Review screen, review the rules you’ve configured, then click Save and sync. The initial sync will then begin to process.

After the initial sync is complete, records will sync within 10 minutes of a change. 

Resync deleted records

If you've deleted records in either HubSpot or your third-party app, you can resync deleted records to recreate them in either app:

1. In your HubSpot account, click the settings settings icon in the top navigation bar. In the left sidebar menu, navigate to Integrations > Connected Apps.
2. Click the app.
3. On the Object view tab, in the Failing column, click the number of records that are failing to sync. 
4. In the right panel, click Actions.
5. Select either Resync deleted records in HubSpot or Resync deleted records in [third-party app].

6. Click Resync all. 

You can also:

1. On the Record view tab, click More > Restore all deleted records. 
2. In the side panel, click the Record type dropdown menu and select the record type and the Destination app dropdown menu to select which app to recreate the contacts in. 
3. Click Review before restore. 
4. Review all the records that will be restored, and click Restore all [number]. 

Turn off data sync

1. In your HubSpot account, click the settings settings icon in the top navigation bar. In the left sidebar menu, navigate to Integrations > Connected Apps.
2. Click the app.
3. Click the Actions dropdown menu and select Turn off sync.

4. In the pop-up box, click Turn off sync.

Once the sync has been turned off, you can turn it on again by clicking Edit sync settings, or delete the sync. 

Review your sync health

After connecting an app, view an overview of the records syncing between HubSpot and your third-party app. 

1. In your HubSpot account, click the settings settings icon in the top navigation bar. In the left sidebar menu, navigate to Integrations > Connected Apps.
2. Click the app.
3. On the Sync overview tab, click Object view to view the sync status by objects.

• • Records that are being processed as part of an initial sync will have spinning circles next to them.
  • A record will have a status of In queue if another sync is in process, to prevent updates happening on the same data, at the same time. 

4. In the In sync column, click the number of records to review all records syncing between HubSpot and the app.
5. In the Failing column, click the number of records to view all records failing to sync between HubSpot and the app. 

• • In the Error category column, review the reason for failure.
  • Hover over the tooltip to review steps to resolve.

6. In the Excluded column, click the number of records to view all records excluded from sync. This could be because they do not match any of the filters in your sync settings, or they do not have a unique identifier assigned to them, which may be due to a matching key being defined. 

• • Click to view all records syncing between HubSpot and the app.
  • Use the dropdown menus to filter the records by object type, syncing status, or a specific time frame.

• To edit the order of the columns, click More > Edit columns. 
• To export all records, click More > Export. 
  • In the dialog box, select the file format. 
  • Click Export. The exported file will be emailed to you.
• To restore all deleted records, click More > Restore all deleted records.
  • In the right panel, select the Record type and Destination app. All previously deleted records will be restored in the selected destination app.