What we do
Tools
Industries
Department
How we workLet's talk →
Home/HubSpot/HubSpot API
HubSpot

Working with the HubSpot API: Which Token, Which Limits, Which Endpoints

HubSpot's API reaches contacts, companies, deals, tickets, custom objects, associations and now workflows. What has changed is how you get in. New legacy private apps can't be created any more, so most tutorials send you to a screen that's gone. Here's what to create instead, the limits that shape any real integration, and what the workflows API can do.

Need a token today?

For a script or server-to-server sync in your own account: create a service key (newly released) and pick its scopes. Send it as Authorization: Bearer <key> to https://api.hubapi.com.

Development Keys Service keys Create service key

Already have a legacy private app? It works for now, but HubSpot ends support for legacy private apps in September 2027 and you can't make new ones. Its token is under Development, then Legacy apps, on the app's Auth tab.

Calling /crm/v3/ or other numbered versions? HubSpot is moving to date-based API versions. Support for v1 to v3 ends after September 2027, and for v4 on 30 March 2027, so check each endpoint's migration path.

Need webhooks, UI extensions or other accounts? Build an app on HubSpot's developer platform with the HubSpot CLI, using static auth for your own accounts or OAuth for the marketplace.

Following a guide that uses hapikey? Account API keys were retired years ago. Swap in a service key.

Which HubSpot credential fits the job

You are building Use Keep in mind
A sync or script that only calls the REST API in your own portal A service key Super admins or users with developer tools access create them. They can't receive webhooks. Rotation gives you a seven-day overlap, or set it to rotate every 3, 6 or 12 months.
An integration that also needs webhook subscriptions or UI extensions, in your own accounts A developer platform app with private distribution and static auth Created and deployed with the HubSpot CLI. Private distribution covers up to 10 allowlisted accounts. Changing scopes means reinstalling.
A product other companies install into their HubSpot An OAuth app distributed through the marketplace Each installing account gets 110 requests per 10 seconds, and buying HubSpot's API limit increase doesn't raise it.
Something already running on a legacy private app Plan the move now HubSpot ends support for legacy private apps in September 2027, and they don't get new platform features in the meantime. List every script using the token and who owns it, then move them to a service key or a static-auth app.

HubSpot API limits that shape the design

These are HubSpot's published limits for apps in your own account. Plan the sync around them, not the other way round.

01

Per 10 seconds, per app

  • Free and Starter: 100 requests
  • Professional and Enterprise: 190 requests
  • Over the limit: 429 with errorType: RATE_LIMIT
02

Per day, per account

  • Free and Starter: 250,000
  • Professional: 625,000
  • Enterprise: 1,000,000
  • Resets at midnight in the account time zone
03

CRM search

  • 5 requests a second per account
  • Up to 200 records a page
  • No more than 10,000 results per query
  • New or edited records can take a moment to appear
04

What keeps you under them

  • Batch endpoints instead of one call per record
  • Cache owners, properties and pipelines
  • Webhooks instead of polling for changes
  • Search in date windows on the last-modified property to stay under 10,000

Building HubSpot workflows through the API

Now you can, in beta. HubSpot's Automation API v4 lists, creates, updates and deletes workflows with the automation scope. Contact-based workflows use the type CONTACT_FLOW and the rest, deal-based included, use PLATFORM_FLOW. You can still enroll records in an existing workflow through the API as well. Note that HubSpot ends support for its v4 APIs on 30 March 2027 as it moves to date-based versions, so check the workflows endpoint's replacement before building a lot on it.

Read the update rules before you script it. An update replaces the whole definition, so any action you leave out of the PUT body is deleted. It needs the current revisionId. A workflow deleted through the API can only be brought back by HubSpot support. Export the definition before every change.

When the logic doesn't fit the builder, a custom coded action can call your own endpoint partway through a workflow, on the HubSpot tiers that include it. Or run the logic outside HubSpot, triggered by the same webhook event, and write the result back. More on the builder side on our HubSpot workflows page.

Questions people ask

Does HubSpot have a public API?

It does. HubSpot's REST API covers contacts, companies, deals, tickets, line items, custom objects, associations, properties, owners and workflows, among others. You call it with a service key, a developer platform app's static token, or an OAuth access token.

What's the difference between a HubSpot private app and a public OAuth app?

A private app gave you a static, scoped token for your own account. Existing legacy private apps still work, but new ones can't be created, so use a service key or a privately distributed static-auth app instead. A public OAuth app is for integrations other companies install: each account authorizes it with the scopes you request.

Can you build a HubSpot workflow through the API?

Yes, through the Automation API v4, which is in beta. It can create, update and delete workflows as well as enroll records. Updates overwrite the full definition and need the current revision ID, so fetch, edit and send back the whole thing.

Does the HubSpot API support custom objects?

It does. Custom objects you've defined use the same CRM object endpoints as contacts and deals, addressed by the object type ID, and their properties and associations work the same way.

Do I need a developer to use the HubSpot API?

For a simple one-way push, a no-code tool may be enough. A two-way sync, custom objects, search that stays under 10,000 results, and retries that recover properly is developer work. n-frames builds those integrations against the HubSpot API, for example HubSpot to NetSuite or QuickBooks where the stock connector's mapping doesn't fit, and keeps them running.

Why does the HubSpot search API stop at 10,000 results?

That's a hard cap per query, and asking for the next page past it returns a 400 error. Split the query into date windows on the record's last-modified date, or use the list endpoints for a full export.

Let's talk

Tell us the one thing your team does manually that eats up time. We read every message and reply within a day.