API Versioning

At Gusto we're committed to enhancing the developer experience by continuously improving our services and introducing new features through the Embedded API. Using a date-based API versioning system allows us to release backward incompatible changes in new versions while ensuring existing versions continue to receive support and benefit from new features.

For more information on all API updates, including new version releases, visit our API Changelog.

Release schedule

When backward incompatible changes are made to the API, we will release a new version on a monthly cadence. Additionally, smaller fixes or tweaks may be batched into future versions. However, if there are no changes requiring an immediate release in a given month, a new version will not be released.

After a version is released, it is guaranteed to receive support for a minimum of 12 months. For improved performance and security, we strongly advise upgrading to the latest API version every quarter. To learn more about setting up API versioning visit our getting setup guide.

Deprecation Periods

Each API version will follow a structured lifecycle ensuring clarity around version support timelines.

• Upon release of a new API version, the oldest supported version is marked as deprecated.
• Partners will be notified with clear timelines and instructions for upgrading.

The deprecation period consist of a 12-months phase during which support for a version gradually phases out. It is divided into two distinct phases:

1. Full Support Phase (6 months):
   • During this phase, the API version will continue to receive full maintenance, including bug fixes, security patches, and new feature support (where applicable).
2. Limited Support Phase (6 months):
   • The API version remains functional but will not receive additional updates such as version-specific bug fixes.
   • Critical security vulnerabilities or major defects will be addressed on a case-by-case basis.

At the end of the 12 month period, the deprecated version will be retired and become unusable.

Example Timeline

If the next API version is released on March 1, 2025, the following transitions apply:

Further details regarding the deprecated version will be published in our API Changelog. Additionally, guidance to aid in upgrading will live in our version upgrade guide.

Once a version is removed, it becomes unusable. If your request header specifies a version older than the oldest supported stable version, your API request will return a 406 Not Acceptable error. If no version is specified in the request header, your API request will default to the minimum API version listed in your Developer Portal.

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.

Backward-incompatible changes

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.

Backward-compatible changes

We consider the following to be backward-compatible changes:

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

These non-breaking changes are additive in nature. They will be documented and applied to previously released API version.