HubSpot API: Complete Guide for Marketing Data Analysts (2026)

Marketing data analysts face a recurring challenge: HubSpot holds critical campaign, contact, and attribution data, but extracting it at scale requires constant API maintenance. Rate limits break dashboards. Schema changes invalidate pipelines. Custom properties multiply faster than documentation can keep up.

The HubSpot API is built to solve this. It gives you programmatic access to contacts, deals, campaigns, forms, and analytics data. With the right approach, you can automate data extraction, maintain clean pipelines, and surface HubSpot insights in your data warehouse or BI tool without manual exports.

This guide walks you through everything you need to use the HubSpot API effectively: authentication, core endpoints, rate limits, versioning, and real-world extraction patterns for marketing analytics.

Key Takeaways

✓ HubSpot has moved to date-based API versioning (e.g. 2026-03) with defined support windows before deprecation, replacing the older v3 structure

✓ Rate limits vary by subscription tier and endpoint type — bulk operations and search endpoints have separate quotas that require careful batching

✓ Campaign properties and events are now available as workflow triggers and first-class data sources in Custom Report Builder, enabling attribution automation

✓ Forms and form submissions can be used in multi-object reports, connecting lead generation directly to deal outcomes

✓ Authentication requires a private app token or OAuth flow — private apps are faster for internal analytics, OAuth is mandatory for third-party integrations

✓ The Personalization app now supports targeting and testing on website pages, not just landing pages, expanding data collection surface area

What Is the HubSpot API

The HubSpot API is a RESTful interface that allows you to read and write data across HubSpot's CRM, Marketing Hub, Sales Hub, and Service Hub. For marketing data analysts, it's the primary method for extracting contact records, campaign performance, deal stages, form submissions, and attribution touchpoints at scale.

Unlike manual CSV exports, the API supports real-time syncs, incremental updates, and filtered queries. You can pull only the records that changed in the last hour, filter by custom properties, or retrieve association data (e.g., which contacts are tied to which deals). This makes it possible to build automated pipelines that feed HubSpot data into warehouses like Snowflake, BigQuery, or Redshift.

HubSpot has moved away from the older v3 versioning scheme to date-based API versions (e.g. 2026-03). Each version is supported for a defined period before deprecation, and new endpoints now use paths like /crm/objects/2026-03/contacts instead of /crm/v3/contacts. This shift means you need to monitor deprecation timelines and update integration code proactively.

Why Marketing Data Analysts Use the HubSpot API

HubSpot's UI exports work for one-off reports. But when you need to track campaign ROI across months, correlate lead source with deal velocity, or build attribution models that span multiple touchpoints, manual exports become a bottleneck.

The API solves four core problems:

• Scale: You can pull thousands of contact or deal records per request, paginated automatically, instead of clicking through UI filters.

• Freshness: Incremental syncs let you query only records updated since the last extraction, keeping dashboards current without full reloads.

• Associations: The API surfaces relationships between objects (contacts ↔ deals, deals ↔ campaigns, contacts ↔ form submissions) that aren't visible in standard exports.

• Custom Properties: Every custom field you create in HubSpot becomes queryable via the API, giving you full control over your data model.

With campaign properties now available as workflow triggers and forms integrated into Custom Report Builder, the API has become even more central to closed-loop marketing analytics.

Step 1: Authentication — Private Apps vs. OAuth

Before you make any API request, you need to authenticate. HubSpot offers two methods: private apps and OAuth 2.0.

Private Apps (Recommended for Internal Analytics)

Private apps are the fastest route for internal data pipelines. You create a private app in your HubSpot account, assign it scopes (read/write permissions for specific object types), and generate an access token. That token is a long-lived credential you include in every API request header:

Authorization: Bearer YOUR_PRIVATE_APP_TOKEN

Private apps are ideal when you're building a pipeline for your own account. You don't need user consent flows, refresh tokens, or redirect URIs. The token never expires unless you manually revoke it.

Scope configuration: Assign only the scopes you need. For marketing analytics, common scopes include:

