HubSpot's Legacy API Sunset: What Admins Must Do Before September 2027

If you admin a HubSpot portal, this notice may already be waiting for you. HubSpot is surfacing "Apps with API versions to update" notifications in accounts where installed apps still call legacy endpoints — and the list it generates is the starting point for a migration every HubSpot customer with integrations needs to complete before September 2027.

The good news: HubSpot has given unusually long lead time, the audit tooling is built into the product, and for many integrations the fix is closer to a find-and-replace than a rebuild. The risk is ignoring it because it looks like a developer problem. It is not — it is an operations problem with a developer task at the end.

What changed: HubSpot replaced v1–v4 with date-based API versions

On March 30, 2026, HubSpot announced the move from semantic API versions (v1, v2, v3, v4) to date-based versions in a /YYYY-MM/ format, such as /2026-03/ and /2026-09/ (read the changelog announcement). Under the new model, described in HubSpot's platform versioning documentation:

• New versions ship twice a year — in March (around Spring Spotlight) and in September (around INBOUND).
• Each version is immutable. Once /2026-09/ ships, its behavior does not change under you.
• Every version gets a minimum 18-month support window, so you always know exactly how long what you built on will keep working.
• Breaking changes land only at those twice-yearly releases, not as mid-cycle surprises.

For teams that maintain integrations, this is a genuinely better model: the version in your URL tells you its age and its support horizon at a glance. HubSpot's developer's guide to date-based versioning walks through the reasoning in detail. But the same change sets the clock on everything built before it.

The sunset timeline: March 2027 and September 2027

Per HubSpot's legacy API migration guide (last modified September 15, 2026), the retirement happens in two waves:

Eleven months sounds comfortable until you subtract scoping, vendor response times, testing, and the change freezes most teams observe around year-end. A migration started in spring 2027 is a migration under pressure; one started this quarter is a line item.

Who is affected — and why it is not just a developer problem

Any portal with software that calls HubSpot's APIs is in scope. That includes private apps your own team built, custom integrations and middleware, and third-party apps installed from the marketplace or supplied by a vendor. HubSpot's migration guide calls out endpoint families that show up constantly in real-world portals: CMS blog posts, CMS site and landing pages, blog settings, templates, URL redirects, and site search — so content and website integrations are squarely in scope alongside CRM syncs. If your team runs a connected tech stack, like the ones we map in our guide to building HubSpot integrations for mid-market growth, assume at least one connection needs review.

This is why the notice belongs on an ops leader's desk, not only in a developer's inbox. The business owner of the portal often does not know which APIs their integrations call — and does not need to. HubSpot's in-app tool answers that question in plain terms: which apps, which endpoints, which sunset date, and how much recent call volume each one carries. Your job is to run the audit and route the results; your developer or vendor's job is the code change.

How to check whether your portal is affected, step by step

1. Open the audit tool. In your HubSpot account, go to Development → Migrations → APIs (the path as of October 2026). Accounts with affected apps will also see the "Apps with API versions to update" notification.
2. Read the list. Each entry shows the app, the legacy endpoint it calls, the endpoint's version, the sunset date (September 2027), and recent call volume for that app.
3. Split the list by owner. Mark each app as internal (your team maintains it) or external (a vendor or marketplace publisher maintains it). Internal apps need your developers; external apps need a vendor conversation.
4. Prioritize by criticality and volume. An integration that syncs deals every night outranks a quarterly reporting job, and high-volume endpoints carry the most operational risk.
5. Save the inventory. Export or screenshot the list into a spreadsheet. It becomes your migration punch list and your checklist for verifying the portal is clean afterward.

If the tool shows no apps, nothing calls legacy endpoints in your portal and no action is needed today.

What to do: the migration process HubSpot recommends

HubSpot's recommended sequence is audit, map, migrate, test — in that order, and not in production first:

1. Audit via the in-app Migrations tool (the steps above) so you are working from HubSpot's own record of what your apps actually call, not someone's memory of what they were built to call.
2. Find the date-based equivalent for each endpoint. In the HubSpot API reference, use the version dropdown to switch the documentation to 2026-09 and locate the matching operation. Many v3 and v4 endpoints have feature parity there.
3. Migrate the code. For many endpoints this is a URL swap — but copy the full new URL, because the version slug moves position in the path:

GET /crm/v3/objects/contacts → GET /crm/objects/2026-09/contacts

Do not assume the URL is the only change. Some endpoints changed request bodies, parameters, or response shapes between the legacy version and 2026-09, so compare the old and new reference pages field by field before cutting over.

4. Test before production. Run the migrated integration in a HubSpot test account or a duplicate project, confirm the Migrations tool no longer flags the app, and only then deploy to your production portal.
5. Monitor after cutover. Watch the integration's first scheduled runs and confirm the audit tool stays clean.

Migration checklist

