> ## Documentation Index
> Fetch the complete documentation index at: https://docs.userintuition.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# HubSpot

> Sync HubSpot CRM contacts, companies, and deals into User Intuition and invite them to interviews directly from HubSpot record pages.

The HubSpot integration connects your HubSpot CRM to User Intuition so the people, companies, and deals you already track in HubSpot become available as Participants for Studies. Once installed, embedded cards appear on HubSpot record pages showing sync status, and a deep link lets you invite any CRM contact to an Interview without leaving HubSpot.

***

## What the HubSpot app does

<CardGroup cols={2}>
  <Card title="Sync CRM data" icon="arrows-rotate">
    Pulls contacts, companies, and deals from your HubSpot portal into User Intuition as Participants and segments.
  </Card>

  <Card title="Embedded UI" icon="window">
    Adds a User Intuition card to contact, company, and deal record pages inside HubSpot.
  </Card>

  <Card title="One-click invite" icon="paper-plane">
    Invite a HubSpot contact to a Study Interview via a deep link from the CRM card.
  </Card>

  <Card title="Automatic provisioning" icon="user-plus">
    Creates or links a User Intuition account during the OAuth flow so installers do not need to sign up separately.
  </Card>
</CardGroup>

***

## Installation

The HubSpot app is installed through HubSpot's standard OAuth flow. Once authorized, an account record is created on the User Intuition side and the embedded cards become available across your portal.

<Steps>
  <Step title="Open the listing">
    Find **User Intuition** in the HubSpot Marketplace (or follow the install link shared by your team) and click **Install**.
  </Step>

  <Step title="Choose your portal">
    Select the HubSpot account you want to connect. You must be an admin of that portal to install third-party apps.
  </Step>

  <Step title="Authorize the requested scopes">
    HubSpot will display the scopes the app requests (read access to contacts, companies, deals, and the ability to render UI extensions on CRM records). Click **Connect app** to authorize.
  </Step>

  <Step title="Land in User Intuition">
    After OAuth completes, you will be redirected to User Intuition. If your email is already associated with a User Intuition account, you will be signed in directly. If not, an invitation is created so you can finish setting up an account using a password or Google sign-in.
  </Step>

  <Step title="First sync">
    A default **All Contacts** segment is created automatically. You can trigger the initial sync from the HubSpot record card or from the app settings page.
  </Step>
</Steps>

<Note>
  The connection between User Intuition and HubSpot is one-to-one per portal. Reinstalling on the same portal updates the existing connection rather than creating a duplicate.
</Note>

***

## CRM record cards

After installation, a **User Intuition** card appears on contact, company, and deal records in HubSpot.

The card surfaces:

* The current sync state for the connected portal (idle, syncing, completed, or error)
* A count of Participants imported into User Intuition
* A button to trigger or re-trigger a sync
* A deep link to open the contact, company, or deal in User Intuition and invite them to an Interview

<Tabs>
  <Tab title="Contact card">
    Displays the sync status for the portal and a **Send to User Intuition** action that opens the matching Participant in User Intuition. From there you can attach the contact to a Study and send an Interview invite.
  </Tab>

  <Tab title="Company card">
    Shows whether the company has been synced and links to the company's record in User Intuition, where you can see all associated Participants.
  </Tab>

  <Tab title="Deal card">
    Shows sync status for the deal and lets you jump to the deal's view in User Intuition for follow-up research with the people on that deal.
  </Tab>
</Tabs>

<Note>
  Card content is rendered with HubSpot UI Extensions, so it follows HubSpot's native look and feel and respects HubSpot's user permissions on the underlying record.
</Note>

***

## App settings page in HubSpot

Open the User Intuition app from **Settings** → **Integrations** → **Connected apps** in HubSpot. The settings page provides:

* An overview of the connected portal and its current sync status
* A button to trigger a manual full sync of contacts, companies, and deals
* High-level batch and timing settings used by the app
* A link out to your User Intuition workspace

Use this page when you want to kick off a sync portal-wide rather than from a single record.

***

## What syncs

The integration moves data **from HubSpot into User Intuition**. It does not push interview data back into HubSpot.

