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

Planhat's bidirectional HubSpot integration enables you to bring your CRM data into Planhat quickly and easily. Within Planhat, all your different data (from a variety of sources) is consolidated, meaning you get a full 360 degree view of your customers. You can analyse your data in Planhat in lots of clever ways without requiring your developers, display your data clearly for greater insights, and automatically take action in response to data for maximum efficiency and productivity. With Planhat's unlimited user model, it's not just Customer Success teams who can benefit from all the features - Sales, Marketing and Product etc. can use it too.

As well as syncing data from HubSpot into Planhat, you can also push data from Planhat to HubSpot, so if you do have colleagues still using HubSpot, you can ensure everyone is on the same page with up-to-date customer information.

The HubSpot integration is highly flexible, enabling you to map your choice of HubSpot object to each of the Planhat models, with your choice of sync direction (including bidirectional) for each pair. You can apply filters to specify which records to include in the sync to/from HubSpot - e.g. only syncing a specific category of Companies (such as paying customers) into Planhat.

Once enabled, the integration automatically syncs new and updated records in close to real time. You can also manually fetch all, so you can bring in your historic records.

In addition, you can use the integration to populate HubSpot marketing contact lists from Planhat End User filters, to facilitate your marketing campaigns.

Planhat's HubSpot integration is very flexible, allowing you to map almost any Planhat model with almost any HubSpot object. This means it can accommodate different types of HubSpot setup.

However, the majority of the time, you'll use some (or all) of the model/object pairs listed here. This table shows you the typical model/object combinations, to act as a guide.

When you select pairs of models/objects in the integration, you also set up mapping on the field level.

*Some exclusions apply.

The HubSpot integration can also be used to populate marketing contact lists in HubSpot. This is a separate type of sync, and is described here. Most of this article is referring to the main sync between objects/models, rather than this section.

It's really simple to set up the HubSpot integration. Even though there is a lot of flexibility in how you can configure it, in many cases defaults are prepopulated for you, and you don't have to make lots of changes or set up additional configuration. However, you are free to edit as much as you wish.

You can customise and save the configuration before you then enable the sync.

The Planhat HubSpot integration is bidirectional, meaning you can choose to push data to, and pull data from, each system.

You set the sync direction independently for each model/object pair, offering a great deal of flexibility.

The default for new sections is "Not Syncing", so you select another direction to enable the sync of that model/object.

For each model/object pair, you can choose from "Send to Provider", "Receive from Provider", or "Both Directions".

It's possible to change the sync direction after your initial configuration - e.g. you could initially select "Receive from Provider" when you're setting up your Planhat tenant, and then change it to "Both Directions" later on.

When you set up field mapping, you can also choose the sync direction for each field - we'll discuss this when we talk about field mapping later in this article.

For each sync section, you will see boxes for IDs under the Planhat model and HubSpot object.

These are unique IDs that are used for identifying and mapping individual records (e.g. Company records could be Apple, Nissan and AstraZeneca). This enables records to be updated, so duplicates aren't created.

You will see that these are automatically prepopulated for you, but in some cases you can click into a dropdown menu (when the box is white rather than greyed out) and edit which field/property is used as the identifying ID if required.

We strongly recommend always using Planhat "SourceId" and HubSpot "Record ID", when available. This means that when you sync a record from HubSpot to Planhat, its ID populates the relevant source ID field in Planhat. (The Planhat Conversation model does not have a source ID field, but it does have an external ID field that can be used in the same way.)

All data fetched from HubSpot must have a direct association to the Planhat Company.

When mapping Planhat models other than Company, it's specified in the integration how that model is connected to the Company model, and also what the equivalent setup is on the HubSpot side (which is likely to be via the HubSpot Company object).

This is required because the Company model has a special position within the Planhat data structure: it's at the top of the hierarchy, and all of the other Planhat models that are available in the integration always have to link to the Planhat Company. This means, for example, that you can't have End Users or Licenses that aren't linked to a Company.

Therefore, when you're syncing e.g. Contacts from HubSpot to Planhat, the integration needs to know what the associated object is in HubSpot (i.e. the object mapping to the Planhat Company model, which is typically the HubSpot Company object). And we need to know what ID is being used to specify the Planhat Company - this is typically the source ID, like discussed above.

Most of the time, this section will simply be prepopulated for you and you won't need to change it, but you can use the dropdowns to edit the selections if required.

It is possible to connect a different HubSpot object (rather than Company) to the Planhat Company model, if this better suits your HubSpot setup, but this option should be used with caution. If you're using a different HubSpot object as the Company equivalent, then the name of that object would need to be specified on the right-hand side, as the associated object, in place of the Company object. For further details, see our technical deep-dive article.

