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

# HubSpot

> Connect Veles to HubSpot: authentication, company sync, deal linking, and pushing quotes back to HubSpot.

Veles integrates with HubSpot natively through OAuth. No package installation or custom objects required -- Veles connects directly to HubSpot's API to sync deal, company, and contact data. The integration is managed from **Admin Console > Integrations > HubSpot**, which contains two configuration tabs covering connection setup and company sync.

This page covers the full HubSpot setup. For a quick overview of CRM connection, see [Connect your CRM](/get-started/quickstart/connect-your-crm).

## Prerequisites

Before connecting, ensure you have:

* **HubSpot admin or super admin credentials** -- the user who authorizes the connection determines the API access level.
* **Veles admin access** -- only Veles admins can configure integrations.
* **A HubSpot plan that supports API access** -- Professional or Enterprise for most features.

## Setup

<Steps>
  <Step title="Navigate to the integration">
    In Veles, go to **Admin Console > Integrations > HubSpot**.
  </Step>

  <Step title="Connect to HubSpot">
    Click **Connect to HubSpot**. You'll be redirected to HubSpot's authorization page.
  </Step>

  <Step title="Authorize Veles">
    Log in with your HubSpot admin credentials and authorize Veles to access your HubSpot account.
  </Step>

  <Step title="Verify the connection">
    Once authorized, you'll be redirected back to Veles. The integration status will show **Configured** with a green badge.
  </Step>
</Steps>

<Info>
  Use a dedicated HubSpot user for the integration connection rather than a personal login. If the authenticated user's HubSpot credentials are revoked or their account is deactivated, the connection will break.
</Info>

## General

The **General** tab manages the core connection between Veles and your HubSpot account.

Once authenticated, the General tab displays:

| Field            | Description                                                    |
| ---------------- | -------------------------------------------------------------- |
| **Connected as** | The HubSpot user who authorized the connection.                |
| **Status**       | Shows **Configured** when the connection is live and active.   |
| **Primary CRM**  | Indicates whether HubSpot is set as your primary CRM in Veles. |

From this tab you can:

* **Enable / Disable** -- toggle the integration on or off without disconnecting.
* **Make Primary CRM** -- set HubSpot as your default CRM. This controls which CRM context appears in the quote builder, opportunity list, and push workflows.
* **Disconnect** -- completely remove the HubSpot connection, credentials, and settings.

## Companies

The **Companies** tab manages company sync between HubSpot and Veles.

### How company sync works

Veles pulls company records from HubSpot and keeps them updated as changes occur. The sync runs in two phases:

1. **Initial sync** -- when first enabled, Veles imports all companies associated with deals modified in the past year. This runs as a background job and may take several minutes depending on your HubSpot data volume.
2. **Incremental sync** -- after the initial sync completes, Veles automatically checks for new and modified companies on a recurring schedule.

### Manual sync

Click **Sync Companies** to trigger an immediate sync rather than waiting for the next automatic cycle. The tab displays a **Last synced** timestamp showing when data was last pulled from HubSpot.

### What syncs

| HubSpot field                      | Veles field                      |
| ---------------------------------- | -------------------------------- |
| Company name                       | Customer name                    |
| Domain                             | Website                          |
| Industry                           | Industry                         |
| Address, City, State, Zip, Country | Address fields                   |
| Phone                              | Phone                            |
| Owner                              | Account owner (matched by email) |

## What syncs between systems

Once connected, Veles exchanges data with HubSpot across these objects:

| Veles object | HubSpot object | Sync direction  | What flows                                                                                   |
| ------------ | -------------- | --------------- | -------------------------------------------------------------------------------------------- |
| **Customer** | Company        | HubSpot → Veles | Company name, address, industry, domain, phone.                                              |
| **Contact**  | Contact        | HubSpot → Veles | Name, email, title, phone. Used to populate the "Prepared For" field on quotes.              |
| **Quote**    | Deal           | Bi-directional  | Quote metadata, status, and totals sync back to the deal. Deal data populates quote context. |
| **Order**    | Deal           | Veles → HubSpot | When a quote converts to an order, committed deal data is pushed to HubSpot.                 |
| **Contract** | Deal           | Veles → HubSpot | Active contract details, including entitlements and renewal dates.                           |

<Note>
  Veles pulls company and contact data from HubSpot, but HubSpot remains the system of record for those objects. Edits to customer or contact info should be made in HubSpot -- they'll sync to Veles automatically.
</Note>

## Linking quotes to deals

Veles quotes can be linked to HubSpot deals, creating a bi-directional connection that keeps both systems in sync.

### Link during quote creation

1. Click **New Quote**.
2. Select the **Link from CRM** tab.
3. Search for a HubSpot deal by name (minimum 2 characters).
4. Click the deal to create a linked quote.

The deal picker shows a searchable table with columns for deal name, company, owner, type, and stage. By default, only open deals are shown.

### Link an existing quote

1. Open the quote in the builder.
2. Click the **HubSpot menu** in the toolbar.
3. Select **Link to Deal**.
4. Search for and select the deal.

### Unlink a quote

1. Open the quote in the builder.
2. Click the **HubSpot menu**.
3. Select **Unlink**.

When a quote is linked, a HubSpot icon appears in the opportunity header. Clicking it opens the deal directly in HubSpot.

## Syncing deal data

Once a quote is linked to a deal, you can pull the latest deal data from HubSpot into Veles at any time:

1. Open the linked quote.
2. Click the **HubSpot menu**.
3. Select **Sync**.

