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:
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.
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.
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):
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.
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.
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.
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.
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.
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.
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: