---
updatedAt: 2026-06-17T17:37:14.000Z
---
Fetch the complete documentation index at: https://docs.gusto.com/embedded-payroll/llms.txt. Use this file to discover all available pages before exploring further. Append .md to any documentation page URL to get its markdown version.
# API versioning
Understanding Gusto date-based versioning
Gusto uses date-based versioning to provide stability while continuously improving our services. This guide explains how our API versioning works and how to implement it in your integration.
See our [changelog](https://docs.gusto.com/embedded-payroll/changelog) for all API updates, including new version releases.
As always, our goal is to create a stable API that you can trust. As we ship updates to the API, you will need to make periodic investments to upgrade your API version to benefit from the latest performance and security updates, as to use new features.
## Quickstart
Set your API version using the `X-Gusto-API-Version` header:
```curl
curl --request GET \
--url https://api.gusto-demo.com/v1/me \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {ACCESS_TOKEN}' \
--header 'X-Gusto-API-Version: 2026-06-15'
```
If no header is specified, your API request will default to the minimum API version listed in the [Developer Portal](https://dev.gusto.com/). Find this by navigating to your application's details and locating the **Default API version** field
We pass back the `X-Gusto-API-Version` in the response header as a way for callers to confirm that their requested `X-Gusto-API-Version` was respected.
All Gusto API request URLs include `/v1`. This **should remain the same for all requests regardless of API version**.
## How our API versioning works
We aim to release new versions containing backward-incompatible changes on a quarterly cadence, with minor fixes potentially batched into future releases.
### Deprecation timeline
When a new API version is released, the oldest supported version is marked as deprecated. Partners are notified with clear timelines and instructions for upgrading. Upon deprecation, every API version receives **12 months of phased support**:
| Phase | Duration | Support level |
| :-------------- | :-------------- | :------------------------------------------------------------- |
| Full support | 6 months | Bug fixes, security patches, and new features where applicable |
| Limited support | 6 months | Critical security fixes only |
| End of life | After 12 months | No longer functional |
### Deprecation headers
Deprecation headers are HTTP headers included in the API response once a version is marked for deprecation. These headers notify the client of an upcoming resource removal and provide information on when the resource will be removed and where to find instructions on upgrading.
Here's what you can expect:
* `Deprecation` header: an HTTP datetime value indicating when the resource has been marked as deprecated
* `Link` header: a link to more information about the deprecated resource and upgrade instructions
* `Sunset` header: specifies the date when the resource will be removed. After this date, all calls to the resource will return a `406 Not Acceptable` error
## FAQ
### What do the date-based versions mean as far as stability?
The dates on the date-based versions **are not guarantees of stability** when that date has passed.
An API version is only considered to be stable after we have moved it out of `Beta` status and publicly announced it as stable.
### What kinds of changes are not gated behind a new version?
Backward-compatible changes—new optional parameters, new endpoints, new response fields, and similar additive updates—roll out across all supported API versions without a version bump.
This also includes changes to **human-readable string content**: error messages, notification text, and label-style fields like tax agency names. These values are considered content, not contract, and can change at any time. They should not be used as the basis for business logic. Renaming or removing existing enum values is a separate category and is gated behind a new API version.
See [What is a breaking change?](https://docs.gusto.com/embedded-payroll/docs/what-is-a-breaking-change) for the full backward-compatibility policy.
### What are your recommendations for staying current?
* **Upgrade often**. We recommend upgrading to the latest stable API version at least once per year to benefit from improvements and stay within the support window
* **Monitor deprecation headers**. We include `Deprecation`, `Sunset`, and `Link` headers on responses when endpoints or versions are approaching end of life. Use these to plan your upgrades
* **Test against beta versions in staging**. Upcoming breaking changes are available in staging under a beta version before they go stable. This gives you early visibility into what's changing
### When does Gusto hotfix API versions?
In certain cases, we apply essential fixes to all API versions immediately rather than gating them behind a new version. This happens when the issue involves:
* Payroll correctness—incorrect calculations or payment amounts
* Compliance—behavior that violates legal or regulatory requirements
* Security—vulnerabilities or data exposure
* Data corruption—incorrect data being stored or returned
For all other bug fixes—particularly those where the current behavior, even if unintended, could be something your integration relies on—we gate the fix behind a new API version.