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.

Authentication and Scope Changes

Version	Breaking Change	Update Required
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
v2023-09-01	Changes to the payroll blockers endpoint: 1. `needs_onboarding` has been deprecated as a blocker type 2. Added new blocker types `pending_information_request` and `pending_recovery_case`, which were previously folded into `pending_payroll_review`	1. Leverage our more granular onboarding blockers 2. 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 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	Changes to the 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` 3. 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
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