đĄ 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 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.
â