• crm.objects.contacts.read

• crm.objects.deals.read

• crm.objects.companies.read

• crm.schemas.custom.read (for custom object definitions)

• forms (for form metadata and submissions)

• analytics.read (for campaign and traffic analytics)

OAuth 2.0 (Required for Third-Party Integrations)

If you're building a tool that connects to multiple HubSpot accounts (e.g., an agency dashboard that aggregates data from 20 clients), you need OAuth. The flow involves:

• Redirecting the user to HubSpot's authorization URL

• User grants permission

• HubSpot redirects back to your app with an authorization code

• You exchange that code for an access token and refresh token

Access tokens expire after a few hours, so you must implement token refresh logic. For single-account analytics, OAuth adds unnecessary complexity — use a private app instead.

Step 2: Core Endpoints for Marketing Analytics

HubSpot's API surface is large. For marketing data analysts, five endpoint families do most of the heavy lifting.

Contacts Endpoint

The contacts endpoint returns individual contact records with all standard and custom properties. You can filter by date ranges, lifecycle stage, or any custom property you've defined.

GET /crm/objects/2026-03/contacts?properties=email,lifecyclestage,lead_source&limit=100

For incremental syncs, use the search endpoint with a filter on lastmodifieddate:

POST /crm/objects/2026-03/contacts/search
{
  "filterGroups": [{
    "filters": [{
      "propertyName": "lastmodifieddate",
      "operator": "GTE",
      "value": "1640995200000"
    }]
  }],
  "properties": ["email", "lifecyclestage", "lead_source"],
  "limit": 100
}

The search endpoint supports complex filters (AND/OR logic, nested groups) and returns paginated results. Batch size is capped at 100 records per request for search, 10,000 for batch read operations.

Deals Endpoint

Deals represent opportunities in your pipeline. For revenue attribution, you'll want deal stage history, close date, amount, and associated contact/company records.

GET /crm/objects/2026-03/deals?properties=dealname,amount,closedate,dealstage&associations=contacts,companies

The associations parameter returns IDs of linked objects. To get full contact details, you'll need a second request to the contacts endpoint or use the batch associations endpoint.

Campaigns Endpoint

HubSpot's campaigns object groups related assets (emails, landing pages, workflows) under a single campaign ID. The API returns campaign metadata, but performance metrics (opens, clicks, conversions) live in the analytics endpoints.

GET /marketing/v3/campaigns

With campaign properties now available as workflow triggers, you can automate lead routing or scoring based on campaign attribution, budget, or ownership. This data becomes especially valuable when joined with deal outcomes in your warehouse.

Forms and Form Submissions

Forms are lead capture endpoints. The forms endpoint returns form metadata (fields, redirect URLs), while submissions give you individual form fill events.

GET /marketing/v3/forms
GET /form-integrations/v1/submissions/forms/{formId}

Since forms and form submissions are now first-class data sources in Custom Report Builder, you can correlate form performance with deal conversion rates without external joins. The API still provides raw submission data for granular analysis.

Analytics Endpoint

The analytics API surfaces aggregated metrics: page views, traffic sources, email performance, and attribution touchpoints. Unlike object endpoints, analytics data is pre-aggregated and returned in time-series or breakdown format.

GET /analytics/v2/reports/:report_id

You can query standard reports (traffic analytics, email analytics) or custom reports you've built in HubSpot's reporting UI. For attribution, the contacts endpoint includes UTM parameters and original source data as contact properties — often more useful than aggregated reports for multi-touch attribution modeling.

Step 3: Rate Limits and Batching Strategies

HubSpot enforces rate limits to protect API performance. Limits vary by subscription tier and endpoint type.

Rate Limit Tiers by Subscription

Search endpoints and batch operations have separate, more restrictive limits. A search query counts as 4 requests against your quota. If you're syncing 50,000 contacts daily, you'll consume 2,000 search requests (50,000 ÷ 100 batch size × 4 cost multiplier).

Batching Best Practices

