Version upgrade guide

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

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

Removed the setup_complete field from the tax requirements response.

• Get company tax requirements

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

• Get a company

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

• Get all payrolls for a company

Payroll receipt now returns paginated employee_compensations.

• Get a payroll receipt

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.

• Create an off-cycle 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.

• Get all payrolls for a company
• Get a single payroll
• Update a payroll
• Prepare a payroll
• Create an off-cycle 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).

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

• 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

• Migrate company to embedded payroll
• Check company migration readiness

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

• Migrate company to embedded payroll
• Check company migration readiness

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.

• Migrate company to embedded payroll

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.

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

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

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.

• Migrate company to embedded payroll

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.

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

Require the email field for employee self-onboarding.

• Create an employee

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

• Update a payroll by ID

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

• 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

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.

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

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

• Sign a contractor document

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

• Get an employee
• Get employees of a company

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.

• Update a payroll by ID

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.

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

Deprecate the payroll_items error key in favor of employee_compensations.

• Update a payroll by ID

Payroll error messages no longer include the employee name.

• Update a payroll by ID

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

• Skip a payroll

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

• 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

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

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

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.

• Get an employee rehire

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.

• Get a single payroll
• Prepare a payroll for update

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.

• Get all payrolls for a company
• Prepare a payroll for update
• Update a payroll by ID
• Get a single 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.

• Update a payroll by ID

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.

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