Skip to main content
Only available for Node.js. This is a read-only datasource.
The Hubspot datasource connects to your Hubspot CRM through the HubSpot API, allowing you to browse and search contacts, companies, deals, tickets, and other CRM objects in Forest.

​
Basic usage

import { createAgent } from '@forestadmin/agent';
import { createHubSpotDataSource } from '@forestadmin-experimental/datasource-hubspot-translation';

const agent = createAgent(options);

agent.addDataSource(
  createHubSpotDataSource({
    accessToken: process.env.HUBSPOT_ACCESS_TOKEN
  })
);

​
Configuration options

​
Access token

Create a Private App in HubSpot to get an access token:
  1. Go to Settings → Integrations → Private Apps in your HubSpot account
  2. Create a new Private App
  3. Grant necessary scopes (contacts, companies, deals, tickets, etc.)
  4. Copy the access token
createHubSpotDataSource({
  accessToken: process.env.HUBSPOT_ACCESS_TOKEN
})

​
Rate limiting

The datasource includes built-in rate limiting using Bottleneck: 
createHubSpotDataSource({
  accessToken: process.env.HUBSPOT_ACCESS_TOKEN,
  rateLimiting: {
    maxConcurrent: 10,  // Maximum concurrent requests
    minTime: 100        // Minimum time between requests (ms)
  }
})
Default rate limits respect HubSpot API constraints:
  • Search API: 4 requests per second
  • Standard API: 100 requests per 10 seconds

​
Custom object configuration

Include custom HubSpot objects in your Forest: 
createHubSpotDataSource({
  accessToken: process.env.HUBSPOT_ACCESS_TOKEN,
  customObjects: ['2-12345678'] // Custom object IDs
})

​
Supported objects

The datasource automatically includes these standard HubSpot objects:
  • companies - Company records
  • contacts - Contact records
  • deals - Deal pipeline records
  • line_items - Product line items
  • products - Product catalog
  • quotes - Quote records
  • tickets - Support ticket records
  • owners - HubSpot user accounts
Custom objects can be added via configuration.

​
Read-only datasource

This datasource is read-only. You can:
  • Browse records
  • Search and filter
  • View relationships
  • Export data
You cannot:
  • Create new records
  • Update existing records
  • Delete records
For write operations, contact us for more info.

​
Filtering capabilities

The datasource supports filtering with these operators:
  • Equal - Exact match
  • NotEqual - Exclude matches
  • In - Match any value in list
  • LessThan, GreaterThan - Numeric/date comparisons
  • Contains - Text contains (limited support)
Limitation: Maximum 5 filter criteria per query due to HubSpot Search API constraints.

​
Relationships

The datasource attempts to map HubSpot associations to Forest relationships: 
// Example: Companies associated with Contacts
// Automatically exposed as relationships in Forest
However, relationships are limited:
  • No native relation support - Relationships are flattened or require manual configuration
  • Association API constraints - Complex associations may not work correctly

​
Pagination

Browse large datasets with automatic pagination:
  • Default page size: 100 records
  • Maximum page size: 100 records (HubSpot API limit)
  • Automatic “Load More” in Forest UI

​
Rate limiting and performance

The datasource handles HubSpot rate limits automatically: Search API limits:
  • 4 requests per second
  • Used for filtering and searching
Standard API limits:
  • 100 requests per 10 seconds
  • Used for basic CRUD operations
If you exceed rate limits, the datasource will queue requests and retry automatically.

​
Live Query

This datasource supports Live Query for advanced filtering and segmentation. Learn more about Live Queries

​
Limitations

  • Read-only - No create, update, or delete operations
  • No native relations - Relationships require manual configuration
  • Search constraints - Maximum 5 filter criteria per query
  • Rate limiting - Subject to HubSpot API rate limits
  • No real-time sync - Data is fetched on-demand, not cached
  • Association complexity - Complex multi-level associations may not work

​
HubSpot API token scopes

Your Private App token needs these scopes:
  • crm.objects.companies.read
  • crm.objects.contacts.read
  • crm.objects.deals.read
  • crm.objects.line_items.read
  • crm.objects.quotes.read
  • tickets
  • crm.objects.owners.read
For custom objects, add:
  • crm.objects.custom.read

​
Source code

This connector is open source. Browse the code or contribute on GitHub: @forestadmin-experimental/datasource-hubspot-translation.