• Use batch endpoints for bulk reads: Instead of looping through individual contact GETs, use /crm/objects/2026-03/contacts/batch/read to fetch up to 100 records per request.

• Implement exponential backoff: When you hit a 429 (rate limit) response, double your wait time between retries.

• Sync incrementally: Query only records modified since your last sync using lastmodifieddate filters. This reduces request volume by 90% or more after the initial load.

• Cache schema metadata: Custom property definitions, pipeline stages, and form field schemas change infrequently. Fetch them once per day, not on every pipeline run.

If you're syncing multiple HubSpot accounts (e.g., agency use case), rate limits apply per portal. You can parallelize requests across accounts but must throttle within each account independently.

Step 4: Handling Custom Properties and Schema Changes

HubSpot's flexibility is a double-edged sword. Marketing teams constantly add custom properties — lead scores, campaign tags, lifecycle substages. Each new property changes the schema your pipeline expects.

Dynamic Property Discovery

Instead of hardcoding property names, query the properties schema endpoint on each pipeline run:

GET /crm/objects/2026-03/properties/contacts

This returns a list of all contact properties (standard + custom), their data types, and field groups. You can programmatically discover new properties and add them to your extraction query without manual updates.

Data Type Validation

Custom properties can have inconsistent types. A field labeled "Annual Revenue" might be stored as a string if a user entered "$50K" instead of a number. The API returns values as-is — your pipeline must handle type coercion and validation.

Common patterns:

• Strip currency symbols and commas from number fields

• Parse date strings into timestamps (HubSpot uses Unix milliseconds for dates)

• Handle null values explicitly (HubSpot returns empty strings for unset properties)

Versioning and Deprecation

With the shift to date-based versioning, HubSpot now publishes deprecation timelines for each API version. When a version is deprecated, endpoints continue to work for a grace period (typically 6–12 months), then return 410 Gone responses.

Monitor the HubSpot developer changelog and set up alerts for deprecation notices. Update your integration code to use the latest version before the cutoff date.

Common Mistakes to Avoid

Ignoring pagination: The API caps result sets at 100–10,000 records depending on the endpoint. If you don't follow the paging.next.after token in the response, you'll miss data.

Hardcoding property names: Custom properties get renamed or deleted. Query the schema endpoint dynamically to avoid broken pipelines.

Not batching requests: Looping through 10,000 contacts with individual GET requests will exhaust your rate limit in minutes. Use batch or search endpoints.

Skipping error handling for 429s: Rate limit errors are normal at scale. Implement retry logic with exponential backoff, not fixed delays.

Fetching full datasets on every sync: Incremental syncs using lastmodifieddate filters reduce API load by 90% or more. Full reloads should only happen on the initial extraction.

Not monitoring API version deprecation: HubSpot's date-based versioning means your code will break if you don't update. Set calendar reminders for deprecation dates.

Assuming consistent data types: Custom fields are user-entered. A "revenue" field might contain strings, nulls, or numbers. Validate and cast types in your transformation layer.

Tools That Help with HubSpot API Integration

You can build HubSpot API integrations from scratch, but pre-built connectors save weeks of development time and eliminate ongoing maintenance.

Improvado handles HubSpot API extraction with pre-built transformations for marketing analytics: attribution modeling, campaign spend normalization, and cross-channel funnel analysis. It monitors HubSpot API versioning changes and updates connectors automatically, so your pipeline doesn't break on deprecation dates. Implementation typically completes within a week, not months.

Step 5: Real-World Extraction Patterns for Marketing Analytics

Theory is useful. Practice is better. Here are three extraction patterns marketing data analysts use daily.

Incremental Contact Sync

Pull only contacts modified since your last sync. Store the last sync timestamp in your pipeline metadata table. On each run:

POST /crm/objects/2026-03/contacts/search
{
  "filterGroups": [{
    "filters": [{
      "propertyName": "lastmodifieddate",
      "operator": "GTE",
      "value": "{last_sync_timestamp}"
    }]
  }],
  "properties": ["email", "lifecyclestage", "lead_source", "utm_campaign"],
  "limit": 100
}

