Version upgrade guide

Authentication

Deprecated legacy terms of service endpoints in favor of new RESTful endpoints.

Impacted endpoints:

• Accept terms of service for an admin
• Retrieve terms of service status for an admin

Migrate to Accept the terms of service and Check the terms of service status for a user.

Company management

Removed the setup_complete field from the tax requirements response.

Impacted endpoints:

• Get company tax requirements

Update references of setup_complete to ready_to_run_payroll.

Company management

New uuid fields included in compensation response objects (hourly_compensations, fixed_compensations, paid_time_off).

Impacted endpoints:

• Get a company

Account for new uuid fields when parsing compensation objects in the company response.

Payroll

GET /v1/companies/{company_id}/payrolls now paginates by default when no pagination parameters are provided.

Impacted endpoints:

• Get all payrolls for a company

Implement pagination handling. Read page and total_pages from response metadata and iterate through pages as needed.

Payroll

Payroll receipt now returns paginated employee_compensations.

Impacted endpoints:

• Get a payroll receipt

Implement pagination handling for employee_compensations in the receipt response.

Payroll

Off-cycle payroll creation now requires at least one employee_uuid in the request body. Requests without employee_uuids, with null, or with [] return 422. Termination payrolls (off_cycle_reason: Dismissed employee) retain the existing "exactly one employee" requirement.

Impacted endpoints:

• Create an off-cycle payroll

Include at least one employee_uuid in the request body when creating an off-cycle payroll.

Payroll

payroll_status_meta.initial_check_date and payroll_status_meta.payroll_late now return null for off-cycle payrolls. Previously these fields returned values that were not meaningful for off-cycle payrolls.

Impacted endpoints:

• Get all payrolls for a company
• Get a single payroll
• Update a payroll
• Prepare a payroll
• Create an off-cycle payroll

Update handling to expect null for initial_check_date and payroll_late on off-cycle payrolls.

Payroll

Employee compensation currency fields now return strings (e.g., "1234.56") instead of floats. Affected fields: gross_pay, net_pay, check_amount, employee_deduction (benefits), company_contribution (benefits), amount (deductions, taxes, hourly compensations), qualified_earning_amount (qualified earnings).

Impacted endpoints:

• Get all payrolls for a company
• Get a single payroll
• Update a payroll
• Prepare a payroll
• Calculate a payroll

Update parsing logic to handle these compensation fields as strings instead of floats.

Company management

Adds new blockers and warnings to the migrate and migration readiness endpoints:

• Marijuana business warning
• Gusto managed benefits blocker
• Time off policies unsupported blocker
• Company suspended blocker
• Integrations unsupported warning
• Terms of service not signed by payroll admin blocker
• Tier unsupported blocker

Impacted endpoints:

• Migrate company to embedded payroll
• Check company migration readiness

Account for new blockers and warnings during the company migration process.

Company management

New error category "migration_blocker" and warning category "migration_warning" for the migrate and migration readiness endpoints.

Impacted endpoints:

• Migrate company to embedded payroll
• Check company migration readiness

Account for the new response structure on migrate and migration readiness responses.

Company management

New response structure for the migrate endpoint: migration_status is now a boolean instead of a string, and warnings are included with the success response.

Impacted endpoints:

• Migrate company to embedded payroll

Update your client to handle the new boolean migration_status and inline warnings.

Company management

Require payroll admin to accept the terms of service and retrieve the terms of service. These endpoints are transitioning to new URLs and the current endpoints will be deprecated in a future API version.

Impacted endpoints:

• Retrieve terms of service status for a company user
• Accept terms of service for a company user

Migrate to the new terms of service endpoints:

• Replace Retrieve terms of service status for a company user with Check the terms of service status for a user for user-level status, or Get the terms of service status for a company for company-level status.
• Replace Accept terms of service for a company user with Accept the terms of service.
• Confirm that the email address passed to Accept the terms of service is one returned by Get all the admins at a company. The previous API accepted emails returned by /admins, /employees, /signatories, and /contractors.

Company management

Remove the signing of the terms of service from the migrate endpoint and introduce a migration blocker when the terms of service isn't signed by a company payroll admin. The email, ip_address, and external_user_id params are no longer required in the migrate endpoint.

Impacted endpoints:

• Migrate company to embedded payroll

Call Accept the terms of service for a payroll admin before calling the migrate endpoint.

Employees

Update benefit now validates the presence of, or auto-populates, the elective parameter for Simple IRA employee benefits. If elective is provided, the API validates that it matches the expected value for the benefit type (true for Simple IRA benefits and false for non-elective Simple IRAs). If elective is not provided, the API auto-sets it based on the benefit type.

Impacted endpoints:

• Update an employee benefit
• Create an employee benefit
• Bulk update employee benefits for a company benefit

Account for the additional validation on the elective field.

Employees

Require the email field for employee self-onboarding.

Impacted endpoints:

• Create an employee

Require the employee email field on your frontend when an employee is self-onboarding, and include it in POST requests or they will be rejected.

Payroll

