HubSpot

8.0

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

Overview

Copy

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.

API Information

Copy

The Base URL used for the HubSpot connector is https://api.hubapi.com. More information can be found on their main API documentation sites. This is where users will also be able to find the API Limitations page.

Authentication

Copy

Within the builder, click on the HubSpot connector to display the connector properties panel. Select the Auth tab and click on the New authentication button.

In the Tray.io authentication pop-up modal name your authentication in a way that will quickly identify it within a potentially large list. For example whether it is a Sandbox or Production auth, etc.

Consider who/ how many people will need access to this authentication when choosing where to create this authentication ('Personal' vs 'Organisational').

Depending on the Auth type you choose you will be expected to select scopes that are relevant to your project and perhaps an API key.

It is critical that you read through the following subheadings as they include important information on each authentication section which you need to be aware of before you begin setting up your authentication.

HubSpot Trigger

Copy

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.

Trigger Operations available:

Copy

• Webhook (event subscription)

• Webhook (custom actions)

Webhook Setup

Copy

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

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.

Available Operations

Copy

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

Copy

API Keys cont.

Copy

As of 30 November 2022 API calls made with API keys on or after this date will return 401 errors.

Please be aware that API Keys vs Developer API keys are NOT the same thing.

HubSpot is sunsetting the use of API Keys. Whereas Developer API Keys are still relevant in some use cases.

Pre-existing HubSpot API Keys will work until 30th November 2022. Accounts which do not have an API key as of 15th July 2022 will not be able to create new API keys.

As a result of this change integrations will instead be required to work with Private Apps.

Scopes cont.

Copy

During your authentication setup you are asked to select project relevant scopes.

On July 31st 2022 the 'contacts' scope was replaced with a more granular selection of customer relationships management scopes.

If you wish to keep using an old authentication simply update your scopes. You can do this by replacing the old 'contacts' scope with the new more precise contact scopes.

The following table gives a scope summary and is an edited version of the information available within the HubSpot 'working with OAuth' documentation site.

So before going further please 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.

Remember that the scopes required will depend on the specific user / app / portal setup of your account.

Headers

Copy

Please be warned that HubSpot headers are case sensitive.

If this is a problem for your use case note that this can be mitigated by using the HTTP Client instead.

Create / update

Copy

Any operations that has the term create / update in its title is essentially an Upsert operation. For example if we take a look at 'Batch create/update contacts':

• If a HubSpot contact does exist, the contact record is updated.

• If a HubSpot contact does not exist, a new contact record is created.

All batch create / update operations work in this manner.

For an example of how this works please see the Example use cases section below.

Engagements

Copy

We have 5 of the main HubSpot Engagement types within out list of available operations:

• Note

• Email

• Task

• Meeting

• Call

The properties related to each Engagement type is different.

You will need to check out the Engagements main documentation page for more information on what they and the limitations associated are if you intend to use any.

As it stands you can Create / List / Update (eg. 'Create email engagement') the main 5 engagement types using the various operations available.

Create an Engagement

Copy

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

List & / or Update an Engagement

Copy

When Listing or Updating an Engagement the Engagement type needs to be known beforehand.

Properties with history

Copy

Operations which have the optional Properties with history input field have a maximum number of items that the operation can return per call.

• Requests made with the 'Properties with history' field return 50 items

• Requests made without the 'Properties with history' field return 100 items

Fallback values

Copy

HubSpot should return null values without any issue. Should you find that this is not the case then please use Fallback values to fix it.

Example use cases

Copy

List contacts & Get Contact by ID

Copy

Below is an example of a way in which you could potentially use the HubSpot connector to list all the available contacts within the database and then add each contact by their ID to a Google spreadsheet.

Workflow

Copy

End result

Copy

Create / Update: Singular vs Batch

Copy

There are essentially two variations of the 'create / update' (i.e. upsert) operations. One is singular and the other processes data in batches. Both will either add information to the HubSpot database or update the fields if they already already exist.

We have briefly outlined both options in the steps below. Both examples assume that a Google sheets form has been submitted via a Tray.io form trigger, and the Google sheet information is either updated or added to the HubSpot database accordingly using one of these operations.

I would recommend using the following Template if you are looking for inspiration regarding the beginning steps outlined above. Bear in mind that you may need to alter some parts of it in order to work with your individual use case.

Workflow/s

Copy

Using the Raw HTTP Request

Copy

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 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 the Hubspot API docs in order 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.

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: https://api.hubapi.com/contacts/v1/lists/all/contacts/all

Notes for Embedded customers

Copy

Developer & CRM Accounts

Copy

Embedded users MUST:

1. Have a Developer account in order to create OAuth applications.

2. Have a CRM account in order to test as an end user.

You will also need to use said Developer account when creating your authentications. Otherwise your workflows will not work.

Custom OAuth apps

Copy

You can create a custom OAuth app in order to White-label your authentications dialog in during your integrations.

Simply follow the steps outlined below.

Custom OAuth apps and webhooks

Copy

It is possible to configure your custom OAuth app to work with webhooks and the Tray HubSpot trigger.

Having created a Custom OAuth app as above and retrieved your ClientID:

You can then go to the Webhooks section of your app and add a custom Tray webhook url.

Please reach out to your customer success representative to obtain this url.

This will work for any event subscription (not custom actions) - e.g. new contact creation etc.

Scopes

Copy

Please be aware of the following points when dealing with scopes while using an Embedded account:

• The scopes you use for your source / master workflow are the scopes that your end users will have when creating the auth.

• You can also override scopes in the solution editor. This will allow you to specify that only a subset of the scopes set in the master workflow are available to your End Users. Please reach out to your Tray technical support if you wish to activate this feature.

• When creating an OAuth app in the HubSpot UI, you can set the required scopes. However, it is NOT recommended as you would have to create a custom OAuth app for every integration that you create for this service to enforce scope limitation.

  • A better way would be to use the standard method of setting the scopes when you are creating an authentication in your source / master workflow for each Solution. This way you can have multiple integrations that use the same custom OAuth app and control them within Tray.