HubSpot CRM Integration

Connect your HubSpot CRM portal to enable AI agents to search contacts, manage deals, log activities, and run marketing operations with automatic schema discovery.

Overview

HubSpot CRM Integration allows your AI agents to interact with your HubSpot portal. The integration automatically discovers your portal's pipelines, custom properties, owners, and data model so agents know exactly what is available. Agents can search records, create and update contacts, companies, and deals, log engagements, manage associations, and operate marketing lists and campaigns.

Use Cases

• Deal Pipeline Review - Agent answers "What deals are in negotiation?" by searching deals filtered by pipeline and stage, returning names, amounts, close dates, and owners
• Contact Research - Agent responds to "Find everything about John Smith" by searching contacts, retrieving associations to deals and companies, and presenting a comprehensive profile
• Post-Meeting Follow-up - Agent logs meeting notes on a deal record and creates a follow-up task assigned to the appropriate owner with a due date
• New Lead Entry - Agent creates a new contact, associated company, and initial deal in the appropriate pipeline stage when told about a new prospect
• Marketing List Management - Agent creates targeted lists for campaigns, adds qualifying contacts, and tracks campaign performance

How It Works

OAuth Connection          Schema Discovery          Agent Tools
        |                        |                       |
        v                        v                       v
+-----------------+       +-----------------+     +-----------------+
| Admin authorizes|  ->   | Auto-discover   | ->  | 7 tools created |
| via HubSpot     |       | pipelines,      |     | with schema-    |
| OAuth 2.0       |       | properties,     |     | enriched        |
|                 |       | owners, objects  |     | descriptions    |
+-----------------+       +-----------------+     +-----------------+

When you connect your HubSpot account via OAuth, the system automatically discovers your portal's schema and creates seven dynamic tools. Tool descriptions are enriched with your actual pipeline names, stages, and custom properties so the LLM knows exactly what is available.

Getting Started

Prerequisites

Before connecting HubSpot:

1. HubSpot Account - You need an active HubSpot account (Free tier or above for core CRM)
2. Admin Access - You must be an admin on the HubSpot account to authorize the OAuth connection
3. Outermind Pro Plus - HubSpot CRM integration requires the Pro Plus subscription tier

info

Marketing Hub Professional or above is required for campaign operations. Enterprise tier is required for custom objects.

Step 1: Navigate to HubSpot Connection

1. Go to Build > Connections > HubSpot
2. You will see the HubSpot integration page with a summary of capabilities

Step 2: Connect HubSpot

1. Click Connect HubSpot
2. You will be redirected to HubSpot's authorization page
3. Sign in to your HubSpot account
4. Review the requested permissions and click Grant Access
5. You will be returned to Control Bridge with your connection established

tip

The OAuth flow requests only the scopes needed for core CRM operations. No HubSpot credentials are stored in Outermind.

Step 3: Review Schema Discovery

After connecting, the system automatically discovers your portal's schema:

• Deal Pipelines with stages and win probabilities
• Contact Properties including custom fields
• Company Properties including custom fields
• Deal Properties including custom fields
• Owners (HubSpot users available for record assignment)
• Custom Objects (Enterprise tier only)
• Lifecycle Stages and Association Types

Schema discovery runs automatically and typically completes within a few seconds.

Step 4: Assign Tools to Agents

1. Go to Build > AI Agents > Agents
2. Edit the agent that should use HubSpot
3. In the Tools section, find the HubSpot tools
4. Enable the tools you want the agent to use
5. Save the agent

Managing Your Connection

Connection Details

Each connection displays:

Field	Description
Portal Name	Your HubSpot portal display name
Hub ID	Unique HubSpot portal identifier
Status	Current connection status (Active, Error, Token Expired)
Connected By	Email of the user who authorized the connection
Last Schema Sync	When the schema cache was last refreshed

Token Management

HubSpot access tokens have a short lifetime and are refreshed automatically:

• Access Token - Expires after 30 minutes (auto-refreshed transparently)
• Refresh Token - Rotated on each refresh (no manual action required)

Token refresh happens automatically when an agent uses a HubSpot tool. If the refresh token becomes invalid (e.g., HubSpot app permissions changed), you will need to reconnect.

Refresh Schema

Click Refresh Schema to manually trigger a fresh discovery of your portal's pipelines, properties, owners, and custom objects. This is useful when you have made changes to your HubSpot data model, such as adding custom properties or creating new pipelines.

Disconnect

To disconnect your HubSpot portal:

1. Click the Disconnect button
2. Confirm the disconnection in the dialog

warning

Disconnecting removes all HubSpot tools and their agent assignments. Agents will no longer be able to access HubSpot data. You can reconnect at any time.

Schema Browser

The schema browser displays your portal's data model in four tabs.

Pipelines Tab

