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.comover HTTPS.The Private App must hold the relevant
crm.objects.<object>.readandcrm.schemas.readscopes for every object insource_table.Missing scopes cause
403 Forbiddenerrors at runtime.
Required parameters
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
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
incremental_key
Not supported
HubSpot ingestion is full-refresh; do not set an incremental cursor.
Sink options
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
batchsource.Object selection: set
source.options.source_tableto one CRM object,schemas, orcustom:<object_name>form from the supported objects table.Fetch semantics: HubSpot ingestion is full-refresh for CRM objects; use
replaceunless 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
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.
Related docs
Last updated
Was this helpful?