HubSpot API Quick Start Guide

calendar-icon

By Anders Grové - February 19, 2020

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:

ERD-Diagram

* 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:

 

External System Name

HubSpot Name

Object Type

Property Type

Notes

email

email

CONTACT

Single line text

 

name

*

CONTACT

Single line text

* Custom property to be created

first name

firstname

CONTACT

Single line text

 

last name

lastname

CONTACT

Single line text

 

role

job_function

CONTACT

Single line text

 

How did you discover us

*

CONTACT

Single line text

* Custom property to be created

subscribe newsletter

*

CONTACT

Single checkbox

* One property for each newsletter type (to be created)

subscription type

*

CONTACT

Dropdown

* Custom property to be created

company

company

CONTACT

Single line text

 

country

country

CONTACT

Single line text

 

number

phone

CONTACT

Single line text

 

more info

*

CONTACT

Single line text

* Custom property to be created

subject

hs_ticket_category

TICKET

Multi-checkboxes

 

support text

content

TICKET

Multi-line text

 

project count

*

CONTACT

Number

* Custom property to be created

project person count

*

CONTACT

Number

* Custom property to be created

file size

*

CONTACT

Number

* Custom property to be created

remaining capacity

*

CONTACT

Number

* Custom property to be created

 

* 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:

Action

Type

Endpoint

Verb

Link to Guide

Register for trial account

Contacts API

/contacts/v1/contact/email/:email/profile

POST

Update by Email

User cancels account

Contacts API

/contacts/v1/contact/email/:email/profile

POST

Update by Email

Contact form

Option 1: Contacts API

/contacts/v1/contact/email/:email/profile

POST

Update by Email

Contact form

Option 2: Forms API

/uploads/form/v2/:portal_id/:form_guid

POST

Submit data to a Form

Contact form

Option 3: Use HubSpot Form

Replace contact form with HubSpot form

-

HubSpot Forms

Contact form

Option 4: Use Non-HS Form

The HubSpot embed allows tracking of forms

-

Non HubSpot Forms

News letter

Email Subscription API

/email/public/v1/subscriptions/:email_address

PUT

Update email subscription

Newsletter: Get Subscription IDs

Email Subscription API

/email/public/v1/subscriptions

GET

Get email subscription types

Support form

Tickets API

/crm-objects/v1/objects/tickets

POST

Create a ticket

Support form: Get Contact VID

Contacts API

/contacts/v1/contact/email/:contact_email/profile

GET

Get a contact by email

Support form: Associate Ticket to Contact

CRM Association API

/crm-associations/v1/associations

PUT

Associate CRM objects

Additional

       

Create deal

Deals API

/deals/v1/deal/

POST

Create a deal

Get deal ID

Deals API

/deals/v1/deal/:dealId

GET

Get a deal

Update deal

Deals API

/deals/v1/deal/:dealId

PUT

Update a deal

Associate Contact to Deal

CRM Association API

/crm-associations/v1/associations

PUT

Associate CRM objects

* 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

HubSpot GitHub Samples

API Documentation

HubSpot API Community

 

HubSpot Developer Slack Channel

That's all you need!

Hopefully you have everything you need to get started building your integration. Good luck!

If you need help, reach out and let's chat!

Learn more about the HubSpot CRM - Contact Us

web-redesign-process-final-comment

...my two cents worth

Teamwork.

It's a lot more rewarding when you work with like-minded individuals who keep you in-the-loop, are keen to share knowledge and who are passionate about turning-out a kick-ass product.

web-redesign-process-teamwork

We promise that we won't SPAM you.