# Connecting HubSpot

> Source: https://docs.trailspark.ai/docs/connecting-hubspot

## Overview

The HubSpot integration uses OAuth 2.0 with a one-click connection flow. No credentials to enter -- TrailSpark handles the OAuth client configuration on the backend.

## Prerequisites

- **Admin access** to your HubSpot account
- **Admin** or **Owner** role in TrailSpark

## Connect to HubSpot

1. Go to **Settings** > **CRM Integration**
2. Click **Connect** on the HubSpot card
3. Log in to HubSpot if prompted
4. If you have multiple HubSpot accounts, select the one to connect
5. Review the requested permissions and click **Connect app**

Once authorized, TrailSpark shows a **Connected** status. Use the **Test Connection** button to verify the integration is working.

### Requested Permissions

TrailSpark requests the following OAuth scopes:

- **crm.objects.contacts.read / write** -- read and write contact records
- **crm.objects.companies.read** -- read company records
- **crm.objects.deals.read** -- read deal records for signal enrichment
- **sales-email-read** -- read email engagement data for sentiment analysis

## What Gets Synced

### Contacts

Standard properties (email, name, job title, lifecycle stage, lead status) plus any custom properties you configure in [Field Mapping](/docs/field-mapping).

### Companies

Company name, domain, industry, employee count, revenue, and custom properties.

### Deals

Deal name, stage, amount, and close date. Deal data is used for signal enrichment and closed-won analysis during ICP creation.

### Engagement Signals

Email opens, email clicks, form submissions, page views, and meeting bookings flow as signals for lead scoring.

## HubSpot Properties

TrailSpark can access both standard and custom HubSpot properties. Common standard properties:

| Category | Properties |
|----------|------------|
| Contact Info | `email`, `firstname`, `lastname`, `jobtitle` |
| Company Info | `company`, `industry`, `website` |

Custom properties are available after you create them in HubSpot and map them in TrailSpark's [Field Mapping](/docs/field-mapping).

## Disconnecting

Disconnecting from TrailSpark does not remove the app from your HubSpot account. To fully revoke access, also disconnect from **HubSpot Settings** > **Integrations** > **Connected Apps**.

## Troubleshooting

### "Access denied" error

- Verify you are selecting the correct HubSpot account during authorization
- Confirm your HubSpot user has admin permissions

### Duplicate contacts

TrailSpark uses email as the primary identifier. If HubSpot contains duplicate contacts with the same email, TrailSpark matches to the most recently updated record.

### Missing engagement data

- Engagement tracking requires the HubSpot tracking code installed on your website
- Marketing email engagement requires HubSpot marketing tools
- Historical engagement depth depends on your HubSpot plan's data retention

## Next Steps

- [Field Mapping](/docs/field-mapping) -- configure how HubSpot properties map to TrailSpark
- [HubSpot Destination](/docs/hubspot-destination) -- write evaluation results back to HubSpot