GuidesAPI ReferenceChangelogAPI PolicyAPI StatusGusto Security

API Versioning

Suggest Edits

API Layer

The Gusto API is now versioned. When a breaking change is introduced to the Gusto API, we release a new API version to avoid breaking exi

At Gusto we are committed to enhancing the developer experience by continuously improving 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 practices

We strive to keep the Embedded 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 API 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.

sting partner applications. Developers may continue to use older API versions, or upgrade their application to use the newest Gusto API version.

All new versions will be announced in our changelog.

Setting your API version

You can set the API version by including a X-Gusto-API-Version header in your API calls. 

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: 2022-09-15'

If no X-Gusto-API-Version is specified, the v1 version will be used. You may notice that 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 will determine the date-based API version associated with your API call.

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

Minimum API Version

We use your application’s minimum API version to validate the supplied X-Gusto-API-Version header version. If the header version is using an API version that is older than the minimum API version, your API request will return a 406 Not Acceptable error.

{"name":"Invalid X-Gusto-API-Version Header","message":"Invalid API Version `2022-09-15`. Version must be >= your application's minimum API version `2022-11-01` and not in the future."}

📘

Version Creation

When you create a demo application, the minimum API version is automatically set to the latest stable version of our API. Your production application’s minimum API version will be set during the launch process.

You can view your applications minimum API version in the Developer Portal.

Breaking changes

We consider the following to be backwards-incompatible changes:

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

Non-breaking changes

We consider the following to be backwards-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 versions.

Updated 3 months ago