How to Use HubSpot API Easily 2026

HubSpot's older API paths use plain numeric versions, like /crm/v3/objects/contacts. In 2026, HubSpot introduced a parallel date-based scheme, where a version is a release date instead of a number, formatted as /YYYY-MM/, for example /2026-03/.

Beta releases carry a -beta suffix, like /2026-09-beta/. The two schemes coexist.

HubSpot's own versioning guide says existing v1 through v4 endpoints keep working at their current URLs during the transition, and as of this check the core CRM Objects API, contacts, deals, companies, and so on, is still documented at /crm/v3/objects/, not a dated path. Don't assume a dated URL for an endpoint until you've confirmed it in HubSpot's own API reference. Guessing at a /2026-03/ path for an endpoint that hasn't moved yet will 404.

Authentication for a custom integration starts in different places depending on which mechanism you use, and which one is right for you changed very recently. Legacy private apps, the option most existing tutorials describe, live under Development, then Legacy apps, in the left sidebar, not under Settings and Integrations as older guides say.

Click Create legacy app, then Private. HubSpot has announced it's disabling the creation of new legacy private apps: from September 28, 2026 for accounts created on or after that date, and from October 26, 2026 for accounts that already existed.

Apps created before those dates keep working; only new creation is blocked. In their place, HubSpot is pushing Service Keys, created at Settings, then Integrations, then Service Keys, now described as the modern route for a system-to-system integration.

Whichever path applies to you, name the app or key and grant it only the specific scopes it needs, like read and write access to Contacts or Deals, not blanket account access. A legacy private app issues an access token.

That's the credential's real name; "Service Key" belongs to the newer mechanism, a separate thing entirely, despite how often the two get conflated in older tutorials. Either credential goes into your requests the same way, as a bearer token: Authorization: Bearer YOUR_TOKEN.

If you're building an OAuth app instead, the equivalent step is exchanging your authorization code at HubSpot's token endpoint, https://api.hubapi.com/oauth/v1/token, a plain numbered path that hasn't moved to the dated scheme. Treat whichever token you get like a password. It's the only credential standing between the public internet and your CRM data.

With a token in hand, a basic GET request to fetch a contact points at /crm/v3/objects/contacts/{contactId} today, the same numbered path integrations have used for years, not a dated one. Whether you're using a plain HTTP client, an API testing tool, or a server-side SDK, the shape of the call is the same: method, URL, Authorization header, and a JSON body for anything beyond a simple read.

Test a single-object GET request first before moving on to batch or bulk calls, so you can confirm your token's scopes cover the object type you're targeting. Check HubSpot's own API reference for the endpoint you need before building against it; that's the only reliable way to know whether it has already moved to a dated path or still sits on v3.

For anything beyond a handful of records, HubSpot's batch read endpoints, such as POST /crm/v3/objects/contacts/batch/read, let you fetch up to 100 records in a single payload, far more efficient than looping single-object requests. Responses beyond that limit include a paging.next.after value carrying the ID of the next record.

Pass it into your next request's after parameter to walk through the full result set page by page instead of guessing at offsets. Skipping pagination logic is one of the fastest ways to silently miss records in a large sync job.

Even with batching and pagination handled correctly, high-volume integrations will eventually hit a 429 response when they exceed HubSpot's rate limits. The standard fix is exponential backoff: catch the 429, wait a short interval, retry, and double that interval on each subsequent failure instead of hammering the endpoint at a fixed rate.

Build this retry loop in from the start. Bolting it on after a production integration starts failing costs a lot more debugging time later.