API Versioning
Use this page to understand version lifecycle and support policy.
Dated versions of our APIs are released when we introduce backwards-incompatible changes to a generally available product or feature. Changes may be limited to a single endpoint or multiple endpoints. The specific changes are listed in the Versions section, including how to pass version information.
Version support
On release, versions will have at least 18 months of support. After a new version is announced, a deprecation date will be set. After a year-long deprecation period, versions will sunset.
- Supported version: Release is actively supported and available on the documentation site for at least 18 months from launch of version or announced deprecation date.
- Deprecated: Version is still available to use for 12 months after deprecation date. Documentation for deprecated versions will not be updated.
- Sunset: Twelve months after deprecation date, the version will sunset. Access to the version is removed, attempts to reach the version will return an error.
Breaking changes
The following are not backwards compatible and will require a new version.
- Adding a new required request parameter, or converting a previously optional request parameter parameter into a required one
- Removing a request parameter from the url or body of request (optional or required)
- Changing the semantic meaning of a parameter
- Changing the type of parameter
- Adding a new validation rule to an existing parameter
- Removing a response field
- Renaming a response field
- Removing enum values
- Altering the existing data structure of a response body to make it non-backwards compatible
- Altering the kind of data a response field returns (e.g. converting an integer to a string)
- Removing, moving, or changing endpoint paths
Non-breaking changes
The following are considered backwards compatible and will not require a new version:
- Adding new API endpoints
- Adding an optional request header
- Adding new optional parameters to existing endpoints
- Adding new data elements to existing response schemas
- Adding a new response header
- Changing the order of properties in existing API responses
- Changing the length or format of opaque strings, such as object IDs, error messages, and other human-readable strings
- Converting a previously required request parameter into an optional parameter
- Sunsetting an existing, deprecated version
Versions
| Version | Accept-Version Header | Description | Migration Guide |
|---|---|---|---|
| rc20260430 | rc20260430 | Current release. Consolidated response schemas, updated aggregation behavior, sunset managed endpoints. | Migration Guide |
| v20250224 | v20250224 | Enhanced search and filtering with product support. New dataRequest field required. | Migration Guide |
| v20111101 | v20111101 | Legacy version. Not recommended for new implementations. | N/A |