This article is part of a series on the HubSpot v2 integration:

The HubSpot integration is easy to use, prepopulating configuration that you can leave on the default settings if they suit you. However, it's also incredibly flexible, allowing you to modify the configuration to suit your specific needs.

In this article, we take you through some of the ways you can tailor the integration. We also provide more detailed information on some specific setups and aspects of the integration than is covered in the main overview article.

In this section:

HubSpot, like Planhat, has a number of field types that support "choosing options":

When syncing your Planhat data with these fields, you should make sure that there is a perfect match (case sensitive) between the options available in Planhat, and the labels (not internal values) for the options in HubSpot.

In short, when the integration performs the "translation" of converting between HubSpot label (UI) values and internal (API) values for you.

We store a table that matches the labels and internal values of the above-mentioned HubSpot fields. Then, when fetching from HubSpot, you should filter on label, and we will take the values you have referenced (e.g. "Onboarding") and replace those labels with the appropriate stored internal (API) values when we query HubSpot.

We do the same when sending data to HubSpot - in the payload we send to HubSpot's API, we take each field label value (e.g. "Onboarding") and replace it with whatever the correct internal value is.

If you want to:

... then you would need to ensure that the available options for the Planhat Phase field are the same as the labels (not internal values) for the available options in HubSpot's Lifecycle Stage field, and you would set up the fetching filter as shown below:

As we mentioned above, the default behaviour for the current HubSpot integration is that Planhat field values are mapped with HubSpot label (UI) values, rather than internal (API) values. In the vast majority of cases, this is much more convenient for you than needing to use HubSpot internal values as your values in Planhat (which can lack formatting, or even simply be a numerical value), or set up workflows in HubSpot (see below) to convert every HubSpot field.

However, it's important to note that for the mapping via labels to work properly, the HubSpot label values must be unique - you can't have duplicates. For example, if you wanted to map (sync) the HubSpot "Deal Stage" field (on the Deal object) bidirectionally, but you had multiple HubSpot pipelines each with a "Closed Won" label value, this would cause issues, because the integration wouldn't be able to differentiate between the duplicates and identify the respective internal values.

Therefore, if you want to sync HubSpot "Deal Stage", and are using multiple pipelines in HubSpot, with duplicate labels (e.g. multiple "Closed Won" across the pipelines), then you should use workflows (automations) in HubSpot to populate a custom field with the unique internal values, which you can sync with Planhat instead. This workaround enables you to keep the integration in your Planhat tenant set to match on HubSpot labels, which is best for most other fields. (This approach assumes that you can't change your labels in HubSpot to be unique, and that you don't want to switch the whole integration to sync with HubSpot's internal values instead of labels.)

This scenario assumes you're syncing the Planhat Opportunity model to the HubSpot Deal object, bidirectionally. If you are only syncing in one direction, you are unlikely to need both the workflows in the instructions below.

In short, this process moves the Deal Stages, which you want to sync, into a new custom field in HubSpot, where the label values are unique and can sync without issue.

The diagram below shows an example similar to workflow 2: "Set PH Deal Stage when Deal Stage is updated". In this example, the workflow is scheduled daily, but you could easily make the workflow trigger whenever the "Deal Stage" is updated, as described above.

Click the image to view it enlarged

Since mapping both of the HubSpot fields with the Planhat "Related Domains" field would cause data duplication in HubSpot, we have created a "virtual field" for the purpose of integrating domain data between Planhat and HubSpot. The virtual field is called "Company Domains (virtual field)" and is accessible in the field mapping dropdown as if it were a HubSpot field.

When you map Planhat "Related Domains" to HubSpot "Company Domains (virtual field)":

In HubSpot, you can assign a single Owner to records. This data can be bidirectionally synced with Planhat, with the integration using some clever configuration we've built in for you.

In HubSpot, the Owner/User field stores an ID that is specific to HubSpot, whereas the corresponding field in Planhat stores an ID that is specific to Planhat.

In order to enable sync of this data, we continuously fetch a list of all HubSpot Users (their IDs and email addresses), and add the Planhat IDs of Users that match these email addresses to the list. This list can't be seen anywhere - it is solely used by the integration to match HubSpot IDs (and therefore Users) with Planhat IDs (and so Users), using email address as the common denominator.

When you select a HubSpot default Owner field or a HubSpot custom User field in the integration, and map it to a Planhat Team Member field, we "replace" values with the "ExternalOwnerId" that we get from HubSpot. If, instead, you map default HubSpot fields such as "created by" and "updated by", you will find that we "replace" values with "ExternalUserId", a different HubSpot ID type.

You can view this by clicking on the chevron on the right-hand side of the field mapping row to expand it out. You'll see "Replace with value when receiving from / sending to HubSpot" dropdown menus, as shown below.

We populate this data for you, and in most cases you don't need to change it. The reason the "replacements" are editable is to enable you to change the setup in case of any edge cases.

The diagram below illustrates the compatibility between different Planhat and HubSpot field types. Use this to help guide your field mapping.

Click the image to view it enlarged

"Syncs with some caveats" means that you can sync data in at least one direction, but that perfect compatibility may not be available, or is not intended. For example:

As we discuss in the main HubSpot integration article, in the Planhat data hierarchy the Company model is at the top. All other Planhat models that can be mapped/synced in the integration must link to the Company model. For example, a License or an End User cannot exist without a connection to a Company. The Company Profile is also a central place where various data types are compiled.

In the majority of cases, the HubSpot integration is configured with the Planhat Company model mapped to the HubSpot Company object. This is the default that is prepopulated when you first authenticate the integration. However, you can change this so that a different HubSpot object (such as Deal) is linked to the Planhat Company model instead.

The integration has been built with this flexibility so that it can accommodate setups in HubSpot where you don't use the Company object - typically, this is where you use the Deal object as your focal point in HubSpot instead. If you can't (or don't want to) restructure your HubSpot data to have Companies attached to your Deals (one Company per Deal), and you want HubSpot Deals to become Planhat Companies instead, you can configure the integration to enable this.

This is easy to do. Once you have chosen the HubSpot object that's mapped to the Planhat Company model, you just have to make sure that in the other sync sections (for other model/object pairs) the "Associated model" on the HubSpot side is set to this HubSpot object instead of the (default) Company HubSpot object.

This is shown below, taking the example of mapping the HubSpot Deal object to the Planhat Company model. The "Associated model in HubSpot", shown on the right for the End User / Contact sync, also needs to be set to this object in all the other sync sections you map.

Planhat's HubSpot integration supports regular sync of very large volumes of data. It is also very fast, syncing new and updated records in near real-time.

For optimal performance, the integration balances speed with rate limits - it is dynamic to ensure we always sync as much data as possible, as quickly as possible, given a number of constraints:

The HubSpot integration applies the following rate limits:

It is important to note that HubSpot's rate limits are not the only consideration affecting how fast/often data is actually ingested on either side. Both Planhat and HubSpot (depending on the sync direction) may also need a short time to process the data, so exact timings are not guaranteed.

The integration continually sends relevant data to HubSpot (if that sync is enabled), and fetches data from HubSpot, provided that 1) the records are associated with a Company that exists in Planhat, and 2) the records have been updated since the section last synced.

This is a summary of how the sync works. It's describing the scenario of a bidirectional sync.

You may hear this referred to as "the cascade structure".

Remember, the rate limits are the limiting factor if the data can be quickly processed in Planhat or HubSpot (depending on direction). This will generally be the case, but it is not guaranteed. The "sync job" that sends and fetches data waits for the previous job to complete before starting a new job, so there may be times when the frequencies/volumes are lower than the rate limits.