Updated June 24, 2026 by Sunny Chauhan.

HubSpot's API surface in 2026 is larger than most builders realize. Most teams come in knowing the CRM API and stop there. There are at least eight distinct API surfaces, and picking the right one for the right job saves you weeks of reverse-engineering. This guide walks through each major HubSpot API, when to use it, how authentication works across the set, the GraphQL alternative that landed in 2024, and the patterns that hold up under production load.

Pro Tip

TL;DR HubSpot's main APIs in 2026: CRM API v3 (REST, the workhorse), CRM GraphQL (for relationship-heavy queries), Events API (custom analytics events), Conversations API (helpdesk inbox), CMS API (pages and content), Marketing API (forms, emails), Workflows API (automation), Files API. All authenticate via OAuth (Marketplace apps) or Private App tokens (internal integrations). All share the 100 requests / 10 seconds per portal rate limit on the per-portal counter. Pick by use case: CRM data → CRM v3 REST, relationship queries → GraphQL, product analytics → Events, helpdesk → Conversations.

The workhorse. Contacts, Companies, Deals, Tickets, Line Items, Quotes, Products, Custom Objects. Read, create, update, delete. Batch endpoints (100 records per call). Property management. Association management. Pipelines. Owners.

Endpoint base: https://api.hubapi.com/crm/v3/

Use it for: anything that's CRUD against CRM objects. 80% of integrations are mostly this one API.

Released 2024. For relationship-heavy queries where REST would require N+1 fetches. Returns nested data in a single request.

Use it when: you need a contact plus all their deals plus all those deals' line items plus the company they belong to. That's one GraphQL query; multiple REST calls otherwise.

