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 and would like to be kept abreast of API changes via email, please fill in this form.

Breaking change notification

20th August 2023

As part of its ongoing commitment to the security of its customer’s information, Fourth will be updating its platform to require all connections to use TLS 1.2 or higher from 9 January 2024. Older versions of TLS will be retired.

TLS is the encryption method used to secure communications over HTTPS. This will have no impact on SFTP connections.

12 May 2021 — Support for half-day holiday requests

For planned absences you can now submit both full and half day absences. The planned absence endpoints are:

You must submit a half day absence as a separate request (or array member) from any full day absence. To create a half day absence, in a request, set:

  • half_Day to true
  • absence_Start_Date and absence_End_Date (if included) to the same date.
  • absence_Days (if included) to 1.

For example, if you need to create a planned absence for 5.5 days, your request would look similar to this:

POST /import/examplecustomer/PlannedAbsences:batchImport HTTP/1.1 
Host: instance.example.com 
Accept: text/json 
Authorization: Basic VXNlcm5hbWU6cGFzc3dvcmQ=

[
   {
       "employee_ID": "M02653",
       "job_Code": "BRST",
       "absence_Reference": "ref73737",
       "absence_Type": "-2",
       "absence_Days": 1,
       "absence_Start_Date": "2021-04-23T00:00:00",
       "absence_Status": "active",
       "absence_Paid": 100,
       "half_Day": true
   },
   {  
       "employee_ID": "M02653", 
       "job_Code": "BRST", 
       "absence_Reference": "ref73738", 
       "absence_Type": "-2",
       "absence_Days": 5,
       "absence_Start_Date": "2021-04-24T00:00:00",
       "absence_Status": "active",
       "absence_Paid": 100,
       "half_Day": false
   }
]

The API will respond with an error message if you send through a request where half_Day is set to true, but the absence_Days is 2 or more (or the start and end dates are not the same).

26 April 2021 — Ability to delete employments and assignments

Note: these updates became available from the 5 February 2021.

Four endpoints are now available that enable you to delete employments and assignments.

These endpoints support Fourth partners who create employments and assignments in advance. It allows partners to remove these when they are no longer required due to the employee deciding not to begin the employment or assignment.  

Fourth expects employments and assignments to only be deleted if the employee did not start either the employment or assignment.

Employments

The employments endpoints are POST request, rather than DELETE, as it allows API users to send batched delete requests:

  • POST /Employments:delete — Enables you to delete one employment. URL is:
    POST [ROOT URL]/import/{externalCustomerCanonicalId}/Employments:delete
  • POST /Employments:batchDelete — Enables you to delete multiple employments at once. We recommend you integrate to this endpoint if possible. URL is:
    POST [ROOT URL]/import/{externalCustomerCanonicalId}/Employments:batchDelete

The endpoints do not have query parameters.

The message body includes the employment (or employments) you wish to delete. You need only send the employee ID and joining date for the employment.

Example batch request body

[
  {
    "employee_ID": "123",
    "employment_Join_Date": "2021-01-21T00:00:00Z"
  },
  {
    "employee_ID": "124",
    "employment_Join_Date": "2021-01-22T00:00:00Z"
  }
]

Response from Fourth

Fourth will respond to valid requests with an HTTP 202 response. Note that this does not indicate that the employment was successful deleted.

Behaviour when using batch delete: We will delete any valid employments and skip any that are not found.

Assignments

The assignments endpoints are:

  • POST /Assignments:delete — Enables you to delete one assignment. URL is:
    POST [ROOT URL]/import/{externalCustomerCanonicalId}/Assignments:delete
  • POST /Assignments:batchDelete — Enables you to delete multiple assignments at once. We recommend you integrate to this endpoint if possible. URL is:
    POST [ROOT URL]/import/{externalCustomerCanonicalId}/Assignments:batchDelete

The endpoints do not have query parameters.

The message body includes the assignment (or assignments) you wish to delete. You need only send the employee ID and the assignment reference you sent through.

Example batch request body

[
  {
    "employee_ID": "125",
    "assigment_Reference": "98765"
  },
  {
    "employee_ID": "126",
    "assigment_Reference": "98766"
  }
]


Response from Fourth

Fourth will respond to valid requests with an HTTP 202 response. Note that this does not indicate that the assignment was successful deleted.

Behaviour when using batch delete: We will delete any valid assignments and skip any that are not found.

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.