HubSpot API: what you can build, what it takes to run, and how to brief it

What is the HubSpot API?

The HubSpot API is how other software talks to your HubSpot account without a person clicking. The API works in three directions, and most projects need more than one.

The API is a set of web addresses at api.hubapi.com, one family per object, with the data as JSON. A developer needs an access key with the right permissions (HubSpot calls them scopes), the documentation at developers.hubspot.com and a test account. HubSpot gives developers free test accounts with a 90-day trial of many Enterprise features.

The HubSpot MCP server is a different thing: it lets AI assistants such as ChatGPT or Claude work in HubSpot, and our HubSpot MCP guide covers it. Apps in the HubSpot Marketplace use the API too, but someone else builds and runs them.

What can you build with the HubSpot API?

The HubSpot API can move almost any data in or out of HubSpot. These are the jobs companies ask for most, and the part of HubSpot each one uses.

The ERP guide covers which ERP data to bring in and who owns each field.

What the API won’t do for you

• Undo. There is no rollback. If an integration writes wrong values to 20,000 contacts, you repair them from property history or an export. Test on a copy first.
• Skip your edition. An API for a feature your subscription lacks, such as custom objects below Enterprise, answers with an error.
• Bypass your rules. Since API version 2026-09, conditional required properties and required fields on record creation also apply to API writes. A call without them fails.
• Match records for you. The API writes what it’s sent. Duplicates come from integrations that create instead of looking up first; our duplicates guide shows the rules that stop them.
• Everything you can click. A few settings still have no endpoint. Pipeline rules and object tags only got one in September 2026. Check the API reference before you plan a feature on it.

Which HubSpot integration route fits: marketplace app, Make or Zapier, workflow code or your own code

Choose the route by the job, then by who will look after it. Your own code comes last, because you carry its upkeep for as long as it runs.

Many teams start with Make or Zapier and stay there for years, which is fine for simple flows. When an integration has to keep HubSpot and another system in step both ways, or carry large volumes, move it to a sync app or your own code before the flows multiply.

HubSpot API access: service keys, apps and the end of legacy private apps

Every API call carries an access key. Since September 2026 there are three current ways to get one, and the one most guides still describe, the private app, is being retired.

Give each key only the scopes its job needs. A sync that reads companies and deals gets read scopes for companies and deals, nothing else. A leaked read-only key can’t change your data, and a wrong write is refused.

1. Step 01

   Create a service key

   Go to Development > Keys > Service Keys and click “Create service key”. Name it after the job and the system, such as “ERP sync (read only)”, because the name shows in logs. Only Super Admins and users with the Developer tools access permission can create one.

   

2. Step 02

   Tick only the scopes the job needs

   Click “Add new scope”, search for the object and tick the read or write scope. Scopes with a warning sign reach sensitive or highly sensitive data; leave them off unless the job needs exactly that data.

   

3. Step 03

   Hand the key over safely

   Click Create. The key is hidden until someone clicks Show, and only admins see it. Give it to your developer through a password manager, never by email or chat. Plan a rotation every six months: “Rotate and expire later” gives seven days to switch.

   

4. Step 04

   Read the call log

   Click View Logs. Each call shows its result, method and address for the past 30 days. A 403 means the key lacks a scope; here a write was refused because the key can only read. HubSpot stores no request content for successful calls, so log what you send in your own system.

   

5. Step 05

   Watch the daily usage

   Under Development > Monitoring > API Call Usage you see the calls of the last 24 hours against your daily limit, split into apps built in your account and third-party apps. All your private apps and keys share one daily limit.

   

HubSpot API rate limits by edition

HubSpot’s usage guidelines limit calls per 10 seconds for each app and per day for the whole account. The day resets at midnight in the time zone set in your account. Over the limit, calls fail with error 429 until the window passes.

The daily limit is rarely the problem. The usual causes of 429 errors are integrations that update one record per call, read every record again each night instead of only the changed ones, or lean on search.

• Search has its own limit: five requests per second per account, 200 records per page and 10,000 results per query. A sync that finds every record by search hits it first.
• Batch everything: create, update and read up to 100 records per call.
• Read only what changed: filter by last modified date, or let webhooks tell you.
• Large exports: the exports API returns a whole object in one file.
• Webhooks sent by workflows don’t count against the API limit.

Which HubSpot APIs need which edition

Most CRM APIs work on every plan, the free CRM included. A few follow the feature they belong to.

The Data Hub guide covers what else Data Hub Professional brings and when it pays.

A webhook doesn’t need Data Hub. The workflow action “Send a webhook” does, but an app built as a HubSpot project can subscribe to record changes on any plan. The app route takes a developer; the workflow action takes a few clicks.

HubSpot webhooks and custom code: calling other systems from a workflow

With Data Hub Professional, a workflow can run your own JavaScript or Python and call any web address. Workflow code covers short checks and pushes without a server of your own. The example checks that a won deal’s company has an ERP customer number, then sends the deal to the ERP.

1. Step 01

   Store the key as a secret

   In the custom code action, click “Add secret” and paste the service key there. The code reads it as process.env and the key never appears in the code. All secrets of one action together may be up to 1,000 characters.

   

2. Step 02

   Return values for later steps

   Define outputs, such as erp_ready and erp_customer_number. Later actions and branches use them, for example to stop a deal without an ERP number before it reaches the ERP.

   

