Search documentation...

K
ChangelogBook a demoSign up

HubSpot

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

Supported syncing

Sync TypeDescriptionSupported Sync Modes
ObjectsSync records to objects such as contacts or companies in HubSpot.Upsert, Update, Insert
EventsSync records as events to HubSpot. This is often in the form of a track call.Insert
SegmentsCreate, sync, and keep contact lists up-to-date in HubSpot.Add, Remove

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.

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.

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.

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.

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.

Inspecting objects in the HubSpot UI

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

Inspecting properties in HubSpot UI

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

Inspecting a property's internal name

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

Inspecting a property's data type and access

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

Lead rating property in HubSpot UI

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.

Lead rating property in HubSpot UI

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.

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

Inspecting a property's uniqueness

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

Inspecting a property's associations

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.

Record matching in the Hightouch UI

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

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.


Check out HubSpot's documentation to learn how to sync Multiple checkboxes.

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.

HubSpot internal naming

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.

HubSpot internal naming

Read-only fields in HubSpot aren't available for mapping in Hightouch.

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.

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.

Associations list in Hightouch

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.

Associations list in Hightouch

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.

Associations list in Hightouch

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.

Overwriting existing associations

By default, syncing with associations only creates the link between the two objects; it doesn't remove previous associations if the associated object is updated or removed. To remove previous associations, you can enable the "Overwrite existing associations" option. It's important to note that this will result in your sync making additional requests because a lookup of the object's current associations is required when removing them.

This setting will also remove any associations that were created outside of Hightouch.

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"

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.

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.

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:

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

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:

{ "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.

Model creation with association labels

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

Association with association labels

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:

BehaviorDescription
Do nothingKeep the record in HubSpot
Clear fieldsKeep the record, but clear the mapped fields
Delete recordDelete 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.

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.

To ensure syncs send each event, your event model must use a truly unique primary key. See the events syncs documentation for more information.

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.

Track configuration in the Hightouch UI

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

Contact assignment in the Hightouch UI

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.

Field mapping in the Hightouch UI

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.

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.

Record matching in the Hightouch UI

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

List creation in the Hightouch UI

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.

Field mapping in the Hightouch UI

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:

{%- if row['column_name'] == null -%} {{null}} {%- else -%} {{row['column_name'] | to_unix}} {%- endif -%}

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

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.

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.

Dropdown select internal values in HubSpot

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.

As explained in the field mapping section, make sure to follow HubSpot's guidelines when syncing to Multiple checkboxes fields.

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.

Ready to get started?

Jump right in or a book a demo. Your first destination is always free.

Book a demoSign upBook a demo

Need help?

Our team is relentlessly focused on your success. Don't hesitate to reach out!

Feature requests?

We'd love to hear your suggestions for integrations and other features.

Last updated: Oct 26, 2023

On this page

Supported syncingUnderstand your HubSpot setupBusiness goalsRequired data specificationsInspect objects, properties, and associationsConnect to HubSpotSync configurationSyncing objectsSyncing eventsSyncing contact listsTips and troubleshootingDate valuesCommon errorsLive debuggerSync alerts

Was this page helpful?