Connectors / Service / Hubspot

From attracting visitors to closing customers, HubSpot brings your entire marketing funnel together. (updated: 1588596996487)

Hubspot

A full platform of marketing, sales, customer service, and CRM software

Overview

HubSpot offers a full stack of software for marketing, sales, and customer service, with a CRM at its core. They can be used independently or together.

IMPORTANT!: Note that v5.X is currently going through an internal upgrade to include all desired Hubspot operations. If the latest version does not have the operation you need please use either the Raw Http Request operation, or v3.11 of the Hubspot connector.

API INFO: The Base URL used for the Hubspot connector is https://api.hubapi.com. More information can be found on their main API documentation (v1.0) site. This is where users will also be able to find the API Limitations page.

Hubspot templates

Please note that we have the following Hubspot templates available:

These will give you pre-configured best practice ways of working with Hubspot and integrating it with other connectors.

However, please continue to at least read the Authentication and Trigger setup instructions on this page to enable you to get started with using Hubspot.

Authentication

Within the workflow builder, highlight the Hubspot connector.

In the Hubspot connector properties panel to the right of the builder, click on the Authenticate tab and the 'New authentication' button.

hubspot-auth-image

This will result in a Tray.io authentication pop-up modal. The first page will ask you to name your authentication and select the type of authentication you wish to create ('Personal' or 'Organisational').

IMPORTANT!: The 'Developer Key' is not needed for most authentications. If your authentication is failing and you are using one, try removing it and test again. For Embedded customers, having a Hubspot Developer account is mandatory. Please see our Note for Embedded Customers section below for more details. The 'API key' is needed only if you want to create, update or delete object schemas.

hubspot-dialog-scopes

Scopes

As you can see, you are asked to set up the scopes required for your individual project. Note that the scopes required will depend on the specific user/app/portal setup of your account.

The following table gives a summary of the accounts that are required for the scopes available in the Tray.

It is an edited version of the information available in the Hubspot 'working with OAuth' documentation:

Scope Provides access to Required account tier Notes
content CMS API and Calendar, Email and Email Events endpoints CMS Hub Professional or Enterprise or Marketing Hub Professional or Enterprise
contacts Contact, Companies, Deals, Properties, Engagements, and Owners endpoints Any account Add to the 'Extra permission scopes' box if required
social Social Media API Marketing Hub Professional or Enterprise
automation Automation API (Workflows endpoints) Marketing Hub Professional or Enterprise
timeline Timeline Events endpoints Any account Grants access to manage custom events on HubSpot CRM records. This includes creating or updating records
forms Forms endpoints Any account Note: Forms access also requires the contacts scope.
files Files (File Manager) and file mapper (CMS templates, modules, and layout) endpoints Any account
hubdb HubDB endpoints CMS Hub Professional or Enterprise or Marketing Hub Professional or Enterprise with Website Add-on
tickets Tickets endpoints Service Hub Free, Starter, Professional, or Enterprise
transactional email Transactional email endpoints Marketing Hub Professional or Enterprise with Transactional Email Add-on
e-commerce Products and line items endpoints Sales Hub Professional or Enterprise Users must be assigned a paid Sales Hub seatto authorize this scope

So before going further, make sure you have only ticked the scope boxes which your account has access to and which are required for the operations you want to carry out.

Hubspot Trigger

If you wish your workflow to be kicked off by a particular action in Hubspot, you can use the Hubspot Trigger.

The Hubspot trigger allows you to receive notifications and trigger workflows when given events occur associated with the selected trigger operation.

Webhook Setup

Select the Hubspot trigger. This can be done either at the create new workflow stage or updated within the workflow builder itself.

hubspot-trigger

Highlight the Hubspot trigger. In the Hubspot trigger properties panel to the right of the builder, click on the Authenticate tab and the 'Add new authentication' button.

Version 3.0+

Version 2.0 & earlier

The example below demonstrates a trigger that will only activate once the "hubspotscore" for a contact is updated.

Available Operations

The examples below show one or two of the available connector operations in use.

Please see the Full Operations Reference at the end of this page for details on all available operations for this connector.

Notes on using Hubspot

Hubspot headers

Advanced users only

