API versioning

Gusto uses date-based API versioning to provide stability while continuously improving our services. This guide explains how versioning works and how to implement it in your integration. For performance and security reasons, we strongly recommend upgrading to the latest API version every quarter.

For all API updates, including new version releases, visit our API changelog .

🚧

Important

Version v2024-03-01 is currently in deprecation. View version upgrade guide.

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: 2024-04-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.
• All Gusto API request URLs include /v1. This should remain the same for all requests regardless of API version; the value passed into the X-Gusto-API-Version header determines the date-based API version associated with your API call.
• 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.

How our API versioning works

We release new versions monthly when backward-incompatible changes are needed, with minor fixes potentially batched into future releases.

If there are no changes requiring immediate release, we won’t release a new version.

Version lifecycle

Each API version follows a structured lifecycle:

1. Upon release of a new API version, the oldest supported version is marked as deprecated. Partners are notified with clear timelines and instructions for upgrading.
2. The deprecation period consists of a 12-month phase with two distinct support phases.
3. At the end of 12 months, the deprecated version is retired and becomes unusable.

Deprecation timeline

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 is what you can expect:

• Deprecation header: An HTTP datetime value indicating when the resources 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.

We recommend you to monitor these changes by logging the presence of the aforementioned headers and plan ahead to avoid breaking integrations. This practice also ensures your compatibility with future API versions and helps you stay informed about new features and enhancements.

FAQ

What changes are considered backward incompatible and compatible?

We consider the following to be backward incompatible changes:

• Deleting a resource or API endpoint.
• Deleting a response field.
• Modifying a resource or method URI.
• Modifying an existing field name.
• Modifying required query parameters.
• Modifying authorization.

We consider the following to be backward-compatible—non-breaking changes that are additive, and which will be documented and applied to previously-released API version.

• Adding new API endpoints.
• Adding new optional parameters to existing endpoints.
• Adding new response fields.
• Changing the order of properties in existing API responses.