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 clear the "read" and "write" box for Deals.
If you later decide to create a sync to upsert deals, it will fail because
Hightouch doesn't 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 and the data type of the field should match the data type of the corresponding column in your model, 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 the data type to match the data type of the column in your model and the hasUniqueValue property to true with the HubSpot API.
If the field is not marked as unique in HubSpot and set to a matching data type, record matching will be very slow and duplicates will occur. (However, keep in mind that you can not set hasUniqueValue on a contact property.)
In Upsert mode, the field you use for matching must be set in HubSpot to
have a hasUniqueValue of true and must be of the same data type as the
matching column in your model. Without these settings, your sync will create
unintentional duplicates.
A warning label will appear if the object is not a Contact and the field is
not unique.
In the example below, We're mapping our model's email field to HubSpot's email field on our Contacts objects.
id is only available for record matching when in Update mode. id is set by
HubSpot and read-only. Users can only use it for matching when updating other
fields.
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're mapping our model's first_name and last_name fields to the HubSpot fields, firstname and lastname.
Read-only fields in HubSpot aren't available for mapping in Hightouch.
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.
More information on Associations can be found in the HubSpot docs.
If you have a Professional or Enterprise HubSpot account, you can also use HubSpot's feature for creating association labels to describe the relationship.
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 API. If a
row doesn't 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 syncing custom behavioural events to HubSpot with custom properties.
To ensure syncs send each event, use a hash function for the event model's primary key . The hash should combine all columns, including member ID, timestamp, etc. See the event sync documentation for more information.
Hightouch allows you to choose how you assign events to contacts. This is done by matching a column to a HubSpot Contacts identifier such as email, contact ID, or user token.
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: