💡 This article is for you if…
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.
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.
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
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:
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.
Here’s a quick summary of some important things to know about the HubSpot API.
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.
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 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:
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:
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.
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 firstname.lastname@example.orgWe’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 email@example.com and I’ll be more than happy to personally help.