API LIMITATIONS: Please be warned that Hubspot headers are case senstive. If this is a problem for your use case note that this can be mitigated by using the HTTP Client instead.

Updating contacts

It is important to note that the 'Update contact' operation is not an "Upsert" operation.

"Upsert" operations either update (for example, a contact which matches a certain ID), or will create a new one if no match is found.

'Update contact' does not support this.

You will therefore need to use a Boolean connector first to check if a contact exists, before attempting to create or update them along the following branches.

For more details please see Example usage: Create/ Update example below.

Note for Embedded customers

Embedded users need to make sure they understand the following before creating any workflows or Hubspot specific authentications.

  1. Embedded users MUST have/ use a Developer account, and use their Developer account during the authentication setup. Otherwise their workflows will not work.

  2. Embedded users will need a Developer account to create Oauth apps, but to then test "as an end user", they will also need to create a free CRM account.

Developer accounts are free and you can create one here.

Login to your Developer Account and select the test account you wish to manage. If you do not have any, create one.

hubspot-dev-account

Only once this is complete should you begin your Embedded Hubspot authentication setup.

  1. Embedded users should also take into account that the scopes you use for your test workflow are the scopes that your end users will have. This cannot be changed.

  2. It is important to note that Embedded users will also need a Standard Hubspot account in order to fully test their automation, aka as an "end user".

  3. The Developer API key is meant for managing apps and test accounts. If this is not what you need, consider using a Standard Hubspot API key instead.

This community Hubspot article may help you if you are stuggling to understand the permissions required when using the Developer API key.

For more information Tray.io wise, see our Embedded Core topics section: (Setting Auth Scopes for End Users)[/embedded/core-topics/authentications/setting-auth-scopes/] for more details.

Using the Raw HTTP Request ('Universal Operation')

USER TIP: To see an example using the Raw HTTP Request operation in action, see ourAdvanced topics: Fallback values: Manual process, example below.

As of version 4.1, you can effectively create your own operations.

To use this you will first of all need to research the endpoint in the Hubspot API documentation v1.0, to find the exact format that Hubspot will be expecting the endpoint to be passed in.

Note that you will only need to add the suffix to the endpoint, as the base URL will be automatically set (the base URL is picked up from the value you entered when you first created your authentication).

The base URL for Hubspot is: https://api.hubapi.com

For example, say that you are using the latest version of the Hubspot connector, and the 'List All Contacts' operation did not exist. You would need to use v1.0 of the Hubspot API docs inorder to find the relevant endpoint - which in this case is a GET request called: Get all contacts.

More details about this endpoint can be found here.

hubspot-get-url

So if you know what your method, endpoint (and details of your query parameters are should you have any), you can get a list of current contacts available with the following settings:

Method: GET

Endpoint: /contacts/v1/lists/all/contacts/all

Body Type : none

Final outcome being: https://api.hubapi.com/contacts/v1/lists/all/contacts/all

hubspot-raw-http

Basic Examples

TRAY POTENTIAL: Tray.io is extremely flexible. By design there is no fixed way of working with it - you can pull whatever data you need from other services and work with it using our core and helper connectors. This demo which follows shows only one possible way of working with Tray.io and the Hubspot connector. Once you've finished working through this example please see our Introduction to working with data and jsonpaths page and Data Guide for more details.

PLEASE NOTE: Some of the operations used in these examples are currently only available in version "3" of the Hubspot connector. So please revert to v3.11 to make use of this functionality, or make use of the Raw Http Request operation.

Below are two basic examples to help users get to grips with the Hubspot connector.

  1. Create/ Update contacts

  2. List and filter contacts by ID

BEST PRACTICES: Whenever you do decide to create your own workflow, please make sure you take a look at our managing data best practices guide.

Create/ Update contacts

Below is an example of a way in which you could potentially use the Hubspot connector to create &/ update a contact's details depending on whether or not the contact already existed.

The steps will be as follows:

  1. Setup using a Webhook trigger and collect the contact info associated with the incoiming data, even if the anser is 'null'.

  2. Check the status of the contact in Hubspot and whether they exist or not based on their email address.

  3. Depending on the result either create or update the contact accordingly.

Your completed workflow should look similar to this:

