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

# HubSpot

> Connect Craft to HubSpot.

Link your accounts so that Deal (or Lead), Contact, and Meeting data from HubSpot flows into Craft as Jobs, Customers, and Appointments — and so that Craft's recordings, AI summaries, and meeting activity appear back on the matching HubSpot record.

<Note>
  You must have admin access to both [HubSpot](https://www.hubspot.com) (a Super Admin, or a user allowed to install apps) and [Craft](https://app.craftflow.co) to complete this process.
</Note>

## Steps to connect

### 1. Connect HubSpot in Craft

<Steps>
  <Step title="Open Integrations in Craft">
    In the Craft web app, go to [**Company Settings > Integrations**](https://app.craftflow.co/company-settings/integrations).
  </Step>

  <Step title="Start the HubSpot connection">
    Open the [**HubSpot**](https://app.craftflow.co/company-settings/integrations/hubspot) integration and click **Connect HubSpot**. You'll be redirected to HubSpot to sign in.
  </Step>

  <Step title="Choose the right HubSpot account">
    If you belong to multiple HubSpot accounts, pick the one whose pipeline you want Craft to work with. Sign in with a user that can install apps and see the records you want Craft to see.
  </Step>

  <Step title="Approve the requested permissions">
    Review and approve Craft's requested scopes (see [Authentication and permissions](#authentication-and-permissions) below for the full list).
  </Step>

  <Step title="You're back in Craft">
    HubSpot redirects you back to Craft, and the sync settings panel appears so you can finish configuration.
  </Step>
</Steps>

<Note>
  Nothing syncs until you save your sync settings — connecting alone doesn't move any data. This gives you a chance to pick the right object and pipeline before Craft starts reading records.
</Note>

### 2. Configure sync settings

<Steps>
  <Step title="Choose your sales record">
    Tell Craft which HubSpot object represents a sales opportunity for your team:

    | Option              | When to use it                                                                                                                                                                              |
    | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | **Deals** (default) | Your reps work out of the classic Deals pipeline.                                                                                                                                           |
    | **Leads**           | Your reps work out of HubSpot's newer [Leads](https://knowledge.hubspot.com/prospecting/manage-your-leads-in-prospecting-workspace) object (requires Sales Hub Professional or Enterprise). |

    Craft syncs one or the other, not both.
  </Step>

  <Step title="Pick a pipeline (optional)">
    By default Craft syncs every pipeline for the chosen object. If only one pipeline is relevant — say your field-sales pipeline, but not your commercial one — select it here and Craft ignores the rest.
  </Step>

  <Step title="Map your stage outcomes">
    Tell Craft which pipeline stages mean **won** and which mean **lost**. Craft uses this to mark appointments and recordings as sold, and to close out follow-up on records that are no longer active. Stages you don't map are treated as still in progress.

    If you use HubSpot's standard "Closed won" / "Closed lost" stages, the defaults already cover you. Custom pipelines should map their equivalents explicitly.
  </Step>

  <Step title="Turn on meeting logging (optional)">
    Enable **Log completed meetings in HubSpot** if you want each analyzed recording written back to HubSpot as a completed meeting activity. You can also pick a meeting *type* property to set on those meetings (for example, to distinguish demos from in-home consultations). See [What Craft writes to HubSpot](#what-craft-writes-to-hubspot).
  </Step>

  <Step title="Save">
    Saving kicks off an initial backfill of roughly the last 90 days of records, and ongoing sync begins from there. You can revisit these settings at any time from the [HubSpot integration page](https://app.craftflow.co/company-settings/integrations/hubspot).
  </Step>
</Steps>

## What syncs from HubSpot

| HubSpot          | Craft        | Notes                                                                                                                                 |
| ---------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------- |
| Deals *or* Leads | Jobs         | Name, stage, pipeline, owner, and close date. Deal amounts also sync so sold revenue shows up in Craft reporting.                     |
| Contacts         | Customers    | The primary contact on each deal or lead — name, email, phone, and address.                                                           |
| Meetings         | Appointments | Scheduled meetings associated with your deals or leads, so Craft knows when reps are due at an appointment.                           |
| Owners           | Craft users  | HubSpot owners are matched to Craft users by email (with a name-based fallback), so activity lands under the right rep automatically. |

Deal and contact changes reach Craft in close to real time, with a periodic catch-up sync behind it so nothing is missed. Two things worth knowing:

* **Leads sync on the catch-up cycle.** HubSpot doesn't publish real-time events for the Leads object, so lead changes can take a few extra minutes to appear in Craft.
* **Craft is read-only on your pipeline.** Syncing never modifies your HubSpot deals, leads, stages, or amounts — see below for exactly what Craft writes.

## What Craft writes to HubSpot

Craft only writes activity and insights — it never changes your pipeline data. Deal amounts, stages, names, and pipelines are treated as HubSpot's source of truth and are never edited by Craft.

With **meeting logging** enabled, after a recording is analyzed Craft logs it in HubSpot:

* If the appointment was already scheduled as a HubSpot meeting, Craft marks that meeting completed rather than creating a duplicate. Otherwise it logs a new meeting.
* The meeting body includes the AI-generated summary and a link to the full recording in Craft.
* The meeting is associated with the matching deal (or lead) and contact, and attributed to the right owner.
* If you configured a meeting type property, it's set based on the kind of appointment that was recorded.

Craft can also write AI-generated content — like recording summaries or appointment briefings — to custom properties on your deals, leads, contacts, or companies, so the insight is visible wherever your team already works. Your Craft contact can set this up with you; you choose the target properties.

## Authentication and permissions

Craft uses HubSpot's standard [OAuth 2.0 flow](https://developers.hubspot.com/docs/api/oauth-quickstart-guide) — there are no API keys to copy and paste, and you can revoke access at any time from your HubSpot account's [Connected Apps](https://knowledge.hubspot.com/integrations/connect-apps-to-hubspot) settings.

The scopes Craft requests:

| Scope                                                                               | Why we need it                                                           |
| ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| `crm.objects.deals.read` / `write`                                                  | Sync deals; log meeting activity and write configured properties on them |
| `crm.objects.leads.read` / `write`                                                  | Same as above, for teams using the Leads object                          |
| `crm.objects.contacts.read`                                                         | Sync the primary contact on each deal or lead                            |
| `crm.objects.companies.read` / `write`                                              | Associate records and write configured company properties                |
| `crm.objects.owners.read`                                                           | Map HubSpot owners to Craft users                                        |
| `crm.schemas.deals.read`, `crm.schemas.contacts.read`, `crm.schemas.companies.read` | Discover pipelines, stages, and properties for configuration             |

Access tokens are short-lived and refreshed automatically, so once connected the integration runs without intervention. Tokens are stored encrypted at rest. If access is ever revoked on the HubSpot side, the [Integrations page](https://app.craftflow.co/company-settings/integrations) surfaces an error and prompts you to reconnect.

## Best practices

* Connect with a HubSpot user who can see every pipeline and record you want in Craft.
* If you use custom pipeline stages, map your won and lost stages during setup — otherwise deals that close in those stages won't register as sold in Craft.
* Switching between Deals and Leads (or changing the pipeline filter) later is supported, but it re-syncs from the new selection — plan to do it once during setup rather than routinely.
* Using the Leads object requires Sales Hub Professional or Enterprise. If lead pipelines don't appear during setup, check your HubSpot subscription tier.

## Need help?

Reach out to your contact at Craft, or email [support@craftflow.com](mailto:support@craftflow.com).