Getting Setup

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/token_info \
     --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, your minimum API version will be used (details on confirming your minimum API version can be found here)

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."} 

Viewing Your Minimum API Version

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

🚧

Version Support Timelines

API versions are guaranteed to be supported for at least 12 months from the version date. Additional information can be found in our API Versioning Guide