hubspot-complete-wf

1 - Setup Trigger & Get contact info

In this case we begin by using a Webhook to send sample data coming in from a third-party service in email format (which indicates an update is required to a contact in Hubspot as per our use case).

With your trigger in place (be it Manual, Scheduled, Callable etc) add a Hubspot connector. Set the operation to 'Find contact by email'.

hubspot-step-1

Feel free to re-name your steps as you go along to make things clearer for yourself and other users. The operation names themselves often suffice.

This will get all the contact information available on the contact in Hubspot which is associated with this email address.

2 - Check contact exists

Next, search for the Boolean connector within your connector panel, and drag it into your workflow as your next step. Set your operation to 'Boolean condition'.

The Boolean connector allows you to check your results in a true or false format. In this example, we will use it to check whether the data found within the previous Hubspot connector step exists or not.

In order to specify the contact you want to check, start by using the list mapping icon (found next to the list input field, within the properties panel) to generate the connector-snake.

While hovering over the 'Find contact' step (with the tail end of the connector-snake), select found from the list of output properties displayed. This will auto-populate a jsonpath within your list input field, and update the type selector to jsonpath.

For more clarification on the pathways you have available, open the Debug panel to view your step's Input and Output.

JSONPATHS: For more information on what jsonpaths are and how to use jsonpaths with Tray.io, please see our Intro page and Data Guide for more details.

CONNECTOR-SNAKE: The simplest and easiest way to generate your jsonpaths is to use our feature called the Connector-snake. Please see the main page for more details.

hubspot-step-2

Don't forget to make sure that the comparision type is set to 'Equal to' and that 'The 2nd of 2 values to compare' has been checked. The latter is set by changing the 'Type selector' to boolean.

3 - Create/ Update contact

Create if NOT found (false)

If the answer is false then the contact must be created as it is clearly new. Select 'Create contact' from the operation dropdown menu options.

Note that in this example we also format the date to be passed, before using the 'Create contact' operation:

hubspot-step-3
Update if found (true)

If the answer is true then we need to update the existing contact with the new information coming in. Use the 'Update contact' operation.

The key point here is that we use the $.steps.hubspot-1.contact.vid jsonpath, to use/ get the vid (aka contact ID) returned by the 'Find contact' step:

hubspot-step-4

List and filter contacts by ID

Below is an example of a way in which you could potentially use the Hubspot connector to list all available contact's and then find/ filter them by their ID field.

The steps will be as follows:

  1. Setup using a manual trigger and list the contacts found within associated Hubspot account.

  2. Iterate through each contact within said list.

  3. Get the relevant contact information for each contact found.

Your completed workflow should look similar to this:

hubspot-complete-list-wf

1 - Setup Trigger & List contacts

With your trigger in place (be it Manual, Scheduled, Callable etc) add a Hubspot connector. Set the operation to 'List Contacts'.

hubspot-list-step-1

Feel free to re-name your steps as you go along to make things clearer for yourself and other users. The operation names themselves often suffice.

Now when your trigger is activated, the Hubspot connector will collect a complete list of contacts associated with your account.

2 - Loop through Contacts

Next, search for the Loop connector within your connector panel, and drag it into your workflow as your next step. Set your operation to 'Loop list'.

The Loop connector allows you to iterate through a list of results. In this example, we will use it to iterate through the data found within the previous Hubspot connector step.

In order to specify the list you want to loop through, start by using the list mapping icon (found next to the list input field, within the properties panel) to generate the connector-snake.

While hovering over the 'List' field in the 'List contacts' step (with the tail end of the connector-snake), select contacts from the list of output properties displayed. This will auto-populate a jsonpath within your list input field, and update the type selector to jsonpath.

For more clarification on the pathways you have available, open the Debug panel to view your step's Input and Output.

hubspot-list-step-2-loop

Now when your workflow is run, it will iterate through the list of contacts found in the previous step one by one.

3 - Get Contact Info

The last step is to drag a Hubspot connector inside the Loop connector step itself. Set the operation to 'Find contact by ID'. As you can see, the 'Contact ID' field is required.

You can generate this jsonpath the same way you did in the previous step only this time place the end of the connector-snake to the Loop connector. Select vid when the options display.

