API Versioning

At Gusto we are committed to enhancing the developer experience by continuously improving services and introducing new features through the 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 Changelog.

Release Schedule

In order to get meaningful, backward incompatible, changes into the hands of partners as expeditiously as possible, we may release new versions as often as monthly. However, in instances where the month yields only minor adjustments that lack substantial impact, we will consolidate and include these smaller changes in a larger subsequent release.

After a version is released, it is guaranteed to receive support for a minimum of 12 months from the version date. 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 practices

We strive to keep the API secure and up-to-date. If certain components become insecure, outdated, or unnecessary, we may mark them as deprecated. A deprecated version indicates that it is no longer supported and will be removed. Specifically, this entails updating the minimum API version in partner integration apps to the next stable version. Further details regarding the deprecated version will be announced in our Changelog and 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.

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.