HubSpot Platform Guide

HubSpot is JetStack AI’s primary supported platform. This guide covers everything you need to know about how JetStack AI interacts with HubSpot, including supported asset types, required permissions, API constraints, portal tier differences, and platform-specific behaviors that affect implementations and audits.

Supported Asset Types

JetStack AI supports importing and deploying 25+ HubSpot asset types across three plan tiers. Each asset type is fully parsed during import, stored in your Asset Library with all configuration intact, and recreated with proper ID remapping during deployment.

CRM Assets (Pro Plan)

Asset Type	Description	Key Capabilities
Workflows	Contact, company, deal, ticket, and custom object workflows	Full action tree, branching logic, enrollment triggers, goal criteria, re-enrollment settings
Lists	Static and dynamic (active) lists	All filter types including TIME_RANGED, property-based, event-based, form submission, page view, and list membership filters
Forms	All form types including embedded, standalone, and pop-up	Field configuration, progressive profiling, dependent fields, validation rules, submission actions, redirect URLs
Emails	Regular, A/B test, automated, RSS, and blog subscription emails	Full HTML/template content, smart content rules, A/B variants, subscription types, reply-to settings
Pipelines	Deal pipelines, ticket pipelines, and custom object pipelines	Stage configuration, stage order, probability values, pipeline-level settings
Properties	Contact, company, deal, ticket, and custom object properties	Field type, group assignment, option values, calculated property formulas, display order
Association Labels	Custom association labels between object types	Label text, association category, inverse labels
Custom Objects	Custom object schema definitions	Object properties, required properties, searchable properties, association definitions

CMS Assets (Pro Plan)

Asset Type	Description	Key Capabilities
Site Pages	Website pages built on HubSpot CMS	Template assignment, module content, meta descriptions, featured images, slug configuration
Landing Pages	Standalone landing pages	Same as site pages plus conversion-specific settings
Templates	Page templates, email templates, blog templates, partial templates, global templates, and drag-and-drop (DND) area templates	Full template source code, module references, generated_layouts path resolution
Template Modules	Custom modules used within templates	Module fields, module HTML/CSS/JS, default values, field groups
Blog Posts	Individual blog articles	Post content, author, tags, featured image, meta description, publish date
Blogs	Blog configuration (the blog itself, not individual posts)	Blog settings, subscription settings, template assignment, listing page configuration
HubDB Tables	Structured data tables	Column definitions, row data, foreign ID columns, published state, CDN caching settings
Email Templates	Coded email templates (separate from drag-and-drop emails)	Template source, smart rules, module references

Ultimate Assets (Ultimate Plan)

Asset Type	Description	Key Capabilities
Dashboards	Custom reporting dashboards	Dashboard layout, report placement, filter configuration
Reports	Custom reports and analytics	Report type, data sources, filters, visualization settings
Snippets	Reusable text blocks for sales and service	Snippet content, shortcut text
Goal Templates	Sales and service goal configurations	Goal type, target metrics, tracking periods
Lead Scores	Lead scoring rules and configurations	Scoring criteria, positive/negative attributes, score thresholds
CRM Cards	Custom CRM card definitions	Card properties, data fetch URLs, display configuration
Preview Views	Custom preview configurations	View settings, display rules
Playbooks	Sales/service playbook definitions	Playbook steps, question types, required fields, outcome tracking
Permission Sets	Custom user permission configurations	Permission categories, access levels

Required OAuth Scopes

When you connect a HubSpot portal to JetStack AI, the OAuth flow requests specific scopes depending on how you intend to use the portal. JetStack AI uses two connection types: Implementation (for importing and deploying assets) and Audit (for running portal audits). You can also connect a portal for both.

Implementation Scopes

Scope	What It Enables
content	Read/write access to CMS pages, templates, blog posts, HubDB tables
automation	Read/write access to workflows
forms	Read/write access to forms
e-commerce	Read/write access to products and line items (used by some pipeline features)
crm.objects.contacts.read	Read contact records for workflow enrollment context
crm.objects.contacts.write	Write contact properties during deployment
crm.objects.companies.read	Read company records
crm.objects.companies.write	Write company properties during deployment
crm.objects.deals.read	Read deal records and pipeline data
crm.objects.deals.write	Write deal properties and pipeline stages
crm.objects.custom.read	Read custom object schemas and records
crm.objects.custom.write	Create custom object schemas during deployment
crm.schemas.contacts.read	Read contact property definitions
crm.schemas.contacts.write	Create/update contact properties
crm.schemas.companies.read	Read company property definitions
crm.schemas.companies.write	Create/update company properties
crm.schemas.deals.read	Read deal property definitions
crm.schemas.deals.write	Create/update deal properties
crm.schemas.custom.read	Read custom object property definitions
tickets	Read/write access to tickets and ticket pipelines
files	Read/write access to the file manager (for image upload during deployment)

Audit Scopes

Audit connections request read-only scopes across the same categories. No write scopes are requested for audit-only connections.

API Rate Limits

HubSpot enforces a rate limit of 100 requests per 10 seconds for OAuth-authenticated apps. This applies globally across all API calls made by the app for a given portal.

How JetStack AI Handles Rate Limits

