Building apps overview

To build a custom integration using HubSpot’s APIs and extensions, you can build apps that can then be installed in HubSpot accounts. Depending on what you want to build, HubSpot offers several types of apps and extensions depending on your needs. Below, learn more about the types of apps and extensions you can build with HubSpot, how to get started building them, and how to manage them in HubSpot.

Types of apps

Apps are packages that can be installed in a HubSpot account. You can choose from the following app types, which enable you to build different types of integrations.

In addition to using apps to make API calls, view the reference table below for a quick overview of which extensions can be built with which types of apps.

Private apps

Private apps can be installed in a single HubSpot account, and are best suited for one-off scripts or single-purpose extensions. For example, you might build a private app for your HubSpot account to:

  • Create a new custom object through the API.
  • Import CRM records from a CSV file.
  • Authenticate API requests in custom automation actions and chat bots.
In general, private apps are simpler to implement than public apps. Private apps authenticate with access tokens and cannot be listed on the HubSpot App Marketplace. Learn more about when to build private apps.

If this type of app fits your needs, get started creating a private app in your HubSpot account.

Private apps in projects (BETA)

Private apps built with projects enable you to create UI extensions for CRM records. The difference when building a private app through this method is that projects only support creating UI extensions, which private apps outside of projects cannot create. You must be enrolled in the projects beta to build private apps this way.

If this type of app fits your needs, you can get started creating a private app and project using the CLI.

Public apps

Public apps can be installed in multiple accounts. In addition to the types of extensions you can build with a private app, public apps support advanced functionality, such as:

  • Subscribing to account-wide events using the webhooks API  
  • Creating custom timeline events on CRM records using the timeline events API 
  • Creating custom app settings pages in HubSpot. 

Public apps authenticate with OAuth and can be listed on the HubSpot App Marketplace. Learn more about when to build public apps.

If this type of app fits your needs, get started creating a public app in your app developer account.

Supported extensions by app type

App type Supported extensions
Private app
Public app
Private apps in projects (BETA) UI extensions

* The custom cards you can build with non-project private apps are different from the cards you can create as UI extensions. UI extensions offer more advanced functionality and customizable components.

Types of accounts for app development

While app developer and test accounts work together, they each serve a distinct purpose.

  • Developer accounts are where you can build and list apps.
  • Test accounts allow you to try our APIs and test the apps you’re building without impacting data from a real HubSpot account. This is separate from a sandbox account that you can create within standard HubSpot accounts.

Learn more about HubSpot's account types.


If you want to build a custom integration with a single HubSpot account, you can create a private app and use its access token to authenticate API calls, or you can use OAuth. Any app designed for installation by multiple HubSpot accounts or listing on the App Marketplace must use OAuth. 

Please note: as of November 30, 2022, HubSpot API Keys are being deprecated and are no longer supported. Continued use of HubSpot API Keys is a security risk to your account and data. During this deprecation phase, HubSpot may deactivate your key at any time.

You should instead authenticate using a private app access token or OAuth. Learn more about this change and how to migrate an API key integration to use a private app instead.

If you want to subscribe to webhooks or set up OAuth for your app, you should create a developer account. With developer accounts, you can also list your apps on the App Marketplace or create a test account.

Developer account API keys

To manage your app settings through the API, you can use a developer API key. This is separate from standard API keys, which are being deprecated. Developer API keys can be used for managing subscriptions for the Webhooks API and creating or updating event types for the timeline events feature. All other API calls need to be made using a private app access token or OAuth.

To access your app developer account API key:

  • In your app developer account, navigate to Apps in the top navigation bar.
  • In the upper right, click Get HubSpot API key.
  • In the dialog box, click Show key. The key will be revealed, and you can then click Copy next tot he key.
  • You can also deactivate the previous API key and generate a new one by clicking Regenerate key.


Manage apps in HubSpot

Find an app's ID

While developing your app, you can find your app ID in two places: 

  • Below the name of your app in the Apps dashboard of your developer account:
Screen Shot 2020-01-15 at 2
  • In your app’s Auth Settings:



Monitor app behavior

HubSpot logs all requests made to or from a connected app, including incoming requests using an OAuth access token or outgoing requests for webhooks or CRM cards. 

To view this request log:

  • In your app developer account, navigate to Apps in the main navigation bar.
  • Click the name of the app.
  • In the left sidebar menu, navigate to Monitoring


  • Use the tabs to view different types of requests being made to or from the app. While viewing these logs, you can click an individual request to view more information about it, including:
    • for successful requests, the request method, path, and time of request.
    • for unsuccessful requests, additional error information such as response headers and body.


Below, learn more about each tab of the Monitoring page.

View API calls

The API call log will list all requests made to your app using an OAuth access token. It can be filtered by HTTP method, response code, timeframe, or request URL.


View webhook requests

The Webhooks tab shows HubSpot requests for any of your app’s webhook subscriptions. Filter by response (including timeouts and connection failures), status (success, will retry, or failure), subscription type, time frame, attempt, batch, event, or account ID. 

Please note: the attempt ID is a combination of the subscriptionId, eventId, and attemptNumber from a specific request.


View CRM extension requests

You’ll find HubSpot requests for your app’s CRM cards in the CRM extensions tab. Filter by extension object type, CRM object type (contact, company, ticket, or deal), error or warning type, time frame, request ID, or CRM record ID (i.e. a specific contact ID).

Delete a developer account

You can delete app developer accounts if they don’t contain apps with installations or active marketplace listings. If your account has apps with installations or active marketplace listings and you’d like to delete your account, please reach out to support for assistance.

Once you delete your account, you will no longer be able to access that account. If you can switch between multiple HubSpot accounts, the deleted account will no longer appear.

In your HubSpot API developer account, click your account name in the top right corner, then click on Account.


Click Delete account. If your account has any apps with installations or active marketplace listings this button will be disabled.


In the dialog box, enter your account ID then click Delete developer account


Related docs

Creating and installing apps

Create a developer account

Create a test account

Set up a HubSpot sandbox account (BETA)

Was this article helpful?
This form is used for documentation feedback only. Learn how to get help with HubSpot.