Audit API Usage Before the 2027 Cutoffs

In March 2026 HubSpot replaced semantic API versioning (v1-v4) with date-based versions (/2026-09/-style paths, two releases a year, at least 18 months of support each). Two clocks are now running: v4 loses support on March 30, 2027, and v1-v3 are already unsupported, with enforcement in September 2027. Separately, HubSpot is retiring legacy private apps in favor of service keys. This skill inventories what in your stack calls HubSpot and produces a migration checklist for both.

Why This Matters

The deadline fails quietly: unsupported APIs "no longer receive updates, bug fixes, or stability guarantees," and marketplace apps that don't migrate risk losing certification. A portal typically has more callers than anyone remembers — service keys, legacy private apps, marketplace apps, middleware (Zapier/Make), form embeds, internal scripts, data warehouse syncs. Finding them takes an afternoon now or an incident later.

Key Facts

Sources: HubSpot developer changelog, "Introducing date-based API versioning" (2026-03-30), "Deprecating support for HubSpot v4 APIs" (2026-05-21), "Legacy private app creation sunset" (2026-08-27), and "Legacy APIs and legacy apps: what's going unsupported and when" (2026-09-15). Re-check these before quoting dates to stakeholders; HubSpot has moved sunset dates before.

Prerequisites

• Super Admin access (to view Integrations settings and app logs)
• Optionally: a service key or existing legacy private app token (HUBSPOT_ACCESS_TOKEN in .env) for the account-level usage query
• Access to the source code of any internal integrations

Execution Pattern

Stage 1: Plan

Confirm with the user: which systems are known to touch HubSpot (CRM syncs, website forms, analytics pipelines, internal scripts), and who owns each.

Stage 2: Before — Build the Caller Inventory

Work through each discovery source and record every caller in a checklist (owner, what it does, endpoints/versions used):

1. Legacy private apps and service keys: Settings > Integrations > Private Apps, and Settings > Integrations > Service Keys. Open each legacy app > Logs: the API call log shows the exact request paths (/crm/v3/..., /contacts/v1/...), which reveal the version in use. Record every legacy private app as a migration item in its own right, whatever endpoints it calls.
2. Connected/marketplace apps: Settings > Integrations > Connected Apps. You can't see their internals; note each vendor — certified apps are being pushed to migrate by HubSpot, but confirm with the vendor for anything business-critical.
3. Internal codebases: grep for version-revealing patterns:

   grep -rEn "api\.hubapi\.com/[a-z-]+/v[0-9]|/contacts/v1|/email/public/v1|hubapi.com/automation/v[23]" .

4. Middleware (Zapier, Make, Workato, n8n): platform-managed connectors migrate on the vendor's schedule; custom HTTP steps inside them do not — check those by hand.
5. Account-wide API usage (optional script check): the account-info API reports daily API usage totals for privately distributed apps:

   resp = requests.get(f"{BASE}/account-info/v3/api-usage/daily", headers=HEADERS)

   This confirms how much traffic flows, not which versions — use the per-app logs from step 1 for version detail.

Stage 3: Execute — Classify and Plan Migrations

For every caller, classify:

For amber/red internal code, the migration is usually mechanical: same resources, new path shape (/crm/v3/objects/contacts becomes /crm/objects/2026-09/contacts) and sometimes renamed fields. HubSpot's migration guide says many v3 contracts carry over unchanged but not all, so test each endpoint rather than assuming. Batch the work per codebase, not per endpoint.

Test writes in particular. From 2026-09, a create or update that omits a property an admin marked required is rejected with MISSING_REQUIRED_PROPERTY or MISSING_CONDITIONAL_REQUIRED_PROPERTY. An integration that wrote sparse records through v3 will start failing after migration unless it sends those properties.

This repo's own scripts are amber: they target /crm/v3/, /marketing/v3/, and /automation/v4/. They work today, and they are on the migration list in CONTRIBUTING.md like everyone else's.

Stage 4: After

1. Every caller in the inventory has a status and an owner.
2. Red items have migration tickets with dates; v4 callers are scheduled before 2027-03, v3 callers and legacy private apps before 2027-09.
3. Re-run this audit every 6 months — each March/September release starts a new support clock.

Rollback

Read-only — nothing to roll back.

Technical Gotchas

1. App logs are the ground truth. Code greps miss dynamically-built URLs; the per-app request logs in Settings show what is actually being called.
2. 404 vs 403 vs unsupported. After end of support, endpoints may keep working for a while — "unsupported" means no fixes or guarantees, not an instant shutoff. Do not treat "it still works" as "we're fine."
3. You cannot create a new private app as a stopgap. After October 26, 2026 the option is gone for existing accounts. A new internal integration needs a service key from day one.
4. Service keys do not receive webhooks. An integration that relies on webhook subscriptions needs a projects-based app, not a service key.
5. OAuth is part of this. Apps using legacy v1 OAuth token endpoints must move to the date-based OAuth API even if their data endpoints are current.
6. SDK versions pin API versions. If an integration uses an official HubSpot SDK, the SDK's major version determines which API version it calls — check the SDK changelog, not just your code.