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

# HubSpot Integration

> Connect HubSpot to sync companies, contacts, deals, and custom fields into Statisfy.

### Connect HubSpot with Statisfy

The HubSpot integration syncs your CRM data into Statisfy, including companies (accounts), contacts, deals (opportunities), and custom fields. This enables unified customer intelligence across your sales and customer success workflows.

**Prerequisites:**

* **Admin access** to both HubSpot and Statisfy
* HubSpot account with API access enabled

### What Data Gets Synced

| HubSpot Object | Statisfy Object | Data Included                                            |
| -------------- | --------------- | -------------------------------------------------------- |
| Companies      | Accounts        | Name, website, owners, custom fields, ARR, renewal dates |
| Contacts       | People          | Name, email, job title, buying role                      |
| Deals          | Opportunities   | Deal name, amount, stage, close date, owner              |
| Owners         | Users           | Name, email (for owner field mapping)                    |

### Steps to Connect

1. **Log in to Statisfy.**

2. Navigate to: **Integrations → Admin Apps → HubSpot → Connect**

3. Click **Connect** to initiate the OAuth flow.

4. You'll be redirected to HubSpot. Sign in and authorize Statisfy to access your HubSpot data.

5. After successful authentication, the HubSpot app will appear as **Connected** in Statisfy.

6. Open **Integrations → HubSpot → Settings** to configure what syncs — no support ticket needed. The settings page has three sections:

   * **Account Filtering** (required) — which companies to sync, and whether they come in as Customers, Prospects, or Partners
   * **Owner Mapping** — which HubSpot properties identify each owner (CSM, Account Owner, and so on)
   * **ARR & Renewal** — where annual recurring revenue and renewal dates come from: a company property, a calculation across associated records (deals, line items, products, or tickets), or skip

   Property pickers are loaded from your live HubSpot account, conditions are validated as you build them, and every save is versioned (see [Integration Concepts](/integrations/self_serve_configuration)).

### Configuration Options

<Accordion title="Account Filters">
  Configure which HubSpot companies sync to Statisfy using filters:

  **Single Account Type:**
  Sync all companies matching specific criteria as "Customers":

  * Filter by lifecycle stage (e.g., `lifecyclestage = customer`)
  * Filter by custom status field (e.g., `customer_status = Active`)

  **Multiple Account Types:**
  Sync different company types with separate filters:

  * **Customers**: Companies with `type = Customer`
  * **Prospects**: Companies with `type = Prospect` and `lifecyclestage = opportunity`
  * **Partners**: Companies with `type = Partner`

  Each account type can have its own filter criteria, and companies are classified based on which filter they match first.
</Accordion>

<Accordion title="Owner Mappings">
  Map HubSpot owner fields to Statisfy owner types:

  | HubSpot Field               | Statisfy Owner Type |
  | --------------------------- | ------------------- |
  | `hubspot_owner_id`          | Sales Owner         |
  | `csm`                       | CSM                 |
  | `technical_account_manager` | TAM                 |
  | `onboarding_manager`        | Onboarding Manager  |

  Owner information is automatically resolved from HubSpot user records.
</Accordion>

<Accordion title="Revenue & Renewal Fields">
  Map your HubSpot fields to Statisfy's standard fields:

  * **ARR Field**: The HubSpot property containing annual recurring revenue
  * **Renewal Date Field**: The HubSpot property containing the next renewal date

  These mappings ensure accurate revenue tracking and renewal forecasting.
</Accordion>

### Filtering on enum (dropdown) fields

<Warning>
  **Filters must use the property's *internal value*, not the display label.** HubSpot enum/dropdown options have a label (what users see in the UI) and an internal value (what the API matches on) — these are often different. If a filter uses the label, the HubSpot Search API silently returns zero records, and any field that depends on it (ARR, renewal date, etc.) will appear empty on accounts.
</Warning>

The same rule applies to `propertyName`: it must be the property's **internal name** (e.g., `deal_lifecycle_stage`), not its display name (e.g., "Contract Status").

**Common gotcha:** Legacy properties that were converted from boolean to enum often retain option values like `"true"` / `"false"` even when their labels read as something readable like "Active Contract" / "Inactive Contract".

**How to find the internal value:**

* In HubSpot, go to **Settings → Properties → \[object] properties**, click into the property, and inspect each option — the internal value is shown alongside the label (sometimes only visible when editing the option).
* Or call the HubSpot API: `GET /crm/v3/properties/{object}/{propertyName}` returns each option's `value` and `label`.

**Symptom of getting it wrong:** the filter matches zero records, and any field that depends on it (e.g., ARR, renewal date) shows up empty on accounts — with no error.

**Example:**

```json theme={null}
// ❌ Wrong — uses the display label
{
  "propertyName": "deal_lifecycle_stage",
  "operator": "EQ",
  "value": "Active Contract"
}

// ✅ Correct — uses the internal option value
{
  "propertyName": "deal_lifecycle_stage",
  "operator": "EQ",
  "value": "true"
}
```

The `"true"` value above looks unusual because the property was originally a boolean before being converted to an enum — a common HubSpot pattern.

### Custom Fields

Custom fields from HubSpot are automatically synced to Statisfy:

* **Text fields** → Text custom fields
* **Number fields** → Numeric or currency fields (based on configuration)
* **Date fields** → Date custom fields
* **Dropdown/Select fields** → Text or multi-select fields
* **Owner lookup fields** → User lookup fields

Field validation rules (max length, decimal places) are also imported to maintain data consistency.

### Sync Behavior

<Note>
  Initial sync may take some time depending on the volume of data in your HubSpot account.
</Note>

* **Incremental sync**: After initial sync, only changed records are updated
* **Bi-directional sync**: Contact support to enable write-back to HubSpot
* **Churn detection**: Customers that no longer match filters are automatically marked as churned
* **Soft deletion**: Non-customer accounts (prospects, partners) are soft-deleted when they no longer match filters

### Troubleshooting

<Accordion title="Companies not syncing">
  **Check your filters:**

  * Ensure companies match at least one configured filter
  * Verify the filter field values are correct in HubSpot

  **Check permissions:**

  * Ensure the connected HubSpot user has access to view companies
</Accordion>

<Accordion title="Missing contacts">
  Contacts are synced via their association to companies. Ensure contacts are properly associated with companies in HubSpot.
</Accordion>

<Accordion title="Owner fields showing as empty">
  * Verify the owner field is populated in HubSpot
  * Check that the HubSpot user exists and has an email address
  * Check the **Owner Mapping** section under **Integrations → HubSpot → Settings** — the property mapped to each owner type must be the one your HubSpot records actually use
</Accordion>

### Need Help?

For configuration assistance or troubleshooting, contact [support@statisfy.com](mailto:support@statisfy.com).