hubspot-list-step-3-loop

Now when run, each contact within the contacts list details will be collected individually.

Check your Output in the Debug panel for more details:

hubspot-list-step-4-loop

Advanced Topics

PLEASE NOTE: Some of the operations used in these examples are currently only available in version "3" of the Hubspot connector. So please revert to v3.11 to make use of this functionality, or make use of the Raw Http Request operation.

Engagements

There are 5 types of Engagement activity in Hubspot, and the properties for each "Engagement type" is different.

  • Note

  • Email

  • Task

  • Meeting

  • Call

To Create an Engagement, the type needs to be selected from the dropdown.

When Updating an Engagement, the "Engagement type" needs to be known beforehand. This can be obtained from the 'Get engagement' operation (as explained below).

Create engagement

In this example we'll create a Call engagement, linking it to a pre-existing contact within Hubspot.

The input is split into 3 areas: 'Engagement details', 'Metadata' and 'Associations'.

'Engagement details' are fields that apply to all engagement types. Currently these are 'Owner ID' and the 'Timestamp' of when the engagement activity occurred.

hubspot-create-eng-1

The 'Metadata' section consists of the type specific properties for the engagement itself.

having selected a 'Metadata' type ('Call'), we can see the 'Call' properties consists of several fields: 'From number', 'To number', 'Duration', 'Recording URL', 'Body' (call notes) and 'Deposition'.

hubspot-create-eng-2

The 'Associations' section allow you to link the Engagement to a contact, company or deal.

Doing this makes the Engagement appear on that particular contact/company view within the Hubspot account UI.

hubspot-create-eng-3

Update engagement

To update an Engagement, two things are required. The 'Engagement ID' and the "Engagement type" as mentioned above in the Engagement section above. This is so the correct metadata properties can be chosen.

hubspot-update-eng-1

IMPORTANT!: The correct "Engagement type" (or 'Metadata' type) MUST be selected even if not updating any metadata properties. For example, even if you are only updating the 'Owner ID'.

If you are not updating any metadata, ensure that you reset the fields. This will change the Empty string value to No value.

IMPORTANT!: If this is not done, the data returned will get overwritten with empty strings instead.

Fallback values

IMPORTANT!: The Hubspot API is designed in such a way that if a field has no value then it will not be returned (at all), in any format, in the returned results. That is to say, if a contact object had a name field with a null value, then not even the name field would be returned. As a result, Fallback values should be used for each return value even if the chances of the return being empty or the call failing are slim.

The Hubspot API does not return empty fields and will error when they empty fields are found. This presents a problem if you you want to update another service or database which is expecting a result, as this will stop the workflow.

When both the field as well as the value is missing from the Input and Output panels debugging can become difficult.

It is therefore strongly recommended that Fallback values are used each time a Hubspot value is expected to be returned. Again, even if the value is simply an empty string, it will be enough to mitigate this issue.

For example, the code below demonstrates a contact object coming in from a random webhook service. In the phone field it contains a null value, amongst others:

WEBHOOK DATA

"employee": [
{
"name": "Andre Webber",
"id": 123456789,
"phone": null,
"startdate": 12/03/2020,
"email": "webber@exmaple.com"
"department": null,
}
]

Because the value that is trying to be manipulated is null, your Hubspot workflow will fail and stop running when this is requested of it:

INPUT PANEL:

"message": "Reference: $.steps.hubspot-1.response.body.employees[0].phone.value in property: 'data[].value' did not resolve to any value."

OUTPUT PANEL:

"message": "There was an error creating connector input. See the input panel for details."

Fallback values create a safe buffer for such instances. They provide an "answer" that the Hubspot API can deal with which means your workflow will be able to continue its run even if there is no "real" data for said field.

You may also be interested in checking out our Fallback values documentation for more general information on the subject.

There are 2 variations of setting Fallback values within Hubspot. Please note that we highly recommend the Manual method over the code based alternative.

  1. Manual method: This is recommended for almost all use cases.

The Fallback values feature has been setup within Tray.io so that even the least technical user can build with error handling in mind. The manual method also makes hand overs easier as the set values are very clear. See below walk through for more details.

  1. Javascript method: Users should be warned that this particular method requires a higher level of technical understanding than the Manual method listed above. Any method that uses a code base is not universally friendly and is harder to maintain.

