​

Configuring HubSpot as a Source

​

1. Add account access

• Authentication Mode: The authentication mode to use. You can select Sign in with HubSpot (OAuth) or use a HubSpot private app token. If you choose to Sign in with HubSpot, you’ll be prompted to log in with an account that has Super Admin permissions in order to install the Nekt app into the workspace.
• Start Date: The date of the first record you want to sync with.
• Enable Leads Stream (Optional): Enable to extract leads data (requires HubSpot Pro, Enterprise, or Enterprise Plus).
• Associations (Optional): Configure which associations to extract per object type. Each entry specifies a HubSpot entity name (e.g. deals, contacts, companies, tickets, leads, calls, emails, meetings, notes, tasks, postal_mail, communication, or a custom object name) and a comma-separated list of associated entities to retrieve for that object. Custom object IDs (e.g. 2-12345) are also supported in the association list. Enable only if necessary, since it significantly increases the extraction time.
• Extract Contact Property History (Optional): Enable to track property changes for contacts. Enable only if necessary, since it significantly increases the extraction time.
• Contact Property History Fields (Optional): If enabled above, specify which properties to track (comma-separated). Default: lifecyclestage, lead_status.
• Extract Deal Property History (Optional): Enable to track property changes for deals. Enable only if necessary, since it significantly increases the extraction time.
• Deal Property History Fields (Optional): If enabled above, specify which properties to track (comma-separated). Default: dealstage.
• Extract Company Property History (Optional): Enable to track property changes for companies. Enable only if necessary, since it significantly increases the extraction time.
• Company Property History Fields (Optional): If enabled above, specify which properties to track (comma-separated). Default: name.
• Extract Ticket Property History (Optional): Enable to track property changes for tickets. Enable only if necessary, since it significantly increases the extraction time.
• Ticket Property History Fields (Optional): If enabled above, specify which properties to track (comma-separated). Default: hs_pipeline_stage, hs_ticket_priority.
• Property objects (Optional): Comma-separated list of HubSpot object types to fetch property definitions for. Default: calls, communication, company, contacts, deals, email, line_item, meeting, notes, postal_mail, product, task, tickets.
• Properties as JSON string (Optional): When enabled, the properties column in CRM object streams (contacts, companies, deals, tickets, etc.) is emitted as a JSON string instead of a structured object. Enable this if your HubSpot account has a very large number of custom properties and you are hitting destination limits on nested fields (e.g. BigQuery’s 10,000 field limit). Default: false.

​

2. Select streams

Tip: The stream can be found more easily by typing its name.

​

3. Configure data streams

• Layer: choose between the existing layers on your catalog. This is where you will find your new extracted tables as the extraction runs successfully.
• Folder: a folder can be created inside the selected layer to group all tables being created from this new data source.
• Table name: we suggest a name, but feel free to customize it. You have the option to add a prefix to all tables at once and make this process faster!
• Sync Type: you can choose between INCREMENTAL and FULL_TABLE. Read more about Sync Types here.

​

4. Configure data source

• Configure Delta Log Retention and determine for how long we should store old states of this table as it gets updated. Read more about this resource here.
• Determine when to execute an Additional Full Sync. This will complement the incremental data extractions, ensuring that your data is completely synchronized with your source every once in a while.

​

5. Check your new source

​

Streams and Fields

​

Available streams

​

Fields by stream

​

Data Model

​

Common data transformations

SELECT
	-- list the regular columns you want to see in the final table
	id,
	createdat,
	updatedat,
	archived,
	_nekt_sync_at,
	-- list the fields that come inside 'properties' column and you want to have a specific column for
	properties.name,
	properties.price,
	properties.description
FROM
   -- example: "nekt.raw"."hubspot_products"
	"nekt_layer"."table_name"

​

Common data transformations

SELECT
	-- list the regular columns you want to see in the final table
	id,
	createdat,
	updatedat,
	archived,
	_nekt_sync_at,
	-- list the fields that come inside 'properties' column and you want to have a specific column for
	properties.name,
	properties.price,
	properties.description
FROM
   -- example: "nekt.raw"."hubspot_products"
	"nekt_layer"."table_name"

​

Use Cases for Data Analysis

​

1. Sales Performance Analytics

-- Sales Performance Dashboard
WITH
   deal_metrics AS (
      SELECT
         d.properties.hubspot_owner_id AS hubspot_owner_id,
         o.firstname || ' ' || o.lastname AS owner_name,
         COUNT(*) AS total_deals,
         SUM(
            CAST(NULLIF(d.properties.amount, '') AS DECIMAL(15, 2))
         ) AS total_value,
         AVG(
            CAST(NULLIF(d.properties.amount, '') AS DECIMAL(15, 2))
         ) AS avg_deal_size,
         COUNT(
            CASE
               WHEN d.properties.dealstage = 'closedwon' THEN 1
            END
         ) AS won_deals,
         COUNT(
            CASE
               WHEN d.properties.dealstage = 'closedlost' THEN 1
            END
         ) AS lost_deals
      FROM
         "nekt_raw"."hubspot_deals" d
         LEFT JOIN "nekt_raw"."hubspot_owners" o ON d.properties.hubspot_owner_id = o.id
      WHERE
         CAST(SUBSTRING(d.properties.createdate, 1, 10) AS DATE) >= DATE_ADD ('month', -6, CURRENT_DATE)
      GROUP BY
         d.properties.hubspot_owner_id,
         o.firstname,
         o.lastname
   )
