Version Upgrade Guide

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_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

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

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

Employees

Deprecate id, effective_from, and effective_to fields on the Employee Home Address object.

Impacted endpoints:

• Get employees of a company
• Get an employee
• Get an employee's home addresses
• Get an employee's home address

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

Payroll

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

Impacted endpoints:

• Get all payrolls for a company
• Get a single payroll
• Prepare a payroll for update
• Update a payroll by ID
• Get the pay schedules for a company
• Get a pay schedule

Rename references from auto_pilot to auto_payroll.

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

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:

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

Update your client to read reimbursements from the employee_compensations object.

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.

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. The default page size is 25 employee compensations, the default page number is 1, and the maximum page size is 100 employee compensations.

Impacted endpoints:

• Get a single payroll
• Prepare a payroll for update

Adjust your page size and request the appropriate page number.

Payroll

Add a maximum page size of 100 payrolls.

Impacted endpoints:

• Get all payrolls for a company

Adjust your page size and request the appropriate page number.

Payroll

Add a maximum input size of 100 employee compensations. The endpoint no longer returns unmodified employee compensations.

Impacted endpoints:

• Update a payroll by ID

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

Payroll

Remove standard unused or $0 fixed_compensations from the fixed_compensations array. Non-standard fixed_compensations — Owner's Draw, Minimum Wage Adjustment, and Severance — are still included even when unused or $0, when applicable. Remove version from the top-level response. Add a new fixed_compensation_types array, and add version to each employee_compensation.

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.