To use the Javascript method add a Javascript connector and set the operation to 'Execute Script'. Place your code within the relevant input panel and run the workflow to execute the script.

Manual method

USER TIP: This explanation delibrately includes steps that use the Raw HTTP Request so as to better demonstarte how v5.X of the connector can be utilised. This is because when writing this example, Hubspot v5.X was undergoing updates and had limited operations available. For those wishing to view the Manual Fallback method, go straight to Step 6.

This method needs less technical knowledge both for the creator and future users, as it uses the manual fallback options available within the Tray.io properties panel.

This workflow collects a list of employee contacts and iterates through each one. It then gathers the associated record details and assigns the data to a Google sheet. If no value is found for the Hubspot field referenced, instead of erroring a Fallback value is supplemented.

In this demo, it is in the Google sheets connector where the Hubspot Fallback values are set as this is where the values need to be checked/ called/ transferred over. See Step 6> for more details.

Your end result should be similar to what is displayed below:

hubspot-fallback-complete

EXTRA AUTHS: In order to complete this workflow, you will also need to be authenticated with the Google sheets connector.

PLEASE NOTE: Note that this example utilises Raw HTTP Request operations and v5.1 of the Hubspot connector. Therefore it utilises Hubspot API documentation v1.0 (aka the Legacy docs).

  1. As this workflow's purpose is to copy Hubspot employee contact data across into a Google sheet, you will need to have your Google sheets authentication set up and use the Hubspot 'Raw HTTP Request' operation.

  2. A quick look at the docs tells us that to collect a list of all contacts available within the associated Hubspot account, we must use the 'Get all contacts' endpoint: /contacts/v1/lists/all/contacts/all.

More information can be found here. Use the correct setup as explained above in the Raw HTTP section.

  1. This will now gather a list of all the current contacts held within your Hubspot account. However, as the Output panel shows, the details per each contact are limited.

They don't include much of the basic information that we need to transfer over. The employee job title, phone number etc is missing from this API call. Therefore another call is necessary and we will need to iterate through each contact.

hubspot-fallback-rtn-call
  1. Once the Loop step is in place it will go through each employee contact found (vis the 'Loop list operation'). Another 'Raw HTTP Request' operation is used this time using the 'Get contact by ID' endpoint: /contacts/v1/contact/vid/:vid/profile.

This returns all the present properties associated with this particular Contact ID record. Try using Interpolation within your 'Endpoint' property for a cleaner result.

hubspot-fallback-get-contact

Note that this will not return all potential properties, just the ones that are affiliated. More information can be found here.

  1. It is in the Google sheets connector where the Hubspot Fallback values are set as this is where the values need to be checked/ called/ transferred over.

