1. Documentation
  2. Workforce Management
  3. UK Employee API
  4. Release Notes

UK Employee API Release Notes

Getting Started
What's New
Integration Options
Authenticating with OAuth
System Status
Identity and Access Management
Single Sign-On & SAML
Outbound Federation
Federated Authentication
Troubleshooting & FAQs
Glossary
Platform
Workforce Management
Fourth Inventory for Hotels
Fourth Inventory for Restaurants

Overview

This page explains the changes that have happened to our UK Employee 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: UK HR Exports.

These Release Notes are up-to-date at the time of the release. Further improvements to corrections 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.

6 May 2021 — Gender identity option added

The PUT and POST /employees methods now include a GenderIdentity field that allows customers to record the gender that employees identify as. This is separate from the existing Gender field, which is used for tax or legal purposes. The possible values are:

  • Male
  • Female
  • Non-binary
  • Genderqueer
  • Transgender
  • Prefer not to say
  • Not Listed above

Note that the field is not mandatory, and customers can choose whether or not to enable this field within the Fourth UI.

Example POST or PUT response (shortened)

...
    "SensitiveInfo": {
      "EthnicOrigin": "string",
      "IsDisabled": "string",
      "DisabledNotes": "string",
      "Religion": "string",
      "HasDependants": "string",
      "DependentChildren": 0,
      "DependentDisabled": 0,
      "DependentElderly": 0,
      "Languages": "string",
      "SexualOrientation": "string",
      "Disability": "string",
      "GenderIdentity": "Transgender"
    }
  }
]

31 March 2021 — Holiday resource is now available

You can now manage employee holidays in Fourth using the new Holidays resource. The endpoint for these requests is:

  • <ROOT>/organisations/{organisationId}/Holidays

The endpoint accepts POST and DELETE requests.

The POST method create a new authorised holiday. You must request each day of a holiday separately. This means that to create a 1.5 day holiday for an employee, you would need to send an array holding two separate absence requests (or send each individually):

[
    {
        "EmployeeNumber": "76215",
        "RequestDate": "2021-03-29 00:00:00",
        "Value": 1,
        "Type": "days",
        "Unpaid": "No"
    },
    {
        "EmployeeNumber": "76215",
        "RequestDate": "2021-03-30 00:00:00",
        "Value": .5,
        "Type": "days",
        "Unpaid": "No"
    }
]

For information on the fields in the request, please see Create holidays in the API reference.

The DELETE method lets you delete a holiday. For example, to delete the half-day holiday created above, the request body would be:

[
    {
        "EmployeeNumber": "76215",
        "RequestDate": "2021-03-30 00:00:00"
    }
]

For information on the fields in the request, please see Delete holidays in the API reference.

24 September 2020 — New filters and fields for Employee and Employments endpoints

New showFormer filter

A new showFormer filter is available for these endpoints:
•    GET /employees
•    GET /employments

This filter lets you to choose whether to restrict the records that are returned to only current employees. The options are:
•    True — Records for both current and former employees are returned.
•    False — Records for only current employees are returned.

The default is true.

For example, this request would get all current employees:

GET <ROOT>/organisations/{organisationId}/Employees?start=&duration=&dateFrom=&dateTo=&delta=false&showFormer=false

This request would get the employment records for the month of August 2019 for current employees:

GET <ROOT>/organisations/{organisationId}/Employees/Employments?start=&duration=&dateFrom=2019-08-01&dateTo=2019-08-31&delta=true&showFormer=false

Additional fields for /employments

The /employees/employments endpoint now returns additional fields that let you know who the employee reports to. The fields are:

[
   { …
    "ReportsTo": "string",
    "ReportsToEmployeeNumber": "string",
    "ReportsToFAID": "string"
  }
]

Where:

  • ReportsTo — The first and last name of the employee’s manager. Up to 99 characters long.
  • ReportsToEmployeeNumber — The manager’s employee number.
  • ReportsToFAID — The manager’s Fourth Account ID number.

10 September 2020 — New EmployeeSource, Locations, and Divisions endpoints

