API Versioning
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 existing 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.
API Versions
Updated about 2 months ago