Version Upgrade Guide

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

API version statuses

Consult this table to see the deprecation timelines for each API version that's currently supported. Read our API Versioning guide for more information.

API Version	Status	Deprecation Start Date	Limited Support Date	Final Sunset Date
v2026-06-15	✅ Stable	TBD	[Deprecation Start Date] + 6 months	[Limited Support Date] + 6 months
v2026-02-01	Deprecated (Full Support)	June 15, 2026	November 15, 2026	June 15, 2027
v2025-11-15	Deprecated (Full Support)	February 1, 2026	August 1, 2026	February 1, 2027
v2025-06-15	Deprecated (Limited Support)	November 17, 2025	May 17, 2026	November 17, 2026
v2024-04-01	No longer supported	June 15, 2025	December 15, 2025	June 15, 2026

Breaking changes by version

v2026-06-15

Domain	Breaking change	Update required
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.

v2025-11-15

Domain	Breaking change	Update required
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.

v2025-06-15

Domain	Breaking change	Update required
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.

v2024-04-01

Domain	Breaking change	Update required
Authentication	API token authentication has been deprecated.	Migrate to System Access Tokens.

v2024-03-01

Domain Breaking change Update required

Payroll

Domain	Breaking change	Update required
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.

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:

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.

Endpoint change index

Alphabetical list of endpoints with breaking changes, and the versions in which they changed.

Endpoint change index

Endpoint	Versions changed
GET /v1/companies/{company_id}/employees	v2025-11-15
GET /v1/companies/{company_id}/pay_schedules	v2025-11-15
GET /v1/companies/{company_id}/pay_schedules/{pay_schedule_id}	v2025-11-15
GET /v1/companies/{company_id}/payrolls	v2025-11-15, v2025-06-15
GET /v1/companies/{company_id}/payrolls/{payroll_id}	v2025-11-15, v2025-06-15
GET /v1/employees/{employee_id}	v2025-11-15
GET /v1/employees/{employee_id}/home_addresses	v2025-11-15
GET /v1/employees/{employee_id}/rehire	v2025-06-15
GET /v1/home_addresses/{home_address_uuid}	v2025-11-15
PUT /v1/companies/{company_id}/payrolls/{payroll_id}	v2025-11-15, v2025-06-15, v2024-03-01
PUT /v1/companies/{company_id}/payrolls/{payroll_id}/prepare	v2025-11-15, v2025-06-15, v2024-03-01