The HubSpot API is the REST interface for reading and writing CRM data - contacts, companies, deals, tickets, and their associations - under /crm/v3/ (and /crm/v4/ for associations). It authenticates with a bearer token (a Service Key, a private app access token, or an OAuth access token), returns JSON, and is rate-limited per second and per day based on your HubSpot subscription.
This page covers how authentication works, the endpoints and objects you'll use most, rate limits and pagination, and where Knit's unified API and MCP server fit if you're connecting HubSpot alongside other CRMs.
Authentication
HubSpot retired its legacy static API keys in 2022. Today, API calls are authenticated with a bearer token from one of three sources: a Service Key (account-level, data-only, in public beta since February 2026), a private app access token (supports webhooks and UI extensions), or an OAuth 2.0 access token from a project-based app (required for Marketplace or multi-account integrations). All three are sent the same way: Authorization: Bearer <token> (HubSpot Developers, Account Service Keys).
For the full walkthrough — creating a Service Key or private app, choosing between them, and a working curl example - see How to Get a HubSpot API Key.
The full, current set of endpoints and required scopes is in HubSpot's CRM API documentation - check each endpoint's page before assuming a token has access.
Common tasks
- Create a contact:
POST /crm/v3/objects/contactswith apropertiesobject containing fields likeemail,firstname,lastname. - Update a deal:
PATCH /crm/v3/objects/deals/{dealId}with thepropertiesto change, such asdealstageoramount. - Search records:
POST /crm/v3/objects/{objectType}/searchwithfilterGroups,sorts, andpropertiesto return — the shared 5 requests/second Search API limit applies regardless of object type. - Associate records:
PUT /crm/v4/objects/{objectType}/{objectId}/associations/{toObjectType}/{toObjectId}to link, for example, a contact to a company or deal. - List custom fields:
GET /crm/v3/properties/{objectType}to see which standard and custom properties exist before reading or writing them. - Fetch open support tickets: see Knit's walkthrough on how to fetch open tickets from the HubSpot API for the properties lookup, pagination, and per-contact filtering involved.
Rate limits and pagination
HubSpot enforces both per-second (burst) and daily rate limits, scoped to your account and subscription tier, documented at HubSpot's API usage guidelines and limits:
Every response includes X-HubSpot-RateLimit-Max and X-HubSpot-RateLimit-Remaining (the burst limit and remaining requests for the current window, with the window length given in X-HubSpot-RateLimit-Interval-Milliseconds), plus - for non-OAuth credentials - X-HubSpot-RateLimit-Daily / X-HubSpot-RateLimit-Daily-Remaining. The older X-HubSpot-RateLimit-Secondly / X-HubSpot-RateLimit-Secondly-Remaining headers are still sent but are deprecated and no longer enforced - don't build new logic against them. Search API responses don't include any of these rate-limit headers. Exceeding a limit returns 429 with a JSON body containing errorType: "RATE_LIMIT" and a policyName of SECONDLY or DAILY telling you which limit you hit.
For pagination, list and search endpoints under /crm/v3/ and /crm/v4/ use cursor pagination: each response includes a paging.next.after value, which you pass back as the after query parameter to fetch the next page. Keep paging until paging.next is absent from the response.
Build it yourself vs. use a unified API
Calling the HubSpot API directly works well for a single account: pick the right credential (Service Key, private app, or OAuth), track per-second and daily limits, and handle cursor pagination on list and search endpoints. It gets more involved once you're connecting HubSpot alongside other CRMs - each with its own auth model, object schema, and rate-limit shape.
Knit's unified CRM API normalizes HubSpot contacts, companies, deals, and tickets alongside connectors like Salesforce behind one schema, handles the auth setup described in the HubSpot API key guide, and manages rate-limit backoff for you. See Knit's HubSpot connector for what's available, or book a demo to see it against your own account. You can also sign up free and connect a sandbox HubSpot account.
Knit's HubSpot connector and AI/MCP
Knit also runs a HubSpot MCP Server, which gives AI agents read/write access to HubSpot CRM objects - contacts, companies, deals, custom objects and fields - through the same unified layer, so an agent built against Knit's MCP doesn't need separate HubSpot-specific auth or endpoint logic.
FAQ
Is the HubSpot API a REST API?
Yes - the HubSpot CRM API follows REST conventions (GET, POST, PATCH, DELETE on resource URLs, JSON request and response bodies) under /crm/v3/ for most objects and /crm/v4/ for associations. HubSpot also offers webhook subscriptions for real-time events, available to private apps and project-based apps but not Service Keys.
How do I authenticate to the HubSpot API?
Send a bearer token in the Authorization header: Authorization: Bearer <token>. The token can come from a Service Key (data-only, no webhooks), a private app (supports webhooks), or an OAuth 2.0 flow for multi-account integrations. See the HubSpot API key guide for how to create each.
How do I paginate through HubSpot CRM records?
List and search endpoints return a paging.next.after value when more results exist. Pass that value as the after query parameter on your next request, and repeat until paging.next is no longer present in the response. This applies to /crm/v3/objects/{objectType} and the /search endpoints alike.
What happens if I exceed HubSpot's API rate limits?
HubSpot returns 429 with errorType: "RATE_LIMIT" and a policyName of SECONDLY (burst) or DAILY. Burst limits range from roughly 100 to 190+ requests per 10 seconds depending on your subscription tier, with the Search API capped separately at 5 requests/second across all object types. Knit handles this backoff automatically across the HubSpot connections it manages.
