GuidesAPI ReferenceChangelogAPI PolicyAPI StatusGusto Security

Version Upgrade Guide

See below for all breaking changes organized by topic, along with the associated API version and update required. To confirm your application's minimum version, see the API Versioning Guide.

For additional questions, reach out to your Technical Solutions representative.

Authentication and Scope Changes

VersionBreaking ChangeUpdate Required
v2023-12-01The Get the current user endpoint (v1/me) has been deprecated.Migrate to the Get info about the current access token
v2023-05-01Starting from version 2023-05-01, all endpoints that authenticate with an access token require a strict access token. A strict access token is reserved for access to only a single company. Requests using tokens that do not meet this requirement shall be responded with a forbidden (403) status.See Strict Access guide
v2023-03-01The following endpoints require additional scopes, which are specified in the changelog:
Get the current user
Get a company
Get all payrolls for a company
Get a single payroll
Get a company benefit
Reach out to your Technical Solutions representative for changes to scopes

Payroll

VersionBreaking ChangeUpdate Required
v2023-09-01Changes to the payroll blockers endpoint:
1. needs_onboarding has been deprecated as a blocker type
2. Added new blocker types pending_information_request and pending_recovery_case, which were previously folded into pending_payroll_review
1. Leverage our more granular onboarding blockers
2. Monitor for the pending_information_request or pending_recover_case blockers for open information requests or recovery cases
v2023-04-01Changes to the get payrolls endpoint

1. totals is no longer included by default
2. employee_compensations and version were removed
3. start_date and end_date range cannot be more than a year. end_date cannot be more than 3 months in the future.
4. Added processing_statuses param used to return processed, unprocessed or both types of payrolls, defaults to processed
5. Added payroll_types param used to return regular, off_cycle, or both types of payrolls, defaults to regular
1. Optionally request totals with the include param, i.e. ?include=totals
2. Use the new prepare endpoint to retrieve employee_compensations and version for unprocessed payrolls and the get a single payroll endpoint to retrieve employee_compensations & totals for calculated & processed payrolls
3. Depends on partner implementation
4. To retrieve both processed and unprocessed payroll, use processing_statuses=unprocessed,processed
5. To retrieve regular and off-cycle payroll, use payrolls_types=regular,off_cycle
v2023-04-01Changes to the get a single payroll endpoint
1. show_calculation parameter has been removed
2. version attribute has been removed
3. employee_compensations and totals attributes have been removed for unprocessed payrolls
1. Payroll calculations will show by default
2. Use the new prepare endpoint to retrieve version
3. N/A
v2023-04-01The update a payroll by start and end date endpoint has been deprecatedUse the update payroll by ID endpoint, using the payroll_uuid returned by the get all payrolls endpoint
v2023-04-01Get pay periods endpoint no longer includes eligible_employeesEligible employees for a payroll are listed in employee_compensations returned by the prepare endpoint
v2023-04-01Changed data type of payroll_deadline field from Date to Timestamp. This impacts responses for the following endpoints:
Get all payrolls for a company
Get a single payroll
Update a payroll by ID
Create an off-cycle payroll
Prepare a payroll
Cancel a payroll
Depends on partner implementation
v2023-04-01All off-cycle payroll reasons are now capitalizedDepends on partner implementation
v2023-04-01check_date will no longer change when fetching unprocessed payrolls from the get payrolls and get a single payroll endpointsTo get an accurate check_date for a late payroll, use the prepare, calculate, and submit payroll endpoints
v2023-03-01For the get payrolls and get a single payroll endpoints, when passing benefits in the include parameter, the employee_benefits scope is requiredReach out to your Technical Solutions representative for changes to scopes
v2022-11-01payroll_id is being deprecated in favor of payroll_uuid. This impacts the following endpoints:
Get a single payroll
Update a payroll by ID
Calculate a payroll
Submit a payroll
Cancel a payroll
Get an employee pay stub
Generate payroll printable checks
Calculate accruing time off hours
Use payroll_uuid, which is returned by the get all payrolls endpoints

For additional migration guidance, see the v2022-11-01 change log.

Company Management

