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

# HubSpot

## Overview

HubSpot tools give your agents access to a wide range of HubSpot objects. Agents can make account summaries and create contacts, deals, opportunities, tickets, and more.

This document provides general information about our HubSpot tools (available tools, setup and authentication) but as the tool will likely evolve, the fresh list of available tools can be found when you are actually connecting the Hubspot tool in your workspace.

## Available Tools

| Tool | Description |
| - | - |
| Get Object Properties | Lists all available properties for a HubSpot object. When creatableOnly is true, returns only properties that can be modified through forms (excludes hidden, calculated, read-only and file upload fields). |
| Create Contact | Creates a new contact in Hubspot, with optional associations. |
| Get Object By Email | Retrieves a Hubspot object using an email address. Supports contacts, companies, deals, owners. |
| Count Objects By Properties | Count objects in Hubspot with matching properties. Supports contacts, companies, deals. Max limit is 10000 objects. |
| Get Latest Objects | Get latest objects from Hubspot. Supports contacts, companies, deals. Limit is 50. |
| Create Company | Creates a new company in Hubspot, with optional associations. |
| Create Deal | Creates a new deal in Hubspot, with optional associations. |
| Create Lead | Creates a new lead in Hubspot (as a Deal), with optional associations. Ensure properties correctly define it as a lead. |
| Create Task | Creates a new task in Hubspot, with optional associations. |
| Create Ticket | Creates a new ticket in Hubspot, with optional associations. |
| Create Note | Creates a new note in Hubspot, with optional associations. |
| Create Communication | Creates a new communication (WhatsApp, LinkedIn, SMS) in Hubspot as an engagement. Requires hs\_communication\_channel\_type in properties. |
| Create Meeting | Creates a new meeting in Hubspot as an engagement. Ensure hs\_engagement\_type='MEETING' and meeting details are in properties. |
| Get Contact | Retrieves a Hubspot contact by its ID. |
| Get Company | Retrieves a Hubspot company by its ID. |
| Get Deal | Retrieves a Hubspot deal by its ID. |
| Get Meeting | Retrieves a Hubspot meeting (engagement) by its ID. |
| Get File Public Url | Retrieves a publicly available URL for a file in HubSpot. |
| Get Associated Meetings | Retrieves meetings associated with a specific object (contact, company, or deal). |
| Search Crm Objects | Searches CRM objects, including contacts, companies, deals, leads, tickets, and activity records such as tasks, notes, meetings, calls, and emails. |
| Export Crm Objects Csv | Exports any object type, including tickets, to a CSV file for table queries, up to 2,000 rows per export. |

## Tickets

Tickets are a supported object. Your agent can search tickets and their fields (status, pipeline, priority, ticket content) with Search Crm Objects, create tickets with Create Ticket, and export a list of tickets to CSV with Export Crm Objects Csv.

There isn't a dedicated tool to pull a ticket's full history in one go. Listing associations currently only works for contacts, companies, and deals, so a ticket's related emails, notes, and calls aren't reachable that way today. If your agent needs a ticket's related activity, have it search those activity records directly and match them to the ticket.

## Workspace Setup and Authentication

See [Managing Tools](https://docs.ruby.ad/docs/user-documentation/admins/tools-management/adding-an-mcp-server.md) for details on how to make HubSpot tools available to your workspace. The setup will require authentication to HubSpot by the admin. Through the OAuth flow the admin will select that will be accessible by this integration.

When connecting the tool as an admin, you will be able to pick between **Personal** and **Workspace** authentication.

* **Workspace** means all agents will use the connecting admin's account when querying Hubspot
* **Personal** means users will need to authenticate the first time they use an agent that has Hubspot access and the actions will then be taken through their account (permissions, audit, etc)

If HubSpot reports that you do not have permission to install the app during OAuth, the user authorizing the app must be a Super Admin or have **App Marketplace Access** permission. Ask your HubSpot admin to grant the required permission, then retry the connection. See [HubSpot's app access guidance](https://knowledge.hubspot.com/integrations/manage-access-to-apps) for account-level restrictions.

## HubSpot permissions

When you connect HubSpot, Ruby asks HubSpot for the permissions (OAuth scopes) below. Only `oauth` is required. The others are optional: if your HubSpot account can't grant one, the connection still works, but agents can't reach the matching objects.

| HubSpot feature | Scopes |
| - | - |
| Contacts | `crm.objects.contacts.read`, `crm.objects.contacts.write`, `crm.schemas.contacts.read` |
| Companies | `crm.objects.companies.read`, `crm.objects.companies.write`, `crm.schemas.companies.read` |
| Deals | `crm.objects.deals.read`, `crm.objects.deals.write`, `crm.schemas.deals.read` |
| Leads | `crm.objects.leads.read`, `crm.objects.leads.write` |
| Owners | `crm.objects.owners.read` |
| Custom objects | `crm.schemas.custom.read`, `crm.objects.custom.read`, `crm.objects.custom.write` |
| Quotes and line items | `crm.objects.quotes.read`, `crm.objects.line_items.read` |
| Products | `crm.objects.products.read` |
| Lists | `crm.lists.read`, `crm.lists.write` |
| Tickets | `tickets` |
| Files | `files` |
| Sales emails | `sales-email-read` |
| Timeline events | `timeline` |
| Marketing emails | `marketing-email` |
| CMS content | `content` |

With **Personal** authentication, each user's connection can only get the permissions the **Workspace** connection was granted.

> [!NOTE]
>
> Marketing campaigns and campaign revenue reporting aren't covered: Ruby doesn't request `marketing.campaigns.read` or `marketing.campaigns.revenue.read`. Requests to the HubSpot `campaigns` object or revenue attribution fail with a `403 MISSING_SCOPES` error, and reconnecting HubSpot won't add these permissions. Reconnecting can only add scopes from the list above.

## Adding HubSpot Tools to agents

HubSpot tools can be added to an agent by selecting them in the agent builder. They require no configuration. Note that when connecting a tool, you can define the provided tools as high stake or low stake.

> [!WARNING]
>
> We highly recommend leaving any tool that can modify data in your CRM in HIGH
> STAKE.

In general you will want to mention in the instructions of your agents the objects you want them to interact with. Example instructions:

```text theme={null}
From the transcripts you are receiving, create a contact if you can't find any existing contact with the interlocutor's name or email, and if a deal has been set create a deal to attach to the current account.
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.