• Exponential backoff — When JetStack AI receives a 429 Too Many Requests response, it waits and retries with exponentially increasing delays
• Rate limit header parsing — JetStack AI reads the X-HubSpot-RateLimit-Interval-Milliseconds and X-HubSpot-RateLimit-Remaining headers to proactively throttle before hitting limits
• Per-operation retry — Each individual API call within an import or deployment retries independently, so a rate limit on one call does not fail the entire operation
• Maximum retries — After a configurable number of retries (default: 3 per call), the operation is marked as failed with a clear error message

Impact on Operations

Operation	Typical API Calls	Approximate Duration
Single asset import	5-15 calls	2-5 seconds
Full workflow import with dependencies	50-200 calls	30-120 seconds
Full portal audit (Quick Mode)	200-500 calls	2-5 minutes
Full portal audit (Full Mode)	500-2000 calls	5-15 minutes
Single asset deployment	10-30 calls	5-15 seconds
Module deployment (20 assets)	200-500 calls	2-8 minutes

Portal Tiers

HubSpot offers four portal tiers, and available features vary significantly between them. JetStack AI adapts to the tier of each connected portal.

Feature	Free	Starter	Professional	Enterprise
Workflows	Not available	Limited	Full	Full
Custom reports	Not available	Not available	Full	Full
Calculated properties	Not available	Not available	Full	Full
Custom objects	Not available	Not available	Not available	Full
Lead scoring	Not available	Not available	Professional	Advanced
Content partitioning	Not available	Not available	Not available	Full
Adaptive testing (A/B)	Not available	Not available	Full	Full
Blog	Not available	Starter level	Full	Full
HubDB	Not available	Not available	Full	Full
Playbooks	Not available	Not available	Professional	Full

Tier Impact on Implementations

When deploying assets to a destination portal, JetStack AI checks whether the target portal’s tier supports each asset type. If you attempt to deploy a workflow to a Free portal or a custom object to a Professional portal, the deployment will fail with a clear tier mismatch error.

Recommendation: Always verify that your destination portal tier supports the asset types you intend to deploy before starting a deployment.

HubSpot-Specific Quirks

Working with the HubSpot API involves several platform-specific behaviors that JetStack AI handles automatically. Understanding these can help you diagnose issues when they arise.

v2 vs v3 API Differences

HubSpot maintains two major API versions, and not all features are available on both:

• Forms: The v3 Forms API does not expose all field-level configuration. JetStack AI uses the v2 Forms API to capture dependent fields, progressive profiling rules, and certain validation settings that v3 omits.
• Emails: Marketing email creation uses the v3 API, but certain properties (like campaign group IDs) require v1 endpoints.
• Templates: Template retrieval and creation use a mix of v2 and v3 calls depending on the template type.

Generated Layouts Path

HubSpot templates reference layout modules through a generated_layouts path in the file system. During import, JetStack AI resolves these paths to capture the full template structure. During deployment, the paths are recreated in the destination portal’s file system. If a template references a custom module, that module must be imported and deployed first.

Campaign Group IDs

HubSpot associates emails and other marketing assets with campaign groups using internal IDs. These IDs are portal-specific and cannot be transferred between portals. During deployment, JetStack AI creates new campaign groups in the destination portal or maps to existing ones by name.

CSRF Tokens for Internal APIs

Some HubSpot features expose data only through internal (non-public) APIs that require CSRF token authentication. The JetStack AI browser extension handles CSRF token acquisition automatically when capturing data that requires these internal endpoints. This primarily affects audit data capture for features like content partitioning settings, internal analytics, and certain pipeline configurations.

TIME_RANGED Filter Timezone Issues

HubSpot lists that use TIME_RANGED filter operations have known timezone handling quirks:

• The API returns an upperBoundEndpointBehavior field (not upperBoundEndpoint — the field name is inconsistent with HubSpot’s own documentation)
• IANA timezone identifiers (e.g., America/New_York) are rejected on POST; only legacy timezone strings (e.g., US/Eastern) are accepted
• indexReference.referenceType values of MONTH are rejected — only TODAY and NOW are valid on the creation endpoint

JetStack AI handles all three of these quirks automatically during deployment by remapping field names, converting IANA timezones to their legacy equivalents, and transforming unsupported reference types.

System Properties

HubSpot has 131+ system properties that are read-only and cannot be created or modified through the API. These include properties like createdate, hs_object_id, hs_pipeline, and many others prefixed with hs_. During deployment, JetStack AI skips these properties automatically rather than failing. If a workflow or list filter references a system property, JetStack AI maps to the existing property in the destination portal rather than attempting to create it.

Property Type Restrictions

When deploying properties, if a property with the same internal name already exists in the destination portal but has a different type (e.g., the source has a number field and the destination has a string field), HubSpot rejects the update. JetStack AI handles this by applying a suffix strategy — creating the property with a modified name and logging the discrepancy for manual review.

Next Steps

• Implementations Overview — Understand the full import-deploy lifecycle
• Supported Asset Types — Detailed breakdown of what is captured per asset type
• Connecting Your First Portal — Step-by-step OAuth connection walkthrough
• Import Failures — Troubleshoot HubSpot-specific import issues
• Deploy Failures — Troubleshoot HubSpot-specific deployment issues