VersionBreaking ChangeUpdate Required
v2023-06-01For the create a pay schedule endpoint, if the company has an existing active pay schedule, this endpoint will create a single pay schedule that is not assigned to any employees rather than creating a new default pay schedule that is assigned to all employees.Depends on partner implementation
v2022-11-01company_id is being deprecated in favor of company_uuidUse company_uuid, which is returned by the create a partner-managed company endpoint and can also be retrieved from the Developer Portal.

For additional migration guidance, see the v2022-11-01 change log.
v2022-11-01location_id is being deprecated in favor of location_uuid. This impacts the following endpoints:
Get a location
Update a location
Get minimum wages for a location
Create a job
Update a job
Use location_uuid, which is returned by the create and get company location endpoints.
v2022-11-01company_benefit_id is being deprecated in favor of company_benefit_uuid. This impacts the following endpoints:
Get a company benefit
Update a company benefit
Delete a company benefit
Get company benefit summary by company benefit id
Create an employee benefit
Use company_benefit_uuid, which is returned by the create and get benefits endpoints.

For additional migration guidance, see the v2022-11-01 change log.
v2022-11-01pay_schedule_id is being deprecated in favor of pay_schedule_uuid. This impacts the following endpoints:
Get a pay schedule
Update a pay schedule
Use pay_schedule_uuid, which is returned by the create and get pay schedules endpoints.

For additional migration guidance, see the v2022-11-01 change log.
v2022-11-01Body param benefit_id has been renamed benefit_type in the following company benefits endpoints:
Get a supported benefit by ID
Get benefit fields requirements by ID
Create a company benefit
Create year-to-date benefit amounts from a different company
Update use of benefit_id to benefit_type

Employees, Jobs, and Compensation

VersionBreaking ChangeUpdate Required
v2023-07-01The existing employee home address endpoints have been deprecated
Get an employee's home address
Update an employee's home address
Use the new home addresses endpoints, which support multiple effective-dated addresses.
Get an employee's home addresses
Create an employee's home address
Get an employee's home address
Update an employee's home address
Delete an employee's home address
v2023-07-01The jobs endpoints no longer include location in the response
Create a job
Get jobs for an employee
Get a job
Update a job
Employee jobs do not need to be associated to a specific work location

To create and retrieve employee work locations, use the new work address endpoints
Get an employee's work addresses
Create an employee's work address
Get an employee's work address
Update an employee's work address
Delete an employee's work address
v2022-11-01employee_id is being deprecated in favor of employee_uuidUse employee_uuid, which is returned by the create and get employees endpoints.

For additional migration guidance, see the v2022-11-01 change log.
v2022-11-01job_idis being deprecated in favor ofjob_uuid. This impacts the following endpoints:
Get a job
Update a job
Delete a job
Get compensations for a job
Use job_uuid, which is returned by the create and get jobs endpoints.

For additional migration guidance, see the v2022-11-01 change log.
v2022-11-01compensation_id is being deprecated in favor of compensation_uuid. This impacts the following endpoints:
Get a compensation
Update a compensation
Use compensation_uuid, which is returned by the create a job, get jobs, get a job, and get compensations for a job endpoints.

For additional migration guidance, see the v2022-11-01 change log.
v2022-11-01garnishment_id is being deprecated in favor of garnishment_uuid. This impacts the following endpoints:
Get a garnishment
Update a garnishment
Use garnishment_uuid, which is returned by the create and get garnishments endpoints.

For additional migration guidance, see the v2022-11-01 change log.
v2022-09-15The finish employee onboarding endpoint has been deprecatedUse the update an employee onboarding status endpoint.

Contractors

VersionBreaking ChangeUpdate Required
v2022-11-01contractor_id is being deprecated in favor of contractor_uuid. This impacts the following endpoints:
Get a contractor
Update a contractor
Delete a contractor
Use contractor_uuid, which is returned by the create a contractor and get contractors endpoints.

For additional migration guidance, see the v2022-11-01 change log
v2022-11-01contractor_payment_id is being deprecated in favor of contractor_payment_uuid. This impacts the following endpoints:
Get a single contractor payment
Cancel a contractor payment
Use contractor_payment_uuid, which is returned by the create and get contractor payments endpoints.

For additional migration guidance, see the v2022-11-01 change log