There's a new version of the HubSpot API

As of November 30, 2022, HubSpot API keys are no longer a supported authentication method for accessing HubSpot APIs. Instead, you should use a private app access token or OAuth to authenticate API calls. Learn more about this change and how to migrate an API key integration to use a private app instead.

HubSpot API Overview

Our APIs are in the midst of a transition. As part of our effort to improve API consistency and completeness, we launched the next generation of HubSpot’s API in early 2020. However, not every endpoint or API has been updated to the latest version, and our older endpoints are still stable and supported

  • Some older APIs don’t have an updated counterpart yet. 
  • Some APIs have an updated counterpart, but both versions are still supported. (Examples: object APIs like Contacts, Companies, Deals, etc.) Even though older APIs are still supported, we strongly recommend upgrading your integration to the latest available version for better consistency and additional functionality. You can find the updated APIs on our new API reference docs.
  • Older APIs that are no longer supported are classified as deprecated. They should not be used in new code and older code should be updated to use supported endpoints.

 

Welcome to the HubSpot API.

The API is built to allow you to create a functional application or integration quickly and easily. We know from experience - these are the APIs that power the HubSpot application. The ecosystem of developers creating integrations on top of the APIs is strong and diverse, ranging from webinar providers to CRMs to social media.

All of the HubSpot APIs are organized around REST - if you've interacted with a RESTful API already, many of the concepts will be familiar to you. All API calls to HubSpot should be made to the https://api.hubapi.com base domain. We use many standard HTTP features, like HTTP verbs, which can be understood by many HTTP clients. JSON will be returned in all responses, including errors. The APIs are designed to have predictable, straightforward URLs and to use HTTP response codes to indicate API errors.

Getting listed on our App Marketplace

If you're considering an integration with HubSpot for commercial use - i.e. installation by mutual customers - you can learn how to get listed here.

Rate limits and accounts

HubSpot's APIs are subject to rate limiting. These limits are applied per account for custom integrations using API keys or per app per account for integrations using OAuth. You can see the specific limits detailed in our full API guidelines.

Each HubSpot account will have access to different APIs based on the products and product levels it has. You can see a detailed breakdown for which APIs are supported for each product level on our APIs by Product Tier page.

Authentication

The HubSpot APIs allow for two types of authentication: OAuth and private app access tokens. See our Authentication Overview for more details about authenticating requests.

Testing

The first thing you'll want to do is create a developer account, where you can create and manage test accounts or create an application and get started with OAuth. You can also use a private app's access token to more quickly make authenticated API calls.

Once you're ready to start testing, you should create a test account. They have access to Enterprise versions of the HubSpot Marketing, Sales, and Service Hubs, allowing you to test most of the HubSpot APIs and tools.

If you ever have questions, check out our developer forum or to leave us some feedback using the Submit Feedback button throughout the site.

Client Libraries

To make working with HubSpot's APIs easier, the community and HubSpot have created and maintained client libraries to handle a lot of the basic calls you might use. Below is a list of the ones HubSpot knows about and who supports them.

Library Language Supported by
HubSpot/hubspot-php PHP HubSpot
adimichele/hubspot-ruby Ruby Community
MadKudu/node-hubspot Node.js Community
jpetrucciani/hubspot3 Python Community
hubspot-net/HubSpot.NET C# .NET Community

In addition there are also example apps available in Node.js, PHP, and Ruby to help see how to use some of these libraries in your app.