For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to page URLs.
Skip to content

HubSpot

HubSpot batch source. Extracts CRM objects (contacts, deals, companies, tickets, products, custom objects) as full-refresh snapshots via the Private App API.

HubSpot is a CRM platform covering marketing, sales, customer service, and operations. Nilus uses HubSpot as a batch source to extract CRM objects, companies, contacts, deals, tickets, products, custom objects, into a downstream warehouse for revenue and support analytics.

Under the hood, Nilus calls the HubSpot CRM API using a Private App access token. CRM objects are fetched as a full snapshot per run; HubSpot does not support incremental loading via this connector.

Requirements

Connectivity and credentials must both be in place before the pipeline can run.

Connectivity

  • The Nilus runtime must be able to reach https://api.hubapi.com over HTTPS.

  • The Private App must hold the relevant crm.objects.<object>.read and crm.schemas.read scopes for every object in source_table.

  • Missing scopes cause 403 Forbidden errors at runtime.

Private App tokens give CRM-wide read access. Store the token via Nilus secrets/projections rather than embedding the literal value in YAML.

Required parameters

Parameter
Required
Default
Description

api_key

Yes

-

HubSpot Private App access token (pat-...). Created in HubSpot → Settings → Integrations → Private Apps.

URI format

hubspot://?api_key=<hubspot-private-app-access-token>

Supported objects

Object
Merge key
Strategy
Description

companies

-

replace

Organization records.

contacts

-

replace

Leads and customers.

deals

-

replace

Sales deals.

tickets

-

replace

Support tickets.

products

-

replace

Product catalog.

quotes

-

replace

Sales quotes.

schemas

name

merge

CRM schema definitions for all objects.

custom:<object_name>

-

replace

Custom CRM object.

custom:<object_name>:<assoc1,assoc2>

-

replace

Custom object with associations expanded inline (passed to HubSpot's associations parameter).

Custom object examples

Ingest a custom object:

Include associations (comma-separated, passed straight to HubSpot's associations parameter):

Behavior

  • The full dataset is retrieved on every run (HubSpot pagination handled internally).

  • Schemas are inferred from the API response.

  • Nested JSON fields are preserved as structured data.

  • Associations are returned as nested arrays when requested.

Source options

Option
Required
Description

source_table

Yes

One of the resources in the supported objects table.

incremental_key

Not supported

HubSpot ingestion is full-refresh; do not set an incremental cursor.

Sink options

Option
Required
Description

dest_table

Yes

Destination table name. Use one stable target per source resource so re-runs merge cleanly.

incremental_strategy

Yes

Destination write behavior. Use merge for time-aware resources, replace for snapshot-style resources.

Sample Nilus config

Behavior and capabilities

  • Pipeline type: HubSpot runs as a batch source.

  • Object selection: set source.options.source_table to one CRM object, schemas, or custom:<object_name> form from the supported objects table.

  • Fetch semantics: HubSpot ingestion is full-refresh for CRM objects; use replace unless the object explicitly documents a merge key.

  • Associations: custom object associations can be expanded by appending comma-separated association names to source_table.

  • API limits: HubSpot enforces account-level API limits. For large accounts, split high-volume objects into separate pipelines and stagger schedules.

Troubleshooting

Symptom
Likely cause
Resolution

401 Unauthorized

Invalid or expired Private App token.

Issue a new Private App in HubSpot → Settings → Integrations → Private Apps and re-supply via Nilus secrets.

403 Forbidden

Private App is missing scopes for the requested object.

Add the crm.objects.<object>.read and crm.schemas.read scopes and reissue the token.

429 Too Many Requests

HubSpot account-level rate limit exceeded by frequent or parallel pipelines.

Reduce pipeline frequency, stagger parallel pipelines, or upgrade the HubSpot plan.

Custom object not found

Wrong API name in custom:<name> (HubSpot custom objects use the developer-facing API name, not the label).

Find the API name in HubSpot → Settings → Objects → Custom Objects.

Last updated

Was this helpful?