Skip to main content

Connect to HubSpot

Connect HubSpot to Retool and manage contacts, companies, deals, and tickets.

HubSpot is a customer relationship management platform for marketing, sales, and support.

What you can do with HubSpot in Retool​

After you create a HubSpot resource in Retool, you can:

  • Retrieve contacts, companies, deals, and tickets.
  • Create and update CRM records and associations.
  • Manage marketing and support workflows.
  • Build sales and support dashboards on top of HubSpot data.

Before you begin​

To connect HubSpot to Retool, you need the following:

  • HubSpot account: A private app token from your HubSpot account, or a HubSpot app if you prefer a custom OAuth app.
  • Retool permissions: Ability to create and manage resources in your organization.

Create a HubSpot resource​

Follow these steps to create a HubSpot resource in Retool.

Create a new resource​

In your Retool organization, navigate to Resources in the main navigation and click Create new → Resource. Search for HubSpot and click the HubSpot tile to begin configuration.

Configure general settings​

Specify a name and description for the resource that indicates which HubSpot account it connects to. The description provides more context to users and Assist about how to use the resource.

Example nameExample description
HubSpot (Sales)HubSpot account used by the sales team to manage deals and contacts.
HubSpot (Support)HubSpot account used to track support tickets and customer records.

API version​

Select the HubSpot API version to use. Retool defaults to the most recent version, but you can select an earlier version if your integration depends on it.

Example
v3 (2023-03-15) (DEFAULT)

Configure authentication​

HubSpot supports authenticating with OAuth 2.0, a private app token, or an API key.

Authentication methodUse cases
OAuthEach user authenticates with their own HubSpot account, or credentials are shared across all users of the resource.
Private app tokenQuick setup for a single HubSpot account using a private app. No OAuth app required in HubSpot.
API key (deprecated)Legacy authentication method. HubSpot has deprecated API keys, so use OAuth or a private app token instead.
Option A: OAuth (Recommended)

Cloud organizations use Retool's hosted OAuth app, so no app configuration is required in HubSpot.

  1. Select OAuth from the Authentication dropdown.
  2. Under Scopes, select the permissions Retool needs, such as reading or writing contacts.
  3. Optionally enable Share credentials between users so all users of the resource authenticate as a single shared HubSpot account instead of individually.
  4. Click Create resource.
  5. Click Connect with OAuth and grant permissions in HubSpot. Retool redirects you back once authorization completes.
Option B: Private app token
  1. Select Private app token from the Authentication dropdown.
  2. Create a private app in the private apps section of your HubSpot account.
  3. Paste the private app token into the Private app token field.
Example
Private app token: pat-na1-12345678-abcd-1234-abcd-1234567890ab
API key authentication is deprecated

HubSpot has deprecated API key authentication. Use OAuth or a private app token for new resources. Refer to the HubSpot Knowledge Base if you need to manage an existing API key.

Configure an existing API key
  1. Select API key from the Authentication dropdown.
  2. Paste your HubSpot API key into the HubSpot API key field.
Example
HubSpot API key: 12345678-abcd-1234-abcd-1234567890ab

Configure advanced options​

Configure optional settings available under the Advanced options section of the resource configuration form.

Outbound region​

If your organization uses outbound regions, select the region that should be used for requests to HubSpot. This controls which geographic region your requests originate from.

Test the connection​

  • Private app token or API key: Click Test connection to verify Retool can connect to HubSpot using your credentials, then click Create resource to save it.
  • OAuth: HubSpot OAuth connections don't include a Test connection button. Your HubSpot resource was already saved when you clicked Create resource during authentication. After you authorize the connection, Retool displays a Connected status once authentication succeeds.

You can now use your HubSpot resource in queries across your Retool apps and automations.

Interact with HubSpot data​

Once you've created a HubSpot resource, you can interact with HubSpot data using Retool.

Switch to the new app builder

Retool recommends using the new app builder so you can use natural language to build React-based apps using AI.

  • To use HubSpot data in the app builder, reference the resource in the prompt with @, such as @HubSpot (Sales). Refer to the data and functions documentation to learn more.
  • For classic apps, workflows, and agents, refer to the REST API queries documentation to learn how to write a resource query.

Best practices​

Follow these best practices to maintain the security of your HubSpot resource.

  • Prefer OAuth or a private app token: Avoid the deprecated API key authentication method for new resources.
  • Use a private app token with least privilege: Scope the private app to only the CRM objects and permissions the resource needs.
  • Avoid shared credentials for sensitive data: Enable Share credentials between users only when it's acceptable for all users of the resource to act as the same HubSpot account. Otherwise, let each user authenticate individually.
  • Rotate credentials regularly: Regenerate private app tokens and rotate OAuth client secrets on a regular schedule.
  • Use resource environments: Organizations on an Enterprise plan can configure multiple resource environments to maintain separate HubSpot credentials for production, staging, and development.