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

# HubSpot

> What connecting HubSpot enables — reading and writing CRM records, list management, automatic activity logging, and workflow triggers.

Connecting HubSpot gives the agent direct read and write access to your CRM, and is the only CRM today with Swan's deeper sync behavior — automatic activity logging and configurable contact-creation rules. You connect it from [Tools](https://agent.getswan.com/tools) via HubSpot OAuth, granted at the org level (one connection is shared by everyone in your org, not per user).

## What the agent can do in HubSpot

Once connected, the agent can:

* Search and read contacts, companies, deals, notes, tasks, and engagements, including cross-object queries (for example, contacts associated with a specific company). A single search can return at most 10,000 results — HubSpot's own API ceiling; past that, Swan reports the result set was truncated and asks for narrower filters.
* Create and update contacts, companies, and deals.
* Create notes and tasks, and update existing tasks (including assigning a task to a specific HubSpot owner). These are HubSpot task records inside your CRM — not [Swan Desk tasks](../workspace/desk-and-tasks.md).
* Create associations between contacts, companies, and deals.
* Search HubSpot lists, read list membership, and add contacts, companies, or deals to an existing manual or snapshot list. Adding to a dynamic (active) list isn't blocked upfront — but because HubSpot controls membership of those lists through its own filters, HubSpot rejects the add and Swan surfaces that error rather than changing the list.
* Archive (delete) HubSpot records.

Reading and searching HubSpot data doesn't cost credits. Every write — creating or updating a contact, company, deal, task, or note; adding to a list; creating an association; archiving a record — costs 1 credit. See [credits](../administration/credits.md) for how that fits into your overall usage.

Swan does not create new HubSpot lists from scratch, and it only writes to HubSpot when your instructions call for it — this toolkit doesn't touch Swan's own internal data model (funnel stage, tags, ICP match). To change how Swan classifies a company or contact internally, that's a separate, non-HubSpot action.

You can enable or disable individual HubSpot tools, and require approval before any of them run, from the HubSpot card's Capabilities tab in [Tools](https://agent.getswan.com/tools).

## Contact and company creation

Whether Swan creates new companies and contacts in HubSpot (versus only updating ones that already exist), and when, is controlled by settings on the integration — for example, only creating contacts once outreach starts, or never creating new companies at all. Set this from the HubSpot card's Configuration tab in [Tools](https://agent.getswan.com/tools), under Automatic Contact Creation. See [Swan vs. your CRM](../data/swan-vs-your-crm.md) for how these policies work.

## Automatic outreach logging

Once a contact exists in both Swan and HubSpot, Swan automatically logs outreach activity to their HubSpot timeline as it happens — connection requests sent and accepted, messages sent, and replies received — as emails or LinkedIn communications (falling back to a note if the direct activity type isn't available). This logging happens in the background; it isn't a tool call the agent makes and doesn't consume credits on its own.

Swan also writes a small set of custom properties to your contacts and companies, grouped under a "Swan AI" property group in HubSpot — including an outreach status field and internal flags Swan uses to track what it created versus what already existed. These are visible directly on the record in HubSpot.

## HubSpot as a trigger source

You can use HubSpot list membership as a filter or exclusion when setting up a trigger, and — going the other direction — you can add Swan as an action inside a HubSpot workflow, so records enrolled in that workflow hand off to a Swan trigger automatically. See [HubSpot workflow triggers](../triggers/hubspot-workflow.md) for how that's set up.

## Field mapping

If your HubSpot portal stores email or LinkedIn URL in a custom property instead of the standard one, you can map those fields in the HubSpot card's Configuration tab (Contact Field Mapping) in [Tools](https://agent.getswan.com/tools), so Swan reads and writes to the right property.

## Common questions

**Does Swan require HubSpot to work?**
No. HubSpot is optional — Swan runs standalone without any CRM connected, and other CRMs like Salesforce, Attio, and Pipedrive are also [built in](built-in-integrations.md).

**Can I make the HubSpot integration read-only?**
There's no built-in read-only toggle. To minimize writes, turn off automatic contact/company creation in the integration settings and avoid instructing Swan to write to HubSpot in your triggers and playbooks.

**Can Swan access HubSpot call recordings or transcripts?**
No — Swan can read call logs and notes already in HubSpot, but not audio recordings or AI-generated transcripts. Connect the built-in [Fireflies or Fathom integrations](built-in-integrations.md) for transcript access.

**My HubSpot connection shows as connected but tools are failing — what's wrong?**
This is usually a stale or expired OAuth token, or an unverified-app consent issue. Go through the HubSpot connect flow again to re-authorize; if the problem persists, check that you're reconnecting to the same HubSpot portal the integration was originally set up on.