Trade-offs: → More expensive per request (counts more against rate limit by design) → Less complete coverage than REST (some objects and operations don't have GraphQL support yet) → Not the right choice for simple CRUD

For tracking custom events on contacts. Product usage analytics, feature engagement, custom user actions. Events are timestamped, attributed to a contact, and queryable for analytics inside HubSpot.

Use it for: product-led growth tooling, analytics integrations, customer journey tracking.

Endpoint base: https://api.hubapi.com/events/v3/

Helpdesk inbox messages, conversations, threads. For service-desk integrations and inbox automation.

Use it for: helpdesk integrations (analogous to Pylon, Intercom-style products), inbox bots, conversation analytics.

Pages, blog posts, files, templates, modules. For content marketing tooling and CMS extensions.

Use it for: products that manage HubSpot CMS content programmatically.

Forms, emails, marketing events, lists, campaigns. Marketing-side data and automation.

Use it for: marketing automation tooling, campaign analytics, list management.

Trigger and read workflows. Limited compared to the full power of HubSpot's workflow engine, but useful for orchestration integrations.

Use it for: integrations that need to start or react to HubSpot workflows from outside.

Upload, list, manage files. The CMS file system surface.

Use it for: any product that handles HubSpot-attached files (attachments on contacts, deals, etc.).

Three questions to route a builder to the right surface:

→ Is the data a CRM object (contact, deal, ticket, custom object)? Yes → CRM API v3 (or GraphQL if you need nested relationships). No → continue.

→ Is it a custom product event or analytics datapoint? Yes → Events API. No → continue.

→ Is it a helpdesk message, inbox conversation, or thread? Yes → Conversations API.

→ Is it marketing content, a form, an email? Yes → Marketing API or CMS API.

For most ISVs, the answer for 80% of needs is CRM API v3 REST.

All HubSpot APIs accept the same OAuth access token. Once you have a token from the OAuth install flow (see our HubSpot OAuth and scopes guide), you can call any API that the token's scopes permit.

The token mechanism:

`` Authorization: Bearer <access_token> ``

Same header, every endpoint, every API surface. The scopes tied to the token determine what calls succeed.

This is materially simpler than ecosystems where each API has its own auth model. Salesforce APIs share auth too (Connected App OAuth), but their scope model is less granular than HubSpot's.

Two ceilings, every API surface:

→ 100 requests / 10 seconds per connected portal. Rolling window. Includes all API surfaces aggregated per portal.

→ A per-app daily cap that aggregates across all your portals. Varies by app tier and customer Hubs. For most apps it's in the high hundreds of thousands per day.

Two stricter caps worth knowing:

1/ Search API: 4 requests / second per portal. Stricter than the general 100/10s. Affects /crm/v3/objects/{type}/search. Cache aggressively.

2/ CRM GraphQL: each query consumes multiple "credits" depending on complexity. Effectively a tighter limit than REST for the same data fetched.

Marketplace certification requires apps to maintain 429 (rate-limited) responses below 5% of total daily requests. See our HubSpot API rate limits guide for the architectural patterns that keep apps under both ceilings.

Since the CRM API does most of the work, four patterns are worth knowing cold:

`` POST /crm/v3/objects/contacts/batch/read POST /crm/v3/objects/contacts/batch/create POST /crm/v3/objects/contacts/batch/update POST /crm/v3/objects/contacts/batch/archive ``

Each batch endpoint handles up to 100 records per call and consumes 1 token from your rate limit. Single-record calls in a loop are an anti-pattern; switching to batch can drop API consumption by 90%.

HubSpot's v3 API uses after cursor pagination. The response includes paging.next.after if more results exist:

``javascript let after; do { const url = new URL('https://api.hubapi.com/crm/v3/objects/contacts'); if (after) url.searchParams.set('after', after); url.searchParams.set('limit', '100'); const response = await fetch(url.toString(), { headers: { 'Authorization': Bearer ${token} } }); const data = await response.json(); processBatch(data.results); after = data.paging?.next?.after; } while (after); ``

If your code assumes offset-based pagination (?offset=200), it won't work on v3.

Linking a contact to a deal:

`` PUT /crm/v3/objects/contacts/{contactId}/associations/deals/{dealId}/contact_to_deal ``

The association type (contact_to_deal) is one of HubSpot's predefined association types. Custom associations exist and are queryable too.

To find associations on an object:

`` GET /crm/v3/objects/contacts/{contactId}/associations/deals ``

Customers define their own properties. Hardcoding standard properties only is brittle. Discover at runtime:

`` GET /crm/v3/properties/contacts ``

Cache the schema for 12-24 hours. Property definitions almost never change.

A typical case where GraphQL wins:

REST approach (multiple calls):

1. GET contact by id (1 call)

2. GET contact's associated deals (1 call)

3. GET each deal's properties (1 call per deal, or 1 batch call)

4. GET each deal's line items (1 call per deal)

5. GET the contact's associated company (1 call)

5+ calls, plus the application-side stitching of the results.

GraphQL approach:

``graphql query { CRM { contact(id: 12345) { id properties { firstname email lifecyclestage } deals { items { id properties { dealname amount dealstage } line_items { items { id properties { name quantity price } } } } } company { id properties { name domain } } } } } ``

One call. Nested response. Application code consumes the structured data directly.

When NOT to use GraphQL: → Simple CRUD (REST is simpler) → Bulk operations (REST batch endpoints are more efficient per record) → Endpoints GraphQL doesn't cover (Events, Conversations, CMS are still REST-only)

At Appnigma we generate Salesforce 2GP Managed Packages where Apex code makes Salesforce SOQL/SOSL queries against the right objects with the right governor-aware patterns. The HubSpot equivalent (auto-picking the right API surface, generating efficient calls, handling pagination and batch correctly) would compress the build time for HubSpot integrations the same way we compress Salesforce.

The patterns the generator would need to get right: REST for CRUD, GraphQL for relationship queries, batch endpoints for multi-record operations, cursor pagination consistently, rate limiter per-portal. These are documented enough that the generator can be deterministic about which to use.

• [ ] Picked the right API for each integration job → Yes / No

• [ ] OAuth tokens stored encrypted, refreshed before expiry → Yes / No

• [ ] Per-portal rate limiter (token bucket) implemented → Yes / No

• [ ] Batch endpoints used for any multi-record operation → Yes / No

• [ ] Cursor (after) pagination, not offset → Yes / No

• [ ] Property schema cached at runtime (not hardcoded) → Yes / No

• [ ] Webhooks subscribed for change detection (not polling) → Yes / No

• [ ] Search API usage minimized or cached (4 rps cap) → Yes / No

• [ ] 429 rate monitored and alerted at 3% threshold → Yes / No

• [ ] GraphQL used only where its complexity earns its place → Yes / No

A conversation intelligence product (Avoma-analog) needed three integration surfaces in HubSpot:

→ Read/write deal records: CRM API v3 REST → Surface meeting summaries inside HubSpot's helpdesk: Conversations API → Track per-meeting analytics events for product-led growth: Events API

Three APIs, one OAuth token, one rate limiter shared across surfaces. The architecture: a single integration service routes calls to the right API by intent. Webhooks subscribed for deal changes (via the CRM webhook surface). Daily 429 rate stayed at 0.4%, well under the 5% certification ceiling.

The lesson: the API choice cascades from the integration's intent, not from "which API do I know best." Picking each surface deliberately keeps the rate limit math sane and the codebase clean.

The HubSpot API is HubSpot's set of programmatic interfaces for integrating with HubSpot's Hubs. In 2026, the main surfaces are CRM API v3 (REST), CRM GraphQL, Events API, Conversations API, CMS API, Marketing API, Workflows API, and Files API. Most ISV integrations use primarily the CRM API (HubSpot Developers, API documentation).

REST is the workhorse: simple CRUD, batch endpoints, broad coverage of all CRM objects. GraphQL is for relationship-heavy queries that would require multiple REST calls. GraphQL counts more against rate limits and has narrower coverage. Use REST for 80% of cases, GraphQL when nested data fetching is the bottleneck.

OAuth for Marketplace apps and multi-tenant integrations, Private App tokens for internal/single-portal integrations. All API surfaces accept the same Bearer token. See our HubSpot OAuth scopes guide.

100 requests / 10 seconds per connected portal (rolling window) plus a separate per-app daily cap. Search API is stricter at 4 requests / second. GraphQL queries consume multiple credits per call. See our HubSpot API rate limits guide.

Yes. developers.hubspot.com/docs/api/overview is the entry point. Each API surface has its own subsection with endpoint references, code samples, and webhook documentation.

CRM API: structured object data (contacts, deals, tickets). Events API: custom analytics events attributed to contacts. Use CRM API for transactional/CRM data, Events API for product-usage and analytics events.

For internal integrations (one company, one portal), Private App tokens work. For Marketplace apps and multi-tenant integrations, OAuth is required. The deprecated legacy API key still works for some existing accounts but cannot be created for new accounts.

Yes, released in 2024. It complements the REST API for relationship-heavy queries. Not all CRM operations have GraphQL support yet; some surfaces (Events, Conversations) remain REST-only.

Sunny Chauhan is the founder and CEO of Appnigma AI, a no-code platform that generates Salesforce AppExchange-ready Managed Packages from natural-language prompts. He holds Salesforce certifications in Platform Developer II, Platform App Builder, Administrator, Data Cloud Consultant, and AI Associate. Appnigma generates Apex code that makes governor-aware CRUD calls against Salesforce; the architectural choices (right API for the job, batch where possible, cursor pagination, async deferral) transfer to HubSpot API integrations.

Originally published June 24, 2026. Last reviewed June 24, 2026. API surfaces and patterns verified against HubSpot's developer documentation current as of the published date.

• HubSpot API Integration Guide: Connect Your SaaS to HubSpot

• HubSpot API Rate Limits Guide

• HubSpot OAuth and Scopes Complete Reference

• HubSpot API Key Management Guide

• HubSpot Webhooks Implementation Guide

• HubSpot Custom Integration Build Guide

• HubSpot Marketplace Complete Guide

1/ HubSpot Developers, API Documentation Overview 2/ HubSpot Developers, CRM API v3 Reference 3/ HubSpot Developers, CRM GraphQL API 4/ HubSpot Developers, API Usage Details and Rate Limits

Which HubSpot API surfaces does your integration touch, and is each one the right tool for the job it's doing?