> For the complete documentation index, see [llms.txt](https://docs.sumble.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sumble.com/system-setup-and-configuration/crm/hubspot.md).

# HubSpot

## HubSpot integration

### Overview

Sumble's HubSpot integration syncs data between your HubSpot instance and Sumble in both directions.

From HubSpot to Sumble:

* **Account list** -- Keep your Sumble account universe in sync with HubSpot Companies
* **Account assignments** -- Personalize Sumble for your reps based on HubSpot owner and user data
* **CRM fields as columns** -- Show Company properties as filterable columns in Sumble. See [Filter and sort by CRM data](/system-setup-and-configuration/crm/crm-columns.md)

From Sumble to HubSpot:

* **Enrichments** -- Write firmographic and technographic data back to HubSpot Company records (updates only, does not create new Companies)
* **Signals** -- Deliver Sumble signals to the matching Company as custom events, so they show up on the Company timeline and can drive workflows and reports

Each of these can be turned on independently. Signals also need the optional event permissions described below.

### How it works

Once connected, Sumble will:

1. Create a **Sumble Information** property group on your Company object
2. Create custom properties (prefixed with `sumble_`) for each enrichment you have asked us to write to your CRM
3. If you subscribe to signals and granted the event permissions, create a **Sumble Alert** custom event on the Company object
4. Sync data daily after the Sumble data pipeline completes

### Installation

#### Before you start

* You need a HubSpot account with **Super Admin** permissions (required to authorize third-party apps)
* You need an active Sumble Enterprise subscription

#### Step 1: Start the connection

1. Go to [sumble.com/integrations/hubspot/start](https://sumble.com/integrations/hubspot/start)
2. Log in to Sumble if prompted

#### Step 2: Authorize in HubSpot

1. You'll be redirected to HubSpot's authorization screen
2. Select the HubSpot account you want to connect
3. Review the permissions (see Permissions below)
4. Click **Connect app**

#### Step 3: Confirm

After authorizing, you'll be sent back to Sumble. You should see **"HubSpot is connected"**.

No further configuration is needed. Sumble starts syncing automatically.

### Permissions

Sumble requests these HubSpot scopes during authorization:

| Scope                         | What it's for                                  |
| ----------------------------- | ---------------------------------------------- |
| `crm.objects.companies.read`  | Read Company records to match accounts         |
| `crm.objects.companies.write` | Write enrichment data to Company records       |
| `crm.objects.contacts.read`   | Read Contact records                           |
| `crm.objects.contacts.write`  | Write Contact data                             |
| `crm.objects.deals.read`      | Read Deal records                              |
| `crm.objects.deals.write`     | Write Deal data                                |
| `crm.objects.leads.read`      | Read Lead records                              |
| `crm.objects.leads.write`     | Write Lead data                                |
| `crm.objects.owners.read`     | Read owner assignments for territory mapping   |
| `crm.objects.users.read`      | Read HubSpot users for account assignment      |
| `crm.schemas.companies.write` | Create custom properties on the Company object |
| `crm.export`                  | Export Company and User records from HubSpot   |
| `crm.import`                  | Import enrichment data into HubSpot            |

Two additional scopes are requested as **optional** -- they power the signals feed, which writes Sumble signals to HubSpot as custom events (see Signals below):

| Scope                                            | What it's for                            |
| ------------------------------------------------ | ---------------------------------------- |
| `behavioral_events.event_definitions.read_write` | Define the Sumble Alert custom event     |
| `analytics.behavioral_events.send`               | Send Sumble signals as event occurrences |

{% hint style="info" %}
HubSpot's custom events API requires an **Enterprise** subscription on one of its Hubs. Because these two scopes are optional, you can still connect the core integration without them -- the CRM sync and enrichment push work as normal, and only the signals feed is skipped. If your HubSpot plan doesn't include custom events, leave these permissions unchecked during authorization.
{% endhint %}

Sumble only creates or modifies properties inside the **Sumble Information** property group. We never alter your existing HubSpot properties.

### Enrichment properties

After the first sync, a **Sumble Information** property group will appear on your Company records. It contains a custom property for each enrichment you have asked us to write to your CRM (technology usage, headcount trends, hiring signals, etc.). Some enrichments also come with a companion `_url` property linking to the evidence in Sumble, and a `_evidence` property holding the supporting detail as JSON. All properties are prefixed with `sumble_` — for example, an enrichment called "job\_count" appears as `sumble_job_count` in HubSpot.

You don't need to create any fields manually. When a new enrichment is enabled for your CRM, the corresponding property is created on the next sync. Not every enrichment on your account is written to HubSpot by default; tell your account team which ones you want in the CRM.

#### Where to find them

1. Open any Company record in HubSpot
2. Scroll to or search for the **Sumble Information** section in the left sidebar

These properties work like any other Company property -- you can use them in lists, workflows, and reports.

### Signals

If your account subscribes to [Sumble Signals](/enterprise-services/sumble-signals.md) and you granted the two optional event permissions, each signal is delivered to HubSpot as an occurrence of a custom event named **Sumble Alert** (`sumble_alert`) on the Company it relates to.

* The event's timestamp is when Sumble generated the signal. The job post's crawl date is carried separately in the `datetime_pulled` property.
* Event properties include the alert type, name and title, priority, location and country, sales angle, the Sumble organization id, name and URL, the job title, an explanation, the matched entities, and, for people signals, the person's name and LinkedIn URL plus their old and new organization.
* Only signals for Companies that exist in your HubSpot and matched a Sumble organization are delivered. Signals for organizations outside your CRM are not sent.
* Each run sends only signals newer than the last one delivered, so nothing is duplicated.

Find them on the Company record's activity timeline, or build lists, workflows, and reports on the Sumble Alert event under **Data Management > Event Management**.

### Creating Companies from Sumble

The daily sync never creates Companies. Separately, and only if you ask us to enable it, users in the Sumble web app can push an account that is not yet in your CRM straight to HubSpot from the account status chip. That creates one Company and records it as matched, so it starts receiving enrichments on the next sync.

Users can also push a person from the Sumble web app, which creates a HubSpot Contact associated to the matched Company. If a Contact with the same email already exists, Sumble links that Contact to the Company instead of creating a new one. The Contact push is off by default; a Sumble admin turns it on per customer. When champion tracking (below) is configured with a LinkedIn property, the push also writes the person's LinkedIn URL to that property so the Contact can be tracked.

### Champion tracking

Champion tracking watches the people already in your HubSpot for job changes. When a Contact you care about moves to a new company, that is often the best moment to reach out: you already have a relationship, and they now have a new budget and new problems. Sumble spots the move and, if you want, reflects it in HubSpot so the Contact is not left attached to a company they no longer work for.

It has two halves, both optional and off by default. Your Sumble account team configures them with you.

#### Pulling Contacts

Sumble pulls the Contacts you choose into its people tracking. You control which Contacts by giving us HubSpot property filters (for example, a lifecycle stage, a custom "champion" checkbox, or a list of owners), and Sumble pulls only the Contacts that match. Contacts need a LinkedIn URL in a property you tell us about; that is how Sumble recognizes the same person when they show up at a new employer. Contacts without one are pulled but cannot be tracked.

Each tracked Contact who changes jobs produces a people signal, delivered like any other [signal](#signals).

#### Syncing job changes back to HubSpot

When a tracked Contact moves to a company that is also in your HubSpot, Sumble can update your CRM. Pick one of two modes:

* **Update existing** -- Sumble edits the existing Contact: it updates the job title, refreshes the LinkedIn property if one is configured, and makes the new Company the Contact's primary association. The old Company stays associated so history is kept, but it is no longer primary.
* **Create new** -- Sumble leaves the original Contact untouched and creates a new Contact at the new Company, with first name, last name, job title, and the LinkedIn property. The new Contact is tracked from then on, so a second move is caught too.

In either mode, if the destination company is not in your HubSpot, nothing is written; you still get the signal.

The sync writes only `firstname`, `lastname`, `jobtitle`, the LinkedIn property you configured, and the primary Company association. It never writes email, phone, or owner, and it never deletes a Contact.

### Account matching

Sumble matches HubSpot Companies to organizations in the Sumble database. The exact HubSpot properties used are configured per customer, but the typical mapping is:

| Field             | Required                                                                     | Typical HubSpot property |
| ----------------- | ---------------------------------------------------------------------------- | ------------------------ |
| Company ID        | <ul class="contains-task-list"><li><input type="checkbox" checked></li></ul> | `hs_object_id`           |
| Company Name      | <ul class="contains-task-list"><li><input type="checkbox" checked></li></ul> | `name`                   |
| Company Domain    | <ul class="contains-task-list"><li><input type="checkbox" checked></li></ul> | `domain`                 |
| LinkedIn URL      | <ul class="contains-task-list"><li><input type="checkbox"></li></ul>         | `linkedin_company_page`  |
| Country           | <ul class="contains-task-list"><li><input type="checkbox"></li></ul>         | `country`                |
| Parent Company ID | <ul class="contains-task-list"><li><input type="checkbox"></li></ul>         | (if applicable)          |

If your HubSpot instance uses non-standard property names for any of these, let us know during setup and we'll configure the mapping accordingly. The full list of account fields, including the optional ones, is in [Data fields](/system-setup-and-configuration/data-fields.md#accounts).

### Sales territories

Sumble reads HubSpot owner assignments to personalize each user's experience. By default, it uses **HubSpot Owner** -- the Company's assigned owner.

Many teams spread account ownership across more than one owner property, such as an SDR, XDR, or CS owner. Those are custom properties rather than HubSpot standard ones, so tell us which properties you use during setup and we'll add them to the mapping. Each one you add gives the rep named on it the same account access as the Company owner.

These assignments determine which accounts each Sumble user sees signals and alerts for. To map owners to users, Sumble pulls the user fields listed under [Users in Data fields](/system-setup-and-configuration/data-fields.md#users).

### Data sync details

#### Pull (HubSpot to Sumble)

* Uses HubSpot's CRM Export API to pull Company records and User records, and Contact records when champion tracking is on
* Only downloads the configured mapping fields (see Account matching)
* Company data is used for account matching; User data is used for owner-to-rep mapping; Contact data is used for champion tracking

#### Push (Sumble to HubSpot)

* Uses HubSpot's batch Company update API, keyed on `hs_object_id`, in batches of 100. Nothing appears in your Imports history.
* **Updates existing Company records only** -- does not create new Companies in HubSpot
* Only writes to properties in the **Sumble Information** group
* Champion tracking, when enabled, updates or creates individual Contacts as described above; it is the only part of the sync that touches Contacts
* Signals, when enabled, go through HubSpot's custom events API as **Sumble Alert** occurrences on the Company

### Disconnecting

To disconnect, contact your Sumble account team. We'll revoke stored credentials and stop syncing.

You can also revoke access from HubSpot directly:

1. Go to **Settings > Integrations > Connected Apps**
2. Find **Sumble**
3. Click **Uninstall**

***

<a href="https://calendly.com/d/cnzk-sjk-q38/sumble" class="button primary">Book a time to chat with us</a>