3. Step 03

   Send the deal with a webhook

   Add “Send a webhook”: method POST, the address your ERP listens on, an API key from a secret in the request header, and only the fields the ERP needs. HubSpot retries a failed call for up to three days.

   

Limits to plan around

• 20 seconds and 128 MB per run. Nightly files and large jobs don’t belong here.
• Rate errors retry for up to three days, but only if the code throws the error. Code that swallows it marks the run as done.
• No version control. The code lives in the workflow. Keep the source in your Git repository, keep the action short and put the logic in a library you test there.
• Every enrolment is a run. A workflow that enrols 50,000 records at once makes 50,000 runs and their API calls.

For sales automation without code, our sales workflows guide shows what standard workflows already do.

App cards: show data from other systems on the HubSpot record

An app card is a small screen your developer builds into the record page. The card shows data that lives elsewhere, so sales sees the credit limit or the last invoice without copying every invoice into HubSpot. App cards work on every plan.

1. Step 01

   Build the app as a project

   Your developer creates a project with the HubSpot command-line tool on platform version 2026.09, with a card and, if needed, webhook subscriptions. The project lists its parts and its build history under Development > Projects.

   

2. Step 02

   Install it in your account

   On the app’s Distribution tab, click “Install now”. HubSpot lists the scopes the app asks for and warns that the app isn’t verified, which is normal for your own app. Check the scopes before you tick the box.

   

3. Step 03

   Subscribe to the changes you need

   Webhook subscriptions sit in the project file: here a company created and a deal stage changed. HubSpot sends them to your server as they happen. Up to 1,000 subscriptions per app.

   

4. Step 04

   Place the card on the record

   In the record layout editor, add the card where sales looks first. Your developer can show the values in each user’s language and number format, as here.

   

A card that only shows HubSpot data needs no server. A card that fetches data live from your ERP needs a backend your developer hosts, or HubSpot’s serverless functions, which need Enterprise.

HubSpot API versions in 2026, and the 2027 deadlines

Since March 2026, HubSpot names API versions by date, such as /crm/objects/2026-09/contacts, and releases a new one every March and September. Each is supported for 18 months. The old numbered versions are being phased out.

An unsupported API isn’t switched off on that day. HubSpot stops fixing it and no longer guarantees that it works. For an integration your order process depends on, treat the date as a deadline. HubSpot announces breaking changes about 90 days ahead in the developer changelog, which is why someone has to read it.

Move integrations straight to the newest dated version. A stop at v3 or v4 on the way means migrating twice. The Migrations page detects old calls when they run, so a quarterly export that didn’t run this month won’t show up. Check the code as well.

What breaks in HubSpot integrations, and who owns the code

These are the failures we see most in HubSpot integrations after go-live. Few of them start in the code.

HubSpot API errors and what they mean

The call log shows a code for each failed call. The four in this table come from the limits, scopes and rules above.

Since autumn 2026, every connected app in HubSpot has a formal owner, set to whoever installed it and changeable by an admin. When you deactivate a user, HubSpot warns you if they own or installed an app.

How to brief a developer for a HubSpot integration

Answer these twelve questions before anyone estimates the work, so every offer prices the same job.

1. 01The job in one sentence, from the user’s view: “Sales sees open items and the credit block on the company before quoting.”
2. 02The systems and their versions, and whether each is in the cloud or on your own servers.
3. 03Each field, its owner and direction: which system is right for it, and whether it flows one way or both.
4. 04The matching key: the ID that links a HubSpot record to the other system’s, never a name.
5. 05Volumes: records today, changes per day, the busiest hour.
6. 06How fast it must be: seconds, hourly or nightly.
7. 07Errors: what happens when a record fails, who is told, and how.
8. 08Access: service key or app, with which scopes, created in your account.
9. 09Your HubSpot rules: required fields, conditional properties and workflows that the integration will trigger.
10. 10Test plan: a sandbox or test account, test records, and who signs off.
11. 11Ownership: who owns code, hosting, keys and documentation, and who reads HubSpot’s developer changelog afterwards.
12. 12Version: the newest dated API version and platform 2026.09, nothing legacy.

HubSpot API projects in Germany, Austria and Switzerland

• ERPs on your own servers. Many ERPs here, from SAP to smaller systems, run on premises. HubSpot can only call them if IT opens an interface; otherwise the integration pulls from HubSpot instead. Clarify this first.
• Data processing. A middleware tool, a hosting provider or a developer’s server processes your customer data. Check where it runs and that a data processing agreement is in place. Your data protection officer decides; our EU data centre guide shows what HubSpot itself stores where.
• Works council. If an integration records what employees do, for example call or login data, involve the works council before it goes live.
• Formats. HubSpot’s API sends numbers with a dot and dates in ISO format. German formats belong in the display only, as in the card above.

How we go about HubSpot API projects

Our order of work on a HubSpot API project, from the brief to the handover.

1. Step 01

   Map the job

   The fields, owners, keys and volumes from the brief above, in one table, agreed with the people who use the data.
2. Step 02

   Check the shelf

   Marketplace apps, HubSpot’s own sync and existing tools in your stack, tested against the table.
3. Step 03

   Build the gap

   Only what nothing else covers, on the newest version, with read-only keys where reading is enough, and error alerts.
4. Step 04

   Hand it over

   Code in your repository, keys in your account, a named owner and a short runbook for what to do when it fails.

Frequently asked questions