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
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	Deprecated (Full Support)	February 1, 2026	August 1, 2026	February 1, 2027
v2026-02-01 (latest version)	Stable	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
v2026-02-01	Payroll update requests with invalid versions will return a 409 status code instead of 422 Impacted endpoints: Update a payroll by ID	Refactor existing error handling to account for change in status code
v2026-02-01	Deprecate the `reverse_wire_detail_id` metadata field surfaced in the `wait_for_reverse_wire` credit blocker Impacted endpoints: Get a single payroll Get all payrolls for a company Get contractor payment groups for a company Preview a contractor payment group Get a contractor payment group	Account for deprecation of this ID field
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 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.
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
v2026-02-01	Adds new blockers and warnings to the migrate and migration readiness endpoints: Marijuana business warning Gusto managed benefits blocker Time off policies unsupported blocker Company suspended blocker Integrations unsupported warning Terms of service not signed by payroll admin blocker Tier unsupported blocker Impacted endpoints: Migrate company to embedded payroll Check company migration readiness	Account for new blockers and warnings during company migration process
v2026-02-01	New error category `“migration_blocker”` and warning category `“migration_warning”` for the migrate endpoint and migration readiness endpoint Impacted endpoints: Migrate company to embedded payroll Check company migration readiness	Account for migrate/migration_readiness response changes
v2026-02-01	New response structure for the migrate endpoint: `“migration_status”` is now a boolean instead of a string Warnings are included with the success response Impacted endpoints: Migrate company to embedded payroll	Account for migrate response changes
v2026-02-01	Require payroll admin to accept the terms of service and retrieve the terms of service. These endpoints are also transitioning to new URLs and the current endpoints will be deprecated in a future API version. Impacted endpoints: Retrieve terms of service status for a company user Accept terms of service for a company user	Account for new terms of service validation: Update Retrieve terms of service status for a company user to use: Check the terms of service status for a user for user-level status, or Get the terms of service status for a company for company-level status Update Accept terms of service for a company user to use Accept the terms of service Confirm the email address included when calling Accept the terms of service is one returned via the Get all the admins at a company endpoint. The previous API accepted emails returned by the company's `/admins`, `/employees`, `/signatories`, and `/contractors` endpoints.
v2026-02-01	Remove the signing of the terms of service in the migrate endpoint and introduce a migration blocker when the terms of service is not signed by a company payroll admin The `email`, `ip_address`, and `external_user_id`, params are now not required in the migrate endpoint Impacted endpoints: Migrate company to embedded payroll	Require accept terms of service to be called for an admin before calling the migrate endpoint
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
v2026-02-01	Update benefit now validates on presence or auto-populates the elective parameter for Simple IRA employee benefits. If elective is provided, validates it matches the expected value for the benefit type (true for simple IRA benefits and false for non-elective simple IRAs). If elective is not provided, auto-sets it based on the benefit type. Impacted endpoints: Update an employee benefit Create an employee benefit Bulk update employee benefits for a company benefit	Account for extra validation on the elective field
v2026-02-01	Require email field for employee self-onboarding Impacted endpoints: Create an employee	Update data validation to require employee email field on frontend if employee is self-onboarding. Ensure employee email field is included in POST requests or requests will be rejected
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 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
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.