Payroll update requests with invalid versions return a 409 status code instead of 422.

Impacted endpoints:

• Update a payroll by ID

Update your error handling to account for the new status code.

Payroll

Deprecate the reverse_wire_detail_id metadata field surfaced in the wait_for_reverse_wire credit blocker.

Impacted endpoints:

• Get a single payroll
• Get all payrolls for a company
• Get contractor payment groups for a company
• Preview a contractor payment group
• Get a contractor payment group

Stop reading the reverse_wire_detail_id field and remove any dependencies on it.

Company management

Fix a bug to allow per_anniversary_year time off policies to have carryover_limit_hours. Previously this was an unsupported field and an error was thrown.

Impacted endpoints:

• Create a time off policy
• Update a time off policy

Ensure your application is not depending on the error that was thrown prior to this fix.

Contractors

Fix a bug so that Sign contractor document fields exemption_from_FATCA, other, and other_text are properly mapped.

Impacted endpoints:

• Sign a contractor document

Ensure your application is not relying on the field mappings from before the fix.

Employees

Optional query params current_home_address and all_home_addresses no longer return id, effective_from, and effective_to.

Impacted endpoints:

• Get an employee
• Get employees of a company

Use effective_date in place of effective_from and effective_to, and use the UUID in place of id.

Payroll

Updating a payroll by ID now returns a 422 error when updating an employee's payment method to direct deposit if they don't have a bank account on file.

Impacted endpoints:

• Update a payroll by ID

Handle the new 422 error in your payroll update flow.

Payroll

Remove reimbursements as a single total amount from the fixed_compensations array and from the fixed_compensation_types array. Reimbursements are now only available as their own itemized array within the employee_compensations object.

Impacted endpoints:

• Update a payroll by ID
• Prepare a payroll for update
• Get a single payroll

Update your client to read reimbursements from the employee_compensations object.

Payroll

Deprecate the payroll_items error key in favor of employee_compensations.

Impacted endpoints:

• Update a payroll by ID

Read errors from the employee_compensations key.

Payroll

Payroll error messages no longer include the employee name.

Impacted endpoints:

• Update a payroll by ID

Use the employee_uuid from the error message to look up additional employee details if needed.

Payroll

Skipping a termination payroll now requires the fields pay_schedule_uuid and end_date, in addition to employee_uuids.

Impacted endpoints:

• Skip a payroll

Pass the new required fields when calling the skip payroll endpoint.

Payroll

Rename the auto_pilot field in the pay schedule and payroll objects to auto_payroll in both input parameters and response payloads.

Impacted endpoints:

• Create an off-cycle payroll
• Get all payrolls for a company
• Get a single payroll
• Update a payroll by ID
• Prepare a payroll for update
• Create a pay schedule
• Update a pay schedule
• Get a pay schedule
• Get the pay schedules for a company

Rename references from auto_pilot to auto_payroll.

Contractors

Preview a contractor payment group now always returns a creation_token. This token is a required body parameter for Create a contractor payment group.

Impacted endpoints:

• Preview a contractor payment group
• Create a contractor payment group

Pass the creation_token from the preview response when calling Create a contractor payment group.

Employees

Get an employee rehire now returns a 204 instead of a 404 when a valid employee UUID is passed in but no rehires are found.

Impacted endpoints:

• Get an employee rehire

Expect a 204 response instead of a 404 when a valid employee UUID has no rehires.

Payroll

Results are automatically paginated in Get a single payroll and Prepare a payroll for update. The default page size is 25 items and the default page number is 1.

Impacted endpoints:

• Get a single payroll
• Prepare a payroll for update

Adjust your page size and request the appropriate page number.

Payroll

The maximum page size for all payroll endpoints is 100 items. This corresponds to 100 payrolls for Get all payrolls for a company, and 100 employee compensations for Prepare a payroll for update, Update a payroll by ID, and Get a single payroll.

Impacted endpoints:

• Get all payrolls for a company
• Prepare a payroll for update
• Update a payroll by ID
• Get a single payroll

Adjust your page size and request the appropriate page number.

Payroll

Update a payroll by ID accepts a maximum of 100 employee compensation inputs. The endpoint now returns only the employee compensation objects that were inputted, instead of all employee compensation objects on the payroll.

Impacted endpoints:

• Update a payroll by ID

Make the appropriate number of update calls for a given payroll.

Other

Notification status is no longer included in the Get a notification response.

Subscribe to Notifications webhooks and the Get events endpoint to fetch notification status updates, and store the notification state in your own system.

Payroll

Fixed compensation behaviors were modified for unprocessed payrolls to improve performance. Payroll version is no longer included in the top-level response of Prepare a payroll for update and Update a payroll by ID. A new fixed_compensation_types array has been added.

Impacted endpoints:

• Prepare a payroll for update
• Update a payroll by ID

Read fixed compensation types from the fixed_compensation_types array returned by Prepare a payroll for update. Apply fixed compensations by calling Update a payroll by ID with the name from that array, a non-$0 amount, and the employee compensation version returned by the prepare request.