Skip to main content
All CollectionsIntegrationsHubSpot
Setting up the HubSpot v2 integration
Setting up the HubSpot v2 integration

An overview of Planhat's HubSpot v2 integration, and step-by-step guidance to set it up

Christian Dreyer avatar
Written by Christian Dreyer
Updated over a week ago

Summary

  • Data you can sync

    • Almost any HubSpot object to almost any Planhat model

      • Any standard or custom field on a synced object/model

    • End User filters to HubSpot contact lists

  • Sync direction

    • Main CRM data:

      • Managed at object/model and field level

      • Choose between bidirectional, send, and receive

    • Marketing contact lists: Planhat to HubSpot

  • Sync frequency

    • Automatic sync: near instant (can be a few minutes)

    • Manual: on demand

  • Data mapping

    • See table below

Who is this article for?

  • All Planhat users

  • It's particularly relevant to those setting up the HubSpot v2 integration

Series

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


Article contents


Introduction

πŸ“Œ Important to note

This article relates to version 2 (v2) of Planhat's HubSpot integration - the current version.

For information on v1, the legacy version of the HubSpot integration, see here.

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.


Data mapping

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.

Planhat model

Sync direction

HubSpot object

Company

Bidirectional (or one-way)

Company

End User

Bidirectional (or one-way)

Contact

License

Bidirectional (or one-way)

Deal

Opportunity

Bidirectional (or one-way)

Deal

Task

Bidirectional (or one-way)

Task

Conversation - type "note"

Bidirectional (or one-way)

Note

Conversation - type "ticket"

Bidirectional (or one-way)*

Ticket

Conversation - another type

Bidirectional (or one-way)

Activity of a specific type

Your choice of model*

Bidirectional (or one-way)

Your choice of object*

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

Planhat

Sync direction

HubSpot

End User filters

From Planhat to HubSpot

Marketing contact lists


