HubSpot

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

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.

Setup

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)

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.

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
• analytics.behavioral_events.send

Syncing Objects

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.

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.
• Insert - pushes new objects to HubSpot and does not update fields that change in your warehouse.

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 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 the example below, we are 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.

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.

Read-only fields in HubSpot are not available for mapping in Hightouch.

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"

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

More information on Hubspot Associations can be found here.

Association Labels

If you have a Professional or Enterprise Hubspot account, you can also use Hubspot's feature for creating association labels to describe the relationship. 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.

Syncing Events

Hightouch supports syncing custom behavioural events to HubSpot with custom properties.

Assigning Events to Contacts

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.

Track Configuration

Hightouch allows you to choose the event name and event timestamp for a custom behavioural event.

Note: The event name is the Internal Name found under Event Details.

Field and Custom Mappings

Hightouch allows you to pass data to the default or custom properties of a HubSpot custom behavioural event.

Note: Custom properties have to be created in your event first before you can sync to them.

Syncing 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.