Three new endpoints are available for the UK employee API:

  • GET Divisions
  • GET EmployeeSource
  • GET Location

GET Divisions endpoint

The new /Divisions endpoint lets you get a list of the departments for an organisation.  For example, front of house, kitchen, or bar.

The fields are:

[
  {
    "DivisionId": 0,
    "DivisionName": "string",
    "AccountingSystemCode": "string",
    "DivisionGUID": "string"
  }
]

Where:

  • DivisionId — Fourth ID for the division. This is unique to the customer but may not be unique across multiple customer instances.
  • DivisionName — The name of the division; for example, bar. Division names are created by the customer.
  • AccountingSystemCode — A unique ID for the division that comes from external software such as a third-party accounting system. Maximum length: 10 characters.
  • DivisionGuid — Fourth's globally unique ID for this job title.

GET EmployeeSource endpoint

This endpoint lets you get a list of the recruitment sources for employees; such as, walk-in or staff referral. The possible values are customer-defined and can be up to 40 characters in length.

Example response:

[
  {
    "SourceDescription": " Website"
  },
  {
    "SourceDescription": "Referral scheme"
  },
  {
    "SourceDescription": "Recruiter"
  }
]

There are no additional path or query parameters.

At present, we do not return this information for specific employees.

GET Locations endpoint

The new /locations endpoing returns the current (active) workplaces for the organisation.

Example response:

[
  {
    "LocationID": 92837572,
    "Description": "Covent Garden Acme Restaurant",
    "Country": "UK",
    "Area": "",
    "AccountingSystemCode": "123ADB",
    "LocationGUID": "BDA123"
  }
]

Where:

  • LocationID — Fourth ID for the customer location. This is unique to the customer but may not be unique across multiple customer instances.
  • Description — The name of the location. Maximum length: 50 characters.
  • Country — The country; one of UK, Ireland and Jersey. More countries may be added at a future date.
  • Area — The area (optional); one of Inner Dublin or Outer Dublin. More areas may be added at a future date.
  • AccountingSystemCode — A unique ID for the location that comes from external software such as a third-party accounting system. Maximum length: 10 characters.
  • LocationGUID — Fourth's globally unique ID for the customer location.

There are no additional path or query parameters for this endpoint.

11 June 2020 — Launch of new /accrual endpoint for getting holiday accrual data

We have launched a new endpoint that lets you get the current holiday accrual for a flexible employee:

  • GET /organisations/{organisationId}/Employees/Accrual

This endpoint provides holiday accrual calculations for flexible employees only. For other employee types (full-time, part-time, and casual), the calculation fields are set to "0".

For further information about flexible employees and holiday calculations, please visit our Customer Community.

Successful response example

[
  {
   "EmployeeID": 15129,
   "ElementName": "Holiday Balance",
   "ElementType": "ACCRUAL",
   "StartDateTime": "2020-05-19T00:00:00",
   "Units": 6.5,
   "UnitType": "Days",
   "IsFlexible": "Yes",
   "AvgSummary": 8.56,
   "AvgTime": 47.29,
   "AvgDays": 5.69,
   "DayRate": 71.99
  }
]

ElementName

One possible value: Holiday Balance

ElementType

One possible value: ACCRUAL

StartDateTime

The date when you requested this data. Fourth will return the most recent information; e.g. you cannot specify a time in the past. The format is yyyy-mm-ddT00:00:00.

Units

The number of hours or days that the employee has accrued as holidays. This value is negative if the employee has been given leave they have not yet accrued.

UnitType

Whether the value of Units is in days or hours.

IsFlexible

Whether the employee is:

  • Yes — A flexible employee.
  • No — A full-time, part-time or casual employee.

AvgSummary

Average hours per day that the employee works.

AvgTime

Average hours per week that the employee works.

AvgDays

Average days per week that the employee works.

DayRate

The average hours per day (AvgSummary) multiplied by the employee’s hourly pay rate.

9 April 2020 — Additional fields to support furlough schemes

To support the furloughing of employees, new fields are available in this endpoint:

  • GET /organisations/{organisationId}/Employees

The fields are:

IsEmployeeFurlough (Boolean)

