On 15 September 2026 HubSpot announced the end of its old API versions. Every endpoint with /v1/, /v2/ or /v3/ in the path, and legacy private apps built before the Projects platform, stop being supported in September 2027. The /v4/ endpoints go earlier, on 30 March 2027. The first hard change lands this month: from 26 October 2026 existing portals can no longer create new legacy private apps.

A year sounds like plenty of time. It usually isn’t. Most HubSpot portals I work on have at least one integration nobody remembers building: a sync script a former contractor wrote, a custom-coded workflow action, a form handler on the website. Those are the things that break quietly when support ends. This post covers what is changing, how to check whether your portal is affected, and what a sensible migration looks like.

What is actually changing

  • API versions. HubSpot is moving from version numbers to date-based versions. /crm/v3/objects/contacts becomes /crm/objects/2026-09/contacts. Semantic versions (v1 to v4) all go unsupported.
  • Legacy private apps. The access tokens many integrations use come from legacy private apps. Existing ones keep working for now, but you can’t create new ones after 26 October, and they are unsupported from September 2027.
  • Legacy public apps. Marketplace and OAuth apps built before 23 June 2026 use the old architecture and need to move to the Projects framework to stay listed.
  • Replacements. For simple server-to-server integrations, HubSpot now offers Service Keys (currently in public beta): scoped API credentials with audit logs and a seven-day grace period when you rotate them. For anything bigger, such as webhooks, UI extensions or app cards, the answer is a Projects-based app on Developer Platform 2026.09.

“Unsupported” is not the same as “switched off” on day one, but it means no fixes, no guarantees and no help from HubSpot support when something stops working. Planning around it is cheaper than finding out the hard way.

Key dates

  • 15 September 2026: announcement; the migration window opens.
  • 28 September 2026: new HubSpot accounts can’t create legacy private apps.
  • 26 October 2026: existing accounts can’t create legacy private apps either.
  • 30 March 2027: /v4/ endpoints become unsupported.
  • September 2027: all v1 to v3 endpoints and legacy apps become unsupported.

Where the old APIs hide in a typical portal

The obvious place is your own integration code. The less obvious places are the ones that cause trouble:

  • Custom-coded workflow actions. Many call the CRM through @hubspot/api-client or plain fetch with a private app token stored as a secret. Each one is a small integration of its own.
  • CMS serverless functions that create contacts, read HubDB or look up deals for a member area.
  • Website form handlers and landing page scripts that post to the old forms or contacts endpoints.
  • Middleware and sync jobs between HubSpot and an ERP, a billing system or a product database.
  • Reporting scripts that pull data into BigQuery, Sheets or a BI tool on a schedule.
  • Old repositories that are still deployed somewhere, even if nobody has opened them in years.

Off-the-shelf Marketplace apps and tools like Zapier are the vendor’s responsibility. It is still worth listing them, so you know who to chase if one stops syncing.

A one-hour self-audit

You can get a reliable picture of your exposure in about an hour:

  • Open HubSpot’s migration view. In the Development section, go to Migrations and open the APIs tab. It lists the legacy endpoints your apps have called recently.
  • List every private app. In Settings, under Integrations, check Private Apps. Note each app’s name, scopes, owner and what it is for. If nobody knows what an app does, that is your highest risk.
  • Search your code. Search every repository, serverless function and custom-coded action for /v1/, /v2/, /v3/ and /v4/, plus api.hubapi.com.
  • Check your SDK versions. If you use HubSpot’s client libraries, note the version, because the client decides which paths you call.
  • Map each integration to a business process. “Syncs paid invoices to deals” is more useful than “invoice-sync.js”. It tells you what breaks, and for whom.
  • Give each one an owner and a target date. Before March 2027 for anything that uses v4, and before summer 2027 for the rest.
# Quick scan of a repository for legacy HubSpot API paths
grep -rnE "api.hubapi.com|/v[1-4]/" --include="*.js" --include="*.ts" --include="*.py" --include="*.php" .

What a sensible migration looks like

For most portals the work is smaller than it sounds. Many v3 endpoints have an identical contract in the 2026-09 version, so the change is a new path and a retest. Some v1 and v2 endpoints have no date-based equivalent yet, and those need a real redesign.

// Before
const res = await fetch(
  'https://api.hubapi.com/crm/v3/objects/contacts?limit=100',
  { headers: { Authorization: `Bearer ${process.env.PRIVATE_APP_TOKEN}` } }
);

// After: date-based version, Service Key credential
const res = await fetch(
  'https://api.hubapi.com/crm/objects/2026-09/contacts?limit=100',
  { headers: { Authorization: `Bearer ${process.env.HUBSPOT_SERVICE_KEY}` } }
);

The order I’d follow:

  • Stop creating new legacy private apps now. Anything new goes on a Service Key or a Projects app, so the list doesn’t grow.
  • Move v4 calls first. Associations and other v4 endpoints have the earlier March deadline.
  • Swap simple tokens for Service Keys with the narrowest scopes each integration needs. This is also a good moment to remove scopes nobody uses.
  • Move anything with webhooks or UI to a Projects app on Developer Platform 2026.09, which has an 18-month support window.
  • Test in a sandbox or developer test account before switching production, especially where response shapes changed.
  • Delete what you no longer need. Every audit I’ve done has found at least one integration that can be switched off instead of migrated.

Don’t leave it until summer 2027

The risk isn’t the migration itself. It’s the integrations nobody knows about, found the week something stops syncing, with the person who built them long gone. An hour of auditing now turns that into a planned, boring project.

If you’d like a second pair of eyes, I’m offering a free legacy API check for HubSpot portals: we go through your private apps, custom code and integrations together, and you get a short list of what needs to move and in what order. Book a free 30-minute call, or read more about my HubSpot development work.

Sources: HubSpot changelog: Legacy APIs and apps, what’s going unsupported and when · Legacy private app creation being disabled · Legacy API migration guide · Fall 2026 Spotlight developer updates