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 activities, manage associations, and operate marketing lists.

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 and adds qualifying contacts to them

How It Works

OAuth Connection          Schema Discovery          Agent Tools
        |                        |                       |
        v                        v                       v
+-----------------+       +-----------------+     +-----------------+
| Admin authorizes|  ->   | Auto-discover   | ->  | 3 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 three 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. Subscription Plan - HubSpot CRM integration requires the Workforce or Platform plan
2. HubSpot Account - You need an active HubSpot account (Free tier or above for core CRM)
3. Admin Access - You must be an admin on the HubSpot account to authorize the OAuth connection

info

Enterprise tier is required for custom objects.

Step 1: Navigate to HubSpot Connection

1. Go to Capabilities > 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 Workforce > Agents > Agents & SMEs
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, three tools are automatically created and made available for agent assignment. Each tool covers one HubSpot resource and exposes several actions on it.

1. HubSpot Records (hubspot_records)

Contacts, companies, and deals: search, read, create, update, archive, and link them to other records.

Action	Description
search	Find records of one type by free text, filters, or both at once
get	Read one record in full, including its linked records when requested
create	Create a new record, optionally linked to other records
update	Update one or more properties on an existing record
delete	Archive a record to the portal recycle bin (only a HubSpot user can restore it, within 90 days)
link / unlink	Associate or disassociate two records (e.g., a contact and a deal)
list_links	List a record's existing associations

Example use: "Find all deals in the negotiation stage worth more than $50,000" or "Create a new contact for Jane Doe at jane@example.com and associate her with the Acme Corp company"

2. HubSpot Activities (hubspot_activities)

Notes, tasks, calls, and meetings logged against records: list, read, and create them.

Action	Description
list	List activities of one type, optionally filtered to those linked to a record
get	Read one activity in full, by its ID
create	Log a new activity, optionally linked to one or more records

Email engagements are not available. HubSpot does not grant the required permission (crm.objects.emails.read) to a connected app, so there is no setting or re-authorization that can enable them. To give an agent email context, use the mailbox integration instead.

Activity 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

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

3. HubSpot Lists (hubspot_lists)

Marketing lists: find, read, and create lists, and add or remove the contacts that belong to them.

Action	Description
list	Find lists by free text, or list every list when no query is given
get	Read one list in full, by its ID
create	Create a new list, either manual or dynamic membership
link / unlink	Add or remove one or more contacts from a list
list_links	List the members of a list

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 Workforce > Agents > Agents & SMEs
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_records (its search and get actions) for read-only CRM lookups
• Operations agents - Enable all three tools for full CRM management
• Email agents - Enable hubspot_records and hubspot_activities 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 Capabilities > 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 Capabilities > 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_records.search to find contacts, companies, or deals
2. Use hubspot_records.get 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 hubspot_records (its read-only actions) and add its write actions as needed
• Assign hubspot_activities to agents that handle meeting follow-ups or task creation
• Reserve hubspot_lists for agents that manage marketing list operations
• Use hubspot_records' link/unlink actions when agents need to connect 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 Runs - View tool execution logs