Complete Guide to Building a Hubspot API Integration

Apr 4, 2024 • 25 minute read

Overview

HubSpot is an all-in-one inbound marketing, sales, and customer service software platform designed to help businesses attract, engage, and delight customers throughout the buyer's journey. As of 2021, HubSpot reported having over 121,000 paying customers in more than 120 countries.

What can you do with the Hubspot API?

The HubSpot API allows interaction with various data models, each serving different purposes within the HubSpot CRM. Here's a breakdown of what is possible for each data model:

Contacts: Store information about individual persons. You can create, read, update, and delete contact records, as well as associate them with other objects like companies and deals.
Companies: Store information about businesses or organizations. Similar to contacts, you can manage company records and associate them with contacts, deals, and other objects.
Deals: Represent revenue opportunities associated with a contact or company. Deals are tracked through pipeline stages, allowing you to monitor their progress towards being won or lost. You can create, update, and manage deal records, including their association with contacts and companies.
Tickets: Represent customer requests for help or support. Tickets are tracked through pipeline statuses, enabling you to monitor their resolution. You can create, update, and manage ticket records.
Calls: Store information about calls made with contacts. Calls can also be associated with other objects as an engagement, allowing for a comprehensive view of communication with contacts.
Quotes: Represent pricing information shared with potential buyers. Quotes can be associated with contacts, companies, deals, and line items, enabling detailed tracking of sales processes.
Custom Objects (Enterprise only): Create custom objects to store any type of data in HubSpot, particularly data that doesn't fit the standard objects listed above. This allows for highly customized data management within HubSpot.

Each of these data models can be interacted with through the HubSpot API, enabling developers to create, read, update, and delete records, as well as manage associations between different objects. This flexibility allows for a wide range of integrations and customizations to suit the specific needs of businesses using HubSpot.

Potential use cases

Here is the markdown text with the trailing list of URLs and citation references removed:

Automate Marketing Campaigns: Use the HubSpot API to automate the creation and management of email marketing campaigns, including scheduling, sending, and tracking email performance.
Integrate with CRM Systems: Connect HubSpot with other CRM systems to synchronize contact, company, and deal data, enhancing data accuracy and efficiency across platforms.
Customize Workflows: Develop custom workflows within HubSpot to automate repetitive tasks, such as updating contact information or managing deal stages, based on predefined triggers and actions.
Enhance Content Management: Utilize the HubSpot API to create, manage, and optimize content across your HubSpot CMS, including blog posts, landing pages, and website content, to improve user engagement and SEO.
Implement Advanced Analytics: Leverage the HubSpot API to access and analyze data from various HubSpot modules (e.g., contacts, deals, and marketing campaigns) to gain insights and make data-driven decisions.

Building with Hubspot's API

How to get a Hubspot developer account and API Keys?

To get a developer account for HubSpot and create an API integration, follow these steps:

Create a Developer Account: Create a developer account to develop public apps that can be installed across multiple HubSpot accounts. This account is where you create HubSpot apps, each authenticated with OAuth and provided with a configurable set of features and permissions.
Create an Application: Once you have a developer account, create a new application. This is necessary for using the Integration Platform APIs, which include the Timeline API, Webhooks API, and CRM Extensions API.
Use Developer API Key for Setup: While setting up your integration, use your developer API key for initial setup tasks. This key is different from the standard API keys and is used specifically for managing subscriptions for the Webhooks API and creating or updating event types for the timeline events feature. Access your developer API key by navigating to the Apps section in your developer account and clicking "Get HubSpot API key".
Implement OAuth for Authentication: After setting up your application and using the developer API key for initial configuration, implement OAuth for your app. This is crucial for HubSpot users to grant your app access to their portals.

Hubspot Logo

Link to Hubspot Developer Docs

https://developers.hubspot.com/docs/api/overview

Open API Spec

https://api.hubspot.com/api-catalog-public/v1/apis/crm/v3/objects/contacts

Here are more OpenAPI Specs for the Hubspot API

API Explorer

Run Queries against the Hubspot API

Hubspot SDKs

Typecript / Javascript

Top Hubspot SDK on NOM

@hubspot/api-client

Ruby

Top Hubspot SDK on Rubygems

hubspot-api-client

Python

Top Hubspot SDK on PyPi

hubspot-api-client

PHP

Top Hubspot SDK on Packagist

hubspot/api-client

Top Hubspot SDK on NuGet

HubSpot.NET

Hubspot API Details

What type of API does Hubspot provide?

HubSpot's APIs are built using REST conventions. They are designed to have a predictable URL structure and use many standard HTTP features, including methods like POST, GET, PUT, DELETE, and error response codes. All HubSpot API calls are made under https://api.hubapi.com, and all responses return standard JSON.

Does the Hubspot API have webhooks?

