HubSpot

Prioritize & personalize your marketing & sales outreach by adding customer data into HubSpot

Setup

We have created a brief product overview here that shows how to setup a sync to HubSpot. This recording contains outdated UI and will be replaced soon, but basic flow is mostly the same.

After selecting the Hubspot destination, you will have two ways to authenticate and give Hightouch certain permissions to sync data to your Hubspot account:

OAuth
Private App Token (more info here)

If there is a given private app token, we will use that when making Hubspot API requests. If you authorize through OAuth, we will delete any previous private app token, if any, and use the token generated from that.

OAuth

You can choose the OAuth route for a simple flow that will just prompt you to login and choose the account to give Hightouch access to. This will include all the necessary scopes required for all types of Hightouch Hubspot syncs. If successful, you will be redirected back to Hightouch to finish setting up.

Private App Token

You can choose to create a private app for Hightouch, which will generate a unique and long-living token specific to Hightouch. Unlike the OAuth flow where we select all the supported scopes for you, you will have to manually select which scopes you want to give access to Hightouch. For example, if you don't want Hightouch to have access to your deals, then you can unselect the "read" and "write" box for Deals.

If you later decide to create a sync to upsert deals, it will fail because Hightouch does not have access to the "Deals" scope.

Here are all the scopes Hightouch supports (read and write access):

tickets
crm.import
crm.schemas.custom (*read only)
crm.objects.custom
crm.objects.contacts
crm.schemas.contacts (*read only)
crm.schemas.companies
crm.objects.companies (*read only)
crm.objects.deals
crm.schemas.deals (*read only)
crm.lists

Syncing

Object Types

Hightouch can both create and update standard HubSpot objects (Contacts, Companies, Deals, etc. ) as well as custom objects (like "invoices" or "projects"). To use a custom object, you first need to create it in HubSpot directly.

If you created a Hubspot destination before 01/21/22, you will need to reauthorize the destination to support syncing ticket objects.

Sync Modes

The HubSpot destination has two different possible modes for how to alter HubSpot objects:

Upsert — pushes new objects to HubSpot and updates fields that change in your warehouse.
Update — updates particular fields on existing objects in HubSpot. It does not add new objects.

Record matching

Records can be matched from your source to your Hubspot objects by one of the available fields in the matching section's dropdown. The field to match should be unique, otherwise the intended records may not be updated or inserted properly. If there isn't an inherent unique property with the object's default fields, we recommend that you create a unique custom field, like an external_id. When creating a custom unique ID property, make sure to set hasUniqueValue: true with the Hubspot API. If the field is not marked as unique in Hubspot, record matching will be very slow. (However, keep in mind that you can not set hasUniqueValue on a contact property.)

A warning label will appear if the object is not a Contact and the field is not unique.

In the example below, we are mapping our model's email field to HubSpot's email field on our Contacts objects.

Field Mappings

You can choose which specific fields you want to update on your Hubspot objects. If you do not have a HubSpot field to place your data in, you can add a new field to the object within HubSpot directly. Then, refresh the Hubspot fields (click the refresh button next to "field from {object}") and the new field should be available to map.

In the example below, we are mapping our model's first_name and last_name fields to the Hubspot fields, firstname and lastname.

Associations

An Association is when you link your syncing object to a different Hubspot object to express a relationship. You can create different types of Hubspot associations in a single sync. The list of available associations supported for your current object will show up in this dropdown.

Next, you will select a field from your model to match to the associated object. Hightouch will use that to look up the associated object's ID and use that ID to create the association.

For example, if you wanted to create an association between Contacts and Companies, you can select CONTACT_TO_COMPANY. Then, you select a field to match to the company you want to associate the contact with. Below, we want to "find the Company where the its name is equal to our model's company column"

Syncing with associations will only create the link between the two objects, it will not remove the previous association if the company value gets updated or removed.

One-to-many relationships

You might want to associate your current syncing object with multiple objects of the same type, like linking a Company to different Contacts in Hubspot. For Hightouch to do this, you will need to make sure that your model's column used to map the association is in one of these formats:

an array of values (string or number)
a comma separated list

You can use SQL helper functions to create an array or concatenate a string into a comma separated list. Below is an example of a SQL query to create an array of company names.

There are also some use cases where you specifically want to associate a Contact to multiple different Companies. Currently in Hubspot, one contact can only be associated with one company. However, Hubspot recently released a BETA feature to support associating a Contact to multiple Companies. This is only available if you opt-in for this "associations improvements" feature in Hubspot. More information can be found here. Once you opt-in, you can follow the above.

Association Labels

If you have a Professional or Enterprise Hubspot account, you can also use their new BETA feature for creating association labels to describe the relationship. You will need to make sure you opt-in for the "associations improvements" feature in Hubspot. Here's more info.

To add association labels in a sync, you will first need to set up your labels in your Hubspot account, which you create in Hubspot directly (refer to the above link).

Then, you will need to update your model's column to contain an object with this set schema:

{ value: string | number, label: string | Array<string> }. The value will be used to match to the associated object and label will be used add the labels on the association.

If you want to add more than one label, you can have label be an array of strings or a comma separated list.
If you want to use association labels for a one-to-many relationship, you can have your source column be an array of objects with the set schema.

Once you have these set up, you can run your sync normally and Hightouch will create these association labels for you.

If you opt to sync with association labels, you must make sure that all of your rows follow this schema to avoid inconsistent behavior with the beta API. If a row does not have a label, you can set label: null.

Be aware of Hubspot's limit with the association labels at the bottom of this page.

You can use some SQL helper functions to create an object or array of objects with this set schema. Below is an example of a SQL query to create an object for an association label.

Hubspot Contact Lists

Hightouch supports automatically creating a new list for your sync. You can specify a custom name for this list, or Hightouch will use the name of the model.

Here, the model name List 1 will be used as the list name:

Sync Modes

This integration supports Segment mode. New users will be inserted into the list. Users that are removed from the model will be removed from the list.

Record Matching

Records can be matched from your source to your list by either an email or Hubspot Contact ID.

To use Hubspot Contact Lists, you will need allow read and write scope for crm.lists. See OAuth or Private App Token above.

Need help?

Our team is relentlessly focused on your success. We're ready to jump on a call to help unblock you.

Connection issues with your data warehouse?
Confusing API responses from destination systems?
Unsupported destination objects or modes?
Help with complex SQL queries?

Feature Requests?

If you see something that's missing from our app, let us know and we'll work with you to build it!

We want to hear your suggestions for new sources, destinations, and other features that would help you activate your data.