HubSpot Legacy APIs and Apps: What Businesses Should Audit Before the 2027 Migration Deadlines

HubSpot legacy API migration is now a two-layer business program: replace numbered API versions with date-based versions and move legacy app architecture to current Projects-based options. A useful audit must cover runtime calls, source code, app type, authentication, ownership, and the business workflows that depend on each integration.

That scope matters because an API endpoint rarely exists in isolation. It may move a website lead into HubSpot, enrich a customer record, synchronize an order, trigger lifecycle automation, or feed a management report. The technical change happens in code. The consequence appears in sales, marketing, service, or finance.

HubSpot’s 15 September 2026 announcement creates time to prepare, but the deadlines are not identical. API version, app architecture, and authentication need separate checks before one migration plan can be trusted.

Update log

• 16 September 2026: Initial publication based on HubSpot’s legacy API and app support announcement, v4 support notice, Developer Platform documentation, and Service Keys guidance.

What changed in HubSpot’s API and app support model?

HubSpot is moving integrations from numbered API paths and pre-Projects apps toward date-based API versions and the current Developer Platform. V1 to v3 APIs and legacy public and private apps face September 2027 enforcement. V4 has an earlier unsupported date of 30 March 2027, according to HubSpot’s separate v4 announcement.

This creates three workstreams that should be audited independently.

HubSpot says public apps created before 23 June 2026 use its pre-Projects architecture. Those apps need the current Projects-based model to retain Marketplace listing and certification. Legacy private apps also have a September 2027 migration requirement. New legacy private-app creation is scheduled to end on 28 September 2026 for new accounts and 26 October 2026 for existing accounts.

V4 needs its own line in the plan. HubSpot’s v4 support notice gives 30 March 2027 as the date when v4 becomes unsupported. Do not group that date under the later v1-to-v3 schedule.

The term unsupported also needs careful interpretation. It does not necessarily mean every call stops on the same morning. It means the integration no longer has the same expectation of updates, bug fixes, security improvements, or stability. For a business-critical workflow, that loss of assurance is enough to require a managed migration.

Next step. Already know you may be affected? Start with the migration plan for sequencing, testing and rollout. If you do not yet know which endpoints, apps or workflows depend on the legacy setup, use the integration audit checklist first.

Why is an endpoint-only audit incomplete?

Searching a repository for /v1/, /v2/, /v3/, and /v4/ is necessary, but it only reveals part of the exposure. The same business process may also depend on a legacy app, an unsuitable replacement credential, a changed object identifier, an external middleware workflow, or code that no longer appears in normal runtime logs.

The first-order task looks simple: find old paths and change the URL. The second-order task is to preserve the behavior around that call.

A newer endpoint may use a different request body, return a different response shape, enforce different scopes, or replace an identifier that another system stores. HubSpot’s v1 Lists API migration guide, for example, distinguishes legacyListId from the newer listId. HubSpot warns that using the wrong identifier can update or delete a different list. That is a data-mapping problem, not a text-replacement task.

Runtime evidence has limits too. A report of recent API calls can reveal active traffic, yet it may not expose:

• a quarterly finance export that did not run during the reporting window;

• a fallback process used only during an outage;

• a seasonal campaign workflow currently paused;

• an integration owned by an external agency or former employee;

• source code that remains deployable even though the current production path is quiet.

Your audit therefore needs two forms of evidence: observed activity and a code-and-configuration inventory. Either source on its own can leave an important dependency unowned.

This is where a general review of your HubSpot integrations becomes more specific. The question is no longer which integrations add value. It is which integration components your business depends on, who can change them, and how you will prove that their replacement behaves correctly.

Which parts of the business system should you audit?

A complete HubSpot legacy integration audit covers five connected layers: API usage, app architecture, authentication, business dependencies, and operational ownership. The output should let a technical owner estimate the change while giving a business owner enough context to rank its importance.

1. API usage in production and source code

Start with HubSpot’s migration or usage views where available, then search every relevant codebase and automation platform. Record the HTTP method, endpoint, API version, request body, response fields, scopes, error handling, rate-limit behavior, and calling frequency.

Extend the search beyond the main application repository. Common locations include serverless functions, data pipelines, middleware, integration-platform workflows, scheduled scripts, reporting jobs, website forms, custom workflow actions, and archived repositories that can still be deployed.

Do not assign a replacement endpoint until you have compared behavior. A v1 call and its date-based replacement may represent the same business action while differing in identifiers, associations, pagination, filters, or returned properties.

2. Public and private app architecture

List every HubSpot public and private app, then classify it as legacy or Projects-based. For public apps, document whether the app is distributed through the HubSpot Marketplace, installed through an allowlist, or used through another distribution model.

Marketplace teams have two separate compliance questions: which API versions the app calls and which architecture the app runs on. Updating endpoint paths does not move a pre-Projects app into the current architecture. Migrating the architecture does not update every API call inside it.

