Skip to main content

​
Overview

HubSpot is a CRM platform whose records — contacts, companies, deals, tickets, and custom objects — are exposed through its CRM API. Datazone connects with a HubSpot private app access token and extracts one CRM object type per extract via the CRM Search API.

​
Prerequisites

Create a private app in your HubSpot account (Settings → Integrations → Private Apps), grant it read scopes for the object types you intend to extract, and copy its access token.

​
Connection Parameters

Set on the source when you create it. Names match the API and CLI payload.
​
string
required
Name — a unique identifier for your HubSpot source.
​
string
required
Access Token — the private app access token, for example pat-eu1-…. Stored encrypted.
​
string
default:"https://api.hubapi.com"
Base URL — HubSpot API base URL. Leave the default unless you have been given a region-specific host.

​
Extract Parameters

Set per extract, in source_parameters. See Shared Extract Parameters for mode, replication_key, and schema_mapping.
​
string
required
Object Type — the singular CRM object type to extract: contact, company, deal, ticket, or the name of a custom object.
​
string
Comma-separated list of properties to fetch, for example email,firstname,lastname,hubspot_owner_id,lifecyclestage.This replaces HubSpot’s default property set rather than adding to it. Only hs_object_id, createdate, and lastmodifieddate are always returned — every other field, including custom properties and owner fields, must be listed explicitly. Omit the parameter to get HubSpot’s default set. Discover available names with GET /crm/v3/properties/{object}.
​
integer
default:"100"
Records requested per API call. The Search API’s maximum is 200.
​
integer
default:"100"
Records written per batch on the Datazone side.
​
integer
default:"60"
Per-request timeout in seconds.
​
boolean
default:"false"
Whether to fetch archived records. The Search API returns active records only, so this has no effect on the current extraction path.
​
string
default:"2026-03"
CRM API version segment. Retained for compatibility; it does not affect the Search endpoint used for extraction.

​
Output Shape

Each record is flattened one level, so the schema stays stable across records regardless of which properties are populated: Because properties arrives as a JSON string, unpack the fields you need in a downstream pipeline transform.

​
Incremental Extraction

Records are read sorted by hs_object_id ascending, and each page is fetched with an hs_object_id > last_id filter. This sidesteps the Search API’s 10,000-record offset cap, so collections of any size can be extracted. In append mode the last id seen becomes the resume cursor.
Incremental extraction advances by object id, so it captures newly created records only — edits to records already extracted are not picked up. Schedule a periodic overwrite run to refresh updated records.

​
Required Permissions

Grant the private app read scopes for each object type you extract, for example:

​
Limitations

  • One CRM object type per extract
  • page_size is capped at 200 by the Search API
  • Rate limits (HTTP 429) and transient errors are retried automatically with backoff, which can extend the runtime of large extracts
  • Nested property values are JSON-stringified rather than expanded into columns

​
Next Steps

After configuring your HubSpot source:
  1. Create extracts to specify which CRM object types to ingest
  2. Configure scheduling for recurring extracts
  3. Unpack the properties JSON in a pipeline transform