Skip to main content

​
Overview

The HubSpot integration enables your agents to search, create, update, and manage CRM records across all HubSpot object types. Works with contacts, companies, deals, tickets, and any other standard or custom objects in your account.

​
Features

  • Powerful Search: Filter and sort any object type with full AND/OR logic, pagination, and property selection
  • Full CRUD: Create, read, update, upsert, and delete records on any object type
  • Association Management: List, create, and remove links between records (e.g., contacts to companies, deals to contacts)
  • Schema Discovery: Agents can discover available properties and field types at runtime, including picklist options
  • Batch Upsert: Insert or update multiple records at once using a unique identifier property (e.g., email)
  • Unified Object API: All tools work with any HubSpot object type — just specify the object name

​
Prerequisites

  • Active HubSpot account
  • A Service Key (recommended) or Private App access token
  • Appropriate scopes for the objects your agent needs to access

​
Setup Guide

1

Create a Service Key

In HubSpot, navigate to Development > Keys > Service Keys and click Create service key. Give it a descriptive name (e.g., “Aster Agents”).Add the scopes your agent needs. At minimum:
  • crm.objects.contacts (read + write)
  • crm.objects.companies (read + write)
  • crm.objects.deals (read + write)
  • crm.objects.tickets (read + write)
  • crm.schemas.contacts (read)
  • crm.schemas.companies (read)
  • crm.schemas.deals (read)
  • crm.schemas.tickets (read)
Add additional object scopes as needed (e.g., crm.objects.leads, crm.objects.products).Copy the generated token (starts with pat-).
Service Keys require the Super Admin role or Developer Tools permission to create. If you don’t have access, ask your HubSpot admin to create the key for you.
2

Enable HubSpot Integration

In Aster Agents, navigate to Control Hub > Integrations and locate the HubSpot card. Click Connect to begin setup.
3

Configure Connection

Provide your HubSpot access token:
  • Access Token: The pat- token from Step 1
4

Add Tools to Your Agent

Edit your agent and enable the HubSpot tools you need:
  • Search HubSpot — find records with filters, sorting, and pagination
  • Manage HubSpot Records — create, read, update, upsert, and delete records
  • Manage HubSpot Associations — link and unlink records
  • Get HubSpot Schema — discover properties and field types
We recommend enabling all four — the agent uses Get Schema to learn your account’s property names before searching or writing data.

​
Available Tools

​
Search HubSpot

Search and filter any CRM object type with full query support:
  • Free-text search across default searchable properties
  • Structured filters with AND/OR logic (up to 5 groups, 6 filters each)
  • Property selection — choose which fields to return
  • Sorting by any property
  • Cursor-based pagination for large result sets

​
Manage HubSpot Records

Perform CRUD operations on any object type:
  • get — retrieve a record by ID with optional property selection
  • create — create a new record with properties and optional associations
  • update — update specific properties on an existing record
  • upsert — batch insert or update records using a unique identifier (e.g., email for contacts)
  • delete — archive a record by ID

​
Manage HubSpot Associations

Manage relationships between records:
  • list — view all associations of a specific type for a record
  • create — link two records with a specific association type
  • remove — unlink two records

​
Get HubSpot Schema

Discover your account’s data model at runtime:
  • Returns all properties for an object type, grouped by category
  • Includes property names, labels, types, and descriptions
  • Shows picklist options for enumeration properties
This is essential for agents to learn your account’s custom properties before making searches or creating records.

​
Security Considerations

  • Use scoped Service Keys — only grant the scopes your agent actually needs
  • Rotate keys periodically — Service Keys support rotation with a 7-day grace period
  • Monitor key activity — check last-used timestamps in HubSpot’s Service Keys dashboard
  • Use a dedicated key per integration — avoid sharing keys across multiple systems
  • Test with limited scopes first — start with read-only scopes and add write access as needed

​
Troubleshooting

  • Verify your access token is correct and starts with pat-
  • Check that the Service Key hasn’t been deactivated in HubSpot
  • If the token was recently rotated, ensure you’re using the new token
  • HubSpot returns a MISSING_SCOPES error when the Service Key doesn’t have permission for the requested operation
  • Go to Development > Keys > Service Keys in HubSpot, edit the key, and add the required scopes
  • Schema scopes (e.g., crm.schemas.contacts.read) are needed for the Get Schema tool
  • HubSpot limits private apps and Service Keys to 150 requests per 10 seconds
  • If you hit rate limits, the tool will return a descriptive error with the retry-after duration
  • For bulk operations, use the batch upsert action instead of individual creates/updates
  • Newly created or updated records may take a few moments to appear in search results
  • Archived records do not appear in search — use the get action with a record ID instead
  • Search is limited to 10,000 total results per query — use more specific filters if needed