Labor Productivity API Release Notes

Overview

This page explains the changes that have happened to our Labor Productivity API since the beginning of 2020. This API allows you to create, update and retrieve a comprehensive set of employee data in Fourth. You may also know this API by the name HR Gateway API or Team Hours API.

These Release Notes are up-to-date at the time of the release. Further improvements or corrections to our API documentation will normally occur in the guide and reference only.

If you have already integrated with Fourth would like to be kept abreast of API changes via email, please fill in this form.

2 April 2020 — New endpoints available and additional filtering provided for /employees endpoint

A number of new GET endpoints were added to the Labor Productivity API. You can find the fields returned and how to integration in the Reference.

New get absences endpoint

GET /export/{externalCustomerCanonicalId}/Absences

This returns all employee absences across the customer's business.

New get job titles endpoint

GET /export/{externalCustomerCanonicalId}/JobTitles

This returns the job titles for a customer, including whether the job is tippable, and any attributes.

New get locations endpoint

GET /export/{externalCustomerCanonicalId}/Locations

This returns the customer’s location data, such as the address and departments.

New get employees (abridged) endpoint

GET /export/{externalCustomerCanonicalId}/employees/restricted

This is similar to the exisitng /employees endpoint. It returns the same set of employee data but with personal information removed such as the employees’ email and pay rates.  

Updated employees endpoint

We’ve updated the endpoint:

GET /export/{externalCustomerCanonicalId}/employees

to add support for the If-Modified-Since header, so that you can request only employee records that were created or updated since the specified date.

As well, new users will need their mutual customer to explicitly authorize access to the endpoint, as this endpoint contains sensitive employee information.

7 August 2019  — New PlannedAbsences endpoints; new departments array; and updates to some field values

New endpoints

Two new endpoints are available for planned absences. These allow you to delete absences for employees, where the start date is in the future. The endpoints are:

  • [ROOT]/delete/{externalCustomerCanonicalId}/PlannedAbsences
  • [ROOT]/delete/{externalCustomerCanonicalId}/PlannedAbsences:batchDelete

Please see the Labor Productivity API Guide and accompanying Reference for further details on these endpoints.

New departments array for locations

The location endpoints now include a department array. This optional array allows you to set the departments that exist in a location. From this release, you can connect assignments to departments as well as locations. If no department is sent, a default one is created per location.

You can set a code and name for each department. For example:

    "departments": [
      {
        "department_Code": "445",
        "department_Name": "Drinks and cocktails"
      },
      {
        "department_Code": "889",
        "department_Name": "Maintenance and cleaning"
      }
    ]

Updates to field values

The POST employees endpoints have had a minor update to some fields you supply in requests:

  • dependent_Income
    The value type was listed as a string. This has been changed to a number with double as the format.
  • rate (part of pay_Part_Values array)
    This was previously listed as a string. This is now a double number.
  • value (part of pay_Part_Values array)
    This was previously listed as a string. This is now a double number.

28 May 2019 — New EmploymentsFullHistory endpoints

We have added new EmploymentsFullHistory endpoints that enable you to provide full employment and assignment history for an employee in a single request. These endpoints accept POST requests.

The system will overwrite any existing data for the employee and replace it with the data in the API call. The endpoints are:

  • /import/{externalCustomerCanonicalId}/EmploymentsFullHistory
  • /import/{externalCustomerCanonicalId}/EmploymentsFullHistory:batchImport

To find out more about these endpoints, please visit the Labor Productivity API Guide and accompanying Reference.

4 April 2019 — New additionalPayments resource

We have launched an additionalPayments resource, which accepts POST requests. This enables you to send in tip data for individual employees.

To find out more about the endpoint, please visit the Labor Productivity API Guide and accompanying Reference.

18 March 2019 — Additional fields to support break waivers and employee onboarding

The following import employments endpoints have additional fields:

  • /import/{externalCustomerCanonicalId}/Employments
  • /import/{externalCustomerCanonicalId}/Employments:batchImport

The fields are optional. They are:

break_Waiver (Boolean)

Set this value to true if the employee has waived their break rights (Boolean). POS providers may find this particularly useful, as the POS system can display a prompt to users based on this data when they clock in or out.

employment_Authorization (string)

Whether the employment has been authorized by the business and the employee is allowed to start working this employment. This can be used in by scheduling solutions in conjunction with onboarding_Status to prevent creating shifts against employees that are not yet cleared to work.

onboarding_Status (string)

The status of the employee's onboarding process.

3 December 2018 — New employees resource that accepts GET requests.

We have enabled a new GET employees resource for the Labor Productivity API. The new endpoint is:

  • [ROOT]/export/{externalCustomerCanonicalId}/employees

This allows other applications to get employee data from Labor Productivity. Use this resource when you need employee information and your customer is not integrated with UK HR & Payroll; for example, for single sign-on integrations.

To find out more about the endpoint, please visit the Labor Productivity API Guide and accompanying Reference.

14 March 2017 — Launch of Labor Productivity API!

Today marks the launch of the Labor Productivity API with partners and customers!

With the Labor Productivity API, you can update the employee and organization data stored in Fourth with data from your other systems. For employee records, this includes both static data — like their name or address — and temporary or transactional data such as time off (planned and unplanned). Fourth can then use this data for workforce management tasks, such as scheduling and productivity analysis.

The Labor Productivity API is an HTTP REST API that can add or update:

  • Employee assignments
  • Employee absences - planned, unplanned and taken
  • Employee HR details
  • Job titles and locations across your business

Connecting with Fourth means that employee data is synchronized across the customer’s entire platform — without any manual data entry. HR systems can advise of upcoming employee absences, while applicant tracking software can add newly onboarded employees, meaning customers can schedule employees in Fourth with the most up-to-date information. And because HR systems can immediately send updates to work locations, roles and pay rates. payroll issues decline as the final timesheets provided to Payroll are aligned with current employee details.

For more information, view the Labor Productivity API documentation on the Developer Hub.