This is either:

  • true — the employee is furloughed.
  • false — the employee is not furloughed.

Note that if an employee is made redundant, the value returns to false.

FurLoughContractHours (floating point)

The number of hours that the employee is normally employed in a week. This is based on the following:

  • For flexible employees, we use the flexible holiday calculation. This matches any current legislation for flexible employees.
  • For all other employees, we use the weekly contracted hours, or the full-time equivalent (FTE) hours, whichever is relevant for the employee.

For more information about furloughed employees, please visit the Customer Community and search for "furlough".

Abbreviated response sample

[
  {
    "EmployeeID": 987654321,
    …
    "IsEmployeeFurlough": true,
    "FurLoughContractHours": 37.5
  }
]

8 April 2020 — Additional fields to support adding EU employee residency information

For this endpoint:

  • POST /organisations/{organisationId}/Employees

There are now additional fields to support adding the residency status of European (EU) employees. These fields allow you to provide Fourth with the “Proof of Eligibility” data the employee has provided. There are three Government-mandated statuses, of which the employee can only have one at any given time:

  • Pre-settled Status
  • Settled Status
  • Temporary Leave to Remain

Abbreviated request example for an employee with settled status

[
  {
    "EmployeeNumber": "string",
    …
    "SettledStatus": "Yes",
    "SettledStatusShareCode": "701408727439",    
    "PreSettledStatus": "",
    "PreSettledStatusExpiryDate": "",
    "TemporaryLeaveToRemain": "",
    "TemporaryLeaveToRemainExpiryDate": "",
    …
  }
]

Abbreviated request example for an employee with temporary leave to remain

[
  {
    "EmployeeNumber": "string",
    …
    "SettledStatus": "",
    "SettledStatusShareCode": "",    
    "PreSettledStatus": "",
    "PreSettledStatusExpiryDate": "",
    "TemporaryLeaveToRemain": "Yes",
    "TemporaryLeaveToRemainExpiryDate": " 2021-Apr-01",
    …
  }
]

SettledStatus (string)

One of: yes (the employee has settled status), no, or left empty.

SettledStatusShareCode (string)

If SettledStatus is yes, then you can include the government-granted share code. This is a string of up to 20 digits, and is an optional field.

PreSettledStatus (string)

One of: yes (the employee has pre-settled status), no, or left empty.

PreSettledStatusExpiryDate

If PreSettledStatus is yes, then you can include the expiry date in the format: yyyy-MMM-dd. For example: 2021-Mar-19.

This is an optional field. If included, the date is used to warn customers if an employee is nearing the expiry date.

TemporaryLeaveToRemain

One of: yes (the employee has temporary leave to remain), no, or left empty.

TemporaryLeaveToRemainExpiryDate

If TemporaryLeaveToRemain is yes, then you can include the expiry date in the format: yyyy-MMM-dd. For example: 2020-Nov-11.

This is an optional field. If included, the date is used to warn customers if an employee is nearing the expiry date.

12 March 2020 — Employees endpoint: Additional values for EthnicOrigin and SexualOrientation

The /employees endpoint now includes more values for the following:

EthnicOrigin

  • Any Other Ethnic Group

SexualOrientation

  • Asexual
  • Gay Man
  • Gay Woman/Lesbian
  • Queer
  • Other
  • Prefer to Self-Describe

We will now return these values in GET /employees responses, and you can include them in any POST or PUT /employees requests.

12 March 2020 — Support for IR35 legislation introduced

Two endpoints now return the IR35 status for an employee. They are:

  • GET /organisations/{organisationId}/Employees
  • GET /organisations/{organisationId}/Employees/Employments

The new field is IR35, and the possible values are Boolean:

  • True — the person falls within IR35 regulation, and their payments must go through payroll.
  • False — the person is a regular employee.

Note that HMRC have postponed implementing this legislation to 6 April 2021. For information about how IR35 details are collected in Fourth, see the Customer Release Note.

Abbreviated response sample (valid for both endpoints)

[
   {
   "EmployeeID": 0,
   …
   "IR35": true,
   …
   }
]