Yes, the official HubSpot API supports webhooks, allowing you to subscribe to events happening in a HubSpot account with your integration installed. Instead of making an API call when an event occurs, HubSpot can send an HTTP request to a configured endpoint, which is more scalable than regularly polling for changes.

To use webhooks, set up a HubSpot app by subscribing to desired events and specifying a secure (HTTPS) URL to receive notifications. The endpoint will receive POST requests containing JSON formatted data from HubSpot. To ensure the requests are authentic, HubSpot includes a X-HubSpot-Signature header with a SHA-256 hash built using the app's client secret and request details.

Webhook subscriptions apply to all customers who have installed your integration. Supported subscription types include contact, company, deal, ticket, product, and line item events. Create webhook subscriptions in your HubSpot developer account by navigating to the Apps dashboard, selecting an app, and then navigating to Webhooks. New subscriptions are created in a paused state and need to be activated for webhooks to send.

Rate Limits and other limitations

The HubSpot API has specific rate limits based on the product tier and whether the integration uses OAuth. Here are the key points regarding API rate limits for HubSpot:

Free & Starter Tiers:
Burst limit: 100 requests per 10 seconds.
Daily limit: 250,000 requests.
Professional & Enterprise Tiers:
Burst limit: 150 requests per 10 seconds.
Daily limit: 500,000 requests.
API Add-on (any tier):
Burst limit: 200 requests per 10 seconds.
Daily limit: 1,000,000 requests.
Integrations using OAuth:
Only subject to a limit of 100 requests per 10 seconds. The limits related to the API add-on do not apply to integrations using OAuth.
Error Responses:
Exceeding these limits will result in error responses with a 429 response code.
Other Considerations:
Integrations that poll HubSpot for new or updated information are limited to polling at intervals of five minutes or more.
Requests resulting in an error response may not exceed 5% of your total requests.
Integrations should use HubSpot's OAuth protocol and store time-to-live (TTL) data for OAuth access tokens.

These limits are reset at midnight based on the HubSpot account's time zone setting. It's important to adhere to these limits to ensure a quality experience for users and to avoid receiving error responses when making API calls.

Latest API Version

The most recent version of the HubSpot API was launched in early 2020 as part of HubSpot's effort to improve API consistency and completeness. However, not every endpoint or API has been updated to this latest version, and some older endpoints are still stable and supported. Some APIs have updated counterparts, but both versions are still supported. It is strongly recommended to upgrade your integration to the latest available version for better consistency and additional functionality. You can find the updated APIs in the new API reference docs provided by HubSpot.

Status Page

The most current status page URL for HubSpot is https://status.hubspot.com/

Code Examples

Building authentication

Here are the steps to set up authentication for the HubSpot API:

Obtain your HubSpot API credentials, including your client ID and client secret.
Redirect the user to the HubSpot authorization URL to grant your application access to their account. Use a CURL request similar to the following:

curl -X GET 'https://app.hubspot.com/oauth/authorize?client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_REDIRECT_URI&scope=SPACE_SEPARATED_SCOPES&response_type=code'

Replace YOUR_CLIENT_ID, YOUR_REDIRECT_URI, and SPACE_SEPARATED_SCOPES with your actual values.

After the user grants permission, HubSpot will redirect them back to your specified redirect URI with an authorization code appended to the URL.
Exchange the authorization code for an access token by making a POST request to the HubSpot token endpoint. Use a CURL request like this:

curl -X POST 'https://api.hubapi.com/oauth/v1/token' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'Accept: application/json' \
  --data-urlencode 'client_id=YOUR_CLIENT_ID' \
  --data-urlencode 'client_secret=YOUR_CLIENT_SECRET' \
  --data-urlencode 'redirect_uri=YOUR_REDIRECT_URI' \
  --data-urlencode 'grant_type=authorization_code' \
  --data-urlencode 'code=AUTHORIZATION_CODE'

Replace YOUR_CLIENT_ID, YOUR_CLIENT_SECRET, YOUR_REDIRECT_URI, and AUTHORIZATION_CODE with your actual values.

The response from the token endpoint will include an access token and a refresh token. Store these securely.
Use the access token to authenticate your requests to the HubSpot API by including it in the Authorization header as a Bearer token.
When the access token expires, use the refresh token to obtain a new access token without requiring the user to reauthenticate. Make a POST request to the token endpoint with the following CURL request:

curl -X POST 'https://api.hubapi.com/oauth/v1/token' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'Accept: application/json' \
  --data-urlencode 'client_id=YOUR_CLIENT_ID' \
  --data-urlencode 'client_secret=YOUR_CLIENT_SECRET' \
  --data-urlencode 'grant_type=refresh_token' \
  --data-urlencode 'refresh_token=YOUR_REFRESH_TOKEN'

Replace YOUR_CLIENT_ID, YOUR_CLIENT_SECRET, and YOUR_REFRESH_TOKEN with your actual values.

By following these steps, you should be able to set up authentication for the HubSpot API and securely make requests to the API endpoints using the obtained access token.