The sync pulls the current deal name, stage, type, owner, and associated company data into Veles. The **Last Synced** timestamp in the menu shows when data was last pulled.

### Owner matching

Veles matches HubSpot deal owners to Veles users by email address (case-insensitive). If a matching user isn't found in Veles, the deal will still link but a warning is displayed.

## Pushing quotes to HubSpot

Push your finalized quote data back to HubSpot as line items and a native HubSpot quote.

<Steps>
  <Step title="Open the push workflow">
    From the HubSpot menu in the quote builder, select **Push to HubSpot**. Or navigate directly to the push page from the opportunity.
  </Step>

  <Step title="Configure the push">
    Select which pricing **option** to push (if your quote has multiple options). The form shows each option's name, TCV, term length, and line count. Optionally set a **service start date**.
  </Step>

  <Step title="Preview (optional)">
    Click **Simulate Push** to run a dry-run preview of what will be sent to HubSpot without making any changes.
  </Step>

  <Step title="Push">
    Click **Push to HubSpot** to send the data. You'll be taken to a status page showing real-time progress of the background job.
  </Step>

  <Step title="Verify">
    Once the push succeeds, click **View in HubSpot** to see the created line items and quote in your HubSpot deal.
  </Step>
</Steps>

### What gets pushed

* **Line items** -- each quote line is created as a HubSpot line item on the deal, including quantity, price, SKU, frequency, and billing period.
* **Native quote** -- a HubSpot quote object is created with the title, total amount, and TCV.
* **Notes** -- optional notes can be attached to the deal.

### Product matching

Veles matches products to HubSpot by **SKU**. Ensure your HubSpot product SKUs match the SKUs configured in Veles for line items to link correctly.

## Company field sync

Individual company records can be synced on demand from the company detail page:

1. Navigate to the company in Veles.
2. Click the **sync icon** next to the HubSpot company ID badge.
3. Veles pulls the latest company properties (industry, lifecycle stage, segment, website) from HubSpot.

The HubSpot company ID appears as a clickable orange badge on the company detail page, linking directly to the record in HubSpot.

## HubSpot data in Veles

Once connected, HubSpot data flows into Veles across several areas:

* **Quotes.** The Context Block can auto-populate from the linked deal: deal name, customer info, rep details, and stage.
* **Opportunity list.** The CRM Link column shows a HubSpot icon for linked quotes. The CRM Account Name column shows the associated company. The Status column shows the HubSpot deal stage alongside the Veles status.
* **Activity feed.** Link and unlink events are recorded in the opportunity's activity history with the user who performed the action and a timestamp.
* **Contract management.** When a quote is promoted to an order or contract, the committed deal data syncs back to HubSpot.

## User authentication

Each Veles user can connect their own HubSpot account for personalized access. This is separate from the admin-level integration connection.

### Connect your personal account

Navigate to **Settings > Integrations** and click **Connect** next to HubSpot. Once connected, your CRM dropdown in the top navigation shows a green status indicator and your HubSpot domain.

### Session expiry

If your HubSpot OAuth session expires, Veles displays a prompt to re-authenticate. Click **Login With HubSpot** to refresh your session. You'll be redirected back to your current page after re-authenticating.

## Troubleshooting

### Connection shows disconnected

* Verify the user who authorized the integration still has active HubSpot admin credentials.
* Check that the HubSpot account hasn't been suspended or downgraded to a plan without API access.
* Try disconnecting and reconnecting from **Admin Console > Integrations > HubSpot**.

### Deals not appearing in search

* Ensure you're searching with at least 2 characters.
* By default, only **open deals** are shown. Closed deals are filtered out.
* Verify your HubSpot user has permission to view the deals in question.
* If you see an authentication error, re-authenticate via the HubSpot login prompt.

### Company sync not running

* The initial sync must complete before incremental syncs begin. Check the **Companies** tab for sync status.
* If the initial sync appears stuck, trigger a manual sync with the **Sync Companies** button.
* Verify the integration is enabled on the **General** tab.

### Push to HubSpot fails

* Confirm the quote is linked to a HubSpot deal before pushing.
* Check that the opportunity is in the correct state (not still in draft).
* Review the job status page for specific error messages.
* Ensure product SKUs in Veles match those in HubSpot for line item matching.

### Owner not matching

* Veles matches HubSpot owners to Veles users by **email address**. Ensure the email addresses match between systems.
* If an owner can't be resolved, the deal will still sync but the owner field may be empty in Veles.

### Rate limiting

If you see rate limit errors in sync operations, HubSpot is throttling API requests. Veles handles this automatically with retry logic, but if issues persist, check your HubSpot API usage dashboard and consider spacing out manual sync triggers.

For persistent issues, reach out to the Veles team at [**hi@getveles.com**](mailto:hi@getveles.com) with the specific error message or sync behavior you're seeing.

## What's next

<CardGroup cols={2}>
  <Card title="Connect your CRM" icon="plug" href="/get-started/quickstart/connect-your-crm">
    Overview of CRM connection for both Salesforce and HubSpot.
  </Card>

  <Card title="Create your first quote" icon="file-lines" href="/get-started/quickstart/creating-a-quote">
    Build a quote linked to a live HubSpot deal.
  </Card>

  <Card title="Connect Stripe" icon="stripe-s" href="/get-started/integrations/stripe">
    Add billing and payment collection to your deal flow.
  </Card>

  <Card title="Rules & Approvals" icon="gavel" href="/get-started/rules-and-approval">
    Set up pricing guardrails now that your data is flowing.
  </Card>
</CardGroup>