Version upgrade 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

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.

v2024-03-01

Changes to the Prepare a payroll and Update a payroll endpoints:

1. version attribute moved from top level of response to each employee_compensations object.
2. added fixed_compensation_types to response.
3. All standard fixed_compensations no longer included in employee_compensations

1. Ensure version is included for each employee_compensation in update request body.
2. To add a fixed compensation to an employee_compensation, in the Update a payroll request add an object to the fixed_compensations array with a valid name from the fixed_compensation_types array and an amount. Fixed compensations with $0.00 amounts will NOT be persisted and included in the payroll response

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.

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

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_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.

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

v2024-03-01

status is being deprecated from notifications responses. This impacts the following endpoint:
Get notifications

ensure you are not using status from the Get notifications response