HubSpot API Quick Start Guide

Welcome to the "HubSpot API Quick Start Guide," a comprehensive resource designed to help you seamlessly integrate with HubSpot's powerful suite of tools. Whether you're new to APIs or an experienced developer, this guide will walk you through the essentials of working with the HubSpot API.   

From understanding the fundamentals of HubSpot's data structures to navigating the complexities of OAuth 2.0 authorisation, this guide is intended to provide you with all the information you need to get started on integrating with the HubSpot API, quickly and effectively.

Hubspot Data Structures

A brief overview of the different types of CRM Objects, Association and Engagements.

API Overview

We take a look at all the critical components of getting up and running with your integration. A high level overview of REST, API limitations, Authorization, Authentication and Webhooks.

Also included in this guide is a mock brief, outlining the steps you need to take to map out the data and endpoint requirements - a crucial step in effective planning.

Sample Requirements Spec

A example of the spec you would have received from the client, outlining the actions that need to map to endpoints, as well as the data that would be required to sync.

Data Mapping

An example of a typical data relationship mapping spreadsheet. Thereafter the endpoint mapping, outlining the specific API endpoints they are integrating with.

Additional Resources

The best handpicked resources on HubSpot API.

HubSpot Data Structures

CRM Object Types

The main object architecture for HubSpot is simplified into 4 primary categories: contacts, companies, deal and tickets.

There are other subtypes as well; Products, Quotes, Engagements, Timeline Events, Notes. We’re not going into detail on these but you can read more about the different objects here.

Additionally, the HubDB is a customizable database(like a spreadsheet) that is typically used to store non-sensitive, relational data.

Contact

All information pertaining to an individual person. Uniquely identified by email address and VID(canonical-vid).

Company

Similar in structure to Contacts, except pertaining to individual companies. Uniquely identified by Company Domain Name and companyID.

Deal

All information pertaining to an individual deal in your CRM pipeline. Any activities that are attributed to revenue needs to be created as a deal so that it can be tracked and ROI measured. Uniquely identified by dealID.

Tickets

Information on an individual ticket. Similar to Deal objects, these tickets are added to a ticket board that is customized to match your processes (like a pipeline). Uniquely identified by objectID.

HubDB

These spreadsheet-like tables are mostly used for storing relational data that is used for supporting features or processes like dynamic content, widget functionality, pricing or pricing tier calculations, resource libraries and more. HubDB tables can be public (CORS enabled), or private (authentication required). Public tables have a rate limit of 10 req/per second, while private tables adhere to default rate limits(see API Overview below).

CRM Object Association

CRM objects can be associated with each other, creating a relationship between records. There are 3 different association methods; Automatic, Manual and association via the API:

Automatic

This feature is a setting that is activated in HubSpot, which will automatically associate records based on specific criteria. An example of this is ‘Automatically create and associate companies with contacts’; if a company domain name matches a contact email domain, the contact and company will be automatically associated, or if the company doesn’t exist it will be created and associated.

Manual

You are able to update association on individual records via the relevant record dashboards. Or you can do bulk association via importing and merging data with a spreadsheet.

API

Essentially the same as manual association but via the HubSpot API. Each association type has a specific corresponding ID and is done through the CRM Associations API. Additionally, knowing what unique IDs are required for association can be seen in the Entity Relationship Diagram below:

* HubSpot ERD Diagram – courtesy of HubSpot.

CRM Engagements

Engagements store data related to actions or activities done in your CRM. They are the interactions someone would have with a prospect/customer. These include notes, tasks, emails, meetings, and calls. The Engagement API is used to create engagements from external systems (logging calls, emails, notes) or extract engagement data for reporting.

API Overview

REST Architecture

HubSpot API’s use a REST architecture. This includes most standard HTTP features like HTTP verbs (get, put, post). All calls are made to the api base domain https://api.hubapi.com and specific endpoints have predictable, descriptive URL structures. All data is in JSON format, including all response codes that indicate API errors.

Limits

Access to APIs are limited to the product tier/level that you are subscribed to (starter/pro/enterprise). Though, it should be noted that very few limitations are in place in this regard. See complete list of API limits by tiers here.

Furthermore, all calls to the HubSpot APIs are subject to rate limiting. These limits are also determined by your product tier. The standard is 250,000 total calls per day and a maximum 100 requests per 10 seconds.

See a full breakdown of rate limits here.

Integrations that exceed their limits will receive an error 429 response code.

Authorization

There are two ways of authentication; API key and OAuth 2.0.

API keys should only be used for prototyping. For security reasons, in commercial production you should always use OAuth.

The first step in Authentication is Authorization. To do this you have to create and register an app in a developer account. This will provide you with your Client ID and Secret Key, which is used to initiate the OAuth handshake between HubSpot and your integration.

Create a Developer account.

OAuth allows you to authorize your integration to work with specific components of the HubSpot API by assigning authorization scopes. Each scope defines access to different parts of the HubSpot API. You can view the full list of available scopes here.

