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.

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
v2025-03-01	Deprecated (Full Support)	May 13, 2025	November 13, 2025	May 13, 2026
v2024-04-01	Stable	June 15, 2025	December 15, 2025	June 15, 2026
v2025-06-15 (latest version)	Latest	TBD	[Deprecation Start Date] + 6 months	[Limited Support Date] + 6 months

Authentication and Scope Changes

Version	Breaking Change	Update Required
v2023-12-01	The Get the current user endpoint (v1/me) has been deprecated.	Migrate to the Get info about the current access token
v2023-05-01	Starting 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-01	The 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	No changes required. Reach out to your Technical Solutions representative for any issues.

Payroll

Version	Breaking Change	Update Required
v2024-03-01	Changes to the Prepare a payroll and Update a payroll endpoints: `version` attribute moved from top level of response to each `employee_compensations` object. added `fixed_compensation_types` to response. All standard `fixed_compensations` no longer included in `employee_compensations`	Ensure `version` is included for each `employee_compensation` in update request body. To add a fixed compensation to an employee_compensation, in the Update a payroll request add an object to the fixed_compensations array with a `valid` name from the `fixed_compensation_types` array and an `amount`. Fixed compensations with $0.00 amounts will NOT be persisted and included in the payroll response
v2023-09-01	Changes to the payroll blockers endpoint: `needs_onboarding` has been deprecated as a blocker type Added new blocker types `pending_information_request` and `pending_recovery_case`, which were previously folded into `pending_payroll_review`	Leverage our more granular onboarding blockers Monitor for the `pending_information_request` or `pending_recover_case blockers` for open information requests or recovery cases
v2023-04-01	Changes to the get payrolls endpoint `totals` is no longer included by default `employee_compensations` and `version` were removed `start_date` and `end_date` range cannot be more than a year. `end_date` cannot be more than 3 months in the future. Added `processing_statuses` param used to return `processed`, `unprocessed` or both types of payrolls, defaults to `processed` Added `payroll_types` param used to return `regular`, `off_cycle`, or both types of payrolls, defaults to `regular`	Optionally request totals with the include param, i.e. `?include=totals` 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 Depends on partner implementation To retrieve both processed and unprocessed payroll, use `processing_statuses=unprocessed,processed` To retrieve regular and off-cycle payroll, use `payrolls_types=regular,off_cycle`
v2023-04-01	Changes to the get a single payroll endpoint `show_calculation` parameter has been removed `version` attribute has been removed `employee_compensations` and `totals` attributes have been removed for unprocessed payrolls	Payroll calculations will show by default Use the new prepare endpoint to retrieve `version` N/A
v2023-04-01	The update a payroll by start and end date endpoint has been deprecated	Use the update payroll by ID endpoint, using the `payroll_uuid` returned by the get all payrolls endpoint
v2023-04-01	Get pay periods endpoint no longer includes `eligible_employees`	Eligible employees for a payroll are listed in `employee_compensations` returned by the prepare endpoint
v2023-04-01	Changed 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-01	All off-cycle payroll reasons are now capitalized	Depends on partner implementation
v2023-04-01	`check_date` will no longer change when fetching unprocessed payrolls from the get payrolls and get a single payroll endpoints	To get an accurate `check_date` for a late payroll, use the prepare, calculate, and submit payroll endpoints
v2023-03-01	For the get payrolls and get a single payroll endpoints, when passing benefits in the `include` parameter, the `employee_benefits` scope is required	Reach out to your Technical Solutions representative for changes to scopes
v2022-11-01	`payroll_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

Version	Breaking Change	Update Required
v2023-06-01	For 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-01	`company_id` is being deprecated in favor of `company_uuid`	Use `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-01	`location_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-01	`company_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-01	`pay_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-01	Body 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

Version	Breaking Change	Update Required
v2023-07-01	The 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-01	The 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-01	`employee_id` is being deprecated in favor of `employee_uuid`	Use `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-01	`job_id`is being deprecated in favor of`job_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-01	`compensation_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-01	`garnishment_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-15	The finish employee onboarding endpoint has been deprecated	Use the update an employee onboarding status endpoint.

Contractors

Version Breaking Change Update Required

Version	Breaking Change	Update Required
v2022-11-01	`contractor_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-01	`contractor_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

v2022-11-01

contractor_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-01

contractor_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

Notifications

Version	Breaking Change	Update Required
v2024-03-01	`status` is being deprecated from notifications responses. This impacts the following endpoint: Get notifications	ensure you are not using `status` from the Get notifications response