Skip to content
threada Docs

HubSpot setup and support

Threada for HubSpot is the planned HubSpot App Marketplace integration for turning governed Threada work into reviewable HubSpot CRM contact operations. The first reviewable package is intentionally narrow: it supports an OAuth install path, HubSpot account mapping, setup-required feedback, governed contact create or update proposals, and safe links back to Threada. It does not perform unmanaged HubSpot writes, update deals or tickets, create CRM cards, write timeline events, create workflow actions, subscribe to webhooks, request marketing or sensitive data scopes, or act as a generic HubSpot AI agent.

This guide supports private HubSpot reviewer testing once a Marketplace review package is available and public HubSpot users after HubSpot approves and lists the app. Until the HubSpot App Marketplace app is approved, existing governed HubSpot action payloads remain tenant-specific integration work and should not be treated as the public HubSpot App Marketplace app.

Requirements

Before installing or testing the HubSpot integration, make sure you have:

  • An active Threada tenant.
  • Studio or Admin access for the Threada workspace that should create or update HubSpot contacts.
  • A HubSpot production or reviewer-safe test account prepared for the reviewed package.
  • A HubSpot user who can install Marketplace apps, such as a Super Admin or a user with HubSpot Marketplace access and the scope groups requested by the app.
  • Permission to authorize the public Threada OAuth app for the target HubSpot account.
  • A configured HubSpot account mapping in Threada for the reviewed package.
  • For private reviewer testing, the exact app install URL, HubSpot account, reviewer user, setup notes, expected contact fields, and cleanup instructions provided through the approved HubSpot review channel.

Do not use production customer HubSpot accounts, customer contacts, CRM exports, OAuth tokens, cookies, developer keys, personal access keys, or screenshots containing private tenant data for Marketplace review evidence.

Install the app

After HubSpot approves the public listing, open Threada from HubSpot App Marketplace. During private review, use only the HubSpot install path or review link provided in the approved review notes.

  1. Open the HubSpot Marketplace listing or approved review install URL for Threada.
  2. Review the app name, company name, pricing information, shared-data disclosure, privacy, terms, and support links.
  3. Start the HubSpot OAuth authorization flow.
  4. Select the HubSpot account prepared for review.
  5. Review the requested scopes. V1 should request only crm.objects.contacts.read and crm.objects.contacts.write.
  6. Connect the app.
  7. Threada validates the OAuth state, exchanges the code, introspects the token through HubSpot OAuth 2026-03, and binds the install to the selected HubSpot portal hub_id.
  8. Confirm HubSpot shows Threada in connected apps and Threada shows the HubSpot account as connected.

If the authorization flow fails, stop and fix the Marketplace app configuration, OAuth redirect URL, client ID, state validation, production URL, scope selection, or reviewer account setup before continuing.

HubSpot listings that change after October 26, 2026 will need the updated Marketplace install flow with an OAuth option that does not require a separate partner sign-in. Threada should opt into that flow when preparing the public listing unless HubSpot reviewer guidance requires a different reviewed path.

Connect HubSpot to Threada

The HubSpot integration must be mapped to a Threada tenant and receiving workspace before approved proposals can create or update contacts.

  1. Sign in to Threada Studio with an admin or builder account.
  2. Open the workspace or pack that should write HubSpot contacts.
  3. Open the integration or channel setup area for HubSpot.
  4. Bind the authorized HubSpot account to the Threada workspace or pack.
  5. Select the receiving queue, approval policy, duplicate-matching rule, and contact field allowlist.
  6. Save the mapping and run the connection test if one is available.

If the reviewed build does not yet expose a self-service Studio mapping UI, follow the reviewer setup notes for the exact HubSpot account, Threada workspace, queue, allowlisted contact fields, and cleanup steps prepared for review. Do not infer tenant mappings from account names, user emails, contact emails, or contact titles alone.

Create or update a governed HubSpot contact

