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

# HubSpot

> Connect HubSpot CRM to auto-create accounts from deals and sync customer data

## Overview

The HubSpot integration enables automatic account creation when deals close, eliminating manual data entry and ensuring customer data stays synchronized between your CRM and Thread.

***

## Benefits

<CardGroup cols={2}>
  <Card title="Auto-Create Accounts" icon="wand-magic-sparkles">
    Deals move to "Closed Won" → Accounts created automatically
  </Card>

  <Card title="No Manual Entry" icon="ban">
    Customer data flows from HubSpot to Thread automatically
  </Card>

  <Card title="Always Up-to-Date" icon="sync">
    Changes in HubSpot sync to Thread
  </Card>

  <Card title="Rich Context" icon="database">
    CRM notes and history power AI generation
  </Card>
</CardGroup>

***

## Setup Instructions

### Prerequisites

* HubSpot Sales Hub (Professional or Enterprise recommended)
* Admin or Super Admin permissions in HubSpot
* Thread account with admin role

### Step 1: Connect OAuth

<Steps>
  <Step title="Navigate to Connectors">
    In Thread: **Connectors** → Find **HubSpot** → Click **"Connect"**
  </Step>

  <Step title="Authorize Thread">
    Redirected to HubSpot → Login if needed → Review permissions → Click **"Grant access"**

    **Permissions requested:**

    * Read deals (to fetch deal data)
    * Read companies (for company info)
    * Read contacts (for customer contacts)
    * Read notes (for context)
  </Step>

  <Step title="Confirm Connection">
    Redirected back to Thread → Green checkmark appears → Status: "Connected"
  </Step>
</Steps>

### Step 2: Configure Auto-Creation

<Steps>
  <Step title="Select Deal Stage">
    Choose which deal stage triggers account creation:

    * "Closed Won" (recommended)
    * "Contract Signed"
    * Custom stage

    **Configuration:**

    * Navigate to **Connectors** → **HubSpot** → **Settings**
    * Select deal stage from dropdown
    * Save configuration
  </Step>

  <Step title="Choose Default Template">
    Select which template to apply to auto-created accounts:

    * Standard SaaS Onboarding (default)
    * Enterprise Implementation
    * Custom templates

    **Why this matters:**
    All accounts created from HubSpot will use this template unless manually changed.
  </Step>

  <Step title="Map Custom Fields (Optional)">
    Map HubSpot deal properties to Thread account fields:

    **Default mappings:**

    ```
    HubSpot → Thread
    ├── Deal Name → Company Name
    ├── Amount → ARR
    ├── Close Date → Close Date
    ├── Primary Contact → Primary Contact
    └── Deal Owner → AE Email
    ```

    **Custom mappings:**
    Add your own field mappings for industry, company size, etc.
  </Step>

  <Step title="Test with Sample Deal">
    Create a test deal in HubSpot:

    1. Set stage to your configured trigger stage
    2. Wait 1-2 minutes
    3. Check Thread for new account
    4. Verify data mapped correctly
    5. Delete test account if successful
  </Step>

  <Step title="Enable Auto-Creation">
    Once tested:

    * Toggle **"Enable Auto-Creation"** to ON
    * All future deals reaching this stage will create accounts
    * Monitor initially for any issues
  </Step>
</Steps>

***

## How It Works

### Webhook Flow

```
1. Deal reaches "Closed Won" in HubSpot
   ↓
2. HubSpot sends webhook to Thread
   ↓
3. Thread fetches deal data via API
   ↓
4. Thread extracts:
   - Company name
   - Deal amount → ARR
   - Close date
   - Contacts
   - Deal notes
   - Custom properties
   ↓
5. Thread creates account with:
   - Mapped data
   - Selected template
   - Handoff Q&A generation (from notes)
   ↓
6. Handoff email sent to deal owner (AE)
   ↓
7. Account appears in Thread
```

***

## Use Cases

### 1. Sales-to-CS Handoff

**Workflow:**

* AE closes deal in HubSpot
* Thread creates account automatically
* AI generates handoff Q\&A from CRM notes
* AE reviews and enriches handoff
* AE assigns CSM
* CSM starts onboarding

**Time saved:** 15-20 minutes per account

### 2. Data Synchronization

**What syncs:**

* Company name changes
* Contact updates
* Deal amount adjustments
* Close date changes
* Custom field updates

**Frequency:** Real-time via webhooks

### 3. Context for AI

**CRM data powers:**

* Handoff Q\&A generation
* Email personalization
* Use case identification
* Risk detection
* Stakeholder mapping

***

## Field Mappings

### Standard Mappings

| HubSpot Field    | Thread Field    | Notes                         |
| ---------------- | --------------- | ----------------------------- |
| Deal Name        | Company Name    | Can customize                 |
| Amount           | ARR             | Converted to annual if needed |
| Close Date       | Close Date      | Date format auto-converted    |
| Company Domain   | Website         | Optional                      |
| Deal Owner Email | AE Email        | For handoff                   |
| Primary Contact  | Primary Contact | Name + email                  |

### Custom Property Mappings

Add mappings for:

* Industry (Deal property → Thread industry)
* Company size (Deal property → Thread company\_size)
* Use case (Deal property → Raw payload for AI)
* Implementation notes (Deal property → Account notes)

***

## Troubleshooting

### "Account Not Created"

**Problem:** Deal closed but no account in Thread

**Possible causes:**

1. Wrong deal stage (not the configured trigger)
2. Webhook not received
3. Missing required fields
4. Auto-creation disabled

**Solutions:**

* Verify deal stage matches configuration
* Check HubSpot webhook logs
* Ensure deal has company, amount, close date
* Check auto-creation toggle is ON
* Manually trigger if needed

### "Duplicate Accounts Created"

**Problem:** Same customer has multiple accounts

**Possible causes:**

1. Deal stage changed multiple times
2. Manual account also created
3. Company name variations

**Solutions:**

* Configure to only trigger once per deal
* Merge duplicate accounts
* Standardize company names in HubSpot

### "Missing Data in Account"

**Problem:** Account created but fields empty

**Possible causes:**

1. Fields not mapped
2. Data not in HubSpot
3. Permissions issue

**Solutions:**

* Check field mappings
* Verify data exists in HubSpot deal
* Reconnect with full permissions
* Manually populate critical fields

***

## Best Practices

<CardGroup cols={2}>
  <Card title="Clean CRM Data First" icon="broom">
    Standardize company names, formats, and fields before connecting
  </Card>

  <Card title="Test Thoroughly" icon="flask">
    Create 3-5 test deals to verify mappings work correctly
  </Card>

  <Card title="Document Workflow" icon="book">
    Train AEs on the new automated handoff process
  </Card>

  <Card title="Monitor Initially" icon="eye">
    Check first 10-20 auto-created accounts for issues
  </Card>

  <Card title="Use Deal Notes" icon="note">
    Rich notes in HubSpot → Better AI handoff generation
  </Card>

  <Card title="Standard Naming" icon="tag">
    Consistent deal/company naming improves matching
  </Card>
</CardGroup>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Create Accounts" icon="plus" href="/csm-guide/accounts/creating-accounts">
    Understand account creation process
  </Card>

  <Card title="Handoff Process" icon="handshake" href="/csm-guide/accounts/handoff-process">
    Learn how HubSpot data powers handoff
  </Card>

  <Card title="AI Generation" icon="robot" href="/csm-guide/automation/ai-generation">
    See how CRM data improves AI drafts
  </Card>

  <Card title="Slack Integration" icon="slack" href="/integrations/slack">
    Connect Slack for customer notifications
  </Card>
</CardGroup>