Below is a high-level overview of the authorization process:

1. The application opens a browser to send the user to the HubSpot OAuth 2.0 server
2. The user reviews the requested permissions, and grants access to the application
3. The user is redirected back to the application with an authorization code in the query string
4. The application sends a request to the OAuth 2.0 server to exchange the authorization code for an access token

Authentication

Once authorization is complete, you will have received a Refresh Token and an Access Token.

The Access token is used to authenticate calls made to the HubSpot API. This token expires after a specified amount of time (default 6 hours) and you use the Refresh Token to request a new Access Token.

Below are a few examples of this process, but it’s recommended to read this step-by-step guide for detailed information on authorization and authentication.

– authorizing the integration with specified scope, provides authorization code:

Example Authorization URL:
Sending a user to this URL will ask the user to approve access to contacts and workflows:
https://app.hubspot.com/oauth/authorize?client_id=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&scope=contacts%20automation&redirect_uri=https://www.example.com/

If they grant access, the user would be redirected to this URL:
https://www.example.com/?code=xxxx

If there are any problems with the authorization, you'll get the error parameters instead of the code:
https://www.example.com/?error=error_code&error_description=Human%20readable%20description%20of%20the%20error

– using the previously obtained auth code to generate the Refresh and Access Tokens:

POST URL:
https://api.hubapi.com/oauth/v1/token
Headers:
Content-Type: application/x-www-form-urlencoded;charset=utf-8
Data:
grant_type=authorization_code&client_id=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&client_secret=yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy&redirect_uri=https://www.example.com/&code=zzzzzzzz-zzzz-zzzz-zzzz-zzzzzzzzzzzz

If successful, you will receive a JSON response with the tokens:
{
  "access_token": "xxxx",
  "refresh_token": "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy",
  "expires_in": 21600
}

- authenticating calls to the API using the provided Access Token:

 {
   headers: {
     'Authorization': `Bearer ${ACCESS_TOKEN}`,
     'Content-Type': 'application/json'
   }
 }

* Code Samples – courtesy of HubSpot.

Webhooks

The Webhooks API allows you to trigger HTTP requests to a specified endpoint based on events in HubSpot. This allows for a better alternative to polling, saving on rate limits and providing a more scalable method of bi-directional data sync.

Webhook subscriptions are configured on your app dashboard, in your developer account. There are various event subscriptions available (contact created, deleted, contact property updated etc). Below is a link to the full list of available subscriptions.

Read the detailed guide here.

Sample Requirements Spec

Below is a sample specification, that your client might provide. It's a high-level overview, describing the endpoint and data requirements:

• User Registers for trial account
  • email
  • first name
  • last name
  • phone 
  • subscribe newsletter
  • subscription type
• User cancels account
  • email
  • subscription type
  • subscription type
• News letter subscription
  • email
• Contact form
  • Name
  • email
  • company
  • role
  • country
  • number
  • more info text
• Support form
  • name
  • email
  • subject
  • support text

Sample Data Mapping

Object Relationship Mapping

The next step in the process is determining the exact data you wish to sync and then mapping the object relationships between HubSpot and your existing system. Based on this mapping you will be able to determine field types, object types, one or bi-directional requirements as well as identify any custom properties that would need to be created in HubSpot.

See the data mapping based on provided data requirements below:

* Note – These assumptions need to be discussed in detail with your client. In this example there are potential use cases for using Deals to track memberships, or potentially use automation workflows to determine expiry dates. All this should be discussed in a workshop session with your client.

Endpoints

After you’ve mapped each property to it’s corresponding equivalent in HubSpot, you can start reviewing the individual endpoint requirements.

All endpoints are well documented and it’s recommended reading the Overview for each endpoint you plan on using. This is where you will find endpoint specific requirements, limit information, use cases, response messages and other related information.

Below is a breakdown of your endpoint requirements, based on provided specification:

* Note – all endpoints use the following base URL: https://api.hubapi.com/ (except in a few instances like the Forms API, which is a public endpoint).

* Note – The required data structure for each request can be found in the provided guide links.

Additional Resources

HubSpot has an extensive knowledge base and should provide everything else you need to get started. Below is a collection of the most useful resources on the HubSpot API:

HubSpot Academy

• Introduction to the HubSpot APIs

HubSpot GitHub Samples

• PHP application
• NodeJS/Javascript application
• Ruby application

API Documentation

• https://developers.hubspot.com/

HubSpot API Community

• https://community.hubspot.com/t5/HubSpot-Developers/ct-p/developers

HubSpot Developer Slack Channel

• https://designers.hubspot.com/slack

That's all you need!

In conclusion, this guide equips you with the knowledge and tools needed to harness HubSpot API's potential. With the ability to seamlessly integrate HubSpot into your applications, you can supercharge your marketing, sales, and customer service efforts and if you’re ready to take your integration to the next level, don't hesitate to book a call with our experts. Our team at Struto is here to assist you every step of the way.