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 Version Guide.

Authentication and Scope Changes

Version	Breaking Change	Update Required
v2023-03-01	The following endpoints require additional scopes to return certain fields, 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	If you require additional scopes as a result of this change, please email [email protected] with the scopes required and context on business need.
v2023-05-01	Starting from version v2023-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-12-01	The Get the current user endpoint (`v1/me`) has been deprecated.	Migrate to the Get info about the current access token
v2024-04-01	API Token authentication has been deprecated.	Migrate to System Access Tokens

Payroll

Version	Breaking Change	Update Required
v2022-11-01	All Payrolls Endpoints `payroll_id` has been deprecated in favor of `payroll_uuid` Impacted endpoints: Get all payrolls for a company Get a single payroll Update a payroll by ID Prepare a payroll	Migrate to `payroll_uuid`, which is returned by all payrolls endpoints. For additional migration guidance, see the v2022-11-01 change log.
v2023-03-01	Various Payrolls Endpoints When passing `benefits` in the `include` parameter, the `employee_benefits:read` scope is required. Impacted endpoints: Get all payrolls for a company Get a single payroll	If you require additional scopes as a result of this change, please email [email protected] with your request and context on business need.
v2023-04-01	Get payrolls endpoint 1. `totals` is no longer included by default 2.`employee_compensations` and `version` were removed 3. `start_date` and `end_date` range cannot be more than a year. `end_date` cannot be more than 3 months in the future. 4. Added `processing_statuses` param used to return `processed`, `unprocessed` or both types of payrolls, defaults to `processed` 5. Added `payroll_types` param used to return `regular`, `off_cycle`, or both types of payrolls, defaults to `regular`	1. Optionally request totals with the include param, i.e. `?include=totals` 2. 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 3. Depends on partner implementation 4. To retrieve both processed and unprocessed payroll, use `processing_statuses=unprocessed,processed` 5. To retrieve regular and off-cycle payroll, use `payrolls_types=regular,off_cycle`
v2023-04-01	Get a single payroll endpoint 1. `show_calculation` parameter has been removed 2. `version` attribute has been removed 3. `employee_compensations` and `totals` attributes have been removed for unprocessed payrolls	1. Payroll calculations will show by default 2. Use the new prepare endpoint to retrieve `version`
v2023-04-01	Update a payroll endpoint This 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 This endpoint no longer includes `eligible_employees`	Eligible employees for a payroll are determined by the `excluded` field in `employee_compensations` returned by the prepare endpoint
v2023-04-01	All Payrolls Endpoints Changed data type of `payroll_deadline` field from Date to Timestamp. `payroll_deadline` now returns the original payroll deadline when the payroll is late. If payroll has not been run by the deadline, a prepare request will update both the check date and deadline to reflect the soonest employees can be paid and the deadline by which the payroll must be run in order for said check date to be met. Impacted endpoints: Get all payrolls for a company Get a single payroll Update a payroll by ID Prepare a payroll	Varies depending on implementation
v2023-04-01	All Payrolls Endpoints All off-cycle payroll reasons are now capitalized. Impacted endpoints: Get all payrolls for a company Get a single payroll Update a payroll by ID Prepare a payroll	Varies depending on implementation
v2023-04-01	Various Payrolls Endpoints `check_date` will no longer change when fetching late, unprocessed payrolls. Impacted endpoints: Get all payrolls for a company Get a single payroll	To get an updated `check_date` for a late payroll, use the prepare endpoint
v2024-03-01	Various Payrolls Endpoints - Removed standard unused/$0 `fixed_compensations` from `fixed_compensations` array -- Non-standard `fixed_compensations` - `Owner's Draw`, `Minimum Wage Adjustment`, and `Severance` - will be included, even if unused or $0, when applicable - Removed `version` from top level response - Added `fixed_compensation_types` array - Added version to each `employee_compensation`Impacted endpoints: Prepare a payroll for update Update a payroll by ID	- Use fixed compensation types retrieved from the `fixed_compensation_types` array returned by the Prepare a payroll for update endpoint- Apply fixed compensations via the Update a payroll by ID endpoint by passing the `name` retrieved from the aforementioned array, a non-$0 amount, and the employee compensation `version` returned by the prepare request.

Company Management

Version	Breaking Change	Update Required
v2022-11-01	All Relevant Endpoints `company_id` has been deprecated in favor of `company_uuid`	Migrate to `company_uuid` For additional migration guidance, see the v2022-11-01 change log.
v2022-11-01	All Relevant Endpoints `location_id` has been deprecated in favor of `location_uuid`.	Migrate to `location_uuid`, which is returned by the create and get company location endpoints. For additional migration guidance, see the v2022-11-01 change log.
v2022-11-01	All Relevant Endpoints `company_benefit_id` has been deprecated in favor of `company_benefit_uuid`.	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	All Relevant Endpoints `pay_schedule_id` has been deprecated in favor of `pay_schedule_uuid`.	Migrate to `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	All Relevant Endpoints Body param `benefit_id` has been renamed `benefit_type`. Impacted 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
v2022-11-01	All Relevant Endpoints `employee_id` has been 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	All Relevant Endpoints `job_id` has been deprecated in favor of `job_uuid`.	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	All Relevant Endpoints `compensation_id` has been deprecated in favor of `compensation_uuid`.	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	All Relevant Endpoints `garnishment_id` has been deprecated in favor of `garnishment_uuid`.	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-12-07	Create an employee termination Change employments.hired_at error into a base error	Varies depending on implementation
v2023-07-01	All Job Endpoints The jobs endpoints no longer include `location` in the response. Impacted endpoints: Create a job Get jobs for an employee Get a job Update a job	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
v2023-07-01	Employee Home Address Endpoints The existing employee home address endpoints have been deprecated. Impacted endpoints: Get an employee's home address Update an employee's home address	Migrate to 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	Relevant Employee Endpoints The `home_address` object has been deprecated. Impacted endpoints: Get employees of a company Get an employee	Migrate to the new home addresses endpoints, which support multiple effective-dated addresses: Get an employee's home addresses Get an employee's home address

Contractors

Version	Breaking Change	Update Required
v2022-09-15	Updated Error Response Shapes Impacted endpoints: Create a contractor Update a contractor	Varies depending on implementation
v2022-11-01	All Relevant Endpoints `contractor_id` has been deprecated in favor of `contractor_uuid`.	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	All Relevant Endpoints `contractor_payment_id` has been deprecated in favor of `contractor_payment_uuid`.	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

Other Changes

Version	Breaking Change	Update Required
v2023-02-01	All Relevant Endpoints Error messages updated to ensure consistent JSON shapes.	Varies depending on implementation Please review the Errors Guide for more information.

Updated 2 months ago