> ## Documentation Index
> Fetch the complete documentation index at: https://forest-chore-open-api.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Hubspot

> Connect to Hubspot CRM data including contacts, companies, deals, and tickets

<Note>Only available for Node.js. This is a read-only datasource.</Note>

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

```javascript theme={null}
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

```javascript theme={null}
createHubSpotDataSource({
  accessToken: process.env.HUBSPOT_ACCESS_TOKEN
})
```

### Rate limiting

The datasource includes built-in rate limiting using Bottleneck:

```javascript theme={null}
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:

```javascript theme={null}
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:

```javascript theme={null}
// 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](/product/process/segments/smart-segments/overview)

## 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`](https://github.com/ForestAdmin/forestadmin-experimental/tree/main/packages/datasource-hubspot-translation).