HubSpot's 2026-09 API Is Live: CRM Write Validation Now Applies to All API Calls
On September 8, 2026, HubSpot shipped the /2026-09/ API version — the second release in its twice-yearly date-based versioning cadence. For most marketing teams the day passes without incident. For developers maintaining custom CRM integrations, it is a hard deadline with real consequences: admin-configured validation rules now apply to every CRM API write, not just actions taken inside the HubSpot UI. Integrations that bypassed field requirements or association permissions in the UI will surface errors from today.
Two additional deprecations are also on the calendar: legacy private app creation is being disabled starting September 28 for new accounts, and the Pipelines API V1 reaches sunset on December 4. Here is a clear breakdown of what changed, who is affected, and what needs to happen before the next milestone.
HubSpot's date-based API versioning: a quick orientation
HubSpot introduced date-based API versioning in early 2026, moving away from the older v1 / v2 suffix model. The mechanics are straightforward:
- New versions ship twice a year, in March and September.
- Each version is immutable once released — no mid-lifecycle breaking changes.
- Each version carries a minimum 18-month support window, giving teams adequate migration time.
- You opt into a new version by updating your API path prefix from
/2026-03/to/2026-09/. Existing calls on an older version continue working until that version’s end-of-life.
The March 2026 version introduced the versioning system itself. The September 2026 version is the first to carry a major breaking change in the CRM write path.
The breaking change: CRM API write validation enforcement
This is the change that matters most for active integrations. Before 2026-09, HubSpot admins could configure validation rules inside the platform — conditional required properties, record-creator restrictions, user-level association permissions — and those rules applied only when a human was working in the HubSpot interface. API writes from custom integrations, automation scripts, or third-party tools bypassed these rules entirely.
Starting September 8, the /2026-09/ API version enforces those same rules on API writes. An API call that creates or modifies a contact, company, deal, or other CRM object is now subject to the same validation the UI enforces.
What kinds of rules are now enforced?
| Rule type | What it means in practice | API impact |
|---|---|---|
| Conditional required properties | A field becomes required when another field has a specific value (e.g., "Industry" required when Deal Stage is Qualified) | API writes that omit the newly required field return a validation error |
| Required fields on the Create Record form | Admin marks certain properties as mandatory for new record creation | POST requests missing those properties are rejected on /2026-09/ |
| User-level association permissions | Admins restrict which users (or service accounts) can associate specific record types | Association write calls from service tokens without permission return 403 |
The practical implication: if your HubSpot admin has configured any of these rules since your integration was built, the integration may have been silently non-compliant — writing records that would fail UI validation — and it will now surface errors when called on the new version.
How to find out if you are affected
- Audit your admin validation rules. In HubSpot, go to Settings → Objects → [Object type] → Record customization and review any conditional required properties and creator restrictions currently active.
- Run a test write on /2026-09/. Before updating your integration’s production paths, point a test call at
/crm/v3/objects/contacts?hapikey=...using the /2026-09/ version prefix and observe whether your payload passes validation. - Check your service token’s permissions. If your integration uses a private app token, verify its associated user scope has the association permissions the new version now enforces.
- Update the API version in your integration path. Only integrations that opt into /2026-09/ trigger the new validation. If you stay on /2026-03/ until that version’s end-of-life, validation does not apply — but you also lose access to any new endpoints shipping in the September version.
Legacy private app creation sunset
Alongside the API version update, HubSpot announced a phased shutdown of the ability to create new legacy private apps — the older, non-Project-based authentication method that predates the Developer Platform Projects system.
| Account type | Sunset date | What changes |
|---|---|---|
| New HubSpot accounts (created on or after Sep 28, 2026) | September 28, 2026 | Cannot create new legacy private apps from day one |
| Existing HubSpot accounts (created before Sep 28, 2026) | October 26, 2026 | UI option to create legacy private apps removed |
| Existing legacy private apps (all accounts) | Not affected yet | Existing apps continue functioning; only new creation is blocked |
The replacement is Service Keys, available through Developer Platform Projects version 2026.09 and later. Service Keys are designed for the same system-to-system use cases legacy private apps covered, with improved scope management and audit logging. If you need to spin up a new integration in October or beyond, the migration path is to create a Developer Platform Project and issue a Service Key from there.
Agencies maintaining multiple client HubSpot portals should prioritize this migration now: after October 26, you will not be able to add a new private app to any existing portal, which blocks standard onboarding workflows that rely on quick token generation.
Pipelines API V1 sunset: December 4, 2026
The third deprecation on the September 2026 changelog is the Pipelines API V1, which reaches end-of-life on December 4, 2026. Any integration that reads or writes pipeline data using /deals/v1/pipelines or the equivalent contacts/ticket pipeline endpoint will stop receiving responses after that date.
The migration target is the CRM Pipelines API available under the date-versioned path. The V1 schema uses a different object model — stages are nested arrays under a pipeline object, whereas the current API treats stages as first-class objects with their own IDs — so this is not a path swap; it requires testing the response structure against whatever downstream logic parses pipeline data in your integration. Teams using event-driven architecture to fan out pipeline stage changes to other systems should pay particular attention: the stage ID format changes, and hardcoded IDs in event listeners will break.
Who is affected across different team types
Not every HubSpot user will feel these changes the same way. Here is a practical breakdown:
Marketing ops teams
If your HubSpot instance uses data sync tools like HubSpot’s native integrations with Salesforce, Segment, or a reverse ETL tool like Census or Hightouch, check whether those tools operate on the versioned CRM API path. Native HubSpot integrations typically manage their own API versioning through the vendor’s update cycle — your action is to verify with the vendor that their September update is in or queued. For custom-built sync scripts, the validation enforcement is the primary risk.
Revenue operations and CRM admins
The validation enforcement change is actually good news for data hygiene. Records that should have been complete but were allowed through via API bypass — contacts without a required "Company Size" field on enterprise deals, for example — will now be blocked at the point of entry rather than discovered during a quarterly data audit. The tradeoff is short-term friction as integrations are updated; the long-term gain is a cleaner, more trustworthy CRM.
Developers and agencies
The critical path is straightforward: audit validation rules, run test writes on /2026-09/, update your integration paths, and plan the legacy private app migration before October 26. If you are also maintaining pipeline integrations, scope the V1 migration before November to leave adequate buffer before the December 4 cutover.
For teams whose CRM integrations have grown organically over several years — layered across multiple private apps, custom webhook listeners, and ad hoc automation scripts — this update is a reasonable prompt to map the full integration surface. A HubSpot audit before any version migration reduces the risk of a fix in one place breaking an undocumented dependency in another. If these integrations have become complex enough that a structured user acceptance testing cycle makes sense before migrating to the new API version, build that into your timeline before September 28.
The broader shift: API parity with UI rules
The validation enforcement change reflects a deliberate strategic decision by HubSpot. For years, the gap between UI validation and API validation was an unofficial feature — it let developers write records quickly without fighting admin-configured constraints, even when those constraints existed for good data governance reasons. That gap is now closing, at least for teams that opt into the new API version.
This aligns HubSpot with how most enterprise CRM systems already work: Salesforce, for example, has long enforced validation rules at the API layer. For teams building new integrations or evaluating the build vs buy decision for their CRM tooling, the new enforcement model means HubSpot integrations need to be built to the same standards as the UI — which is architecturally healthier but more demanding upfront.
If the validation changes have surfaced structural gaps in your CRM data model, or if this update is the prompt to move from ad hoc HubSpot scripts to a properly scoped integration, the September window is a practical starting point. Teams that need a custom CRM integration built to spec — one that handles validation logic correctly from the first write rather than patching it later — will find the new enforcement model makes the investment easier to justify to stakeholders.
Migration checklist
- Review all active HubSpot admin validation rules in Settings → Objects → Record customization.
- Identify every integration, script, or third-party tool that writes to the HubSpot CRM via API.
- Run test writes against /2026-09/ in a sandbox portal before touching production.
- Update API path prefixes in your integration code from /2026-03/ to /2026-09/ after tests pass.
- Plan legacy private app replacements before October 26 — migrate to Service Keys via Developer Platform Projects.
- Map all Pipelines API V1 calls and migrate to the date-versioned Pipelines API before December 4.
- Document the integration surface now, while the context is fresh, so the next version cycle (March 2027) requires less archaeology.
FAQ
What is HubSpot's 2026-09 API version?
It is the September 2026 release of HubSpot's date-based versioned API, shipping on September 8, 2026. Versions release twice yearly (March and September), are immutable once shipped, and carry an 18-month support window. The 2026-09 version introduces CRM write validation enforcement as its primary breaking change.
What does CRM API write validation enforcement mean?
Admin-configured rules that previously only applied to HubSpot UI actions — conditional required properties, record-creator restrictions, association permissions — now also apply to API write calls on the /2026-09/ version path. Integrations that omit required fields or use service accounts without the right permissions will receive validation errors.
Do I have to migrate to /2026-09/ immediately?
No. Existing integrations on /2026-03/ continue working until that version reaches end-of-life (18 months from March 2026). You only encounter the new validation rules if you update your API path to /2026-09/. However, new endpoints and features shipping in September 2026 are only accessible on the new version path.
What happens to my existing legacy private apps after October 26, 2026?
Existing legacy private apps continue functioning after October 26 — only the ability to create new ones is removed. For new integrations, the replacement is Service Keys issued through Developer Platform Projects. HubSpot has not announced an end-of-life date for existing legacy apps yet.
When does the Pipelines API V1 stop working?
December 4, 2026. After that date, calls to the V1 Pipelines API endpoints will not receive responses. The migration path is to the date-versioned CRM Pipelines API, which uses a different object model for stages — test the response structure carefully before cutover.
