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

# HubSpot Integration

> Sync contacts and companies between HubSpot CRM and your Raycaster sheets

## Overview

The HubSpot integration provides bidirectional sync between your HubSpot CRM and Raycaster sheets. Pull contacts and companies into your workspace, enrich them with AI research, and push updates back to HubSpot.

## Setting Up HubSpot

<Steps>
  <Step title="Open Integration Settings">
    Navigate to **Settings → Integrations** in the sidebar.
  </Step>

  <Step title="Add HubSpot">
    Find the HubSpot section and click **"Add Integration"**.
  </Step>

  <Step title="Authorize">
    Sign in to your HubSpot account and grant Raycaster access. You'll be redirected to HubSpot's OAuth page.
  </Step>

  <Step title="Confirmation">
    Once authorized, the integration becomes active and is available to all members of your organization.
  </Step>
</Steps>

<Note>
  HubSpot integrations are always organization-scoped. Each organization has a single HubSpot connection shared by all members.
</Note>

## Using CRM Templates

The fastest way to get started with HubSpot sync is to use a CRM template:

1. Create a new sheet and select **"From Template"**
2. Choose **"Company/Accounts Template for CRMs"** or **"People Template for CRMs"**
3. The template includes columns pre-mapped to common CRM fields

## Syncing Data

### Configuring Sync

<Steps>
  <Step title="Open a Sheet">
    Open the sheet you want to sync with HubSpot. For best results, use a CRM template.
  </Step>

  <Step title="Open CRM Settings">
    Click the **CRM** button in the sheet toolbar to open the sync configuration.
  </Step>

  <Step title="Select Entity Type">
    Choose what you want to sync:

    * **Contacts** — Individual people in your HubSpot
    * **Companies** — Organizations in your HubSpot
  </Step>

  <Step title="Map Fields">
    Map your sheet columns to HubSpot fields. The field mapping interface shows:

    * Your sheet columns on the left
    * Available HubSpot fields on the right (both standard and custom)
    * Click to create a mapping between them

    **Example mappings:**

    | Sheet Column | HubSpot Field |
    | ------------ | ------------- |
    | First Name   | `firstname`   |
    | Last Name    | `lastname`    |
    | Email        | `email`       |
    | Company      | `company`     |
    | Job Title    | `jobtitle`    |
  </Step>

  <Step title="Choose Sync Direction">
    Select the sync direction for this operation:

    * **Pull** — Import data from HubSpot into your sheet
    * **Push** — Export data from your sheet to HubSpot
    * **Bidirectional** — Sync in both directions
  </Step>

  <Step title="Run Sync">
    Click **Sync** to execute. Progress is tracked in real-time.
  </Step>
</Steps>

### Sync Directions

<Tabs>
  <Tab title="Pull (HubSpot → Sheet)">
    Import contacts or companies from HubSpot into your sheet:

    * All mapped fields are pulled from HubSpot
    * New rows are created in your sheet for each record
    * Both standard and custom HubSpot properties are supported
  </Tab>

  <Tab title="Push (Sheet → HubSpot)">
    Export data from your sheet to HubSpot:

    * Creates new records in HubSpot for each sheet row
    * Mapped columns are sent as HubSpot properties
    * Useful for adding AI-enriched data back to your CRM
  </Tab>

  <Tab title="Bidirectional">
    Sync in both directions:

    * Pulls new/updated records from HubSpot
    * Pushes new/updated rows from your sheet
    * Use with caution to avoid data conflicts
  </Tab>
</Tabs>

## Custom Fields

HubSpot custom properties are fully supported:

* Custom properties appear alongside standard fields in the field mapping interface
* Map them to any sheet column just like standard fields
* Custom field values are synced in both pull and push directions

## Sync Tracking

Each sync operation is tracked with:

* **Event type** — Pull, push, or bidirectional
* **Records processed** — Number of contacts/companies synced
* **Errors** — Any records that failed to sync, with error details
* **Timestamp** — When the sync occurred

View sync history from the integrations settings page.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Fields not appearing in mapping">
    * Verify the field exists in your HubSpot account
    * Check that your HubSpot user has access to the field
    * Custom properties may take a moment to load — refresh the mapping interface
  </Accordion>

  <Accordion title="Sync creates duplicates">
    * Ensure your field mappings include a unique identifier (typically `email` for contacts)
    * Use the pull direction first to import existing records before pushing new data
  </Accordion>

  <Accordion title="Permission errors">
    * Verify the HubSpot account used for authorization has sufficient permissions
    * CRM data access requires appropriate HubSpot subscription level
    * Try disconnecting and reconnecting the integration
  </Accordion>
</AccordionGroup>

## Disconnecting

To remove the HubSpot integration:

1. Go to **Settings → Integrations**
2. Find the HubSpot integration
3. Click **Disconnect**
4. Confirm the removal

<Warning>
  Disconnecting does not delete any data that was already synced to your sheets or pushed to HubSpot. It only prevents future sync operations.
</Warning>