Migrating from v2 to v3
Keep production on v2 until general availability on January 4, 2027.
Why it matters: until then v3 carries no support or SLA guarantees. After GA it carries v2’s. The exception is the v3-only surface, healthcare entities and webhooks: if you need it, go now.
- You will not be forced off v2. It stays fully supported. Only deprecated endpoints get sunset dates.
- Most endpoints just gain fields. Same request, richer response. One endpoint, Person Search, is deprecated.
- Discover does not. v3 reshapes its request body. Budget a rewrite, not a path swap.
How versioning works#
- The version is a path segment:
/v2/{environment}/…→/v3/{environment}/…. Move one endpoint at a time. - Auth, errors, rate limits, and normalization are global. Identical on both versions, nothing to migrate.
- Deprecated endpoints respond with
Deprecation: trueandSunsetheaders on v3 until removal. - The
testenvironment has full v3 parity. Run your integration suite there before touching live traffic.
Status at a glance#
| Functional area | Status | Action required |
|---|---|---|
| Person APIs | Deprecation | Adopt additive fields; stop assuming a professional social media URL is present; migrate Search → Discover before January 31, 2028 |
| Company & Product Catalog | Additive | None required — but stop assuming a social profile URL is present |
| Discover | Breaking | Rewrite request bodies into filter groups; re-baseline any stored counts |
| Vendorgraphics | No changes | None |
| Contact Info | No changes | None |
| Utilities, Errors & Rate limits | Global | None — unversioned |