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

# HubSpot Integration

> Sync your HubSpot deals, companies, and contacts with Minoa

Minoa integrates with HubSpot to automatically sync your deals, companies, and contacts. Deal data flows from HubSpot into Minoa, and business case data flows back to HubSpot as custom deal properties.

## What Gets Synced

<Columns cols={3}>
  <Card title="Deals" icon="handshake">
    Become Minoa Opportunities with all key fields: name, stage, close date, value, and description.
  </Card>

  <Card title="Companies" icon="building">
    Become Minoa Accounts, linked to their associated deals.
  </Card>

  <Card title="Owners" icon="user">
    HubSpot owners are automatically matched to Minoa users by email address.
  </Card>
</Columns>

### Deal Field Mapping

| HubSpot Property                    | HubSpot Field   | Minoa Field       |
| ----------------------------------- | --------------- | ----------------- |
| `dealname`                          | Deal Name       | Opportunity Name  |
| `amount`                            | Amount          | Value             |
| `closedate`                         | Close Date      | Close Date        |
| `dealstage`                         | Deal Stage      | Stage             |
| `hs_is_closed` / `hs_is_closed_won` | Closed Won/Lost | Status            |
| `description`                       | Description     | Description       |
| `hubspot_owner_id`                  | Deal Owner      | Owner             |
| `createdate`                        | Create Date     | Created At        |
| `deal_currency_code`                | Currency        | Currency Override |

<Note>
  Deals must be associated with a company in HubSpot to sync. Deals without company associations are skipped during
  sync.
</Note>

### User Matching

Minoa automatically maps HubSpot owners to Minoa users by matching email addresses. When a deal syncs:

* If the deal owner's email matches a Minoa user, that user becomes the opportunity owner
* If no match is found, the deal still syncs—you can configure a fallback owner or manually assign it

## Setting Up the Integration

### Prerequisites

* Admin access to your HubSpot account
* Admin or Integration permissions in Minoa

### Connect HubSpot

<Steps>
  <Step title="Go to Integrations">In Minoa, navigate to **Settings** → **Integrations**.</Step>
  <Step title="Select HubSpot">Click **Connect** next to the HubSpot integration.</Step>

  <Step title="Authorize">
    You'll be redirected to HubSpot to grant Minoa access. Sign in and click **Connect app**.
  </Step>

  <Step title="Done!">Return to Minoa—your deals will start syncing within minutes.</Step>
</Steps>

<Check>Once connected, Minoa syncs automatically every 5 minutes. No manual action required.</Check>

## Configuring Deal Co-Owners

HubSpot deals often have multiple people working on them. Minoa can pull in a co-owner from a custom deal field—useful if your team uses a "Sales Engineer" or "Technical Contact" field in HubSpot.

<Steps>
  <Step title="Open Integration Settings">Go to **Settings** → **Integrations** → **HubSpot** → **Configure**.</Step>

  <Step title="Select a Co-Owner Field">
    Choose from the dropdown of user-reference fields available on your HubSpot deals.
  </Step>

  <Step title="Save">Click **Save**. Future syncs will populate the co-owner on matching opportunities.</Step>
</Steps>

<Tip>
  Good candidates for co-owner fields include "Technical Owner," "SE Assigned," or any custom user field your team
  uses.
</Tip>

## Sync Behavior (HubSpot → Minoa)

### Automatic Sync

* Syncs run every **5 minutes**
* Only deals modified since the last sync are processed (incremental sync)
* Large datasets are processed in batches across multiple sync runs

### Manual Sync

Need data immediately? You can trigger a sync from **Settings** → **Integrations** → **HubSpot** → **Sync Now**.

### What Happens During Sync

1. **Deals** are fetched with their associated companies
2. **Companies** are created as Minoa Accounts (or updated if they exist)
3. **Deals** become Minoa Opportunities linked to those accounts
4. **User mapping** matches HubSpot owners to Minoa users by email

<Warning>
  Deleting a deal in HubSpot does not automatically delete the opportunity in Minoa. This is intentional—it protects
  your business case work from accidental CRM changes.
</Warning>

## What Gets Written Back

