HubSpot Contacts

​

Overview

HubSpot Contacts is a customer context source (CRM enrichment). It adds details from HubSpot to the contacts in your Dovetail contacts database: properties of each HubSpot contact, and of the company associated with it. Data flows one way, from HubSpot into Dovetail. Dovetail never writes back to HubSpot. Dovetail matches HubSpot contacts to Dovetail contacts on the Email default contact field, and updates only contacts that already exist. You choose which HubSpot properties fill which contact fields, then sync on demand or once a day. Channels 2.0 uses the company and revenue on linked contacts to roll up revenue on ideas. Learn more about customer context sources →

---

​

Prerequisites

HubSpot Contacts is set up once for the whole workspace, and permissions depend on the action:

• Connecting requires Dovetail workspace admin access and Full access or Can edit on the Contacts database. You also need a HubSpot account that can authorize the connection and read contacts and companies.
• Mapping fields and the Daily syncing setting can be changed only by the user who connected HubSpot. Other users with access to Contacts can open the configuration, but only to view it. To create a contact field while mapping, the user who connected HubSpot also needs permission to create contact fields.
• Disconnecting is limited to workspace admins.
• Running a sync, for all contacts or for one, is available to any user with edit access to the Contacts database.

Contacts are matched by email address, so a contact without an email address isn’t enriched.

---

​

Connect HubSpot

A workspace admin connects HubSpot once for the whole workspace. If Salesforce is already connected, disconnect it first.

---

​

Map fields

Mapping decides which HubSpot properties fill which Dovetail contact fields. You can map properties of the HubSpot contact (Contact.*) and of its associated company (Company.*).

​

Map a property you add later

HubSpot properties aren’t mapped automatically. When you add a property in HubSpot, map it in Dovetail so it appears on your contacts:

1. Add the property to the contact or company object in HubSpot, as you normally would.
2. In Dovetail, open the Configure HubSpot dialog and go to the Configuration tab. The new property appears in the list of HubSpot properties.
3. Map it to a contact field, or create a field for it, and select Save configuration.
4. The next daily sync fills in the values, or you can sync straight away. See Syncing your contacts.

---

​

Syncing your contacts

Once your configuration is saved, you can enrich your Dovetail contacts with HubSpot data. There are three ways to sync.

​

Set up an automatic daily sync

1. On the Sources page, select the HubSpot source under Customer context, then select Configure.
2. On the Configuration tab, turn on Daily syncing, then select Save configuration.

Only the user who connected HubSpot can change this setting. Each day, Dovetail updates the contacts it has synced before, and any other contacts whose email address matches a HubSpot contact. If a daily sync fails, or some contacts fail to sync, Dovetail notifies the user who connected HubSpot. Resolve failed contacts from the Sync Errors tab. See Resolving sync errors.

​

Sync an individual contact

1. Go to the Contacts page and select a contact that has an email address.
2. In the contact side panel, select Sync contact.

The mapped fields from their HubSpot record populate in Dovetail within a few seconds.

​

Bulk sync contacts

1. On the Contacts page, open the Sources dialog from the header and select Bulk sync next to HubSpot.
2. Select Sync contacts to confirm. Dovetail syncs every contact with a matching HubSpot record and notifies you when the sync finishes. The sync can’t be undone.

---

​

Field protection

While HubSpot is connected, a mapped field with syncing turned on is read-only on contacts synced from HubSpot. This prevents any user from editing values that the next sync would replace. To make a field editable again, turn off syncing for its row in the Configure HubSpot dialog and save the configuration, or disconnect HubSpot.

---

​

Resolving sync errors

When a contact fails to sync, Dovetail pauses syncing for that contact and lists it on the Sync Errors tab of the Configure HubSpot dialog. From the ••• menu on each row you can:

• Re-sync contact — retry the sync. If it succeeds, the contact comes off the list and syncing resumes for them.
• Un-sync contact — remove the link between the contact and its HubSpot record. The contact keeps its current data, and the next sync matches it by email address again. Use this when a contact’s email address has changed: un-sync the contact, then correct its email address.

When there are no errors, the tab shows an empty state.

---

​

Requested permissions

When you connect HubSpot to Dovetail, you grant the following read-only scopes:

• crm.objects.contacts.read — read your HubSpot contacts.
• crm.schemas.contacts.read — read the contact property definitions so you can choose which to map.
• crm.objects.companies.read — read the companies associated with your contacts.
• crm.schemas.companies.read — read the company property definitions so you can choose which to map.

Dovetail only pulls data from HubSpot — it never writes anything back. The HubSpot access token is short-lived (around 30 minutes); Dovetail uses a long-lived refresh token to keep the connection active without asking you to sign in again.

---

---

​

Troubleshooting

I can’t connect HubSpot. Only workspace admins with Can edit or Full access on the Contacts database can connect HubSpot, and a workspace can connect only one CRM at a time. If Salesforce is connected, disconnect it first. A contact didn’t get enriched. Confirm the contact has an email address in the Email default contact field, and that a HubSpot contact has the same email address. Contacts with no matching HubSpot contact are skipped. If the contact is listed on the Sync Errors tab, syncing is paused for it. See Resolving sync errors. A company property came across empty. Company properties only resolve when the HubSpot contact has an associated company. Contacts with no associated company sync their contact properties but leave company fields empty. I can’t edit a field on a contact. Fields mapped to HubSpot are protected while HubSpot is connected. Turn off syncing for the field in the Configure HubSpot dialog, or disconnect HubSpot, to make the field editable. A contact was deleted in HubSpot. On the next sync, that contact is skipped and keeps its last-synced values in Dovetail. Their data isn’t wiped.

---

​

Disconnect HubSpot

A workspace admin can disconnect HubSpot from its source on the Sources page. Dovetail loses access to your HubSpot data and stops syncing. Contacts keep the data already synced, and their previously mapped fields become editable again. Disconnecting also removes your field mappings, so if you reconnect later, map fields again before you sync. HubSpot Contacts and a HubSpot Service Hub source are separate connections in Dovetail, so disconnecting one doesn’t affect the other. To revoke Dovetail’s access from the HubSpot side, remove the Dovetail app in your HubSpot account’s Connected Apps settings (a HubSpot setting).

---

​

Related guides