Page through results using the after token. Upsert records into your warehouse by email or HubSpot ID. Update the last sync timestamp after a successful run.

Deal Stage History for Velocity Analysis

The deals endpoint returns current stage, but stage history (how long a deal spent in each stage) requires the engagements API or custom properties that log stage transitions. If your HubSpot workflows log stage changes to a custom property, extract that field and parse it in your transformation layer.

Alternatively, snapshot deal records daily and calculate stage duration by comparing snapshots over time. This approach avoids complex engagement parsing but requires persistent storage.

Attribution Touchpoint Extraction

HubSpot stores original source, UTM parameters, and lifecycle stage transitions as contact properties. For multi-touch attribution, extract:

• hs_analytics_first_touch_converting_campaign

• hs_analytics_last_touch_converting_campaign

• hs_latest_source

• utm_campaign, utm_source, utm_medium, utm_content, utm_term

Join this data with deal records (via contact ↔ deal associations) and campaign spend data from ad platforms to build position-based or time-decay attribution models in your BI tool.

Step 6: Personalization and Advanced Use Cases

HubSpot's 2026 updates expanded the API's role in dynamic content and buyer intent tracking.

Website Personalization Data

The Personalization app now supports targeting on website pages, not just landing pages. This means more touchpoint data: which visitors saw which content variant, engagement metrics by segment, and conversion lift by personalization rule.

If you're running multivariate tests across your site, the API can extract variant performance data to feed into broader campaign analytics. Correlate personalized content exposure with deal velocity or lifecycle stage progression.

Buyer Intent Signals

HubSpot's Company Buyer Intent feature now surfaces signals like Industry Recognition, Office Closure, Physical Expansion, and Regulatory Approval. These aren't always available via the standard companies endpoint — check the hs_predictive_* property namespace or query the insights API if you have access.

For account-based marketing teams, these signals can trigger workflows or feed into lead scoring models stored in your data warehouse.

Step 7: Security and Compliance Considerations

Marketing data includes PII: emails, names, phone numbers, IP addresses. When you extract HubSpot data via API, you become responsible for securing it in transit and at rest.

Token Security

Private app tokens are equivalent to passwords. Store them in secret managers (AWS Secrets Manager, HashiCorp Vault, Azure Key Vault), never in code repositories or environment files checked into version control.

Rotate tokens periodically. If a token leaks, revoke it immediately in HubSpot's app settings and generate a new one.

Data Retention and GDPR

HubSpot honors GDPR deletion requests automatically within its platform. But if you've copied contact data to your warehouse, you must implement deletion logic to stay compliant.

Set up a webhook listener for HubSpot's contact.deletion event, or poll the contacts endpoint periodically to detect deleted records (they return 404 on GET requests). Delete corresponding rows from your warehouse within 30 days of the HubSpot deletion.

Audit Logging

Log every API request your pipeline makes: timestamp, endpoint, response code, record count. This audit trail is essential for debugging data discrepancies and proving compliance during audits.

If you're using Improvado, audit logs are built in and retained for 2 years. For custom integrations, implement structured logging to a persistent store (S3, CloudWatch, BigQuery).

Conclusion

The HubSpot API gives marketing data analysts the access they need to automate reporting, build attribution models, and surface insights that don't exist in HubSpot's native UI. But using it effectively requires understanding rate limits, handling schema changes, batching requests intelligently, and monitoring API versioning.

For teams that need HubSpot data connected to 10+ other sources (Google Ads, Meta, Salesforce, SQL databases), building and maintaining API integrations in-house becomes a full-time job. Pre-built connectors eliminate that maintenance burden and give you more time for analysis instead of pipeline debugging.

Whether you build or buy, the principles remain the same: sync incrementally, batch aggressively, validate data types, and monitor for schema drift. Follow those rules, and your HubSpot data pipeline will stay reliable at scale.

FAQ