Create or update a HubSpot contact only through a governed Threada action proposal.

  1. Open or create the prepared Threada WorkItem or lead record.
  2. Create a HubSpot contact upsert proposal using the reviewed workflow.
  3. Confirm the proposal shows the email, first name, last name, phone, company, title, and other allowlisted properties that will be sent to HubSpot.
  4. Approve the proposal when the configured policy allows it.
  5. Confirm Threada shows a succeeded state and records the HubSpot contact reference.
  6. Open the contact in HubSpot and confirm the fields match the approved proposal.

Deal upsert, ticket update, CRM cards, timeline events, workflow actions, webhook subscriptions, and packaged HubSpot knowledge sync are follow-on capabilities. They must not be marketed until the public app proves the required scopes, field allowlists, tenant mapping, reviewer flow, audit behavior, and HubSpot review evidence.

Setup-required responses

If the integration is authorized but not connected to a Threada tenant or workspace, Threada should show a setup-required response instead of silently dropping the request or attempting an unauthenticated HubSpot write.

Common setup issues:

  • The HubSpot account is not mapped in Threada.
  • The mapped Threada workspace or pack was disabled.
  • The receiving queue, duplicate-matching rule, or approval policy is missing.
  • Required contact field allowlists are incomplete.
  • The Marketplace package still uses placeholder app ID, OAuth client ID, redirect URL, install URL, support, privacy, terms, or setup identifiers.
  • The app points to a development, staging, sandbox, ngrok, or otherwise non-production URL.
  • OAuth state validation, token exchange, refresh, revocation, disconnect, or uninstall handling failed.
  • The reviewed app has not produced the three active unique production installs required for HubSpot Marketplace listing.

For review builds, include the HubSpot account, Threada workspace, proposal ID, approximate test time, and sanitized error text in support requests. Do not send OAuth client secrets, refresh tokens, access tokens, cookies, developer keys, personal access keys, CRM exports, contact lists, or private contact content.

Disconnect or uninstall

To stop creating or updating HubSpot contacts:

  1. In Threada Studio, disable or remove the HubSpot mapping for the workspace, pack, or account.
  2. Revoke or uninstall the Threada app in HubSpot if the account should no longer be connected.
  3. Run the reviewed test workflow and confirm Threada returns setup-required feedback rather than creating or updating a contact.

Disconnecting the integration stops future HubSpot contact writes. Existing WorkItems, proposals, approvals, HubSpot contact references, and audit events remain available in Threada according to the tenant retention policy.

Data handling

For v1, Threada stores the HubSpot account mapping, OAuth authorization metadata, the authorized portal ID and optional portal domain returned by HubSpot token introspection, HubSpot contact identifiers returned by HubSpot, and the contact fields required for approved contact creation or update. Threada uses this data only to bind the install to the correct HubSpot portal, create or update governed HubSpot contacts, show setup and execution status, support disconnect, and maintain an auditable record.

The public install path must use HubSpot OAuth as the sole authorization method for multi-account Marketplace distribution. Do not use private app tokens, API keys, developer keys, personal access keys, or manually provisioned tenant secrets as the public Marketplace install path. The shared-data disclosure in the listing must match the selected scopes and the v1 contact data flow.

If a future version adds deals, tickets, CRM cards, timeline events, workflow actions, webhook subscriptions, marketing objects, sensitive data scopes, or packaged knowledge sync, Threada must update this guide, explain the exact data use, complete the required security and privacy review, and submit the updated app for HubSpot review before marketing the new capability.

Support

For setup help, contact support@threada.ai. For privacy or deletion requests, contact privacy@threada.ai. To report a security issue, contact security@threada.ai.

Support requests for the HubSpot integration receive a response within 2 business days. Include the Threada tenant, HubSpot account, proposal or contact reference when available, app version when known, approximate test time, and sanitized error text. Do not send secrets, tokens, cookies, CRM exports, contact lists, customer exports, or private contact content.