Shows all deal pipelines with their stages and win probabilities. For example:

Sales Pipeline
 |- Appointment Scheduled (20%)
 |- Qualified to Buy (40%)
 |- Proposal Sent (60%)
 |- Negotiation (80%)
 |- Closed Won (100%)
 |- Closed Lost (0%)

Agents use pipeline names and stage names directly in their queries, so any changes to your pipelines should be followed by a schema refresh.

Properties Tab

Displays all properties for contacts, companies, and deals, separated into standard and custom categories. Each property shows:

Column	Description
Name	Internal property name used in queries
Label	Display name shown in HubSpot
Type	Data type (string, number, date, enumeration, etc.)
Field Type	UI field type (text, select, checkbox, etc.)

Custom properties created in your portal appear alongside standard HubSpot properties, giving agents full visibility into your data model.

Owners Tab

Lists all HubSpot users who can be assigned as record owners. Agents use owner IDs when creating tasks or assigning records.

Custom Objects Tab

Displays custom object schemas discovered from your portal. Custom objects are only available on HubSpot Enterprise tier. If your portal does not have custom objects, this tab will be empty.

Available Tools

When you connect HubSpot, seven tools are automatically created and made available for agent assignment.

1. HubSpot Search (hubspot_search)

Search and query CRM records with filters, sorting, and free-text search.

Parameter	Description
objectType	The CRM object to search: contacts, companies, or deals
query	Free-text search across default searchable properties
filters	Array of filter objects with property, operator, and value
properties	Specific properties to return (omit for defaults)
sort	Sort by property name and direction
limit	Maximum results to return (1-100, default 20)

Example use: "Find all deals in the negotiation stage worth more than $50,000"

2. HubSpot Get Record (hubspot_get_record)

Retrieve full details of a specific record by ID, including associations to other records.

Parameter	Description
objectType	The CRM object type: contacts, companies, or deals
recordId	The HubSpot record ID
properties	Specific properties to return (omit for all)
includeAssociations	Object types to include associations for (e.g., contacts, deals)

Example use: "Get the full profile for contact ID 12345 including their associated deals"

3. HubSpot Create Record (hubspot_create_record)

Create a new contact, company, or deal with properties and optional associations.

Parameter	Description
objectType	The CRM object to create: contacts, companies, or deals
properties	Key-value pairs of properties to set on the new record
associations	Optional records to associate with the new record

Example use: "Create a new contact for Jane Doe at jane@example.com and associate her with the Acme Corp company"

4. HubSpot Update Record (hubspot_update_record)

Modify properties on an existing CRM record.

Parameter	Description
objectType	The CRM object type: contacts, companies, or deals
recordId	The HubSpot record ID to update
properties	Key-value pairs of properties to update

Example use: "Update the deal amount to $75,000 and move it to the Proposal Sent stage"

5. HubSpot Manage Associations (hubspot_manage_associations)

Create, remove, or list associations between CRM records.

Parameter	Description
action	create, remove, or list
fromObjectType	Source object type
fromObjectId	Source record ID
toObjectType	Target object type
toObjectId	Target record ID (required for create/remove)
associationLabel	Optional label (e.g., "Decision Maker", "Primary Company")

Example use: "Link contact John Smith to the Acme Corp renewal deal as Decision Maker"

6. HubSpot Engagements (hubspot_engagements)

Create and read activity records: notes, tasks, calls, meetings, and emails.

Parameter	Description
action	create, list, or get
engagementType	notes, tasks, calls, meetings, or emails
properties	Engagement-specific properties (see below)
associations	Records to associate the engagement with

Engagement properties by type:

Type	Key Properties
Notes	hs_note_body, hs_timestamp
Tasks	hs_task_subject, hs_task_body, hs_task_status, hs_task_priority, hubspot_owner_id
Calls	hs_call_body, hs_call_direction (INBOUND/OUTBOUND), hs_call_duration
Meetings	hs_meeting_title, hs_meeting_body, hs_meeting_start_time, hs_meeting_end_time
Emails	hs_email_subject, hs_email_text

Example use: "Log a note on the Acme deal that we discussed pricing and create a follow-up task for Sarah due next Friday"

7. HubSpot Marketing (hubspot_marketing)

Create and manage marketing lists, campaigns, and list membership.

Parameter	Description
action	create_list, get_list, search_lists, add_to_list, remove_from_list, get_list_members, create_campaign, get_campaign, search_campaigns, link_asset_to_campaign
listName	Name for new list
listType	MANUAL (static) or DYNAMIC (filter-based)
listId	List ID for membership operations
recordIds	Record IDs to add or remove from a list
campaignName	Name for new campaign
campaignProperties	Campaign properties (status, dates, audience, UTM)