• Inventory exported from the Migrations tool, split by internal vs. vendor ownership
• Every endpoint mapped to a 2026-09 equivalent — or flagged as "no equivalent yet"
• Request bodies, parameters, and response parsing compared field by field, not assumed identical
• Migrated integrations tested in a HubSpot test account or duplicate project
• Written vendor confirmations for every third-party app
• Cutover scheduled before March 2027 for anything touching v4 or /2025-09/ CRM APIs, and before September 2027 for everything else
• Post-cutover verification that the Migrations tool reports no remaining legacy calls

What if an endpoint has no date-based equivalent yet?

Some older v1 and v2 endpoints do not have a date-based equivalent as of October 2026. HubSpot says the migration guide is updated regularly as those gaps close, so the correct posture is: migrate everything that has an equivalent now, track the short remainder against the guide, and raise any blocker with HubSpot support or your implementation partner so it is on record well before September 2027. Do not let a missing equivalent for one endpoint stall the migration of twenty that are ready.

Newer integration surfaces, like the HubSpot MCP server for AI CRM integration, build on the current platform — one more reason legacy surface area is shrinking rather than being maintained indefinitely.

What to ask your integration vendor or implementation partner

For every external app on your audit list, send the vendor five questions:

• Which HubSpot API versions does your app call in our account today?
• Have you migrated to date-based endpoints (target /2026-09/), and if not, when will you?
• How does your timeline compare to the March 2027 (v4 and /2025-09/ CRM APIs) and September 2027 (all legacy APIs) deadlines?
• Will the migration arrive as a normal product update, or does it require a plan change or paid work?
• After your update ships, how will you confirm our account no longer appears in the Migrations tool?

A vendor with no answer to the first two questions in late 2026 is telling you something about their maintenance posture. Factor that into renewal decisions.

How Vantage Point Helps

Vantage Point is a HubSpot Solutions Partner, and API-driven integration work is core to our HubSpot consulting practice. We help ops leaders run the Migrations audit, separate internal from vendor-owned fixes, map legacy endpoints to their 2026-09 equivalents, and sequence the work against the March and September 2027 deadlines. Where the migration touches broader data flows, our system integration and data migration team handles the rebuild and testing, and our senior consultants validate the portal is clean before cutover. Senior consultants only — no junior handoffs; the experts you meet are the experts who deliver.

Frequently Asked Questions

When does HubSpot's legacy API sunset take effect?

September 2027 for all legacy semantic-versioned APIs (v1, v2, v3, and v4). Two groups lose support earlier: v4 APIs and the /2025-09/ CRM APIs sunset at the /2027-03/ release in March 2027. These dates come from HubSpot's migration guide, last updated September 15, 2026.

What is date-based API versioning in HubSpot?

Date-based versioning names each API version after its release month in a /YYYY-MM/ format, such as /2026-03/ or /2026-09/, instead of semantic versions like v3. HubSpot introduced it on March 30, 2026; new versions ship twice a year (March and September), each version is immutable, and every version is supported for a minimum of 18 months.

How do I know if my HubSpot account uses legacy APIs?

Check the in-app audit tool at Development → Migrations → APIs. Portals with apps calling legacy endpoints receive an "Apps with API versions to update" notification, and the tool lists each legacy endpoint, its version, its sunset date, and recent call volume per app. If the list is empty, none of your apps currently call legacy endpoints.

Will my HubSpot integrations break in September 2027?

Any integration still calling legacy endpoints after the sunset dates risks failing once support ends. The practical risk arrives sooner for v4 and /2025-09/ CRM APIs, which sunset in March 2027. Migrating to date-based endpoints — for many endpoints a URL change — removes the risk.

How hard is it to migrate from v3 to a date-based endpoint?

For many endpoints, it is a URL swap: GET /crm/v3/objects/contacts becomes GET /crm/objects/2026-09/contacts, with the version slug moving position in the path. Some endpoints changed request bodies, parameters, or response shapes, so compare fields one by one in the API reference before cutting over, and test in a HubSpot test account first.

What should I ask my integration vendor about the API sunset?

Ask which HubSpot API version their app calls today, whether they have migrated to date-based endpoints, and when the migration will ship relative to the March 2027 and September 2027 deadlines. Also ask whether the update arrives as a normal product update and how they will confirm your account no longer appears in the Migrations tool.

What happens if an endpoint I use has no date-based equivalent?

Some older v1 and v2 endpoints do not have date-based equivalents yet, and HubSpot says the migration guide is updated regularly as gaps close. Migrate every endpoint that has an equivalent now, track the remainder against the guide, and raise the gap with HubSpot support or your partner so it is on record before September 2027.

Sources

• Legacy API Migration Guide — HubSpot Developers (last modified September 15, 2026)
• Introducing Date-Based API Versioning — HubSpot Changelog, March 30, 2026
• Platform Versioning — HubSpot Developer Documentation
• A Developer's Guide to HubSpot's Date-Based API Versioning — HubSpot Developer Blog
• HubSpot API Reference — Latest Version Overview

Vantage Point is a boutique CRM consulting firm helping businesses transform with Salesforce, HubSpot, and AI. Learn more at vantagepoint.io.