v2022-11-01

These are all breaking changes for a new version that was created.

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

IDs are being deprecated in favor of UUIDs in the API version.

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.

What does this mean for your development?

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.
   1. 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.
   1. 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.
   1. 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.

Caveats and things to watch 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
• Get an employee's custom fields

The request body parameter benefit_id has been renamed to benefit_type in company benefits endpoints.

This change can be seen in:

• Create a company benefit
• Create year-to-date benefit amounts from a different company