Use the 'Create row' operation and make sure to set the 'Spreadsheet ID' and 'Worksheet name' properties. Most often, the latter is defaulted to `Sheet 1' and can be selected from the dropdown options available.

Setting Fallback Values

  1. If you have a field with a null value, you may see error messages similar what is displayed below. Here, we have a situation where an employee field is missing, aka an employees job title.

As you can see, the message returned does not clarify what the actual problem is. Luckily we already understand that this is due to having a null field value.

hubspot-fallback-error-msgs
  1. The easiest way to set Fallback values is by first checking the Debug panel. Having checked what is being returned/ coming in from our second Hubspot step ('Get contact details') we can use the connector-snake to set the jsonpath.

hubspot-fallback-step-1

Once this is done, hover over the 'Row data' -> 'Field' -> 'Value' to enable the Fallback option. Follow the numbered steps for more clarification on how Fallback values can be set.

hubspot-fallback-step-2
  1. Now when a null value is found within the 'Job title' field, instead of halting the workflow and returning an error, the Fallback value is sent instead:

hubspot-fallback-step-results

All Operations

Latest version:

5.6

Archive property

Move a specified property to the recycling bin.

Archive property group

Move a specified property group to the recycling bin.

Associate crm objects

Associates two CRM objects.

Associate custom object

Associate a custom object with another object.

Cancel marketing event (beta)

Mark a marketing event as cancelled.

Create CRM contact

Create a contact in Hubspot CRM.

Create blog post

Create a new blog post.

Create company

Creates a company.

Create contact

Create a new contact in HubSpot.

Create contact list

Create new contact list.

Create custom object

Create a CRM object with the given properties and return a copy of the object, including the ID.

Create deal

Creates and tracks deals in HubSpot. It also allows you to connect HubSpot with an external CRM or other sales management software.

Create marketing event (beta)

Create a new marketing event in HubSpot.

Create object schema

Define a new object schema, along with custom properties and associations.

Create property

Create a property on an object type.

Create property group

Create a new property group for an object type.

Create/update marketing event (beta)

Upsert a marketing event. If there is an existing marketing event with the specified ID, it will be updated; otherwise a new event will be created.

Create/update subscriber by ID (beta)

Record a subscription state between multiple HubSpot contacts and a marketing event, using vids(contact IDs).

Create/update subscriber by email (beta)

Record a subscription state between multiple HubSpot contacts and a marketing event, using contact email addresses.

Delete blog post

Delete a specified blog post.

Delete comment

Mark the comment as deleted.

Delete contact

Delete contact.

Delete contact list

Delete a contact list.

Delete custom object association

Delete a custom object association.

Delete object schema

Delete a schema. NB: Any existing records of this schema must be deleted first, otherwise this request will fail.

Get app settings (beta)

Retrieve the current settings for the application.

Get blog post

Retrieve a specified blog post.

Get company property

Get a specific company property by its (internal) name.

Get contact property

Retrieve contact property.

Get deal

Returns a specified deal.

Get file import status

Retrieve the status of a file import.

Get marketing event

Retrieve details of the specified marketing event.

Get owner

Read an owner by given ID or User ID.

Get subscription status

Retrieve the email subscription information for the given email address and portal.

Get subscriptions timeline

Retrieve a time-ordered list of subscription changes.

List CRM contacts

Retrieve a list of CRM contacts.

List associations DDL

List authors

Retrieve a list of blog authors.

List blog posts

Retrieve a list of blog posts.

List blog posts DDL

List comments

Retrieve the comments from your HubSpot blogs.

List comments DDL

List company properties

Gets all company properties, including their definition, for a given account.

List company properties DDL

List contact list contacts

Retrieve a list of contacts on a particular list.

List contact lists

Retrieve contact lists for the account.

List contact lists DDL

List contact properties

Retrieve contact properties.

List contact properties DDL

List contacts

Retrieve all the contacts that have been created in the account.

List contacts DDL

List crm contacts DDL

List custom objects

Retrieve a list of custom objects of a specified type.

List deals

Retrieve a list of deals in Hubspot

List deals DDL

List folder IDs DDL

List folder paths DDL

List folders

Retrieve and search a list of folders.

List object schemas

Retrieve a list of object schemas that have been defined for your account.

List object schemas DDL

List object types DDL

List properties

List all properties for a given object type.

List properties DDL

List property groups

List all property groups for a given object type.

List property groups DDL

List subscription types

Retrieve all email subscription types that have been created in the given Hub ID.

List subscription types DDL

Raw HTTP request (advanced)

Perform a raw HTTP request with some pre-configuration and processing by the connector, such as authentication.

Search objects

Search for objects of a particular type.

Update CRM contact

Update CRM contact by ID. Properties values can be cleared by passing an empty string.

Update app settings (beta)

Create or update the current settings for the application. NOTE: You must provide a valid developer API key to successfully run this operation.

Update blog post

Update a single blog post.

Update custom object

Update a CRM object. The values assigned to 'Properties' can be cleared by passing an empty string.

Update deal

Updates a deal.

Update marketing event (beta)

Update an existing marketing event in HubSpot.

Update object schema

Update the details for an existing object schema.

Update property

Perform a partial update of a specified property. Provided fields will be overwritten.

Update property group

Perform a partial update of a specified property group. Provided fields will be overwritten.

Update subscription status

Update an email address' email type subscription status or permanently unsubscribe an email address from all subscriptions.

Upload file from URL

Asynchronously import a file at a given URL into the file manager.