| HubSpot object                  | Becomes in User Intuition | Notes                                                                                         |
| ------------------------------- | ------------------------- | --------------------------------------------------------------------------------------------- |
| Contact                         | Participant               | Email, name, and phone are mapped; remaining properties are stored on the Participant record. |
| Company                         | Company / segment context | Used to group Participants and surface company context in research.                           |
| Deal                            | Deal context              | Provides additional context for Interviews tied to a sales motion.                            |
| HubSpot list (where applicable) | Segment                   | Lists become segments you can target when sending Interview invites.                          |

### Manual triggering

You can start a sync at any time from:

* The User Intuition card on any HubSpot record
* The User Intuition settings page in HubSpot's connected apps screen

A manual sync re-fetches contacts, companies, and deals in batches and updates Participants in User Intuition. Repeated syncs are idempotent — existing Participants are updated in place rather than duplicated.

### Automated triggering

The app subscribes to HubSpot webhook events for incremental updates so changes flow through without requiring a full re-sync each time:

* **Contact created** — a new Participant is created in User Intuition.
* **Contact property changed** — the matching Participant is updated.
* **App uninstalled** — triggers cleanup (see below).

For larger portals, periodic full syncs are still useful as a backstop in case any incremental events are missed.

<Warning>
  Initial syncs on large portals can take several minutes. The card will display an in-progress state and update once the sync completes.
</Warning>

***

## Inviting CRM contacts to Interviews

The CRM card includes a deep link from any HubSpot contact directly into User Intuition. Use it to:

<Steps>
  <Step title="Open the contact in HubSpot">
    Navigate to the contact's record. The User Intuition card appears in the right-hand sidebar (or wherever you have placed it in your record layout).
  </Step>

  <Step title="Open in User Intuition">
    Click the link on the User Intuition card. You are taken to the matching Participant in your User Intuition workspace.
  </Step>

  <Step title="Send an invite">
    From the Participant view, attach them to a Study and send an Interview invite. You can also send invites in bulk to a synced segment from the Studies area.
  </Step>
</Steps>

<Note>
  Bulk invites to an entire HubSpot list (or any synced segment) are sent from User Intuition rather than from inside HubSpot. The HubSpot card focuses on per-record actions.
</Note>

***

## Uninstall behavior

Uninstalling the User Intuition app from HubSpot triggers cleanup on both sides:

1. HubSpot fires the **app uninstalled** webhook to the User Intuition HubSpot service.
2. The HubSpot app calls User Intuition's external integration API to remove the connection.
3. Local OAuth tokens, sync state, and the HubSpot account record are removed.
4. Imported Participants and segments associated with the disconnected portal are detached so they no longer receive automated updates from HubSpot.

<Warning>
  Reconnecting a previously disconnected portal will start fresh — sync state and external mapping are not preserved across an uninstall. Plan a reconnection during a quiet window if you have a large portal.
</Warning>

***

## Pitfalls and known limits

<CardGroup cols={2}>
  <Card title="Admin install only">
    Installing the app requires HubSpot admin permissions on the portal. If install fails, confirm the installer's role.
  </Card>

  <Card title="Email is the bridge">
    Participants are matched to HubSpot contacts by email. Contacts without an email address sync but cannot receive Interview invites.
  </Card>

  <Card title="One portal per workspace">
    A given User Intuition workspace is connected to a single HubSpot portal. Connecting another portal requires a separate workspace.
  </Card>

  <Card title="Outbound only">
    The integration syncs data into User Intuition. Interview transcripts and outcomes are not currently written back to HubSpot records.
  </Card>

  <Card title="Webhook coverage">
    Incremental updates rely on HubSpot's contact webhooks. Property updates that are not part of the subscribed events are picked up on the next full sync.
  </Card>

  <Card title="Large portals">
    Initial sync time scales with the size of your portal. For very large CRMs, expect the first sync to run for several minutes before the card shows a completed state.
  </Card>
</CardGroup>

***

## Next steps

<CardGroup cols={2}>
  <Card title="Create a Study" icon="plus" href="/creating-a-study/overview">
    Build a Study and invite synced HubSpot contacts as Participants.
  </Card>

  <Card title="Intelligence Hub" icon="brain" href="/managing-your-study/intelligence-hub">
    Combine Interview results from synced HubSpot contacts with other Studies for cross-cutting analysis.
  </Card>
</CardGroup>