Can I request a rate limit increase for the HubSpot API?

HubSpot does not offer manual rate limit increases on a per-account basis. Rate limits are tied to your subscription tier (Free, Starter, Professional, Enterprise). If you're hitting limits consistently, the recommended approaches are: upgrade to a higher subscription tier, implement more aggressive batching and incremental syncs to reduce request volume, or use a data integration platform that manages rate limits and retries automatically. Improvado, for example, handles HubSpot rate limiting transparently across multiple client accounts, so you don't have to build retry logic or worry about quota exhaustion.

Does the HubSpot API support custom objects?

Yes. HubSpot introduced custom objects in 2020, and they're fully accessible via the API. Custom objects follow the same endpoint structure as standard objects (contacts, deals, companies). You can query, create, update, and associate custom object records using /crm/objects/2026-03/{objectType} endpoints. Custom object schemas are retrievable via the properties API, so you can dynamically discover custom object definitions and their fields. This is especially useful for teams that model industry-specific entities (e.g., projects, inventory items, events) in HubSpot and need to extract that data for analytics.

How far back can I pull historical data from HubSpot via the API?

There is no hard time limit on historical data extraction. You can query contacts, deals, and companies created years ago. However, the analytics API (for aggregated metrics like page views or email opens) typically retains data for 13–24 months depending on the report type and your subscription tier. For contact-level data (UTM parameters, lifecycle stage history), retention is indefinite unless you or HubSpot delete the record. If you need multi-year trend analysis, extract data continuously rather than relying on one-time historical pulls — this ensures you capture schema changes and custom property additions over time.

Is the HubSpot API real-time or batched?

The HubSpot API is real-time in the sense that GET requests return the current state of an object at the moment you query it. However, some aggregated metrics (especially in the analytics API) are computed asynchronously and may lag by 15–60 minutes. For contact and deal data, updates made in the HubSpot UI or via workflows appear in API responses within seconds. If you're building dashboards that require sub-minute latency, you'll need to poll frequently (within rate limit constraints) or set up HubSpot webhooks to receive near-instant notifications of record changes. Webhooks are more efficient than polling for high-frequency use cases.

How do I detect deleted records in HubSpot via the API?

HubSpot does not provide a "deleted records" endpoint. When a contact, deal, or company is deleted, GET requests for that record ID return a 404 error. To detect deletions in your data warehouse, you must implement tombstone logic: periodically query all record IDs you've previously synced, and if any return 404, mark them as deleted in your warehouse. Alternatively, subscribe to HubSpot's webhooks for contact.deletion, deal.deletion, and company.deletion events. Webhooks are more efficient and provide near-instant deletion notifications, but require a publicly accessible endpoint to receive the webhook payloads. Improvado handles deletion detection automatically and removes stale records from downstream systems without manual intervention.

Can I use one API integration to pull data from multiple HubSpot portals?

Yes, but you need separate authentication credentials for each portal. Each HubSpot account (portal) has its own private app tokens or OAuth credentials. If you're an agency or multi-brand enterprise managing 10+ HubSpot accounts, you'll need to store credentials securely for each portal and parallelize API requests across accounts. Rate limits apply per portal, so you can query multiple accounts simultaneously without cross-contamination. Tools like Improvado are built for this use case: you connect multiple HubSpot accounts once, and the platform handles credential management, rate limiting, and data aggregation automatically. This eliminates the need to build and maintain multi-tenant infrastructure in-house.

Should I use the HubSpot API or HubSpot's native integrations with data warehouses?

HubSpot offers native integrations with some BI tools and data warehouses, but they're limited in scope. Native integrations typically sync a predefined set of objects and properties, with little control over transformation logic or sync frequency. The API gives you full control: you decide which properties to extract, how to handle custom fields, and when to sync. For marketing analytics teams that need to join HubSpot data with ad spend, web analytics, and attribution models, the API (or a purpose-built connector like Improvado) is the better choice. Native integrations are sufficient for simple dashboards but break down when you need custom data models or cross-platform reporting.