Skip to main content

HubSpot

Connect your Gravity Rail workspace to HubSpot CRM. The integration links workspace members to HubSpot contacts and gives your agents the ability to search and read HubSpot records, and to create and update contacts, during conversations. In a test conversation an agent's create or update is not sent to HubSpot.

The integration uses OAuth 2.0 with encrypted token storage. One HubSpot account connects to one workspace. In most cases you connect through the Gravity Rail HubSpot app, so you don't need to create an app in HubSpot.

Prerequisites​

You need a HubSpot user who can install apps in your HubSpot account (usually a Super Admin). When the connection page shows Connect HubSpot, you do not need to create a HubSpot app. If the page shows a three-step setup guide instead, follow Use your own HubSpot app.

Connect HubSpot​

  1. Open Connections → Manage, choose Directory, find HubSpot and open it. Once HubSpot is connected, its page is also listed under Connections → Apps in the sidebar.
  2. Open Setup and click Connect HubSpot. Your browser goes to HubSpot.
  3. Choose the HubSpot account to connect, review the permissions, and click Connect app.
  4. HubSpot returns you to Gravity Rail. The status changes to Connected, and your HubSpot Portal ID appears in the connection header on every tab.

Gravity Rail asks HubSpot for these permissions:

  • Connect to your HubSpot account (oauth)
  • Read and write contact records (crm.objects.contacts.read / crm.objects.contacts.write)
  • Read and write company records (crm.objects.companies.read / crm.objects.companies.write)
  • Read and write deal records (crm.objects.deals.read / crm.objects.deals.write)

It also asks for four optional permissions, which HubSpot may leave out:

  • Read lists and segments (crm.lists.read), so you can import Members from a HubSpot segment. Without it, importing by segment asks you to reconnect HubSpot; importing by contact property or by file still works.
  • Read owners (crm.objects.owners.read), so Contact owners can add each HubSpot contact owner as a Member and link contacts to their owner.
  • Read forms (forms), so you can sync HubSpot form submissions into a Data Type.
  • Read Meetings booking links (scheduler.meetings.meeting-link.read), so you can pick a booking link to sync bookings into a Data Type.

Enable the optional permissions you need when you approve the connection in HubSpot. If access is still missing after reconnecting, an admin must allow it under Connected Apps → Approved apps → Manage access → Data Permissions, then authorize again. Declaring a scope in the app and requesting it does not ensure HubSpot grants it. See HubSpot's app access guide.

Use your own HubSpot app (optional)​

Most workspaces should use Connect HubSpot above. If your organization must use its own HubSpot app, click Advanced: use your own HubSpot app on the Setup tab. The tab then shows a three-step guide: create the app, add its credentials, authorize.

