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:

As stated in the main article on setting up the HubSpot integration, the default behaviour is that Planhat integrates with the internal values of HubSpot fields, rather than the labels. This means, for example, that if you mapped the HubSpot "Deal Stage" field (on the Deal object) to Planhat, the field value "Closed Won" would actually be sent to Planhat as "closedwon", since that's the internal value.

In most cases, this is fine, because the internal values generally correspond fairly well with the labels you set. When you add a new "Deal Stage" value, you will notice that HubSpot auto-fills the internal value to match the label, but in lower case. However, some default internal values are numeric, which are not very intuitive when integrating data. There is a solution available to you, though!

If you want to work with the labels of, for example, HubSpot "Deal Stage", then we recommend an approach using HubSpot workflows, as detailed below.

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.

The basic principle is:

More detailed method:

The diagram below shows an example of 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.