API 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 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 --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-02-01'

If no header is specified, your API request will default to the minimum API version listed in the Developer Portal. 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:

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 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.