> For the complete documentation index, see [llms.txt](https://docs.dos.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.dos.ai/dosclaw/plugins-and-connectors/crm/hubspot.md).

# HubSpot CRM

Connect your HubSpot CRM account to DOSClaw AI agents. Enable customer service, sales development (SDR), and account management agents to search contacts, look up company profiles, check active deal stages, and inspect pipeline health in real time.

## Capabilities & MCP Tools

| MCP Tool              | Operation | Description                                                                                                 |
| --------------------- | --------- | ----------------------------------------------------------------------------------------------------------- |
| `search_contacts`     | Read      | Search CRM contacts by email, phone, or name. Returns contact properties, lifecycle stage, and lead status. |
| `get_contact_detail`  | Read      | Retrieve complete contact record including owner ID, associated company, and custom properties.             |
| `search_companies`    | Read      | Query companies by domain or name. Returns company revenue, industry, and phone.                            |
| `search_deals`        | Read      | Search active and closed deals by name, pipeline, or associated contact/company.                            |
| `get_pipeline_stages` | Read      | Fetch deal pipelines, stages, probability percentages, and stage IDs.                                       |

***

## Prerequisites

1. An active **HubSpot account** (Free, Starter, Professional, or Enterprise).
2. Super Admin or App Marketplace installation permissions in your HubSpot portal.

***

## Setup Guide

### Step 1: Connect via HubSpot OAuth

1. In the **DOS.AI Dashboard**, navigate to **Integrations** $\rightarrow$ **HubSpot CRM**.
2. Click **Connect with HubSpot**.
3. You will be redirected to HubSpot's official authorization screen (`app.hubspot.com`).
4. Select your target HubSpot Account / Portal.
5. Review the requested CRM scopes:
   * `crm.objects.contacts.read`: Search and read contacts.
   * `crm.objects.companies.read`: Search companies.
   * `crm.objects.deals.read`: Look up deals and pipelines.
   * `crm.schemas.contacts.read`: Retrieve custom property mappings.
6. Click **Connect app**.
7. DOS-Me securely encrypts and vaults the generated OAuth tokens.

### Step 2: Bind to Your Agent

1. Open your agent $\rightarrow$ **Integrations** $\rightarrow$ enable **HubSpot CRM**.
2. Configure permissions:
   * **Allowed Objects**: Toggle Contacts, Companies, and Deals.
3. Click **Save Changes**.

***

## Example Conversational Workflows

### Contact & Lead Verification

When a customer interacts with your agent on WhatsApp, Telegram, or Web Chat:

> **Customer**: "Chào bạn, mình là Hoàng từ công ty ABC Logistics (email: <hoang@abclogistics.vn>). Dự án trước báo giá đến đâu rồi?"\
> **AI Agent**: Calls `search_contacts({ "email": "hoang@abclogistics.vn" })` followed by `search_deals({ "associated_contact_id": "189421" })`\
> **Response**: "Dạ chào anh Hoàng! Em thấy trên hệ thống hợp đồng triển khai giải pháp kho vận của ABC Logistics đang ở giai đoạn **Thương thảo hợp đồng** do chuyên viên Nguyễn Văn Nam phụ trách. Anh Nam đã gửi bản phụ lục hôm qua qua email của anh. Anh có cần em kết nối trực tiếp với anh Nam không ạ?"

***

## Security & Architecture

* **No Third-Party Brokers**: Unlike generic integration wrappers, DOS.AI connects directly to HubSpot's official API (`api.hubapi.com`). No third-party data broker touches your customer records.
* **Zero-Secret Containers**: Agents execute tools through the DOSClaw Gateway runtime. Access tokens are dynamically injected per request and never stored in agent disk memory or LLM contexts.

***

## Troubleshooting

| Issue                             | Cause                   | Solution                                                                           |
| --------------------------------- | ----------------------- | ---------------------------------------------------------------------------------- |
| 403 Forbidden on Deals            | Missing deal scopes     | In HubSpot, verify your user account has access to the Sales Hub and Deals object. |
| Contact search returns no records | Strict query formatting | Search by exact email or international phone format (e.g. `+84901234567`).         |
| Token refresh failure             | Portal uninstalled app  | Re-click **Connect with HubSpot** in the dashboard to re-authorize.                |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.dos.ai/dosclaw/plugins-and-connectors/crm/hubspot.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.