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

# HubSpot troubleshooting and FAQ

> Fixes for the common HubSpot sync issues (reconnect, missing contacts, duplicates, scopes, rate limits) and answers to the questions teams ask before connecting.

Most HubSpot issues come down to a setting, a missing email, or a token that needs refreshing. This page covers the fixes and the questions teams ask most.

## If you're coming from RB2B

RB2B documents three errors and asks you to hand-create two properties before some syncs work. Squid ID creates its properties for you and handles more failure modes automatically.

<div className="compare">
  <table>
    <thead>
      <tr><th /><th>RB2B</th><th>Squid ID</th></tr>
    </thead>

    <tbody>
      <tr><td>Manual property prerequisites</td><td>LinkedIn + Industry</td><td>None (auto-created)</td></tr>
      <tr><td>Token refresh</td><td>Manual reconnect</td><td>Automatic</td></tr>
      <tr><td>Rate-limit handling</td><td>Not documented</td><td>Automatic retry with backoff</td></tr>
    </tbody>
  </table>
</div>

<p className="why"><strong>Why this matters.</strong> The connector is built to recover on its own where it can (refresh, retry, dedupe) so the list of things you have to fix by hand is short.</p>

## Contacts are not appearing

Work through these in order:

1. **The connector is paused.** Check the HubSpot card on **Settings → Integrations** and make sure the toggle is on.
2. **The visitor has no email.** HubSpot contacts require an email, so a visitor we can't resolve to an email is skipped. This is expected.
3. **Your targeting is too tight.** If **Sync** is set to a specific ICP or a specific high-intent page, only those visitors sync. Set it to *All identified visitors* to confirm, then narrow again.
4. **A requirement is excluding them.** "Require a company / LinkedIn" and the email-type setting are AND gates. Loosen them to test.
5. **Send is set to once.** In *once per visitor* mode a person already synced won't sync again. Switch to *every identified visit* if you expect repeat syncs.

## Squid ID+ fields are empty

`squid_mobile_phone`, `squid_personal_email`, and `squid_home_address` (and the standard mobile/address fields) are populated only for records that are **unlocked**. Turn on [Squid ID+ Automatic](/add-ons/squid-id-plus#turning-on-automatic) for the website, or reveal the record, and they fill in on the next sync.

## A field I expected wasn't updated

By design. On an **existing** contact Squid ID writes only its `squid_` properties and never overwrites standard fields your team manages. The standard fields (name, job title, mailing address) are set only when the contact is first created. See [what HubSpot receives](/integrations/hubspot-fields).

## Duplicates

Squid ID matches contacts by **email** and upserts, so it does not create a second contact for an email that already exists. Duplicates in HubSpot usually predate the connection or come from a different email variant (for example `jane@acme.com` vs `jdoe@acme.com`). Merge those in HubSpot.

## Reconnect or disconnect

* **Reconnect:** open the HubSpot connector and connect again. The connector refreshes its own access token automatically, so you rarely need to do this, but a revoked app or changed permissions will require it.
* **Disconnect:** open the connector and click **Disconnect**. This removes the connection from Squid ID. To also remove it inside HubSpot, go to **Settings → Integrations → Connected Apps** there and revoke it.

## Frequently asked

<AccordionGroup>
  <Accordion title="Does connecting overwrite my existing HubSpot data?">
    No. New contacts get the standard fields; existing contacts get only the `squid_` properties. Your team's fields are never overwritten.
  </Accordion>

  <Accordion title="Do I need to create any properties first?">
    No. Squid ID creates its `squid_` properties (and their group) automatically when you connect.
  </Accordion>

  <Accordion title="Will it sync my historical visitors?">
    No. The connector syncs visitors identified after you connect. It does not backfill past records.
  </Accordion>

  <Accordion title="Can I connect more than one website?">
    Yes. The connection is per website. Switch the active site and connect each one; routing and actions are set per site.
  </Accordion>

  <Accordion title="Public app or Private App token?">
    Both work. The public app is one-click OAuth and is the normal choice. A HubSpot Private App token is an alternative for a single portal; paste it in the connector instead of using OAuth.
  </Accordion>

  <Accordion title="What about rate limits?">
    The connector respects HubSpot's limits and retries on a rate-limit or server error with backoff. Mapping errors are not retried so they don't loop.
  </Accordion>
</AccordionGroup>

## Related

* [Sync visitors to HubSpot](/integrations/hubspot)
* [What HubSpot receives](/integrations/hubspot-fields)
* [HubSpot playbooks](/integrations/hubspot-workflows)