HubSpot is retiring the private apps and developer apps you used to create from the HubSpot settings pages: no new developer apps since June 23, 2026, and no new private apps after October 26, 2026 (HubSpot accounts created since September 28, 2026 already can't create them). A new app must be built on HubSpot's developer platform with the HubSpot CLI -- see HubSpot's create an app guide. An app that you created before these changes continues to work.

  1. Give your app the Redirect URL shown in step 1 of the guide, and the scopes listed above, including oauth. Add crm.lists.read, crm.objects.owners.read, forms and scheduler.meetings.meeting-link.read as optional scopes, not required ones: Gravity Rail requests them as optional, and HubSpot rejects an authorization request that names a scope your app does not declare. The URL has this form, and it must match exactly:

    https://api.gravityrail.com/api/v2/w/{your-workspace-uuid}/app-connections/hubspot/oauth/callback

    On the app's Auth tab, HubSpot shows a Client ID and a Client Secret.

  2. Click Enter credentials in the guide, enter the Client ID and Client Secret, and save.

  3. Click Connect HubSpot and approve access.

If importing Members from a HubSpot segment says the connection is not allowed to read lists or segments, your app's authorization does not include crm.lists.read. Add crm.lists.read to your app's optional scopes, then authorize again: run gr hubspot authorize -w <workspace-uuid> --allow-write and open the authorizeUrl it prints. Enable the optional permission for reading lists and segments when you approve access.

Move to the Gravity Rail HubSpot app​

A connection set up with your own HubSpot app can move to the Gravity Rail app. Open the Setup tab, click Use the Gravity Rail HubSpot app instead, and confirm. Gravity Rail removes your app's Client ID and Client Secret. Your sync settings and Member links stay.

If HubSpot then asks you to approve access, sign in to the same HubSpot account that is connected now. Member links point at that account's contacts. Once the connection shows Connected again, you can delete your own HubSpot app.

Set up from the command line (optional)​

The same steps are available through the Gravity Rail CLI. Run gr hubspot install --help for the full sequence.

With the Gravity Rail HubSpot app, one command does it all. It prints an authorizeUrl; open it in a browser to grant access:

gr hubspot connect -w <workspace-uuid> --allow-write

With your own HubSpot app, go step by step:

# 1. Create the connection. The response shows "platformAppAvailable".
gr hubspot install -w <workspace-uuid> --allow-write

# 2. Only with your own app (or when "platformAppAvailable" is false):
# save its credentials. Skip this step for the Gravity Rail app.
gr hubspot configure -w <workspace-uuid> --allow-write \
-d '{"clientId":"...","clientSecret":"..."}'

# 3. Authorize. Open the returned "authorizeUrl" in a browser to grant access.
gr hubspot authorize -w <workspace-uuid> --allow-write

# Check progress at any time.
gr hubspot status -w <workspace-uuid>

Use the connection page​

The header keeps the connection status and Portal ID visible on every tab. After a successful sync, Last synced opens that run on Sync. The three-dot menu holds Reconnect and Disconnect when available.

  • Overview shows sync success rate and Linked, Unlinked, Unlinkable and Errored Member counts. Unlinkable counts Members that lack every identity field the match strategy reads, so a sync cannot link them. A strategy that matches another way shows 0.
  • Members links or imports HubSpot contacts.
  • Settings chooses what to sync and saves mappings.
  • Sync starts syncs and shows run history.
  • Data shows the connection's Data Types, record counts and field map.
  • Setup connects the account and shows app credentials, callback URL and permissions.

On Members, Link Members offers an automatic matching pass or Review matches to choose records yourself. Use Import Members when you need to create Members from HubSpot contacts. See Link Existing Members for the matching and confirmation steps.

On Settings, changes stay in a draft. The floating bar offers Save changes and Discard after an edit. If you try to leave, choose Stay to keep editing or Discard and leave to drop the draft. A disabled Save button explains what is incomplete. See Save or Discard Settings for details.

Connection states​

StateBadgeMeaning
Setup in progressSecondaryYour own app is selected, but its credentials haven't been entered yet
Awaiting OAuthSecondaryThe connection is ready, but HubSpot authorization hasn't been completed yet
ConnectedGreenOAuth is complete and the API connection is active
ErrorRedSomething went wrong (see Troubleshooting)
Not ConnectedSecondaryNo connection has been configured

Troubleshooting​

The page shows a three-step setup guide, not "Connect HubSpot"

The Gravity Rail HubSpot app isn't available for your workspace yet, or your connection already uses your own app. If the guide shows Use the Gravity Rail HubSpot app instead, your connection can move to the Gravity Rail app: see Move to the Gravity Rail HubSpot app. Otherwise follow Use your own HubSpot app, or contact Gravity Rail support.

HubSpot says you don't have permission to install the app

The HubSpot user must be able to install apps, and must have access to contacts, companies and deals. Ask a HubSpot Super Admin to click Connect HubSpot.

redirect_uri_mismatch error during OAuth (your own app only)

The Redirect URL registered on your HubSpot app doesn't match the one Gravity Rail uses. Copy the OAuth Callback URL from the guide (step 1) or, once connected, from the Setup tab, and update your app to use that exact URL.

Connection stuck on "Awaiting OAuth"

The OAuth flow didn't complete. Click Connect HubSpot to start it again (the OAuth state is valid for 10 minutes).

Connection shows "Error" or "Reconnect required"

The access may have been revoked, or a required scope is missing. Click Reconnect in the connection header to authorize again. For a connected account, open the header’s three-dot menu and choose Reconnect. Disconnect is in the same menu and asks for confirmation; initial authorization and app credentials are on Setup.

  • Channels -- Overview of all communication channels and integrations
  • HubSpot Sync -- Field mapping, sync rules, and data sync configuration