SELECT
   owner_name,
   total_deals,
   total_value,
   avg_deal_size,
   won_deals,
   lost_deals,
   ROUND((won_deals * 100.0 / total_deals), 2) AS win_rate,
   ROUND((total_value / NULLIF(total_deals, 0)), 2) AS avg_deal_value
FROM
   deal_metrics
ORDER BY
   total_value DESC

​

2. Customer Journey Analysis

-- Customer Journey Funnel
WITH
   contact_stages AS (
      SELECT
         properties.lifecyclestage,
         COUNT(*) AS contact_count,
         COUNT(
            CASE
               WHEN properties.lifecyclestage IN (
                  'lead',
                  'marketingqualifiedlead',
                  'salesqualifiedlead'
               ) THEN 1
            END
         ) AS qualified_leads,
         COUNT(
            CASE
               WHEN properties.lifecyclestage = 'opportunity' THEN 1
            END
         ) AS opportunities,
         COUNT(
            CASE
               WHEN properties.lifecyclestage = 'customer' THEN 1
            END
         ) AS customers
      FROM
         "nekt_raw"."hubspot_contacts"
      WHERE
         createdat >= DATE_ADD ('month', -12, CURRENT_DATE)
      GROUP BY
         properties.lifecyclestage
   ),
   funnel_metrics AS (
      SELECT
         'Total Contacts' AS stage,
         SUM(contact_count) AS COUNT,
         100.0 AS conversion_rate
      FROM
         contact_stages
      UNION ALL
      SELECT
         'Qualified Leads' AS stage,
         SUM(qualified_leads) AS COUNT,
         ROUND(
            (SUM(qualified_leads) * 100.0 / SUM(contact_count)),
            2
         ) AS conversion_rate
      FROM
         contact_stages
      UNION ALL
      SELECT
         'Opportunities' AS stage,
         SUM(opportunities) AS COUNT,
         ROUND(
            (SUM(opportunities) * 100.0 / SUM(qualified_leads)),
            2
         ) AS conversion_rate
      FROM
         contact_stages
      UNION ALL
      SELECT
         'Customers' AS stage,
         SUM(customers) AS COUNT,
         ROUND((SUM(customers) * 100.0 / SUM(opportunities)), 2) AS conversion_rate
      FROM
         contact_stages
   )
SELECT
   *
FROM
   funnel_metrics
ORDER BY
   COUNT DESC

​

Implementation Notes

• Stream Permissions: During the discovery phase, the connector verifies access to dynamic streams (such as custom objects). If the provided Private App Token lacks the necessary scopes for an object, the connector will gracefully skip that stream rather than failing the entire sync. If you notice missing streams, check your token’s scopes in HubSpot.
• API Limits & Performance: Extracting associations and property history involves an additional API call per record. The connector uses connection pooling to keep this efficient, but enabling associations for multiple object types simultaneously will still significantly increase sync duration. Enable these features only when necessary.
• Unified Associations Config: Associations are configured through a single associations array. Each entry targets one object type (e.g. deals, contacts) and lists the associated entities to retrieve as a comma-separated string (e.g. contacts, companies, tickets). Custom object IDs such as 2-12345 are supported in the association list.
• Custom Object Association Keys: To ensure compatibility with downstream systems, custom object association keys are sanitized. Keys that are custom object type IDs (e.g., 2-12345) or fully qualified names containing portal IDs are normalized to a stable format prefixed with custom_ (e.g., custom_2_12345). Standard association names (like contacts or companies) remain unchanged.
• Stream Discovery and Permissions: If the authenticated HubSpot account lacks the necessary scopes or subscription tier to access certain objects (e.g., Services, Leads), the connector will gracefully skip those streams during discovery and log a warning, rather than failing the entire setup.
• API Limits & Large Property Lists: HubSpot imposes a hard limit of 3,000 characters on /search API request bodies. For heavily customized objects (such as Contacts with hundreds of custom properties), the list of properties can exceed this limit. The connector dynamically evaluates the request size: if the limit would be exceeded, it falls back to a lean search strategy — first requesting only the replication keys via /search, then calling the /batch/read endpoint to hydrate the full property values in chunks of 100 records. This increases the number of API calls but guarantees all custom properties are extracted without failing due to HubSpot’s character constraints.
• Audit Logs limit: The HubSpot API enforces a strict hard limit of 365 days for retrieving historical audit logs. To prevent extraction failures, if your source configuration has a Start Date older than 365 days, the connector will automatically adjust it to 364 days ago to safely fetch the maximum history allowed. Additionally, if the API rejects a payload for requesting data out of this limit bounds, the connector will skip the stream without failing the entire pipeline.
• Search API and object_coordinates properties: HubSpot’s CRM Search API (which is used for Incremental syncs) does not support querying properties of type object_coordinates (such as hs_origin_object_coordinates). Due to this restriction, properties of this type are excluded from the extraction payload to prevent API errors during Incremental syncs. To extract these properties, you must perform an Additional Full Sync or set your Sync Type to Full table.

​

Skills for agents