We designed this playbook to serve both developers maintaining source code and builders who manage automations, middleware, Postman collections, or HubSpot configurations. The objective remains the same for both groups: shift HubSpot API versioning from a reactive emergency response to a predictable, low-risk, scheduled maintenance workflow that integrates seamlessly into your existing development cycles!
If you write code, this guide will help you audit endpoints, centralize versioning, test safely, and roll changes out with confidence. If you’re less code-savvy, use this guide as an operational checklist. You may not need to change the source code directly. However, you still need to know which HubSpot APIs your tools rely on, whether those API endpoints have date-based version (DBV) equivalents, which version your integration calls, and how to validate that critical workflows still work after an API version change.
The most important mindset shift is this: treat the HubSpot date-based API versioning upgrade like any other dependency upgrade. It should be scoped, testable, observable, and scheduled, and not something you discover only after a workflow breaks!
Each step is written so that both technical and less technical readers can follow it:
For every step, try to answer these 3 simple questions:
If your team includes both developers and builders, work through this playbook together. Builders are often closest to the business workflow that could break, while developers are closest to the code or client configuration that needs to change.
Start by getting a clear picture of how your integration interacts with HubSpot today. Identify all HubSpot endpoints your code calls, including background jobs, webhooks, and one-off utilities. For each endpoint, note whether it uses a semantic version (such as v3 or v4) or a date-based version (such as /2026-03/).
For teams, this step is quickest if you:
You can also:
As you go, capture:
Common roadblock: Teams get stuck waiting for “everything” to be on DBV before starting. Treat DBV availability per endpoint as metadata in this inventory, and plan to migrate incrementally rather than all at once.
This inventory becomes your migration checklist, your source of truth for testing, and your map of who needs to be looped in. It also helps you prioritize: the flows with real customer impact should get the most attention during testing and rollout.
Next, choose the DBV release you want to adopt first, such as /2026-03/. When picking a version, confirm two things:
In practice, that often looks like:
You do not need to target the latest version immediately if it does not offer anything you need, and the API you are leveraging is still supported.
Before changing any behavior, ensure your integration can switch API versions without a major code refactor.
The most effective pattern is to centralize the API version in a single place - such as an environment variable or shared silent constructor - rather than hard-coding versions through the codebase (don’t do that). For example, instead of embedding v3 or /2026-03/ in every request, define it once and reference it everywhere.
This single change dramatically reduces the cost of future upgrades. It also gives you a clean rollback lever if you need to revert during testing or rollout.
If your integration uses a HubSpot SDK rather than raw REST calls, your migration path may be simpler than manually updating the endpoint.
The public Typescript, Python, PHP, and Ruby SDK repos all include HubSpot’s date-based versioned APIs for the 2026-03 release, meaning these SDKs incorporate the latest API versioning format.
Some important notes about this update:
For most teams, the safest SDK migration pattern is:
Important note: Currently, HubSpot’s SDKs do not support a hybrid upgrade approach, meaning that you cannot leverage legacy semantic versions (v3 or v4) with date-based API versions in the same SDK. However, you can leverage either the semantic API version or the date-based API version. Additionally, DBV support for the Node.js SDK library will be released by the end of Q2 2026.
With the configuration in place, point your integration at the target date-based version in a non-production environment.
Start by running your existing automated test suite. Because DBV versions are snapshots, most differences should be intentional and documented rather than surprising. After automated testing, manually validate business-critical flows, especially those that impact customer-visible behavior, billing, error handling, pagination, downstream processing, or data synchronization. If you’re upgrading close to a release window, using the corresponding beta version in staging can help you catch issues early. Still, betas should not be the only version your production traffic relies on.
For a non-code-savvy builder, the best practice is to validate workflows based on business outcomes rather than endpoints. For each critical workflow, describe it in plain language, the expected result, and run it in a test or staging environment. Then, confirm the result in HubSpot and any connected system, and make sure to note anything changed or failed.
Test a few realistic scenarios, including a normal case, a case with missing optional fields, and a case that should fail gracefully. If possible, have the person who created the workflow or uses it most, validate it - they often know the behavior best!
This step is about confirmation - not discovery. By this point, you should already know which workflows matter most and what success looks like for each one.
Once testing looks solid, roll out the version change incrementally.
Common rollout strategies include:
Make sure to track:
If something goes wrong, pause the rollout and switch back to the last stable API version or SDK release. Then, recheck your most important workflows to confirm they have recovered before you resume.
Treat this like any other dependency upgrade: observable, reversible, and incremental.
Finally, make DBV upgrades part of your normal maintenance processes. This is where most teams either succeed or end up back in “surprise migration” mode.
By setting expectations early, version upgrades become routine rather than emergency responses to deprecations.
This playbook shifts API version upgrades from reactive fixes to planned maintenance. Once the initial migration is done and versioning is centralized in your configuration, future upgrades should be small, predictable changes that fit naturally into your existing development workflow.
For many teams, the migration itself is manageable. The bigger source of confusion is understanding what the new URLs mean and which path to trust.
2026-03 is the version, not a date to edit
In a path like /crm/objects/2026-03/contacts, 2026-03 is the API version name. It is neither a placeholder date nor an error in the docs. You do not update that value on every request; you only change it when you intentionally migrate to a newer release, such as /2026-09/.
Copy the documented path URL exactly
With DBV, the version's position in the URL matters. If the developer documentation shows/crm/objects/2026-03/{objectType}/search, then that is the supported URL path. If another URL appears to work, but is not documented, treat it as an undocumented alias, not a supported contract. Do not build against unsupported path variations just because they happen to resolve today.
The safest rule to give a developer is:
This guidance aligns with DBV's purpose: predictable contracts and explicit upgrade boundaries.
Not every similar-looking path is equivalent
Some confusion comes from assuming that if two paths look similar, they are interchangeable. They are not always. Some common examples include:
To reduce mistakes, I recommend this checklist:
If you cannot find the DBV endpoint, do not guess
Semantic versions (like v3 and v4) continue to work for now, and early DBV releases are intentionally close to the latest semantic behavior. However, legacy versions will move to unsupported status on a schedule (for example, current v4 APIs become unsupported with the release of /2027-03/), so you should plan migrations rather than waiting until the last minute.
What if not all APIs I use have DBV equivalents yet?
That’s expected. Run a hybrid setup where:
Can I pin production traffic to /YYYY-MM-beta/ for the long term?
We strongly recommend that you don’t. Betas are temporary, may change, and will be unsupported shortly after the corresponding GA version ships. Use betas in staging and short-lived experiments, then move production to the GA /YYYY-MM/ API version as soon as it’s available.