GuidesAPI ReferenceChangelog
Log In

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

VersionBreaking ChangeUpdate Required
v2023-03-01The 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-01Starting 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-01The Get the current user endpoint (v1/me) has been deprecated.Migrate to the Get info about the current access token

Payroll

VersionBreaking ChangeUpdate Required
v2022-11-01All 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-01Various 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-01Get 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-01Get 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-01Update 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-01Get 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-01All Payrolls Endpoints

Changed data type of payroll_deadline field from Date to Timestamp.

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-01All 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-01Various 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-01Various 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

VersionBreaking ChangeUpdate Required
v2022-11-01All 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-01All 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-01All 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-01All 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-01All 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

VersionBreaking ChangeUpdate Required
v2022-11-01All 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-01All 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-01All 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-01All 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.
v2023-07-01All 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-01Employee 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

Contractors

VersionBreaking ChangeUpdate Required
v2022-11-01All 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-01All 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