GuidesAPI ReferenceChangelogAPI PolicyAPI StatusGusto Security

What's new in `v2022-11-01`

To learn more about versions in our API, read the Versioning guide.

What’s happening?

IDs are being deprecated in favor of UUIDs in the API version released on 2022-11-01. This means that API calls made with the “X-Gusto-API-Version” header on or after 2022-11-01 will no longer be accepted in request bodies, and no longer be available in response bodies. UUIDs will be accepted and returned instead.

Why are IDs being deprecated?

The effort to deprecate IDs and migrate to UUIDs is important in strengthening the data security of our API and reducing possible enumeration attack surface. Note that in v1 of our API, we already support and return UUIDs in a number of our endpoints. You can find them documented in the v1 API reference at docs.gusto.com.

What does this mean for me?

If you would like to migrate your application to support UUIDs, we recommend following our migration guide below. Please note that as a prerequisite, your API implementation should be compatible with API version release 2022-09-15.

Note that most of our endpoints also support UUID request parameters unless noted otherwise.

How do I migrate my application to use UUIDs?

  1. Accept both IDs and UUIDs in your application.
    If you primarily rely on Gusto IDs, start adopting UUIDs which are readily available in all endpoints in your current version. If you store Gusto IDs in your application database; please make sure you additionally store the corresponding UUIDs in a new column.
  2. Switch to using UUIDs in place of IDs.
    To deprecate ID usage in your application, we recommend that you make API requests using the UUIDs returned from API responses or stored in your database.
  3. Drop ID usages in your application.
    If applicable, you may drop the ID column in your application databases.

When migrating individual endpoints to leverage UUID, we recommend starting with company endpoints first. Once your application has migrated to UUIDs with the company resource, you can continue migrating dependent resources, such as employees.

Once the above 3 steps are done, you have completed the UUID migration process and your API implementation should be compatible with the 2022-11-01 API version. You can fully upgrade to this version by adding X-Gusto-API-Version: 2022-11-01 to all request headers.

What should I watch out for?

While ID deprecation across the API is mostly straightforward and involves introducing new UUID response and request parameters, there are a few implementation caveats that we’d like to mention.

  • You should still expect to handle IDs with a small subset of our endpoints
    • Update an external payroll endpoint
    • Get an employee’s custom fields endpoint
    • Update an employee’s state taxes endpoint
  • The request body parameter benefit_id has been renamed to benefit_type in company benefits endpoints
    • Create a company benefit endpoint
    • Create ytd benefit amounts from a different company endpoint