Setting up the integration

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.

  1. Navigate to the HubSpot v2 integration

    • Go to the Operations Module (icon at the bottom in the black left-hand bar), ensure the "INTEGRATE" tab is selected, and click on "HubSpot"

    • πŸš€ Tip: Find the HubSpot integration more quickly by typing in the search box, or clicking into the "CRM" section (both shown below)

      Click the image to view it enlarged

  2. Authenticate the integration

    • Click the blue "Connect" button

    • The integration uses your HubSpot user authentication data to connect the integration

    • Via the pop-up from the integration, log into HubSpot and accept the required access - click the orange "Connect app" button in HubSpot

    • It will return you back to the integration, with model/object sync sections now showing, but nothing syncing at this stage

    Click the image to view it enlarged

  3. Configure the model/object sync sections

    • You'll see some model/object sync sections prepopulated for you

      • These are the most commonly synced model/object combinations, so this makes it really quick and easy for you to have data mapping without additional configuration on your part

      • However, you can make changes to the existing sync sections, add new sync sections (via the blue "Add New Section" button at the bottom), and remove sync sections you don't need (via the red "Remove Section" button)

      • πŸš€ Tip: Click on the chevron symbol on the left-hand side of each sync section to expand it out and view/edit the details

    • For each sync section:

      1. Confirm/select the Planhat model and HubSpot object

        • In most cases, these are prepopulated for you, and you will likely leave them as-is

        • However, you can change the model/object for the prepopulated sections if you wish. (Note that the Planhat Company model is the "top" data model in the Planhat data hierarchy, so it's required to include it in the mapping)

        • If this is a new sync section you've manually created, select the desired model and object from the dropdown menus

      2. Choose the sync direction

        • This starts as "Not Syncing", so select a sync direction if you'd like that model/object pair to sync (either from and/or to HubSpot)

        • See here for further details

      3. Review/confirm IDs

        • These are prepopulated for you, so you can typically just leave them as-is, but you can edit them in some cases

        • See here for further details

      4. Review/confirm Company associations

        • These are prepopulated for you, so you can typically just leave them as-is, but you can edit them in some cases

        • See here for further details

      5. Finalise field mappings

        • Some key field mappings are prepopulated for you. These are typically to cover cases where either the Planhat model or HubSpot object has required fields. However, you can edit these if required

        • Click the blue "Map a Field" button each time you would like to add another pair of mapped fields. You can use the red "x" to remove a field mapping pair

        • See here for further details

      6. Set sending and/or fetching filters

        • These optional filters allow you to define which records of the model (e.g. which Planhat Companies) are sent to HubSpot, and which records of the object (e.g. HubSpot Companies) are fetched from HubSpot and synced to Planhat

        • You can also choose whether "null" field values are included in the sync to and/or from HubSpot

        • See here for further details

      7. Save your configuration

        • Click the green "Save Section" button for each model/object sync section when you have finished configuring it

        • πŸš€ Tip: When you have made changes to the configuration, you will see that an asterisk (star) shows next to the HubSpot object name (example below). This is a helpful reminder that you need to save your configuration. Press "Save Section" and, once the save completes, you'll see the asterisk disappear

  4. Initiate the ongoing sync ...

    • ... by clicking on the "Enable the HubSpot integration" toggle switch at the top of the integration (from "OFF" to "ON")

    • This means that new/updated records will be automatically synced from this point on

  5. Initiate the historic sync ...

    • ... by clicking the blue "Full Sync" button at the top right of the integration

    • You need to correctly configure and save the sync sections to enable this button

    • This brings in your past records

πŸ“Œ Important to note

"Tickets" and "Notes" are each types of the Conversation model in Planhat. When you authenticate the integration, there are sync sections for each of these automatically created for you, but if you remove them and later create a new sync section for either of these (or create a sync section for a different type of Conversation), you should first select "Conversation" as the model, and then select the type as "Ticket" or "Note" etc.

πŸ“Œ Important to note

If your tenant has access to both the HubSpot v1 and v2 integrations, you will be able to connect and authenticate v2 without issues. However, in order to enable the integration (i.e. switch on the automatic ongoing sync) for v2, v1 will be disabled and deleted. You will be warned with a modal asking you to confirm this, when you click the "enable" toggle.

However, in Beta, both HubSpot v1 and v2 are available, and can't be removed or deleted. Do not have both integrations connected and enabled at the same time, as this can cause issues.


Sync direction

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.

πŸ“Œ Important to note

For data security reasons, regardless of direction, the integration does not delete records (e.g. if you manually delete an End User in Planhat, the integration won't delete the corresponding Contact in HubSpot), but records can be created and updated.


Unique IDs

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


Company associations

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.


Record filtering

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.

Sending to HubSpot

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.

Fetching from HubSpot

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:

  • A property (field) on the HubSpot object

  • An operator (e.g. "Equal to")

  • A value (e.g. "true")

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

πŸš€ Tip

If you select an operator that allows multiple values, and you want to fetch HubSpot records where the field is equal to any of a choice of specified values (x, y and z), then you would set the filter up as follows:

  • HubSpot multi-select field / In (which means "any of") / x,y,z

  • You type out the values yourself, separated by commas, with no spacing - as in the example above (x,y,z)

πŸš€ Tip

There are extra possibilities in the fetching filter for HubSpot Companies and Notes. In both these cases, you can either use the special/alternative filter described below, or the standard filter described above in the article body.

  • In the fetching filter for Companies, you have the option to refer to the "Pipeline" and "Deal Stage" of associated Deals in HubSpot

    • To set this up, open the fetching filter, and select "Associated Deals" from the dropdown menu. (You need to have a sync section configured to fetch HubSpot Deals for this to be available)

    • Rows to define both the "Pipeline" and "Deal Stage" will then be visible

    • You need to use the labels in HubSpot here

  • In the fetching filter for Notes, you have the option to exclude Notes based on the HubSpot object they are associated with

    • To set this up, open the fetching filter, and select "Associations" from the dropdown menu

    • Then, toggle the relevant switch(es) to "YES"

πŸ“Œ Important to note

The Company acts as a kind of filter itself: in the Planhat data structure, Company is at the top, and (almost) all other models have to link to a Company. The integration continuously fetches data from HubSpot, provided that the records are associated with a Company that exists in Planhat.

This means that, for example, only Contacts (End Users) belonging to a Company synced to Planhat are synced in from HubSpot, as Planhat doesn't support End Users not connected to a Company.

Filtering null values

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.


Field mapping

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.

  1. Click the blue "Map a Field" button to add a new field mapping row

    • Add a new row for each new pair of fields you'd like to sync

  2. Select a Planhat field from the left-hand dropdown menu

    • Selecting a field will automatically detect and display the field type

  3. Choose the sync direction

    • The sync options for the fields are limited by the sync direction you have chosen for the parent model/object - so, for example, if the parent is "Both Directions", you can pick any sync direction for its fields, but if the parent is set to "Receive from Provider", the fields can only be "Receive from Provider" or "Not Syncing"

  4. Select a HubSpot field from the right-hand dropdown menu

    • Selecting a field will automatically detect and display the field type

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

Fields mapped as default; required fields

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.

Mapping list/multipicklist fields

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.

πŸ“Œ Important to note

Before the release of the label-conversion feature, some integrations were set up to use internal values instead of labels. Contact Support, or your CSM, if you want to switch to using labels.

Field mapping in detail

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

  • We list the fields that are automatically mapped in these sync sections (either when you first authenticate the integration, or when you add a new sync section and select these models/objects)

    • These can be edited (or even removed) by you if desired, but note it is recommended to leave them as-is, because typically they are required fields

  • We also describe other suggested field mapping pairs

  • You are free to add your choice of field mapping - e.g. if you have custom fields you'd like to sync. Just keep clicking the blue "Map a Field" button each time you want to add a new pair of fields


Planhat Company - HubSpot Company

Fields automatically mapped for you

  • Planhat "Name" to HubSpot "Company name"

    • These are required fields in Planhat and HubSpot respectively

Recommended fields for you to map

  • Planhat "Phase" to HubSpot "Lifecycle Stage"

    • Make sure the HubSpot "Lifecycle Stage" field labels rather than internal values exist as values for the Planhat "Phase" field

  • Planhat "Description" to HubSpot "Description"

  • Planhat "Owner" to HubSpot "Company owner"

  • Planhat "Country" to HubSpot "Country/Region"

  • Planhat "Related Domains" to HubSpot "Company Domains (virtual field)"

    • We strongly recommend this field mapping (bidirectionally)

    • "Company Domains (virtual field)" is not a real HubSpot field - it combines the HubSpot fields "Company Domain Name" and "Additional Domains", to facilitate the sync

    • You can read more in our technical deep-dive article


Planhat End User - HubSpot Contact

Fields automatically mapped for you

  • Planhat "First Name" to HubSpot "First Name"

  • Planhat "Last Name" to HubSpot "Last Name"

  • Planhat "Email" to HubSpot "Email"

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


Planhat License - HubSpot Deal

Fields automatically mapped for you

  • Planhat "Start Date" to HubSpot "Close Date"

  • Planhat "Value" to HubSpot "Amount"

  • Planhat "Currency" to HubSpot "Currency"

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


Planhat Opportunity - HubSpot Deal

Recommended fields for you to map

  • Planhat "Close Date" to HubSpot "Close Date"

  • Planhat "Sales Stage" to HubSpot "Deal Stage"

    • Make sure the HubSpot "Deal Stage" field labels rather than internal values exist as values for the Planhat "Sales Stage" field

  • Planhat "Sale" to HubSpot "Amount"

  • Planhat "Owner" to HubSpot "Deal owner"


Planhat Task - HubSpot Task

Fields automatically mapped for you

  • Planhat "Due Date" to HubSpot "Due date"

    • "Due date" is a required field for the HubSpot Task object

  • Planhat "Description" to HubSpot "Task Title"

    • This could alternatively be configured Planhat "Description" to HubSpot "Notes"

Recommended fields for you to map

  • Planhat "Status" or "HubSpot Status" (custom field) to HubSpot "Task Status"

  • Planhat "Action" to HubSpot "Task Title"

  • Planhat "Owner" to HubSpot "Assigned to"


Planhat Conversation (type "ticket") - HubSpot Ticket

Fields automatically mapped for you

  • Planhat "Description" to HubSpot "Ticket description"

  • Your choice of Planhat field (select one from dropdown) to HubSpot "Ticket name"

    • We recommend you use the Planhat "Subject" system field

  • Your choice of Planhat field (select one from dropdown) to HubSpot "Ticket status"

    • You should create a custom Planhat field for this (see information box below)

  • Your choice of Planhat field (select one from dropdown) to HubSpot "Pipeline"

    • You should create a custom Planhat field for this (see information box below)

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

πŸ“Œ Important to note

When you are creating the custom fields in Planhat, remember that when mapping list/multipicklist fields, it's important that the values (possible options) in those fields are identical in both systems - and that this is referring to the labels in HubSpot rather than the HubSpot internal values.

πŸ“Œ Important to note

The Conversation Type "ticket" is a reserved standard Conversation Type within Planhat. Conversations of this Type can only be created via integrations (such as this HubSpot integration) or the API. This means you can't create records of this Type via the Planhat UI to send back to HubSpot.

Alternatively, rather than mapping HubSpot Tickets to Planhat "tickets", you could map them to a custom Conversation Type in Planhat, and that way you could create the relevant tickets within the Planhat UI and sync them to HubSpot.

Whichever Conversation Type you map to in Planhat though, it won't be possible to reply to HubSpot tickets from within Planhat.


Planhat Conversation (type "note") - HubSpot Note

Fields automatically mapped for you

  • Planhat "Description" to HubSpot "Note body"

Recommended fields for you to map

  • Planhat "Date" to HubSpot "Activity date"

    • "Activity date" is a required field in HubSpot

  • Planhat "Team Members" to HubSpot "Activity assigned to"

πŸ“Œ Important to note

If you add this as a new sync section (rather than using the one that's automatically created when you authenticate the integration), in order to display the relevant automatically mapped fields for Notes, select "Notes" as the HubSpot model on the right-hand side, before you select "Conversation" as the Planhat model. Remember to set the Conversation type as "Note".

πŸ“Œ Important to note

Conversations in Planhat can have different Conversation Types, but Notes in HubSpot don't (and you can't set this up via custom fields). That means if you sync such Conversations from Planhat to HubSpot Notes and then back again, you will lose the Conversation Types.

The workaround for this is to map Planhat Conversations to the HubSpot Call object, because HubSpot Calls can have Call Types, and you can configure HubSpot Call Types and Planhat Conversation Types to match up. This means that the Conversation Type would be correctly synced into Planhat.

The screenshot below shows where/how you can enable Call Types and edit options in HubSpot.

Click the image to view it enlarged

Because you specify the Conversation Type in the integration sync section, you would need to set up a separate sync section for each of your custom Conversation Types you would like to sync, such as "Kick Off".

The screenshot below shows the recommended/required fields for mapping Calls, with an example of a custom Conversation Type selected.

Click the image to view it enlarged


HubSpot marketing lists

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:

  • At the top of the HubSpot integration, above the model/sync sections, you'll see a section for "Marketing lists"

  • Click the blue "Map List" button to add a row you can complete

  • Select a Planhat End User filter in the left-hand dropdown

  • Select a HubSpot contacts list in the right-hand dropdown

  • Click the green "Save" button

πŸ“Œ Important to note

The marketing lists sync requires you to also be syncing between the Planhat End User model and HubSpot Contact object in the main part of the integration, and the direction for that sync section needs to be "Both Directions" or "Send to Provider".


Further reading

Did this answer your question?