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

# Connect HubSpot to Your Scout Agents

> Integrate HubSpot CRM with Scout so agents can read and write contacts, companies, deals, tickets, and custom objects directly within workflows.

Connecting Scout to HubSpot CRM lets agents read and write CRM data — looking up contacts, creating deals, updating properties — directly within workflows. After connecting, you can issue natural-language requests and the agent handles them without manual entry. Setup takes about five minutes through a HubSpot Private App.

<Note>
  HubSpot is also covered in the combined [CRM integration page](/integrations/crm) alongside Salesforce. This page goes deeper on HubSpot-specific scopes, verification, and troubleshooting.
</Note>

## What Your Agent Can Do

Available actions depend on the scopes you grant during setup.

* Look up, create, and update contacts, companies, and deals
* Search and filter records (for example, finding open deals over a threshold)
* Create and manage tickets for support workflows
* Read and update custom objects and properties
* Access associations between records — contacts linked to a company, deals linked to a contact
* Trigger and check automation workflows
* Manage lists and list membership

## Prerequisites

* A HubSpot account with admin access
* A Scout workspace

## Getting Started

<Steps>
  <Step title="Create a HubSpot Private App">
    Log in to HubSpot, click the **Settings** (gear) icon in the top navigation, then go to **Integrations → Private Apps** in the left sidebar. Click **Create private app** and give it a recognizable name like "Scout CRM Integration" plus an optional description.
  </Step>

  <Step title="Configure app scopes">
    Under the **Scopes** tab, grant only the scopes you plan to use — you can update them later.

    | Category        | Scopes                                                                                                                 |
    | --------------- | ---------------------------------------------------------------------------------------------------------------------- |
    | **CRM Objects** | Read/write for `contacts`, `companies`, `deals`, `tickets`, `custom`, and `line_items`, plus `crm.objects.owners.read` |
    | **CRM Schemas** | Read/write for `contacts`, `companies`, `deals`, and `custom`                                                          |
    | **Additional**  | Associations read/write, `sales-email-read`, `tickets`, `timeline`, `automation`, and lists read/write                 |

    Click **Create app** when finished.
  </Step>

  <Step title="Copy your access token">
    Copy the access token from the confirmation screen for the next step. Treat it like a password — anyone with this token can read and write your CRM data.
  </Step>

  <Step title="Connect to Scout">
    Go to [studio.scoutos.com/integrations](https://studio.scoutos.com/integrations), find **Enhanced HubSpot**, and click **Add Workspace**. Paste your access token into the API key field and click **Create Connection**. A confirmation appears once connected.
  </Step>

  <Step title="Verify the connection">
    Open an agent, go to its **Tools** section, and enable the HubSpot integration for that agent. Then start a chat and try a prompt like:

    ```
    List the 5 most recently created contacts in HubSpot.
    ```

    If set up correctly, the agent returns real contact records.
  </Step>
</Steps>

## Best Practices

* **Least privilege** — enable only the scopes you need. Skip write scopes for read-only agents.
* **Rotate tokens periodically** — revoke and recreate the token if it's ever exposed.
* **Use clear app names** — distinguish multiple workspaces (e.g., "Scout Prod", "Scout Staging").
* **Review unused apps** — private apps don't expire, so clean up old ones you no longer use.

## Instruction Guardrails

CRM writes are consequential. A bad update can corrupt a record, create a duplicate, or overwrite data another rep entered. Add this block to your agent's **Instructions** before enabling any write tools:

```markdown theme={null}
For CRM tasks:

1. Look up the record before writing.
2. Match by stable identifier (record ID, email, domain) before updates.
3. Return the CRM object ID, fields changed, and reason after each write.
4. Ask before creating duplicates when confidence is low.
```

## Troubleshooting

| Issue                      | Solution                                                              |
| -------------------------- | --------------------------------------------------------------------- |
| "Invalid access token"     | Ensure you copied the full token — they're long and easy to truncate. |
| "Insufficient permissions" | Add the missing scope to your private app in HubSpot.                 |
| "App not found"            | Confirm the private app is active, not archived.                      |

## Next Steps

<CardGroup cols={2}>
  <Card title="CRM Overview" icon="database" href="/integrations/crm">
    Compare Salesforce and HubSpot, and connect both for teams that use them side by side.
  </Card>

  <Card title="Agents Overview" icon="robot" href="/agents/overview">
    Learn how to use HubSpot tools with agents and workflows.
  </Card>

  <Card title="Integrations Overview" icon="grid" href="/integrations/overview">
    See the full integration stack and recommended connection order.
  </Card>

  <Card title="Slack" icon="slack" href="/integrations/slack">
    Route pipeline summaries and deal alerts to your team channels.
  </Card>
</CardGroup>