When you build a business case in Minoa, selected data automatically syncs to HubSpot as custom properties on the associated Deal. These properties are grouped under a "Minoa" section on the Deal and are only populated for deals that have a Minoa business case. For all other deals, the fields remain empty.

| HubSpot Property ID                 | Description            | Value                                     | Format                    |
| ----------------------------------- | ---------------------- | ----------------------------------------- | ------------------------- |
| `business_case_name`                | Business Case Name     | BC name (falls back to opportunity name)  | Text                      |
| `total_annual_benefit_minoa`        | Total Benefit          | Total benefit for contract duration       | Number (2 decimal places) |
| `roi_minoa`                         | ROI                    | ROI multiple                              | Number (1 decimal place)  |
| `summary_minoa`                     | Summary                | Primary scenario description              | Text                      |
| `use_cases_minoa`                   | Use Cases              | Primary scenario use case names           | Comma-separated text      |
| `external_collaborator_count_minoa` | External Collaborators | Count of accepted external collaborators  | Integer                   |
| `minoa_link_minoa`                  | Minoa Link             | Direct link to the business case in Minoa | URL                       |
| `last_modified_minoa`               | Last Modified          | Date of last sync                         | Date (YYYY-MM-DD)         |

<Note>
  Your HubSpot admin must create the custom deal properties before business case data can sync. If you are connecting
  HubSpot for the first time, write permissions are included automatically. Existing integrations will need to
  re-authenticate to grant the additional write scope.
</Note>

## Sync Direction

<Info>
  The HubSpot integration supports **two-way sync for business cases**: deal data flows from HubSpot into Minoa, and Minoa
  business case data flows back to HubSpot as custom deal properties.
</Info>

This means:

* New deals in HubSpot → appear in Minoa
* Updated deals in HubSpot → update in Minoa
* Minoa business cases → sync to HubSpot deal properties
* Other changes in Minoa (like currency or opportunity name) → do not sync to HubSpot

HubSpot remains the source of truth for core deal data. Minoa only writes business case metrics to custom properties.

## Troubleshooting

<AccordionGroup>
  <Accordion title="My deals aren't syncing">
    **Check company associations.** Deals must be linked to a company in HubSpot. Go to your deal in HubSpot and ensure it has an associated company.

    **Wait for the next sync.** Syncs run every 5 minutes. Check back shortly or trigger a manual sync.
  </Accordion>

  <Accordion title="Deal owners aren't mapping correctly">
    User mapping relies on **email matching**. Make sure:

    * The HubSpot owner's email matches their Minoa user email exactly
    * The Minoa user has been added to your workspace

    Check **Settings** → **Team** to see your Minoa users.
  </Accordion>

  <Accordion title="I see 'Authentication expired' errors">
    OAuth tokens occasionally expire. To reconnect:

    1. Go to **Settings** → **Integrations** → **HubSpot**
    2. Click **Disconnect**
    3. Click **Connect** and re-authorize

    This refreshes your authentication without affecting historical data.
  </Accordion>

  <Accordion title="Sync seems slow for my large dataset">
    Minoa processes HubSpot data in batches to stay within API limits. For large HubSpot accounts (10,000+ deals), the initial sync may take several sync cycles to complete. Incremental syncs after that are much faster.
  </Accordion>
</AccordionGroup>

## Disconnecting the Integration

If you need to disconnect HubSpot:

1. Go to **Settings** → **Integrations** → **HubSpot**
2. Click **Disconnect**
3. Confirm the action

<Warning>
  Disconnecting stops all syncing. Your existing Minoa opportunities and accounts remain—they just won't receive
  updates from HubSpot.
</Warning>

## Security & Permissions

Minoa requests the following HubSpot scopes:

* **crm.objects.companies.read** — Read companies and their properties
* **crm.objects.contacts.read** — Read contacts for user matching
* **crm.objects.deals.read** — Read deals and their properties
* **crm.objects.deals.write** — Write business case data to deal properties
* **crm.objects.owners.read** — Read owner information for user mapping
* **crm.schemas.deals.read** — Read deal property schemas (for co-owner field configuration)
* **oauth** — OAuth token management

Business case data is written to custom properties on the Deal object. We do not modify your existing standard deal fields, contacts, or companies.