Example use: "Create a static list called 'Q1 Renewals' and add all contacts associated with deals closing this quarter"

Assigning Tools to Agents

After connecting HubSpot:

1. Go to Build > AI Agents > Agents
2. Edit the agent that should use HubSpot tools
3. In the Tools section, find the HubSpot tools
4. Enable the tools appropriate for the agent's role
5. Save the agent

tip

Recommended tool assignments by agent type:

• Research agents - Enable hubspot_search and hubspot_get_record for read-only CRM lookups
• Operations agents - Enable all seven tools for full CRM management
• Email agents - Enable hubspot_search, hubspot_get_record, and hubspot_engagements for context-aware email handling

Rate Limiting

HubSpot tools include built-in rate limiting to protect your portal:

Limit Type	Value
Burst (OAuth apps)	110 requests per 10 seconds per portal
CRM Search	5 requests per second
Daily	Unlimited for OAuth apps

The integration handles rate limiting automatically:

• 429 responses trigger automatic retry with exponential backoff (up to 3 attempts)
• CRM search requests are throttled to stay under the 5/second limit
• Schema caching reduces API calls by storing pipeline, property, and owner data with intelligent TTLs (6-24 hours)

Troubleshooting

Connection Fails

Problem: OAuth authorization does not complete

Solutions:

1. Verify you are signed in to HubSpot as an admin
2. Check that your HubSpot account is active
3. Ensure pop-up blockers are not preventing the OAuth redirect
4. Try again in a private/incognito browser window

Token Expired

Problem: HubSpot tools return authentication errors

Solutions:

1. Token refresh is automatic; wait a moment and retry
2. If refresh fails, navigate to Build > Connections > HubSpot and check the connection status
3. If status shows "Token Expired", click Disconnect and reconnect via OAuth

Schema Not Showing Custom Properties

Problem: Custom properties you created in HubSpot do not appear

Solutions:

1. Click Refresh Schema to trigger a fresh discovery
2. Verify the custom property is not archived in HubSpot
3. Check that the property is assigned to the correct object type (contact, company, or deal)

Rate Limit Exceeded

Problem: Agents receive rate limit errors

Solutions:

1. The system retries automatically with backoff; most rate limit issues resolve on their own
2. If persistent, reduce the number of agents using HubSpot tools simultaneously
3. Review agent instructions to minimize unnecessary queries
4. Schema data is cached to reduce API calls; avoid frequent manual schema refreshes

Agent Cannot Find HubSpot Tools

Problem: HubSpot tools do not appear when editing an agent

Solutions:

1. Verify the HubSpot connection is active at Build > Connections > HubSpot
2. Confirm the connection status shows "Active" (not "Error" or "Disconnected")
3. Refresh the page
4. If you recently connected, wait a moment for tool creation to complete

Search Returns Empty Results

Problem: Valid queries return no data

Solutions:

1. Verify your HubSpot portal has data for the object type being searched
2. Check filter parameters match existing record values (property names are case-sensitive)
3. Test the same search directly in HubSpot to confirm data exists
4. Review the agent's instructions to ensure correct query formation

Security

Data Protection

• OAuth 2.0 authorization (no HubSpot credentials stored)
• Tokens encrypted with AES-256-CBC at rest
• Automatic token refresh every 30 minutes
• Refresh tokens rotated on each use
• Tenant isolation ensures each customer's portal is separate

Access Control

• Only authorized admin users can create or disconnect HubSpot connections
• Tool assignment controlled through agent configuration
• All tool executions logged for audit purposes
• One connection per tenant prevents cross-tenant data access

Audit Logging

Every HubSpot tool execution is recorded in the agent execution log, including:

• Tool name and action performed
• Object type and record count
• HubSpot portal ID
• Execution duration
• Associated agent and execution ID

Best Practices

Agent Instructions

Help your agents use HubSpot effectively by including guidance in their instructions:

When looking up CRM information:
1. Use hubspot_search to find contacts, companies, or deals
2. Use hubspot_get_record with includeAssociations to get full context
3. Summarize key details: name, email, deal stage, amount, owner
4. If creating records, always check for duplicates first

Schema Refresh

• Refresh schema after adding or modifying custom properties in HubSpot
• Refresh schema after creating new deal pipelines or stages
• Schema caches automatically with TTLs of 6-24 hours depending on the data type

Tool Assignment Strategy

• Start with read-only tools (hubspot_search, hubspot_get_record) and add write tools as needed
• Assign hubspot_engagements to agents that handle meeting follow-ups or task creation
• Reserve hubspot_marketing for agents that manage campaign operations
• Use hubspot_manage_associations when agents need to link records across object types

Related Topics

• Tools Overview - All available agent tools
• Agents - Configure agents to use tools
• HTTP API Tools - Connect other external APIs
• Agent Executions - View tool execution logs