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 .

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

Authentication and Scope Changes

Version	Breaking Change	Update Required
v2024-04-01	API Token authentication has been deprecated.	Migrate to System Access Tokens .
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
v2025-11-15	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	Ensure that you are handling this error
v2025-11-15	Removal of reimbursements as a single total amount from the fixed_compensations array and from the fixed_compensation_types array; now only available as their own itemized array within the employee_compensations object.- Impacted endpoints*: Update a payroll by ID Prepare a payroll for update Get a single payroll	Account for data structure changes
v2025-11-15	Deprecating the use of the payroll_items error key in favor of employee_compensations- Impacted endpoints*: Update a payroll by ID	Retrieve errors from employee_compensations
v2025-11-15	Payroll error messages that previously included employee name now do not- Impacted endpoints*: Update a payroll by ID	Leverage employee_uuid from error message to obtain additional employee details if needed
v2025-11-15	Skipping a termination payroll now requires the fields pay_schedule_uuid and end_date, in addition to employee_uuids- Impacted endpoints*: Skip a payroll	Pass new required fields to skip a payroll
v2025-11-15	The auto_pilot field in the pay schedule object and payroll objects has been renamed to auto_payroll in input parameters and response payloads. This affects payroll and pay schedule endpoints.- Impacted endpoints*: All endpoints returning a payroll: Create an Off Cycle Payroll Get all payrolls for a company Get a single payroll Update a payroll by ID Prepare a payroll for update\All endpoints returning a pay schedule: Create a Pay Schedule Update a pay schedule Get a pay schedule Get the pay schedules for a company	Update references of auto_pilot to auto_payroll
v2025-06-15	Results are automatically paginated in both the ‘Get a single payroll’ endpoint and the ‘Prepare a payroll for update’ endpoint. The default page size is 25 items and the default page number is 1.	Adjust page size and request the appropriate page number.
v2025-06-15	The maximum page size for all payroll endpoints is 100 items. This corresponds to 100 payrolls for the ‘Get all payrolls for a company’ endpoint, and 100 employee compensations for the ‘Prepare a payroll for update’ , ‘Update a payroll by ID’ , and ‘Get a single payroll’ endpoints.	Adjust page size and request the appropriate page number.
v2025-06-15	The ‘Update a payroll by ID’ endpoint accepts a maximum of 100 employee compensation inputs.Additionally, this endpoint will now only return the employee compensation objects that were inputted, as opposed to all employee compensation objects on the payroll.	Make the appropriate number of update calls necessary for a given payroll.
v2024-03-01	For more details on the following changes, see the changelog .Various Payroll endpoints- Fixed compensation behaviors were modified for unprocessed payrolls to improve the performance of the payroll API endpoints.

• Payroll version is no longer included in the top level response of payrolls#prepare and payrolls#update.

• Added fixed_compensation_types array | Use fixed compensation types retrieved from the fixed_compensation_types array returned by the Prepare a payroll for update endpointApply 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. | | 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 endpoint1. totals is no longer included by default
3. employee_compensations and version were removed
4. start_date and end_date range cannot be more than a year. end_date cannot be more than 3 months in the future.
5. Added processing_statuses param used to return processed, unprocessed or both types of payrolls, defaults to processed
6. 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 endpoint1) show_calculation parameter has been removed
6. version attribute has been removed
7. 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 endpointsFor additional migration guidance, see the v2022-11-01 change log. |

Company Management

Version	Breaking Change	Update Required
v2025-11-15	Fix a bug to allow per_anniversary_year time off policies to have carryover_limit_hours. Previously this was an unsupported field and an error was thrown.- Impacted endpoints*: Create a time off policy Update a time off policy	Ensure that your application is not depending the error that was thrown prior to this fix
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
v2025-11-15	When using Get an employee endpoint or Get all employees endpoints: optional query params current_home_address and all_home_addresses will no longer return id, effective_from, and effective_to.- Impacted endpoints*: Get an employee Get employees of a company	Rely on:- effective_date in place of effective_from and effective_to

• UUID in place of id | | v2025-06-15 | The ‘Get an employee rehire’ endpoint’ endpoint now returns a 204 instead of a 404 when a valid Employee UUID is passed in but no rehires are found. | When processing the API response from this endpoint, expect a 204 instead of a 404 when a valid Employee UUID is passed and no rehires are found. | | 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 locationTo 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_idis being deprecated in favor ofjob_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
v2025-11-15	Fix a bug so that Sign contractor document fields exemption_from_FATCA, other, and other_text are properly mapped.- Impacted endpoints*: Sign a contractor document	Ensure your application is not relying on the mappings pre-fix
v2025-06-15	The ‘Preview a contractor payment group’ endpoint will now always return a creation_token. This will be a required body parameter for the ‘Create a contractor payment group’ endpoint.	Where you are calling the ‘Create a contractor payment group’ endpoint, make sure to pass the creation_token from the ‘Preview a contractor payment group’ endpoint.
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

Other Changes

Version	Breaking Change	Update Required
v2024-03-01	Notification status is no longer included in notifications#get response.	Subscribe to our Notifications webhooks and events#get endpoint to fetch notification status updates from our system, and to store and update the notification in your own notification system.

---

API versioning

API fundamentals