Before you begin your Hightouch to HubSpot sync configuration, clarifying your business goals and understanding your HubSpot setup is crucial. Walk through the following considerations to ensure your team is aligned and your sync plans are clear. If you prefer, you can download this resource as a PDF to share with your team.
First, you need to plan what data you want to sync to HubSpot, how you want to update it, and how frequently you want to update it. Consider your business needs and consult with your team to align on the answers to these questions.
The following table shows how the responses affect your sync configuration.
Consideration
Effect on sync configuration
What standard and custom objects do you want to sync to HubSpot? Contacts, companies, etc.?
The response affects your sync types—in other words, which objects you select to sync to. You need to set up a separate sync configuration for each object you want to sync to.
What standard and custom properties do these objects have that you want to sync to?
The response affects the field mapping on each of your syncs.
Do you have new data to add, old data that needs updating, or a combination of both?
The response affects your sync modes—for example, insert mode for new data, update mode for old, and upsert mode for both.
How frequently do you need to update the data?
The response affects your sync schedule. This is the last step of your sync configuration.
To learn what objects and properties you are using in your HubSpot instance, follow these steps.
Once you've confirmed the objects and properties you want to sync, you need to confirm that:
they have the correct data types
you have permission to edit them
You can find the answers to these questions by following these steps.
Consideration
Effect on sync configuration
Is the property that you would like to use for record matching unique?
Non-unique values can lead to duplicates and sync errors.
What are the expected data types of the properties you want to sync to?
The response affects your field mapping; if the expected type differs from your model column type, you must type cast your data in your model configuration.
Are the properties you want to sync editable?
Hightouch only displays editable fields during field mapping.
Are any of the properties you want to sync calculated properties?
Calculation properties are non-editable and read-only. Change the field type if you want to sync data to it.
Are any of the properties you want to sync enumeration properties?
Enumeration properties only accept specific values. Ensure your data matches these values or create a new property.
Are there any associations you want to make between objects?
You can set up associations while field mapping, assuming the association exists in HubSpot first.
Does the user you are authenticating to Hightouch have edit access?
The sync will error if the user doesn't have the correct permissions.
In your HubSpot account, click the settings icon in the main navigation bar. Under Data Management > Objects, select the object you want to inspect, such as Contacts, Companies, Deals, etc.
In the object's overview page, under Setup, click Manage [object] properties.
Review both standard and custom properties you want to sync data to. Make note of their:
Internal name: This is the name that appears in the Hightouch UI for record matching and field mapping. You can access it by clicking on the property name and then clicking </> in the property inspector.
Property access: The HubSpot user you use to authenticate to Hightouch should have access to edit the property.
Data type: For example, Single-line text or Number—you can view these under the property Name. When selecting model columns for field mapping, you must ensure the data type matches. For example, a Single-line text property requires text data and a Number requires numerical data.
Check whether any of the properties you plan on syncing to are an enumeration type, such as Dropdown select, Radio select, or Multiple checkboxes. For example, the native Lead rating property for contacts is a radio select property.
If you plan on syncing to enumeration properties, the data you sync must match the internal value of the options. Lead rating, for example, can accept the values "bucket_1," "bucket_2," "bucket_3," and "bucket_4," though the labels are "1 Star," "2 Stars," etc.
Since internal values can't be updated once created, you may need to create a new custom property to accept data from your model. Refer to HubSpot's guide on property field types to select the appropriate field type when creating new properties.
Check if the property requires unique values: Click on its name, then go to Rules. Under Validation rules, see if Require unique values for this property is checked. Properties you want to use for record matching must have this validation.
Return to the object's overview page and select Associations. Look for associated child objects like contacts, companies, or deals linked to the records. You can use these to map associations in Hightouch. Add, remove, or correct links between objects as needed.
Once you've validated the properties and associations of the objects you want to sync to, you're ready to configure your sync in Hightouch.
Go to the Destinations overview page and click the Add destination button. Select HubSpot and click Continue. You can then authenticate Hightouch to HubSpot with OAuth. If you plan on syncing events, select OAuth with enterprise scopes. Otherwise, you can select OAuth.
Once successful, you will be redirected back to Hightouch to enter a descriptive name for your destination and complete setup.
Once you've set up your HubSpot destination and have a model to pull data from, you can set up your sync configuration to begin syncing data. Go to the Syncs overview page and click the Add sync button to begin. Then, select the relevant model and the HubSpot destination you want to sync to.
Hightouch can create and update standard HubSpot objects such as contacts, companies, deals, etc. Hightouch can also sync data to custom HubSpot objects. To sync to a custom object, you must create it in HubSpot first.
To match rows from your model to objects in HubSpot, select a HubSpot property and the corresponding column from your model.
You can match on any of the available properties in the dropdown. It's best to select a property that HubSpot automatically deduplicates on. These include email address or user token for contacts, company domain for companies, or record ids for other object types.
If you select a model column with duplicates to send to one of these properties, HubSpot returns a 409 error and the sync errors.
The id property is only available for record matching when in update mode.
It is a read-only property, and HubSpot sets its value upon object creation.
The HubSpot property you select to match on should be unique, and its data type must match the data type of the corresponding column in your model. If the property to match on isn't unique, record matching will be slower and duplicate records may occur. You can check a property's uniqueness validation by inspecting the property in HubSpot.
If the object doesn't have a native unique property, we recommend creating unique custom property. Refer to HubSpot's instructions on how to do so.
Field mapping lets you choose which properties you want to update on your HubSpot objects. If the HubSpot object you're syncing to doesn't have the specific property you want to send your data to, you need to create a new property on the object in HubSpot first.
You can also sync to enumeration
properties,
such as Dropdown select, Radio select, and Multiple checkboxes.
Make sure to create your property's internal values before syncing them, as
explained in the Common errors
section.
After creating or editing properties, you can refresh the available properties for mapping by clicking the refresh button next to Field from HubSpot. The new property should then be available.
Hightouch displays the property's Internal name, not label, in the dropdown. You can find a property's internal name by inspecting the property in HubSpot.
Read-only fields in HubSpot aren't available for mapping in Hightouch.
Associations let you express a relationship between the object you're syncing to (the main object) and a different HubSpot object (the associated object).
For example, you may be syncing contacts to HubSpot and want to associate a company with each one.
Click Add mapping, then select the association label under Field from HubSpot.
The list of supported association labels for the object appears in the dropdown.
You can find an object's supported associations and add others by inspecting the object in HubSpot.
In Hightouch, you can search for the object you want to associate to (the associated object).
For example, if you want to associate a company with each contact you're syncing, you can search for "company." Then, select the appropriate association.
In this example, you would select CONTACT_TO_COMPANY.
The association should only be set up in the main object's sync configuration.
In this example, you would only add it to the Contact sync and not to the
Company one. You can learn more about this in the Common
errors section.
Make sure that the sync to the associated object always runs before the one to
the main object. After creating your syncs, you can set up a
sequence to schedule them in the correct
order.
Next, select the properties to match on. For example, if you're associating companies with contacts and a company's name matches the COMPANY_NAME in your contact data, you would select those properties.
If your data contains the id of the object you want to associate to, it's best to use this column for matching. Since the sync doesn't have to perform a lookup, sync performance is significantly faster.
The example below shows using contact data that includes the associated company's id in a column called ACCOUNT_ID.
You can create multiple HubSpot associations in a single sync. Click Add mapping for each association you want to make.
Associations will only be appended to the record. This setting will not remove previous associations if the associated object is updated or removed.
Delete existing associations and create added associations
Before creating new associations, delete all existing associations of the mapped types. For example, if you have CONTACT_TO_COMPANY associations mapped, then all CONTACT_TO_COMPANY
associations will be removed from the record before adding the associations from the model. This setting may delete data not authored by Hightouch.
Delete removed associations and create added associations
This mode will find the differences between sync runs to delete associations in HubSpot that have been removed from the model, then create associations that have been added to the model.
This setting will also remove any associations that were created outside of
Hightouch.
You might want to associate the object you're syncing to with multiple objects of the same type. For example, if you're syncing company objects, you may want to link several contacts to each company.
For Hightouch to associate multiple objects, the model column you select for the association must be in one of these formats:
an array of string or number values, for example, ["id1", "id2", "id3"]
a comma-separated string, for example, "id1, id2, id3"
Confirm that the association cardinality in your HubSpot settings is
compatible with the data you're syncing to HubSpot. You can learn more about
this in the Common errors section.
If you have a Professional or Enterprise HubSpot account, you can also use HubSpot's association labels feature to describe relationships between objects.
Association labels let you add descriptive text to an association that provides more context about the relationship. For example, instead of just linking a contact to a company, you can use an association label like "Employee at" or "Customer of" to clarify the nature of the relationship.
Before configuring a sync to use association labels, check out HubSpot's
association label limitations at the bottom of this HubSpot
doc.
To add association labels to a Hightouch sync, you must first set up your labels in your HubSpot account. Then, you need to update the model column you use for associations to contain an object with this schema:
Make sure to set the model column's data
type to Object / Array.
Hightouch uses the value to match the associated object and the label as the label on the association in HubSpot. For example, if you're associating companies with contacts, you may set the company name as the value and the contact's role as the label.
{"value":"ABC Corp","label":"Employee at"}
If you want to add more than one label, the label can be an array of strings or a comma-separated list. For example, if you're associating companies with a contact and the contact has multiple roles, a row from your model might look like this:
If you want to add more than one association label to an object, you can sync an array of association label objects.
For example, if you're associating billing data with multiple contacts, a row from your model might look like this:
Ensure all rows follow this schema to avoid inconsistent behavior with HubSpot's API. If a row doesn't have a label, you can set the label as null.
For example, suppose you want to associate a company with a contact but don't have any information about the contact's role there. The model row should look like this:
{"value":"ABC Corp","label":null}
You can use some SQL helper functions to create an object or array of objects with this schema. Below is an example of a SQL query that creates an object for an association label:
The delete behavior you select dictates what to do when a row no longer appears in your model's query results. Depending on the sync mode you're using, you can select from some or all of these options:
Behavior
Description
Do nothing
Keep the record in HubSpot
Clear fields
Keep the record, but clear the mapped fields
Delete record
Delete the record in HubSpot
In Upsert mode, you can select from all three. In Update mode, you can only select between Clear fields and Delete record. Insert mode doesn't support delete behavior.
Hubspot counts all objects in a batch as rejected if the request contains a single invalid record.
To pinpoint which records are getting rejected with which errors and reduce the number of valid records that get retried,
you can enable split retries.
Providing an event name is required to log an event in HubSpot. You can either provide a static value or select to use a column from your model data.
The event name should match the event's internal name. HubSpot assigns the internal name automatically when you create the event. You can find an event's internal name either in HubSpot or by using the HubSpot events API.
Follow the instructions in HubSpot's docs to learn how to find the internal name for an event.
You can optionally select a column that contains timestamps of when events occurred. If this field is empty, Hightouch uses the time the event arrives at the server.
Hightouch lets you choose how you assign events to contacts. Select a column in your events data that matches one of these HubSpot contacts identifiers:
In the field mapping section, you can select columns from your model to sync to the default or custom properties of a HubSpot custom behavioural event.
Custom properties must exist on the event before you can sync to them. See
HubSpot's docs on how to create a custom
property
on an event.
Hightouch supports syncing contacts to contact lists in HubSpot. You can sync data to an existing contact list or create a new one on the first sync run. Select Segment as the sync type.
To identify which contacts to add or update in a contact list, select a model column and the corresponding HubSpot field.
You can match on either Email or HubSpot Contact ID.
Hightouch supports automatically creating a new list for your sync. You can specify a custom name for this list; if left empty, Hightouch defaults to the model name. The example below shows defaulting to the model name "Newsletter subscribers."
If you opt to sync to an existing list, you can select the list name from the dropdown.
When syncing date or timestamp values to HubSpot, you need to consider which data type the HubSpot field should use: date or datetime.
HubSpot date fields support date values which store a date without a time. datetime fields support timestamps. For more information, check out HubSpot's timestamp FAQ.
Values you send to a date field must follow one of these formats:
date-only ISO 8601 strings (YYYY-MM-DD), for example, 2020-02-29
EPOCH-millisecond timestamps, with the time set to midnight UTC: for example, 1430438400000
If you're syncing a timestamp to a date field, Hightouch automatically sets its time to midnight UTC, as required by HubSpot.
Values you send to a datetime field values must follow one of these formats:
ISO 8601 formatted strings (YYYY-MM-DDThh:mm:ss.sTZD), for example, 2020-02-29T03:30:17.000Z
EPOCH-millisecond timestamps: for example, 1427997766000
HubSpot displays datetime values in the timezone of the user viewing the record.
A convenient way to convert your date values to Unix millisecond timestamps is to use the to_unix function in the template mapper.
The to_unix function throws an error if the input row's value is null. To avoid this, you can enter this Liquid into the template mapper:
Be sure to replace column_name with the name of your model column.
If you notice the timestamp from your Hightouch model column isn't appearing in Hubspot for your datetime field, edit the JSON mapping in your sync configuration to include "skipDateParse": true. See example below:
You may receive a 409 - Contact already exists or 400 - Duplicate IDs found in batch input error for three reasons:
the model column you are using for record matching contains duplicate values
the model column mapped to HubSpot's email field contains duplicate values
you're attempting to create a new contact in HubSpot that has the same email value as an already existing HubSpot contact, but a different value in the HubSpot field used for record matching (for example, user_id)
HubSpot uses email as the primary unique identifier to avoid duplicate contacts.
In other words, two different contacts can't share the same email.
See HubSpot's Contacts API Reference for more information.
To resolve these errors, ensure:
the column you selected for record matching doesn't contain duplicate values
any email information you are syncing also doesn't include duplicate values
you aren't attempting to create a new HubSpot contact with the same email as an already existing one, but a different value in the record-matching field
The 409 - Contact already exists error message contains an Existing ID
value returned by HubSpot. This value refers to HubSpot's ID for the contact
and doesn't necessarily correspond to any values in your model data.
You may receive a 400 - Cannot update object with type: ... the following properties were cleared: ... because there is no data being sent to a required property in HubSpot. The properties listed after the following properties were cleared are the required property or properties.
You can resolve the error by either:
Removing records with empty values in the required property; you can update your model definition to exclude rows like this
You may receive a 400 - {"status":"error","message":"Property values were not valid: [{"isValid":false,... error message because you are attempting to send a value to an enumeration property that isn't one of the valid options.
Enumeration properties include Dropdown select, Radio select, and Multiple checkboxes.
Ensure that the values exactly match the Hubspot's Internal values and not the Labels.
These values are case sensitive.
"error":"INVALID_OPTION","message": {...} was not one of the allowed options...
These can help pinpoint which Hubspot field is in question. Refer to step 4 of the Inspect objects, properties, and associations section to find the Internal Values of your Hubspot field.
This error can occur if you set up an association both in the main object's and the associated object's sync configuration.
In this case, make sure to remove the association from the associated object's sync configuration.
This error can also happen if you add an association to your sync configuration, but the cardinality of your association or association label in HubSpot isn't compatible with the data you're syncing.
For example, if the cardinality is set to 1-to-1 for the given association, your sync can't associate multiple records on the main object with one record on the associated object, or vice versa.
To resolve this, access the main object's HubSpot settings, open the Associations tab, and check your associations' cardinalities.
In your Hightouch sync configuration, make sure to use an association or association label that has the correct cardinality.
When syncing contact lists and matching on Email, you may receive a Row with ID email...could not be added to the list error. This occurs when the contact you're trying to sync doesn't exist in your HubSpot workspace. To resolve this, ensure that the contact exists in HubSpot prior to syncing it to a contact list.
Hightouch provides complete visibility into the API calls made during each of your sync runs. We recommend reading our article on debugging tips and tricks to learn more.