HubSpot’s Developer Platform overview explains that current platform apps are created and deployed through the HubSpot CLI. That changes ownership expectations. Your audit should identify who controls the project source, deployment access, environments, and release process.

3. Authentication and credential use

Record each credential, the integration that uses it, its scopes, the accounts it can reach, where it is stored, when it was last rotated, and who can revoke it. This is also the point to determine whether the replacement should use a Service Key, a Projects-based app token, or OAuth.

HubSpot describes Service Keys as account-level credentials for data-only integrations. A scheduled data sync or internal script may fit that model. An integration that needs webhooks, UI extensions, app pages, or distribution across multiple accounts needs a Projects-based app and, where relevant, OAuth.

Do not choose the credential model from the current token alone. Choose it from what the integration does and how it is distributed.

4. Business workflows and data dependencies

Map every technical asset to a business action. Useful categories include lead capture, customer or company synchronization, order and product data, lifecycle automation, service processes, consent handling, audience creation, attribution, and management reporting.

For each workflow, record:

• the system of record;

• the direction and frequency of data movement;

• the fields and identifiers that must remain stable;

• the teams that consume the result;

• the acceptable delay or outage window;

• the reconciliation method after a test or cutover.

This dependency map also supports better HubSpot data management. A migration can produce technically valid responses while changing field mapping, list membership, association logic, or update order. Business acceptance must therefore test the resulting records and workflows, not only the API response code.

5. Ownership, environments, and test evidence

An integration without a named owner is harder to migrate than a complex integration with current documentation. Record the business owner, technical owner, repository, vendor, deployment method, test environment, monitoring location, and rollback route.

Then define the evidence required for acceptance. Depending on the workflow, that may include record counts, field-level comparison, association checks, workflow enrollment, duplicate detection, webhook delivery, report reconciliation, or confirmation from the operational team that uses the output.

The audit should make ownership visible before development begins. If no one can approve the expected behavior, the technical team cannot prove that the migration preserved it.

How should you prioritize the migration exposure?

Prioritize each integration by deadline, business consequence, replacement uncertainty, and change surface. An earlier unsupported date raises urgency. A revenue or customer-service dependency raises impact. Missing endpoint parity or unclear ownership raises uncertainty. A wide response-model change increases the amount of testing required.

A practical first pass uses four queues.

Queue D often creates the most planning friction. A quiet integration can be obsolete, seasonal, or waiting for a specific event. Treat absence of traffic as a question to resolve, not proof that the asset is safe to remove.

The prioritization should also remain separate from the build estimate. A small code change can deserve high priority because it supports lead capture. A larger internal reporting integration may tolerate a later slot if the business has an agreed temporary route. Effort and consequence are different variables.

What should business and technical owners decide after the audit?

The audit should end with decisions, not a longer inventory. Each integration needs a named target model, accountable owners, an evidence-based priority, unresolved questions, and the next checkpoint. That creates a stable boundary between understanding the exposure and planning the migration itself.

For every item, confirm:

1. Disposition: migrate, replace, consolidate, or retire.

2. Target: date-based endpoint, Projects-based app, Service Key, OAuth, or another documented route.

3. Ownership: one business approver and one technical owner.

4. Evidence: what must match before and after cutover.

5. Dependency: which teams, vendors, systems, and release windows affect timing.

6. Open issue: missing parity, unclear documentation, credential choice, or unverified dormant use.

Businesses with a broad HubSpot estate may also need to assess whether the current delivery model can support the work. Flatline’s guide to choosing a HubSpot partner offers a useful starting point for evaluating technical capability, integration knowledge, and fit. The migration audit itself should remain vendor-neutral: define the work before deciding who should perform it.

Review the plan again when HubSpot publishes replacement details or changes a support date. The article’s dates reflect official information available on 16 September 2026. The latest HubSpot documentation should remain the authority at production and cutover time.

Key takeaways

• HubSpot’s migration affects API versions, app architecture, and authentication. Audit the three layers independently before combining them into one plan.

• V4 has an earlier unsupported date of 30 March 2027. V1 to v3 and legacy app enforcement follow in September 2027 under HubSpot’s current announcement.

• Runtime usage reports need a source-code and configuration review beside them. Dormant, seasonal, fallback, and externally owned integrations may not appear in recent traffic.

• Map every technical asset to its business workflow, owner, acceptance evidence, and fallback route. A successful response code does not prove that the business outcome stayed intact.

• Finish the audit with a disposition and target model for each integration. That turns an inventory into a migration brief.

The immediate goal is a reliable map of the HubSpot estate: what exists, what it supports, who owns it, and which decision comes next. Once that map is agreed, teams can migrate in a sequence based on consequence and evidence instead of endpoint count alone.