Note that if you sync in a HubSpot record associated with multiple Companies, Planhat will only take account of the primary associated Company.

One of the great things about the HubSpot integration is that you can optionally filter records synced in each direction - so for each model/object pair, you can specify a "sending filter" and a "fetching filter". This is super useful - it means you don't have to sync every record of an object/model, just the relevant ones. Example use cases include filtering HubSpot Companies so only those that are paying customers sync into Planhat, or filtering HubSpot Deals so that open ones sync into Planhat Opportunities but closed ones sync into Planhat Licenses.

You can see these filters in each of the model/object sync sections, underneath the field mapping. Simply click on each blue filter symbol to open up the filter modal, where you can view and edit the filter.

All sync sections are filtered independently of each other - filtering is not inherited from e.g. the Planhat Company sync section.

The "sending filter" filters Planhat records before they are sent to HubSpot.

This filter works much like the standard Planhat filters you're used to using throughout Planhat. As usual, you can list multiple criteria, grouping/nesting as required. To refresh your filter knowledge, see here.

Note that you need to create a new filter here, rather than selecting an existing filter.

Cross-model filtering is not available.

The "fetching filter" is applied when the integration fetches data from HubSpot.

Each standard fetching filter is based on a single property.

The structure is:

You can read more about HubSpot filtering in their documentation here.

Underneath the main sending and fetching filters, you'll see toggle switches where you can choose whether to include null field values in the sync. You enable/disable this separately for send and receive, and this is per model/object sync section.

The default is that this is not turned on (i.e. it's set to "NO"), which means fields with null values are excluded from the payloads we send to or fetch from HubSpot.

If you choose to enable either of these toggle switches (i.e. set them to "YES"), this could lead to data being wiped (either in HubSpot if you send nulls, or in Planhat if you fetch nulls).

Within the field mapping, you have the option to set default values for each field, which can be used to substitute for (i.e. replace) any nulls synced. To do this, click on the chevron symbol on the right-hand side of a pair of fields to show the cells to fill in.

For each of the model/object sync sections, you can set up field mapping: link up specific Planhat fields with specific HubSpot fields. (Note that the integration does not create fields - it only syncs data between them - so you would need to create any required custom fields first before selecting them in the integration.)

This is great because you don't need to sync data from every single field that exists in your HubSpot; think about which fields contains relevant data for your team working in Planhat. Similarly, if you still have colleagues working in HubSpot, consider which Planhat data in particular is useful to sync back.

The field mapping section for each model/object will look something like this:

Click the image to view it enlarged

This is very simple to set up. In many cases, some field mapping is automatically prepopulated for you, with required/recommended fields for that model/object pair. You can easily modify these, or add your own pairs of fields.

If you want to delete a field mapping row, simply click the red "x" on the right-hand side.

As we just mentioned, some field mappings are created by default when you create a new sync section and model/object is selected. We have pre-configured these to make it easy for you to include fields that are required for either Planhat or HubSpot. For example, Planhat requires a "Name" in order for a Company to be created, and an "Email" and "First Name" for an End User to be created.

However, you can modify or delete these field mappings if you like. This gives you extra flexibility. There could be alternative ways you could ensure that required fields are included in the mapping - for example, by mapping them to custom fields.

If you delete a field mapping for a required field, and the section is set to sync, you'll see a helpful warning triangle - simply put your mouse over the warning triangle to see details of which required fields are missing in your field mapping. You should ensure that any required fields are mapped to ensure successful syncing.

In the next section of this article (starting here), we list the fields that are mapped as default, or are otherwise recommended, for some typical model/object pairs.

When mapping list/multipicklist fields, it's really important that the values (available options) in those fields are identical in both systems. The integration cannot create new values in either system, only assign existing values.

For this, the available values of the field in Planhat need to match the labels in HubSpot, rather than the internal values - this is important to get right to ensure the integration can sync all data.

For example, this is the case for the default Stage, Status, and Pipeline fields on various HubSpot objects.

In the sections below, we take a look at field mapping for typical model/object pairs.

These are all required fields, so you should keep these selected.

Planhat Licenses require the following fields: "Start Date", "Currency", and one of "Value", "MRR" or "ARR". If you use "Value"/"Amount" rather than "MRR" or "ARR", you will also need to map "End Date".

"Ticket name", "Ticket status" and "Pipeline" are required fields in HubSpot.

As well as the bidirectional sync of model/object CRM data as discussed in the rest of this article, the HubSpot integration also enables you to sync End User filters you've designed in Planhat to HubSpot marketing static contact lists, so you have the option to send targeted email campaigns via HubSpot. This is a one-way sync.

To set this up: