UK Employee API Guide

Introduction

With the UK Employee API, you can create, update and retrieve employee data in Fourth. 

It is intended for use where a Fourth customer in the United Kingdom is using Fourth as their employee master record and payroll system.

Quick Facts

Integration type HTTP REST with:
  • GET requests: JSON
  • POST requests: JSON / XML
Authentication Basic authentication
Availability United Kingdom only
Testing A test environment is available
More information See the Reference

Get Access

To get started with this API, you will need:

  • A UK Employee API account to access this API
  • The organisation ID used as a URL path parameter for identifying your requests
  • The root URL for requests

Your mutual Fourth customer must request credentials on your behalf. Please ensure they do this as soon as possible. The Fourth Professional Services team member managing the integration can provide the above information and help you with any integration questions you may have.

Updates

You can find any updates on the Release Notes page for the UK Employee API.

Where to find additional help

This guide is intended to help partners integrate with the API; however, it does not cover conceptual information such as employment law or how things are configured in the Fourth user interface. Please visit the Fourth Customer Community (no login is required) if you need help with topics, such as:

  • Furloughs
  • IR35
  • How holiday is calculated for flexible employees

Unique identifiers

GET requests to this API will return the following identifiers: 

  • FAID — This identifier is returned for the GET Employees request. This is the Fourth Account ID for the user and is used to identify the employee across the Fourth Platform. For example, it is commonly used as the identifier in SSO integrations.
  • EmployeeID — the Fourth ID for the employee. While the ID is globally unique in Fourth, it is used primarily within Workforce Management.
  • PayrollNumber — this identifier is editable by customers or third-parties. In POST requests, the EmployeeNumber field sets a value for this field. When not supplied, Fourth autogenerates an ID.
  • Reference — the individual record in the data; e.g. each address, absence, employment, etc, has a record number. An employee may have multiple records for the same type of data returned in the same request.

Employments and assignments

Amongst other things, this API allows you to get employments data from Fourth. To differentiate between an employee’s jobs and their overall employment, we use the concepts of employment and assignments. You can make an Employees/Employments GET request to retrieve the details of employments from Fourth. 

Employment represents the contract between an employee and employer. As employees have one contract with an employer, an employee can only have one employment for the same period with the same employer. However, they may have multiple employment records if they are hired multiple times; for example Oct-Dec 2017 and Jun-Aug 2018. This ensures that rehired employees have just the one record about their overall employment at the business. 

Assignments represents what an employee is doing for an employer; for example "sous-chef". The minimal properties that define this is location, job, rate type, contracted hours, rates, and whether it is the primary job (“main” assignment) of the employee. An employee may have multiple assignments for the same period of time, but only one main assignment at any point in time.

In the following example, an employee (Geoff) has 2 employment records. The first one starts on the 20th of March 2018, and ends on the 3rd of May 2019. The second one starts on the 5th of June, and is ongoing. During his employments, Geoff has multiple assignments, some of which overlap, which represents changes to location and job title.

Date Activity Record changes
20 March 2018 Geoff joins the business. Employment starts.
Main assignment (1) starts: Sous chef at Alpha location.
21 April 2018 Geoff is given additional shifts at another location. Additional assignment (2) starts: Sous chef at Beta location. This assignment is concurrent with the main assignment.
04 July 2018 Geoff is promoted to head chef.

Previous main assignment (1) ends.
Additional assignment (2) ends.
New main assignment (3): Head chef at Alpha location.

03 May 2019 Geoff leaves the business.
 
Main assignment (3) ends.
Employment ends.
05 June 2019 Geoff rejoins the business.

New employment starts.
New main assignment (4) starts.

European (EU) employees

The residency status of European (EU) employees has changed due to Britain leaving the EU ("Brexit"). This is reflected in the employee POST endpoint:

  • /organisations/{organisationId}/Employees

This endpoint includes fields for any “Proof of Eligibility” data that an EU employee has provided. There are three Government-mandated statuses, of which the employee can only have one at any given time:

  • Settled status; use:
    • SettledStatus (Boolean)
    • SettledStatusShareCode (string)
  • Pre-settled status; use:
    • PreSettledStatus (Boolean)
    • PreSettledStatusExpiryDate (date) — used by Fourth to warn customers when an employee is nearing the expiry date.
  • Temporary leave to remain; use:
    • TemporaryLeaveToRemain (Boolean)
    • TemporaryLeaveToRemainExpiryDate (date) — used by Fourth to warn customers when an employee is nearing the expiry date.

For more on EU employee changes, see our Customer Community.

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",
    …
  }
]

Sensitive information fields

Fourth provides sensitive information fields to allow employees and employers record details related to protected characteristics and diversity.  These fields are non-mandatory. The drop-down options for each are listed below:

Disability

  • No known impairment, health condition or learning difference
  • A mental health difficulty, such as depression, schizophrenia, or anxiety disorder
  • A physical impairment or mobility issues, such as difficulty using your arms or using a wheelchair
  • A social/communication impairment such as a speech and language impairment or Asperger’s syndrome/other autistic spectrum disorder
  • A specific learning difficulty such as dyslexia, dyspraxia, or AD(H)D
  • Blind or have a visual impairment uncorrected by glasses
  • Deaf or have a hearing impairment
  • An impairment, health condition or learning difference that is not listed above
  • Prefer not to say

Ethnic origin options

  • Any Other Ethnic Group
  • White - British
  • White - British Northern Irish
  • White - Irish
  • White - Other
  • Mixed - White and Black Caribbean
  • Mixed - White and black African
  • Mixed - White and Asian
  • Mixed - Other
  • Asian or Asian British - Indian
  • Asian or Asian British - Pakistani
  • Asian or Asian British - Bangladeshi
  • Asian or Asian British - Other
  • Black or Black British - Caribbean
  • Black or Black British - African
  • Black or Black British - Other
  • Chinese or Other Ethnic Group - Chinese
  • Chinese or Other Ethnic Group - Other
  • Arab & Middle Eastern - Arab
  • Arab & Middle Eastern - Iraqi
  • Arab & Middle Eastern - Other
  • Arab & Middle Eastern - Kurdish
  • Arab & Middle Eastern - North African
  • Middle Eastern - Middle Eastern Descent
  • Gypsy / Traveler / Irish Traveler
  • Prefer Not To Say

Language

  • Afrikaans

  • Akan

  • Albanian

  • Algerian

  • Amharic

  • Arabic

  • Armenian

  • Ashanti

  • Assamese

  • Assyrian

  • Azerbaijani

  • Azeri

  • Badini

  • Bajuni

  • Basque

  • Belorussian

  • Bengali

  • Berber

  • Bosnian

  • Brava

  • Bulgarian

  • Burmese

  • Cambodian

  • Cantonese

  • Catalan

  • Cebuano

  • Chaochow

  • Cherokee

  • Columbian

  • Creole

  • Croatian

  • Czech

  • Danish

  • Dari

  • Dutch

  • Egyptian

  • English

  • Eritrean

  • Esperanto

  • Estonian

  • Ethiopian

  • Fanti

  • Farsi

  • Fijian

  • Finnish

  • Flemish

  • French

  • Fulla

  • Gaelic (Scottish)

  • Georgian

  • German

  • Gorani

  • Greek

  • Gujarati

  • Hakka

  • Hausa

  • Hebrew

  • Hindi

  • Hungarian

  • Icelandic

  • Igbo

  • Ilocano

  • Indonesian

  • Iranian

  • Iraqi

  • Italian

  • Japanese

  • Kashmiri

  • Kazakh

  • Korean

  • Kosovan

  • Krio

  • Kurdish

  • Kurmanji

  • Lao

  • Latvian

  • Lebanese

  • Lingala

  • Lithuanian

  • Lubwisi

  • Luganda

  • Luo

  • Lusoga

  • Macedonian

  • Malay

  • Malayalam

  • Maltese

  • Mandarin

  • Mandinka

  • Marathi

  • Mirpuri

  • Moldovan

  • Mongolian

  • Moroccan

  • Nepalese

  • Nigerian

  • Norwegian

  • Nyakuse

  • Pahari

  • Persian

  • Philipino

  • Polish

  • Portuguese

  • Punjabi

  • Pusthu

  • Romanian

  • Russian

  • Samoan

  • Serbian

  • Serbo-Croat

  • Shona

  • Sinhalese

  • Slovak

  • Slovenian

  • Somali

  • Sorani

  • Sotho

  • Spanish

  • Sudanese

  • Swahili

  • Swedish

  • Sylheti

  • Tagalog

  • Taiwanese

  • Tamil

  • Telegu

  • Thai

  • Tibetan

  • Tigre

  • Tigrinian

  • Tswana

  • Turkish

  • Turkmanish

  • Twi

  • Ugandan

  • Other

  • Welsh

  • Vietnamese

Religion

  • Animism
  • Atheism
  • Bahai Faith
  • Buddhism
  • Chinese folk
  • Christianity
  • Confucianism
  • Hinduism
  • Islam
  • Jainism
  • Judaism
  • No Religion
  • Shamanism
  • Shinto
  • Sikhism
  • Spiritism
  • Taoism
  • Wicca
  • Zoroastrianism
  • Not listed above
  • Catholic
  • Protestant
  • Orthodox Christianity
  • Prefer not to say
  • Amish
  • Catholic ( R )
  • Protestant ( R )
  • Not Listed Above

Gender identity

  • Male
  • Female
  • Non-Binary
  • Genderqueer
  • Transgender
  • Prefer not to say
  • Not Listed Above

Sexual orientation

  • Bi/bisexual
  • Heterosexual/Straight
  • Homosexual
  • Prefer Not To Say
  • Asexual
  • Gay
  • Lesbian
  • Queer
  • Other
  • Prefer to self describe
  • Not Listed Above
  • Pansexual

Resources

You need to put the organisation ID in the URL path. The base path is:

<ROOT>/organisations/{organisationId}/

The GET requests have query parameters for filtering results. You must include all of the datetime and delta query parameters with the request; however, you only need to specify a value for delta. For example: 

<ROOT>/organisations/{organisationId}/Employees?start=&duration=&dateFrom=&dateTo=&delta=false
Resource Description
Divisions Returns the department used by the organisation; for example, front of house, kitchen, or bar.
Employees

The POST request creates or updates a single employee. This request can include a wide variety of information such as name, contact details, visa status, national insurance number, next of kin, and pay details. There is also a PUT request option.

The GET request returns a smaller set of core employee information, including name, DOB, nationality, furlough status, marital status, education and disability.

Employees/Absences The GET, POST, PUT and DELETE request lets you manage employee absences.
Employees/Accrual Returns the holiday accrued by flexible employees.
Employees/Addresses Returns employee addresses. If the employee has had multiple addresses during the time period, then all addresses are returned as separate records. The EffectiveDate identifies when the address change came into effect.
Employees/CountrySpecific Returns any country-specific fields that are not included in other requests. These fields are determined by Fourth (rather than being custom fields).
See the example below
Employees/Dependents Returns the dependents listed for each employee. 
Employees/Documents Returns the details of any documents (seen and recorded) for each employee during the time period. The documents you require from employees are defined within your business. 
Employees/Employments Returns the employment details for each employee during the specified time period. Employees may have multiple employments. 
Employees/NextOfKin Returns the next of kin for each employee. 
Employees/Passports Returns passports details associated with an employee.
Employees/PaymentDetails 

Returns the payment details of employees. If the employee updated these details during the specified time range, then all payment details are returned as separate records.

Employees/PayParts Returns information about the shifts that occurred during the pay period, such as start time and end, hours worked, job code and description.
There will be a record for each shift. 
Employees/Payslips Returns the details of any payslips issued during the time period. There will be one record returned for each transaction (or “element”) on the payslip.
EmployeeSource Returns a list of recruitment sources. We do not currently return this information for specific employees.
Holidays This endpoint accepts POST and DELETE requests, enabling you to manage paid and unpaid holidays for employees.
ImportLogs Used to check whether POST Employee requests were successfully processed. It returns a status and any relevant error message. See the explanation and example below.
Locations Returns an array of current workplaces for the organisation.
PayrollPeriod Returns the details of any payroll periods during the specified period. 

Time ranges and records

This API’s GET requests retrieve data for a specified time range — by default, this is the last calendar month. One of the effects of using a time range is that you may get multiple record entries for the same employee. For example, the GET Employees/Passports request returns the passport information recorded for employees. If this request is made with a time range of 12 months, then any employees who supplied new passport details during that time will have multiple records. In the following example, the same employee (EmployeeID 123) has both old and new passport records (PassportReference 70 and 71):

[ 
  {
   "EmployeeID" : "123",
   "PassportText" : "",
   "PassportReference" : "71",
   "PassportNumber" : "LK654321",
   "IssuingCountry" : "New Zealand",
   "IssueDate" : "2017-02-21",
   "ExpiryDate" : "2022-02-20"
   },
   {
   "EmployeeID" : "123",
   "PassportText" : "",
   "PassportReference" : "70",
   "PassportNumber" : "LK123456",
   "IssuingCountry" : "New Zealand",
   "IssueDate" : "2012-04-05",
   "ExpiryDate" : "2017-04-04"
   }
]

By default, any employee records that exist during the time range are included in the response, regardless of whether they are currently employed, or only employed during part of the specified time range. For some endpoints, you can filter out former employees using the showFormer query parameter.

Specifying the time range

By default, all GET requests will retrieve data for the last calendar month. You can specify an alternative time range using URL query parameters.

Query parameter Description
start and duration

Specifies a time range relative to the current day:

start — the number of days or months in the past to start the time range

duration — the number of days or months to include in the results

The days are inclusive. The format is (n)d for days, and (n)m for calendar months. For example: 

  • 7d — seven days 
  • 0d — today (for start) or zero days (for duration)
  • 2m — two full calendar months (e.g. if it is mid-April the export will start from the beginning of February).

To use these parameters, you must set a value for both. 

dateFrom and dateTo

The parameters dateFrom and dateTo let you get results by date, using the format YYYY-MM-DD. The dates are inclusive.

To use these parameters, you must set a value for both. 

If you use dateFrom and dateTo, then any values set for start and duration are ignored.

delta

The delta parameter allows you to get all records. You can set a boolean value:

true — Results are filtered by the specified time range.

false — All records are returned. The other time-related parameters are ignored.

You cannot use delta in GET requests to the Payroll, Employees/Payslip or ImportLogs resources. 

For example, to get employee absences for the last week, specify:

GET <ROOT>/organisations/{organisationId}/Employees/Absences?start=7d&duration=7d&dateFrom=&dateTo=&delta=true

To get the absences of all employees employed in 2017, specify:

GET <ROOT>/organisations/{organisationId}/Employees/Absences?start=&duration=&dateFrom=2017-01-01&dateTo=2017-12-31&delta=true

If you wish to include all records, set the delta query parameter to false in your request. For example, this request retrieves all employees ever employed:

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

Filtering for current and previous employees

The 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 without retrieving any former 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

Retrieving manager details

If you need to retrieve the manager an employer, use the GET /Employees/Employments endpoint. The fields that identify the manager are:

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

Request header

For all requests, you must provide your authentication details using Basic authentication in the header.

Example header:

GET /organisations/{organisationId}/Employees/Absences?
start=90d&amp;duration=90d&amp;datefrom=&amp;dateto=&delta=true  HTTP/1.1
Host: instance.example.com
Authorization: Basic VXNlcm5hbWU6cGFzc3dvcmQ=
Field Description
Authorization Your UK Employee API ID and password, separated by a colon, and then base64 encoded. Your ID and password are case-sensitive.
Content-Type The data format you are using for POST request. Options are: application/json, text/json, application/xml, text/xml.

Making POST employee requests

The POST Employees request allows you to add or update an employee (one per request). For full details of this request, see the reference and the example below.

To update an existing employee, use the same request. Fourth uses the EmployeeNumber to identify the record that needs updating. As it is a POST request, make sure you send the full record details rather than a subset of them. 

Requests are processed asynchronously, so you may want to use the ImportLogs request to confirm that the request was successfully processed.

POST /organisations/{organisationId}/Employees/
Host: instance.example.com
Content-Type: application/json
Authorization: Basic VXNlcm5hbWU6cGFzc3dvcmQ=

[ 
{
   "EmployeeNumber" : "9999",
   "Title" : "Mr",
   "FirstName" : "Chris",
   "MiddleName" : "Starr",
   "Surname" : "Jones",
   "PreferredName" : "Dr Jones",
   "DateOfBirth" : "1979-Jan-01",
   "Gender" : "Male",
   "MaritalStatus" : "Single",
   "Address1" : "17 Wayside Ave",
   "Address2" : "Burnside",
   "Address3" : "",
   "Town" : "Beckenham",
   "County" : “Kent",
   "Postcode" : "AB1 CD1",
   "HomeTel" : "02010000001",
   "MobileTel" : "00000000000",
   "Email" : "noemail@example.com",
   "HomeEmail" : "noemail@example.com",
   "NIN" : "",
   "Location" : "Fourth Restaurant 1",
   "Division" : "Bar",
   "JobTitle" : "Bar Staff",
   "StartDate" : "2018-Jan-01",
   "TerminationDate" : "",
   "PaidByRota" : "N",
   "IncludedInRota" : "Y",
   "PayType" : "",
   "RateOfPay" : "",
   "AnnualSalary" : "34000",
   "EmploymentType" : "Fulltime",
   "ContractHours" : "35",
   "PaymentMethod" : "BACS",
   "BankName" : "Bank Name",
   "BankAccountName" : "xyz abc",
   "BankSortCode" : "112233",
   "BankAccountNumber" : "12345678",
   "BuildingSocietyRollNumber" : "",
   "NOK1Title" : "Mr",
   "NOK1Firstname" : "Brother_Firstname",
   "NOK1Surname" : "Brother_Surname",
   "NOK1Relationship" : "brother",
   "NOK1Phone1" : "01031254522",
   "NOK1Phone2" : "02015847455",
   "NOK1Email" : "brother@example.com",
   "NOK2Title" : "Mrs",
   "NOK2Firstname" : "Mother_Firstname",
   "NOK2Surname" : "Mother_Surname",
   "NOK2Relationship" : "Mother",
   "NOK2Phone1" : "123456789",
   "NOK2Phone2" : "123456789",
   "NOK2Email" : "noemail@fourth.com",
   "OverrideFTE" : "",
   "FTEDays" : "",
   "FTEShifts" : "",
   "FTEHours" : "",
   "HolidayDaysTaken" : "",
   "HolidayAverageHoursPerWeek" : "",
   "HolidayAverageDaysPerWeek" : "",
   "HolidayEffectiveDate" : "",
   "EmployeeSourceDesc" : "ATS",
   "EffectiveDate" : ""
   }
]

Making POST Holidays requests

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

POST /organisations/{organisationId}/Holidays 
Host: instance.example.com 
Content-Type: application/json 
Authorization: Basic VXNlcm5hbWU6cGFzc3dvcmQ=

[
    {
        "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": 1,
        "Type": "days",
        "Unpaid": "No"
    },
    {
        "EmployeeNumber": "76215", 
        "RequestDate": "2021-03-31 00:00:00", 
        "Value": .5, 
        "Type": "days", 
        "Unpaid": "No" 
    }
]

Your request's details must match how the employee is paid. For example, salaried employees will have their holiday calculated as days, while other employees may be either hourly or shift workers. For example, if an hourly worker wanted to take a days leave (and normally worked 6.5 hours a day over a work week) the request would be:

POST /organisations/{organisationId}/Holidays
Host: instance.example.com
Content-Type: application/json
Authorization: Basic VXNlcm5hbWU6cGFzc3dvcmQ=

[
    {
        "EmployeeNumber": "51267",
        "RequestDate": "2021-04-01 00:00:00",
        "Value": 6.5,
        "Type": "hours",
        "Unpaid": "No"
    }
]

For information on the fields, please see the API Reference.

Response 

Successful requests

Successful GET requests receive an HTTP 200 OK response with the data requested in the response body.

Unsuccessful requests

Unsuccessful requests receive an HTTP 400-599 response, with an empty response body. 

Response to country specific requests

The Employees/CountrySpecific resource returns country specific fields that are not included in other requests. These fields are determined by Fourth and include the following:

  • NationalInsuranceNumber
  • P45 Rec / P46 Completed?
  • WTD opt-out Date (working time directive)
  • US social security number

The response will have a record for each field relevant in the country, for that employee. For example, a UK employee may have three separate records returned to cover the NI number, working time directive, and P45/46 information.

GET /organisations/{organisationId}Employees/CountrySpecific?start=0d&duration=1d&dateFrom=&dateTo=&delta=true
Host: instance.example.com
Accept: application/json
Authorization: Basic VXNlcm5hbWU6cGFzc3dvcmQ=

[ 
   {
   "EmployeeID"="123",
   "Country"="GB",
   "Property"="NationalInsuranceNumber",
   "Value"="SK000000"
    },
   {
   "EmployeeID"="123",
   "Country"="GB",
   "Property"="P45 Rec / P46 Completed?",
   "Value"="Yes"
    },
   {
   "EmployeeID"="123",
   "Country”="GB",
   "Property”=”WTD opt-out Date",
   "Value"="2018-01-04"
    }
]  

Checking Employee imports

There are a lot of validation checks required when Fourth receives a POST Employees request, and so this data is processed asynchronously. You will receive a synchronous response to acknowledge that the data was successfully received; however, to confirm that it was successfully processed, you must use an ImportLogs request. 

The ImportLogs resource returns batched data for a set time range. We recommend using a request regularly (e.g. daily) to look at recent employee requests. You’ll need to specify importType=employee as a query parameter. For example:

GET <ROOT>/organisations/{organisationId}/ImportLogs?resourceId=&importType=employee&start=1d&duration=1d&dateFrom=&dateTo=

The response from Fourth will include the results of every POST employee request for the last day. Included in the response is:

  • Id — A unique number assigned by Fourth for the original employee request.
  • ReferenceNumber — The unique ID you sent as EmployeeNumber in the request. 
  • Xml — Your original request as XML-formatted data.
  • Status — one of:
    • Added — A new employee record was successfully added.
    • Updated — An existing employee record was successfully updated. 
    • ValidationError — Normally issues to do with the formatting of the original request, including whether values are too long or use invalid characters.
    • InternalError — Normally issues found after the initial validation check, such as missing properties/elements, values that are contradictory (such as around salaried vs waged data), or values that don’t exist yet in Fourth (such as a new job title).
  • Error — If there was an issue, this provides a description of the problem, including help with how to provide valid data. For successfully processed requests, this is left blank. 

In the example response below, the XML data is truncated to make it easier to view the JSON properties. 

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

[
    {
        "Id": 81,
        "XmlType": "employee",
        "ReferenceNumber": "acme12",
        "Xml": "<Employee xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\" xmlns:xsd=\"http://www.w3.org/2001/XMLSchema\">
   <EmployeeNumber>acme12</EmployeeNumber>
   ...
</Employee>",
        "Status": "Updated",
        "DateCreatedUtc": "2018-02-07T14:01:13.0583374",
        "Error": ""
    },
    {
        "Id": 80,
        "XmlType": "employee",
        "ReferenceNumber": "acme31",
        "Xml": "<Employee xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\" xmlns:xsd=\"http://www.w3.org/2001/XMLSchema\">
   <EmployeeNumber>acme31</EmployeeNumber>
   ...
</Employee>",
   "Status": "ValidationError",
   "DateCreatedUtc": "2018-02-07T13:29:32.9535221",
   "Error": "Validation error(s) updating employee: Employee's Pay Type can be changed only on the Rota Week Start Day"
    },
   {
        "Id": 79,
        "XmlType": "employee",
        "ReferenceNumber": "acme23",
        "Xml": "<Employee xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\" xmlns:xsd=\"http://www.w3.org/2001/XMLSchema\">
   <EmployeeNumber>acme23</EmployeeNumber>
   ...
</Employee>",
        "Status": "InternalError",
        "DateCreatedUtc": "2018-02-07T07:46:38.4610637",
        "Error": "System.Exception: Unexpected error adding employee: Missing or invalid 'Personal Email' - . Must be a valid email address because Global Setting 'Personal Email Address Mandatory?' is on. Supported format: [Alphanumeric or Characters ._%+-] [@] [Alphanumeric or Characters &.-][.][This value must be between 2 and 4 characters long]. This value must not exceed 40 characters."
    },
   {
        "Id": 78,
        "XmlType": "employee",
        "ReferenceNumber": "acme03",
        "Xml": "<Employee xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\" xmlns:xsd=\"http://www.w3.org/2001/XMLSchema\">
   <EmployeeNumber>acme03</EmployeeNumber>
   ...
</Employee>",
   "Status": "InternalError",
   "DateCreatedUtc": "2018-02-05T10:27:21.9098163",
   "Error": "System.Exception: Unexpected error adding employee: 'First Names' is a required field."
    }
]

Troubleshooting & FAQs

Questions

Is there rate limiting on the UK Employee API?

Yes, however, it is fairly high; approximately 100 requests per second. We do not expect API users will exceed this limit when using the API for reasonable/fair and legitimate purposes.

Can we query employee and get employments nested or does it require a second query?

You need to do a second query.

Is there a way to only poll for users changed in the last month? Or users that got terminated last month?

Yes. This can be done by using the startDate and endDate parameters in the request.

Does Fourth have user groups in People Systems or Labor Productivity? If so, how are they exposed?

Not explicitly for users, no. User can be grouped by location or job title though.