HubSpot

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

Supported syncing

For more information about sync modes, refer to the sync modes docs.

Understand your HubSpot setup

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.

Business goals

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.

To learn what objects and properties you are using in your HubSpot instance, follow these steps.

Required data specifications

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.

Inspect objects, properties, and associations

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

2. In the object's overview page, under Setup, click Manage [object] properties.

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

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

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

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

Connect to HubSpot

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.

Sync configuration

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.

Syncing objects

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.

Record matching

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

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.

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.

Associations

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.

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.

For more information on associations, check out HubSpot's association docs.

Association modes

Create added associations

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.

One-to-many relationships

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"

Association labels

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.

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:

{ "value": string | number, "label": string | Array<string> }

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:

{ "value": "ABC Corp", "label": ["Employee at", "Decision maker"] }

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:

[{ "value": "John Doe", "label": "Buyer" }, { "value": "Jane Doe", "label": "Seller" }]

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:

SELECT
  id,
  first_name,
  last_name,
  email,
  JSONB_BUILD_OBJECT('value', company_name, 'label', role) as company_obj`

The query creates a column called company_obj and sets the company_name name as the value in the object and the role as the label in the object.

Once you've formatted the data correctly, ensure the association in your sync configuration uses the column with the properly formatted object.

Delete behavior

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:

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.

Split retries

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.

Syncing events

Hightouch supports syncing custom behavioral events to HubSpot with custom properties. To sync events, ensure you logged in via OAuth with enterprise scopes when you connected Hightouch to HubSpot.

Event name

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.

Event timestamp

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.

Assigning events to contacts

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:

• email
• object (contact) ID
• user token

Field mapping

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.

Syncing contact lists

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.

User identifers

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.

List creation or selection

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.

Tips and troubleshooting

Date values

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:

mappings: [
  {
    "from": "hightouch_datetime_column",
    "to": "hubspot_datetime_field",
    "skipDateParse": true
  }
]

Common errors

If you encounter an error or question not listed below and need assistance, don't hesitate to reach out. We're here to help.

429 - You have reached your secondly limit

You may receive a 429 - You have reached your secondly limit error message for two reasons:

• You have another sync to HubSpot running simultaneously, which could make you reach HubSpot's secondly limit.
• You've set up associations in your sync configuration. The HubSpot API has constraints that cause sync slowness when using associations.

To reduce the occurrence of this error, ensure you're following record matching configuration suggestions. For more information about Hubspot's API limits and other 429 errors, see Hubspot's API usage guidelines.

409 - Contact already exists

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

400 - Cannot update object with type ... the following properties were cleared ...

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
• Adding a value to the required property

400 - Property values were not valid

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.

The error message may contain lines like this:

• "error":"INVALID_OPTION","name":"custom_dropdown_field"...
• "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.

CONFLICTING_ONE_TO_ONES_SPECIFIED

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.

Row with ID email...could not be added to the list.

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.

Live debugger

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.

Sync alerts

Hightouch can alert you of sync issues via Slack, PagerDuty, SMS, or email. For details, please visit our article on alerting.