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

# Sync HubSpot with Stairoids for Real-Time CRM Signals

> Sync HubSpot contact updates, deal stage changes, and email activity as live signals, and trigger CRM actions automatically from Stairoids.

The HubSpot integration turns your CRM into a real-time signal source. Every deal movement, contact property update, form fill, and meeting booking becomes a scored signal in Stairoids that can trigger automations across your entire GTM stack. Outgoing actions close the loop by writing changes back to HubSpot — keeping your CRM accurate without manual updates.

## Prerequisites

Before connecting, make sure you have:

* A HubSpot account (any paid tier, or a free account with the relevant features enabled)
* **Super Admin** or a custom role with **Integration** permissions in HubSpot
* Admin access in your Stairoids workspace

## Connect HubSpot

<Steps>
  <Step title="Open Integration Settings">
    In Stairoids, go to **Settings → Integrations** and click **Add Integration**.
  </Step>

  <Step title="Select HubSpot">
    Choose **HubSpot** from the integration catalog and click **Connect with HubSpot**.
  </Step>

  <Step title="Authorize via OAuth">
    You'll be redirected to HubSpot's OAuth consent screen. Select the HubSpot account you want to connect, review the requested scopes, and click **Connect app**. Stairoids requests only the scopes it needs — it does not request write access to objects you haven't enabled outgoing actions for.
  </Step>

  <Step title="Choose events to sync">
    Back in Stairoids, toggle on the incoming signal event types you want to track. You can update these at any time from **Settings → Integrations → HubSpot → Configure**.
  </Step>

  <Step title="Verify the connection">
    Stairoids performs a test API call and confirms the connection is live. Navigate to your **Signal Feed** — you should see HubSpot signals appearing within a few minutes.
  </Step>
</Steps>

<Note>
  The HubSpot integration uses OAuth exclusively. You do not need to generate or manage a HubSpot API key. If you disconnect and reconnect, you'll go through the OAuth flow again to issue fresh tokens.
</Note>

## Supported incoming signal events

These are the HubSpot events Stairoids can receive and convert into signals:

| Event                    | Signal type                | Key properties                                             |
| ------------------------ | -------------------------- | ---------------------------------------------------------- |
| Deal stage changed       | `deal_stage_changed`       | `deal_id`, `from_stage`, `to_stage`, `deal_name`, `amount` |
| Contact property updated | `contact_property_updated` | `contact_id`, `property_name`, `old_value`, `new_value`    |
| Email opened             | `email_open`               | `contact_id`, `email_subject`, `campaign_id`, `opened_at`  |
| Email link clicked       | `email_click`              | `contact_id`, `link_url`, `email_subject`, `clicked_at`    |
| Form submitted           | `form_submit`              | `contact_id`, `form_id`, `form_name`, `page_url`           |
| Meeting booked           | `meeting_booked`           | `contact_id`, `meeting_type`, `scheduled_at`, `owner_id`   |

## Supported outgoing actions

When a Stairoids automation targets HubSpot, it can perform the following actions:

* **Create contact** — create a new contact record with mapped properties
* **Update contact property** — write a value to any standard or custom HubSpot property
* **Update deal stage** — move a deal to a specified pipeline stage
* **Enroll contact in workflow** — trigger a HubSpot automation workflow for a contact
* **Add contact to list** — add a contact to a static or active HubSpot list

## Field mapping

Stairoids maps HubSpot properties to its own signal schema automatically for standard fields. When a `contact_property_updated` signal arrives, the contact's HubSpot `email`, `firstname`, `lastname`, and `company` map directly to the Stairoids contact object. For custom HubSpot properties, Stairoids preserves them as key-value pairs under `signal.properties`.

You can configure additional mappings from **Settings → Integrations → HubSpot → Field Mapping**. Use this to map custom HubSpot properties to Stairoids account or contact fields that your playbooks rely on.

<Tip>
  Map your HubSpot lifecycle stage to a Stairoids contact field to use it as a filter condition in your automations. For example, trigger a HeyReach LinkedIn sequence only when the contact is in the "Marketing Qualified Lead" stage.
</Tip>

## Troubleshooting

<Accordion title="Signals not appearing in Stairoids">
  1. Confirm the connection is active under **Settings → Integrations → HubSpot**. If the status shows **Disconnected**, re-authorize via OAuth.
  2. Check that the relevant event types are toggled on in the HubSpot configuration panel.
  3. Verify that the HubSpot user who authorized the integration still has the required permissions. If that user was removed or their role changed, the OAuth token may have been revoked — reconnect with a Super Admin account.
  4. HubSpot can occasionally delay webhook delivery during high traffic periods. Wait a few minutes and check whether the signal appears in the **Signal Feed**.
</Accordion>

<Accordion title="Permission denied on outgoing action">
  Outgoing actions write to HubSpot objects using the OAuth token issued during setup. If Stairoids returns a `403 Permission Denied` error on an outgoing action:

  1. Go to **Settings → Integrations → HubSpot** and check which scopes were granted.
  2. Disconnect and reconnect the integration. During the OAuth flow, make sure the authorizing account is a Super Admin — this ensures Stairoids receives all required write scopes.
  3. If you're trying to enroll contacts in a HubSpot workflow, confirm the workflow is set to **Active** in HubSpot. Stairoids cannot enroll contacts into draft workflows.
</Accordion>

<Accordion title="Duplicate contacts being created">
  Before creating a new contact, Stairoids checks for an existing match by email address. If duplicates are appearing:

  1. Confirm the incoming signal includes a valid `contact.email` value. Signals without an email address bypass the deduplication check.
  2. Review your automation's action configuration — ensure **Match existing contact** is enabled rather than **Always create new**.
  3. If the duplicate contact has a different email casing (e.g., `User@example.com` vs `user@example.com`), Stairoids normalizes to lowercase before matching. Check whether HubSpot has pre-existing duplicates that Stairoids is reflecting.
</Accordion>