💡 This article is for you if…

1. You want a quick start alternative to reading through the vast amount of HubSpot documentation.
2. You’ve built your HubSpot integration already but want to learn about common gotchas and best practices to make your integration more robust.

‍

HubSpot is an all-in-one marketing and sales CRM and one of the fastest-growing GTM tools on the market. If your product needs to integrate with CRM data of any kind, then you’ll probably need to build an integration with your customer’s HubSpot account sooner or later.

Thankfully, HubSpot is one of the most developer-friendly integrations you can build, with plentiful documentation and robust developer accounts. Nevertheless, it still comes with its own set of quirks, nuances, and pitfalls and it’s no small task to spin up and maintain a customer-facing HubSpot integration. Fortunately, we’ve already gone through the headache of building and maintaining a complex native HubSpot integration and have distilled all of the wisdom and gotchas we’ve picked up over the years into this guide.

If you’re unfamiliar with what native integrations are in the first place, you can reference our previous blog post aptly titled “what are native integrations?”

As a side note, I’ll be using the Vessel SDK to build this integration so I don’t have to worry about setting up Auth or handling any HubSpot API quirks. If you want to follow along you can fork this template repo here.

If you don’t want to use Vessel, no worries, I’ve kept this guide as generic as possible and it’ll be useful regardless of how you decide to build your native HubSpot integration.

Getting Setup For your HubSpot Integration

Before you dive into writing code for your HubSpot integration, there are a few logistical things you’ll want to get out of the way before we can begin making API calls.

Create a Developer Account

First, you’ll need access to a developer account where we can muck around with fake data without worrying about messing up anything in a real HubSpot account. Developer accounts are free and essentially the same in functionality as a real accounts but come with some major restrictions to prevent you from abusing them.

🔗 You can set up a developer account here

Create A HubSpot OAuth App

If you’re using Vessel, you can go ahead and skip this step since we’ve got a pre-approved HubSpot application you can use. If you’re not using Vessel, you’ll need to keep reading to learn how to set up an OAuth app.

HubSpot recently sunset support for API key access so you’ll need to create an OAuth app to get access to your customer’s HubSpot account data. We’ll worry about how to use this App to connect to your customer's account later.

To create an app, you can log into your developer account, head to the ‘Apps’ navigation section, and click ‘Create app’.

This should spin up a new draft OAuth app. You can ignore most of the configuration for now, there’s only two things you’ll need to fill in:

• The Scopes, for this tutorial we’ll give ourselves CRM contact read and write access but you can pick whatever objects you’d like. These scopes are changeable so don’t worry about nailing the exact set you need right now.

• Additionally, you’ll need to fill in the Redirect URL, you can go ahead and put ‘localhost’ for now since we’ll need that for local testing.

And that’s it, you’ve got a working OAuth app and you’re ready to get building 👷🏻‍♂️! Head to the next section for a breakdown of how to build the integration.

The HubSpot API at a Glance

Here’s a quick summary of some important things to know about the HubSpot API.

Authentication

The first step to making an API call is to ask your user for permission to access their data. We do this by “installing” the OAuth app we created in the step above (or already had if you’re using Vessel) inside of their CRM instance.

During this process, your user will be shown a popup window that asks them to grant you permission to read and write their data.

Which objects they grant you access to will depend on which scopes you selected when creating the OAuth app. In our case, the user would only see permissions related to contacts (such as ”View properties and other details about contacts.”) since that’s all we requested when creating our OAuth app.

OAuth is a complicated and nuanced topic, for brevity, I’m not going to touch on how to build out an OAuth flow since it’s not HubSpot-specific.

If you’re new to OAuth and just need to get something going fast or don’t want to deal with the notorious headache of OAuth, you can use a framework like Vessel to handle it for you. You can see how this is done in Vessel in our template repo on the client here and the backend here.

If you’d prefer to do this yourself, you can read HubSpots tutorial on OAuth which is actually pretty decent. Forewarning, the HubSpot tutorial is very HubSpot specific so if you know you’ll need to build other integrations in the future, I’d invest in doing more research so you understand how to build a more generic Auth flow since OAuth is an infamously difficult problem.

Once you’ve got an Auth flow in place, you can reference the “Working with OAuth” HubSpot document to get the authorization and redirect URLs.

Regardless of how you choose to build authentication, the important part is that you’re able to get an accessToken for your user. The accessToken is what will allow us to pull and push data to the user's HubSpot instance.

Making an API Call

Now that you’re able to authenticate your user, you can begin making API calls to their CRM 🥳. In this section, we’ll explore how to read and write to the HubSpot API in real time.

Reading From the API

Reading from the HubSpot API is pretty straightforward and decently well-documented. Each object includes a get, get-all, and batch-get endpoint giving you a variety of ways to pull data.

With that said, here are a few gotchas to watch out for:

1. Associations:  When reading data, you’ll need to specify the associations you want to retrieve for an object during each API call.
2. Properties: Every object property needs to be manually requested during each API call. You can use the properties endpoint to list all of the properties, including custom, that a CRM object has. Since objects can have a huge number of properties, this can result in needing to make multiple API calls to the properties endpoint to get all the properties you need which eats up valuable rate limits.
3. Filtering & Sorting: Individual read endpoints don’t support any sort of filtering or sorting. You’ll need to call the dedicated search endpoint if you need to apply any filters.

Through HubSpot API

‍

With Vessel

Writing to the API

Writing to the HubSpot API is also pleasantly straightforward and well-documented. Additionally, Most objects, with a few exceptions like Owners, support both updates and creates.

With that said, there are still a few gotchas to watch out for:

1. Associations: Unfortunately, there’s no way to update or create an association through any of the regular object endpoints. You must use the standalone associations endpoints if you’re going to be updating or creating associations.
2. Rate limits: While there is a ‘batch create’, HubSpot doesn’t support any ‘batch updates’. Considering the relatively strict rate limits, this can be a real problem if you have a use case that requires updating many objects at once.

Through HubSpot API

With Vessel

Closing Thoughts

Publishing your Application

At this point, it’s safe to call this integration done. You can connect to your customer’s HubSpot instance and begin reading and writing through the API - congrats 🎉! The next thing to consider is getting your application approved and listed in the HubSpot App Market place. Not only will this give your application a special badge denoting it as “Certified”, but it’s also great for marketing.

You can learn more about the publishing process here.

About Us

Hopefully, you found this article helpful for building out your native HubSpot integration. I know I certainly wish something like this existed when we built out our HubSpot integration.

If you decided to give Vessel a spin while following this tutorial, thank you. If you have any feedback while using the SDK, don’t hesitate to reach out at support@vessel.devWe’re a team of engineers at heart and take every piece of feedback extremely seriously.

if you’re curious to learn more about why we started Vessel and how we view the future of customer-facing integrations, you can read more in our “what are native integration platforms” posts.

On that note, if you ever have any questions about building a HubSpot integration while you’re going through this tutorial, regardless of if you decide to use Vessel, don’t hesitate to reach out at zach@vessel.dev and I’ll be more than happy to personally help.

‍