Employees

The Employee API in Unit4 ERPx manages employee-related data - creation, retrieval, updates, and termination (soft-delete) of employee records. It is designed for integration with mobile and other external applications, supporting microservice-based development, testing, and maintenance.

Purpose:
The Employee API manages all aspects of employee data, including creation, update, validation, and soft deletion (termination).

Base URL:
/v1/employees

Authentication:
All APIs require a Client ID and Client Secret.
Refer to the global authentication documentation for details.

System Parameters:
System parameters for this API are available in Online Help → Personnel → Personnel → Fixed Registers → System Parameters.

Supported Methods

HTTP Method	Endpoint	Description	Limits & Notes
POST	`/v1/employees`	Create a single employee record	Only 1 employee per call. Can create employments and relations at the same time.
POST	`/v1/employees/batch`	Create multiple employee records	Max 200 employees per call (hard limit).
POST	`/v1/employees/validate`	Validate creation without saving	Used to validate employee data before creation.
GET	`/v1/employees/{personId}`	Retrieve single employee data	Supports multiple optional filters. When any of the optional parameters are specified as false, the data retrieved contains less property, allowing a faster response.
PATCH	`/v1/employees/batch`	Update employee data	Allows modifying employee and related records.
PATCH	`/v1/employees/validate`	Validate update without saving	Used to validate data before applying updates.
DELETE	`/v1/employees/{personId}`	Terminate (soft-delete) an employee	Changes status to ‘Terminate’.

Swagger / Schema

Version v1

Method Details

Sample Request

{
  "companyId": "SD1",
  "dateFrom": "2000-01-09T00:00:00.000",
  "dateTo": "2099-01-31T00:00:00.000",
  "nameInformation": {
    "aliasName": "JD",
    "firstName": "John",
    "surname": "Doe"
  },
  "paymentInformation": {
    "payMethod": "CH",
    "supplierGroupId": "1",
    "supplierId": "123"
  },
  "personId": "123",
  "personnelType": "E",
  "status": "N",
  "contactPoints": [{
    "address": {
      "countryCode": "GB",
      "streetAddress": "The Matrix"
    },
    "contactPointType": "1"
  }],
  "relatedValues": [{
    "status": "N",
    "relationId": "C1",
    "relatedValue": "111",
    "dateFrom": "2000-01-09T00:00:00.000",
    "dateTo": "2099-12-31T00:00:00.000"
  }]
}

Validation Rules for POST Method

POST_001 - User is not authorised

Element	Details
Scenario ID	POST_001
Scenario Name	User is not authorised
HTTP Code	403
GIVEN	A new employee needs to be created
WHEN	Calling the POST method of the API
BUT	User does NOT have permissions
THEN	API is not reached; 403 Forbidden response is returned
Example Error Message	“User is not authorised.”

POST_002 - Unknown CompanyID

Element	Details
Scenario ID	POST_002
Scenario Name	Unknown CompanyID
HTTP Code	403
GIVEN	A new employee needs to be created
WHEN	Calling the POST method of the API
BUT	CompanyID does not exist
THEN	API is not reached; 403 Forbidden response is returned
Example Error Message	“User is not authorised.”

POST_003 - Missing mandatory fields

Element	Details
Scenario ID	POST_003
Scenario Name	Missing mandatory fields
HTTP Code	422
GIVEN	A new employee needs to be created
WHEN	Calling the POST method of the API
BUT	A mandatory field is missing
THEN	Employee is not created; 422 response is returned
Example Error Message	“The {0} field is required.”

POST_004 - Invalid format of fields

Element	Details
Scenario ID	POST_004
Scenario Name	Invalid format of fields
HTTP Code	422
GIVEN	A new employee needs to be created
WHEN	Calling the POST method of the API
BUT	Field format is invalid
THEN	Employee is not created; 422 response is returned
Example Error Message	“Invalid date time format…” / “Error converting value {0} to type ‘{1}’…”

POST_005 - Unsatisfied model restrictions

Element	Details
Scenario ID	POST_005
Scenario Name	Unsatisfied model restrictions
HTTP Code	422
GIVEN	A new employee needs to be created
WHEN	Calling the POST method of the API
BUT	Field violates model restrictions (length, range, numeric limits)
THEN	Employee is not created; 422 response is returned
Example Error Message	“The field {0} must be a string with max length {1}” / “{0} must be equal or earlier than {1}”

POST_006 - Duplicate personId

Element	Details
Scenario ID	POST_006
Scenario Name	Duplicate personId
HTTP Code	409
GIVEN	A new employee needs to be created
WHEN	Calling the POST method of the API
BUT	personId already exists within companyId
THEN	Employee is not created; 409 response is returned
Example Error Message	“Employee with ID {0} already exists within company {1}.”

POST_007 - Invalid data

Element	Details
Scenario ID	POST_007
Scenario Name	Invalid data
HTTP Code	422
GIVEN	A new employee needs to be created
WHEN	Calling the POST method of the API
BUT	Data does not exist on ERP (attribute values, list of possible values)
THEN	Employee is not created; 422 response is returned
Example Error Message	“{0} is not a legal {1}” / “Illegal {0}”

POST_008 - Missing field on DTO

Element	Details
Scenario ID	POST_008
Scenario Name	Missing field on DTO
HTTP Code	400
GIVEN	A new employee needs to be created
WHEN	Calling the POST method of the API
BUT	Property is not present in the request body
THEN	Employee is not created; 400 response is returned
Example Error Message	—

POST_009 - Employee is created

Element	Details
Scenario ID	POST_009
Scenario Name	Employee is created
HTTP Code	201
GIVEN	A new employee needs to be created
WHEN	Calling the POST method of the API
BUT	—
THEN	A new employee is created
Example Error Message	RESPONSE: returns the created employee

POST_009b - Employee is created when RESNO Autonumbering is active and personId is not provided

Element	Details
Scenario ID	POST_009b
Scenario Name	Employee is created when RESNO Autonumbering is active and personId is not provided
HTTP Code	201
GIVEN	A new employee needs to be created
WHEN	Calling the POST method of the API
BUT	personId is not provided AND Autonumbering for employee is active
THEN	A new employee is created; response returns assigned personId and supplierId
Example Error Message	RESPONSE: returns the created employee with auto-assigned IDs

POST_010 - Employee is created and Workflow is active

Element	Details
Scenario ID	POST_010
Scenario Name	Employee is created and Workflow is active
HTTP Code	202
GIVEN	A new employee needs to be created
WHEN	Calling the POST method of the API
BUT	Workflow is active when creating a new employee
THEN	A new record is created and pending for approval; response contains messages for fields awaiting approval
Example Error Message	“Field {0} is awaiting approval.”

Sample Request

{
     "companyId": "SD1",
    "dateFrom": "2000-01-09T00:00:00.000",
    "dateTo": "2099-01-31T00:00:00.000",
    "nameInformation": {
        "aliasName": "JD",
        "firstName": "John",
        "surname": "Doe"
    },
    "paymentInformation": {
        "payMethod": "CH",
        "supplierGroupId": "1",
        "supplierId": "123"
    },
    "personId": "123",
    "personnelType": "E",
    "status": "N",
    "contactPoints": [
        {
            "address": {
                "countryCode": "GB",
                "streetAddress": "The Matrix"
            },
            "contactPointType": "1"
        }
    ],
    "relatedValues": [
        {
            "status": "N",
            "relationId": "C1",
            "relatedValue": "111",
            "dateFrom": "2000-01-09T00:00:00.000",
            "dateTo": "2099-12-31T00:00:00.000"
        }
    ]
},
{
    "companyId": "SD1",
    "dateFrom": "2000-01-30T00:00:00.000",
    "dateTo": "2099-01-31T00:00:00.000",
    "nameInformation": {
        "aliasName": "JS",
        "firstName": "Jane",
        "surname": "Smith"
    },
    "paymentInformation": {
        "payMethod": "CH",
        "supplierGroupId": "1",
        "supplierId": "321"
    },
    "personId": "321",
    "personnelType": "E",
    "status": "N",
    "contactPoints": [
        {
            "address": {
                "countryCode": "GB",
                "streetAddress": "Bond Street"
            },
            "contactPointType": "1"
        }
    ],
    "relatedValues": [
        {
            "status": "N",
            "relationId": "C1",
            "relatedValue": "222",
            "dateFrom": "2000-01-30T00:00:00.000",
            "dateTo": "2099-12-31T00:00:00.000"
        }
    ]
}
]
}

Validation Rules for POST Method (batch)

POST_001 - User is not authorised

Element	Details
Scenario ID	POST_001
Scenario Name	User is not authorised
HTTP Code	403
GIVEN	A new employee needs to be created
WHEN	Calling the POST method of the API
BUT	User does NOT have permissions
THEN	API is not reached; 403 Forbidden response is returned
Example Error Message	“User is not authorised.”

POST_002 - Unknown companyID

Element	Details
Scenario ID	POST_002
Scenario Name	Unknown companyID
HTTP Code	403
GIVEN	A new employee needs to be created
WHEN	Calling the POST method of the API
BUT	companyID does not exist
THEN	API is not reached; 403 Forbidden response is returned
Example Error Message	“User is not authorised.”

POST_003 - Missing mandatory fields

Element	Details
Scenario ID	POST_003
Scenario Name	Missing mandatory fields
HTTP Code	422
GIVEN	A new employee needs to be created
WHEN	Calling the POST method of the API
BUT	A mandatory field is missing
THEN	Employee is not created; 422 response is returned
Example Error Message	“The {0} field is required.”

POST_004 - Invalid format of fields

Element	Details
Scenario ID	POST_004
Scenario Name	Invalid format of fields
HTTP Code	422
GIVEN	A new employee needs to be created
WHEN	Calling the POST method of the API
BUT	Field format is invalid
THEN	Employee is not created; 422 response is returned
Example Error Message	“Invalid date time format…” / “Error converting value {0} to type ‘{1}’…”

POST_005 - Unsatisfied model restrictions

Element	Details
Scenario ID	POST_005
Scenario Name	Unsatisfied model restrictions
HTTP Code	422
GIVEN	A new employee needs to be created
WHEN	Calling the POST method of the API
BUT	Field violates model restrictions (length, range, numeric limits)
THEN	Employee is not created; 422 response is returned
Example Error Message	“The field {0} must be a string with max length {1}” / “{0} must be equal or earlier than {1}”

POST_006 - Duplicate personId

Element	Details
Scenario ID	POST_006
Scenario Name	Duplicate personId
HTTP Code	409
GIVEN	A new employee needs to be created
WHEN	Calling the POST method of the API
BUT	personId already exists within companyId
THEN	Employee is not created; 409 response is returned
Example Error Message	“Employee with ID {0} already exists within company {1}.”

POST_007 - Invalid data

Element	Details
Scenario ID	POST_007
Scenario Name	Invalid data
HTTP Code	422
GIVEN	A new employee needs to be created
WHEN	Calling the POST method of the API
BUT	Data does not exist on ERP (attribute values, list of possible values)
THEN	Employee is not created; 422 response is returned
Example Error Message	“{0} is not a legal {1}” / “Illegal {0}”

POST_008 - Missing field on DTO

Element	Details
Scenario ID	POST_008
Scenario Name	Missing field on DTO
HTTP Code	400
GIVEN	A new employee needs to be created
WHEN	Calling the POST method of the API
BUT	Property is not present in the request body
THEN	Employee is not created; 400 response is returned
Example Error Message	—

POST_009 - CompanyId is different in more than one employee

Element	Details
Scenario ID	POST_009
Scenario Name	CompanyId is different in more than one employee
HTTP Code	403
GIVEN	A new employee needs to be created
WHEN	Calling the POST method of the API
BUT	CompanyIds are different inside the request
THEN	Employee is not created; 403 response is returned
Example Error Message	“WebAPI: There is a mismatch between the url parameter and the passed object.”

POST_010 - Employees are created

Element	Details
Scenario ID	POST_010
Scenario Name	Employees are created
HTTP Code	201
GIVEN	A new employee needs to be created
WHEN	Calling the POST method of the API
BUT	—
THEN	A new employee is created
Example Error Message	RESPONSE: returns the created employees

POST_011 - Employee is created when RESNO Autonumbering is ACTIVE and personId is not provided (multiple employees)

Element	Details
Scenario ID	POST_011
Scenario Name	Employee is created when RESNO Autonumbering is ACTIVE and personId is not provided (multiple employees)
HTTP Code	201
GIVEN	A new employee needs to be created
WHEN	Calling the POST method of the API
BUT	personId is not provided AND Autonumbering for Employees is active
THEN	A new employee is created
Example Error Message	RESPONSE: returns the created employees AND each DTO contains personId and supplierId with the ID assigned to each employee

POST_012 - Employee is created when RESNO Autonumbering is ACTIVE and personId is not provided (single employee)

Element	Details
Scenario ID	POST_012
Scenario Name	Employee is created when RESNO Autonumbering is ACTIVE and personId is not provided (single employee)
HTTP Code	201
GIVEN	A new employee needs to be created
WHEN	Calling the POST method of the API
BUT	personId is not provided AND Autonumbering for Employee is active
THEN	A new employee is created
Example Error Message	RESPONSE: returns the created employee AND personId and supplierId contain the ID assigned to this new employee

POST_013 - Employee is created and Workflow is active

Element	Details
Scenario ID	POST_013
Scenario Name	Employee is created and Workflow is active
HTTP Code	202
GIVEN	A new employee needs to be created
WHEN	Calling the POST method of the API
BUT	Workflow is active when creating a new employee
THEN	A new record is created and pending for approval; response contains messages on fields awaiting approval
Example Error Message	“Field {0} is awaiting approval.”

Sample Request

{
    "companyId": "SD1",
    "dateFrom": "2000-01-09T00:00:00.000",
    "dateTo": "2099-01-31T00:00:00.000",
    "nameInformation": {
        "aliasName": "JD",
        "firstName": "John",
        "surname": "Doe"
    },
    "paymentInformation": {
        "payMethod": "CH",
        "supplierGroupId": "1",
        "supplierId": "123"
    },
    "personId": "123",
    "personnelType": "E",
    "status": "N",
    "contactPoints": [
        {
            "address": {
                "countryCode": "GB",
                "streetAddress": "The Matrix"
            },
            "contactPointType": "1"
        }
    ],
    "relatedValues": [
        {
            "status": "N",
            "relationId": "C1",
            "relatedValue": "111",
            "dateFrom": "2000-01-09T00:00:00.000",
            "dateTo": "2099-12-31T00:00:00.000"
        }
    ]
}

Validation Rules for POST Method (validate)

POST_001 - User is not authorised

Element	Details
Scenario ID	POST_001
Scenario Name	User is not authorised
HTTP Code	403
GIVEN	A new employee needs to be created
WHEN	Calling the POST method of the API
BUT	User does NOT have permissions
THEN	API is not reached; 403 Forbidden response is returned
Example Error Message	“User is not authorised.”

POST_002 - Unknown companyID

Element	Details
Scenario ID	POST_002
Scenario Name	Unknown companyID
HTTP Code	403
GIVEN	A new employee needs to be created
WHEN	Calling the POST method of the API
BUT	companyID does not exist
THEN	API is not reached; 403 Forbidden response is returned
Example Error Message	“User is not authorised.”

POST_003 - Missing mandatory fields

Element	Details
Scenario ID	POST_003
Scenario Name	Missing mandatory fields
HTTP Code	422
GIVEN	A new employee needs to be created
WHEN	Calling the POST method of the API
BUT	A mandatory field is missing
THEN	Employee is not created; 422 response is returned
Example Error Message	“The {0} field is required.”

POST_004 - Invalid format of fields

Element	Details
Scenario ID	POST_004
Scenario Name	Invalid format of fields
HTTP Code	422
GIVEN	A new employee needs to be created
WHEN	Calling the POST method of the API
BUT	Field format is invalid
THEN	Employee is not created; 422 response is returned
Example Error Message	“Invalid date time format…” / “Error converting value {0} to type ‘{1}’…”

POST_005 - Unsatisfied model restrictions

Element	Details
Scenario ID	POST_005
Scenario Name	Unsatisfied model restrictions
HTTP Code	422
GIVEN	A new employee needs to be created
WHEN	Calling the POST method of the API
BUT	Field violates model restrictions (length, range, numeric limits)
THEN	Employee is not created; 422 response is returned
Example Error Message	“The field {0} must be a string with max length {1}” / “{0} must be equal or earlier than {1}”

POST_006 - Duplicate personId

Element	Details
Scenario ID	POST_006
Scenario Name	Duplicate personId
HTTP Code	409
GIVEN	A new employee needs to be created
WHEN	Calling the POST method of the API
BUT	personId already exists within companyId
THEN	Employee is not created; 409 response is returned
Example Error Message	“Employee with ID {0} already exists within company {1}.”

POST_007 - Invalid data

Element	Details
Scenario ID	POST_007
Scenario Name	Invalid data
HTTP Code	422
GIVEN	A new employee needs to be created
WHEN	Calling the POST method of the API
BUT	Data does not exist on ERP (attribute values, list of possible values)
THEN	Employee is not created; 422 response is returned
Example Error Message	“{0} is not a legal {1}” / “Illegal {0}”

POST_008 - Employee is created

Element	Details
Scenario ID	POST_008
Scenario Name	Employee is created
HTTP Code	201
GIVEN	A new employee needs to be created
WHEN	Calling the POST method of the API
BUT	No error is found
THEN	A new employee is created
Example Error Message	RESPONSE: returns the JSON

POST_009 - Missing field on DTO

Element	Details
Scenario ID	POST_009
Scenario Name	Missing field on DTO
HTTP Code	400
GIVEN	A new employee needs to be created
WHEN	Calling the POST method of the API
BUT	A property is not present on the body
THEN	Employee is not created; 400 response is returned
Example Error Message	—

Sample Request

N/A

Additional Parameters

The following parameters help retrieve basic information about an employee:

Parameter	Value	Description	Data Type	Default Value
includeHistory	optional	Specify if you wish to include or exclude retrieval of historical information related to a specific `personId`.	boolean	true
getDescriptions	optional	Specify if you wish to retrieve descriptions of field values related to a specific `personId`.	boolean	true
includeFlexiFields	optional	Specify if you wish to include or exclude retrieval of information from flexi-fields related to a specific `personId`.	boolean	true
includeRelatedValues	optional	Specify if you wish to include or exclude retrieval of related values for a specific `personId`.	boolean	true

Validation Rules for GET Method

GET_001 - User is not authorised

Element	Details
Scenario ID	GET_001
Scenario Name	User is not authorised
HTTP Code	403
GIVEN	Data from an existing employee needs to be retrieved
WHEN	Calling the GET method of the API
BUT	User does NOT have permissions
THEN	API is not reached; 403 Forbidden response is returned
Example Error Message	“User is not authorised.”

GET_002 - Unknown companyID

Element	Details
Scenario ID	GET_002
Scenario Name	Unknown companyID
HTTP Code	403
GIVEN	Data from an existing employee needs to be retrieved
WHEN	Calling the GET method of the API
BUT	companyID does not exist
THEN	API is not reached; 403 Forbidden response is returned
Example Error Message	“User is not authorised.”

GET_003 - Missing mandatory fields

Element	Details
Scenario ID	GET_003
Scenario Name	Missing mandatory fields
HTTP Code	405
GIVEN	Data from an existing employee needs to be retrieved
WHEN	Calling the GET method of the API
BUT	personId is not indicated
THEN	Employee is not retrieved; 405 response is returned
Example Error Message	(Empty message)

GET_004 - personId does not exist

Element	Details
Scenario ID	GET_004
Scenario Name	personId does not exist
HTTP Code	404
GIVEN	Data from an existing employee needs to be retrieved
WHEN	Calling the GET method of the API
BUT	personId does not exist for the companyId
THEN	Employee is not retrieved; 404 response is returned
Example Error Message	“The entity of the following parameters [Company: {0}, Employee: {1}] was not found.”

GET_005 - Employee exists

Element	Details
Scenario ID	GET_005
Scenario Name	Employee exists
HTTP Code	200
GIVEN	Data from an existing employee needs to be retrieved
WHEN	Calling the GET method of the API
BUT	—
THEN	200 response is returned together with the information of the employee
Example Error Message	RESPONSE: Employee information is retrieved

GET_006 - Employee exists BUT without Flexi-fields

Element	Details
Scenario ID	GET_006
Scenario Name	Employee exists BUT without Flexi-fields
HTTP Code	200
GIVEN	Data from an existing employee needs to be retrieved
WHEN	Calling the GET method of the API AND additional parameter includeFlexiFields is false
BUT	—
THEN	200 response is returned together with the information of the employee WITHOUT information of their flexi-fields (`customFieldGroups` is not part of the response, not even as `customFieldGroups: []`)
Example Error Message	RESPONSE: Employee information is retrieved

Sample Request

  employees/123
    {
        "path": "employments",
        "op": "RemovedById",
        "value": {
          "positionId": "0009",
          "startDate": "2024-08-01",
          "endDate": "2025-10-14"
        }
  }

  employees/123?childEndAtEndDate=true
{
        "path": "employments",
        "op": "AddOrReplaceById",
        "value": {
          "positionId": "0009",
          "startDate": "2024-08-01",
          "endDate": "2025-10-14"
        }
  }

Additional Parameters

The following parameters help retrieve or update basic information about an employee:

Parameter	Value	Description	Data Type	Default Value
childStrategy	optional	Used for patching Employments and their relations. Within a specified Date Range, you must decide which Child Entities to update and whether to create new Entities if required. Possible values: `"AddOrUpdate"`, `"Add"`, `"UpdateValidAsOfStartDate"`	string	AddOrUpdate
childEndAtEndDate	optional	Used for patching Employments and their relations. Specify if you wish to populate the End Date for a specific `personId` or its relations.	boolean	true
includeFlexiFields	optional	Specify if you wish to include or exclude retrieval of information from flexi-fields related to a specific `personId`.	boolean	true
includeRelatedValues	optional	Specify if you wish to include or exclude retrieval of related values for a specific `personId`.	boolean	true

Limits & Notes

One employee per call.
Possibility to update several fields per call.
Possibility to add, update, and remove employments, and update or remove relations.
childStrategy parameter is only valid for Employments and their relations. The possible values are:
- AddOrUpdate – Add or update connections between given start-date and end-date (e.g. update and/or fill/stretch to guarantee coverage between the given start and end-date).
  Typically used to create new connections or to extend/update existing connections while ensuring coverage for the specified interval.
- Update – Update existing connections between given start-date and end-date without adding or filling intervals where no connection exists.
  Typically used when existing connection intervals need updating for periods that already exist — the user doesn’t have to specify each employment interval in detail.
- UpdateValidAsOfStartDate – Update the connection valid as of the given start-date. Returns an error if not found.
  Applies the changes only to the one existing connection valid as per the start-date (while preserving history).
Patch operators for employee’s relations: AddOrReplaceById and RemoveById
- Keys on employee-relations: dateFrom, dateTo, relationId
- Other properties may help identify unique employee relations
Patch operators for employments and their relations: AddOrReplaceById and RemoveById
- Keys on employment: positionId, startDate, endDate
- Keys on employment-relations: positionId, dateFrom, dateTo, relationId
- Other properties may help identify the uniqueness of the employment and/or employment relations
If the relation being modified or deleted belongs to an attributeId marked as Duplicate, additional fields (e.g. relatedValue) must be provided to identify the correct column to modify.
The startDate of an employment cannot be amended (using AddOrReplaceByID) to a date after the existing startDate.
In this case, include the date where the employment is no longer valid and use a RemoveById operation instead.

Validation Rules for PATCH Method Details

PATCH_001 - User is not authorised

Element	Details
Scenario ID	PATCH_001
Scenario Name	User is not authorised
HTTP Code	403
GIVEN	Data from an existing employee needs to be modified
WHEN	Calling PATCH method of the API
BUT	User does NOT have permissions
THEN	API is not reached; 403 response is returned
Example Error Message	“User is not authorised.”

PATCH_002 - Missing mandatory fields

Element	Details
Scenario ID	PATCH_002
Scenario Name	Missing mandatory fields
HTTP Code	422
GIVEN	Data from an existing employee needs to be modified
WHEN	Calling PATCH method of the API
BUT	A mandatory field is missing
THEN	Data is not updated; 422 response is returned
Example Error Message	“The {0} field is required.”

PATCH_003 - Invalid format of fields

Element	Details
Scenario ID	PATCH_003
Scenario Name	Invalid format of fields
HTTP Code	422
GIVEN	Data from an existing employee needs to be modified
WHEN	Calling PATCH method of the API
BUT	Field format is invalid
THEN	Data is not updated; 422 response is returned
Example Error Message	“Invalid date time format…” / “Error converting value {0} to type ‘{1}’…”

PATCH_004 - Unsatisfied model restrictions

Element	Details
Scenario ID	PATCH_004
Scenario Name	Unsatisfied model restrictions
HTTP Code	422
GIVEN	Data from an existing employee needs to be modified
WHEN	Calling PATCH method of the API
BUT	Field violates model restrictions
THEN	Data is not updated; 422 response is returned
Example Error Message	“The date must be between {0} and {1}” / “The field {0} must be a string with max length {1}”

PATCH_005 - Unknown companyID

Element	Details
Scenario ID	PATCH_005
Scenario Name	Unknown companyID
HTTP Code	422
GIVEN	Data from an existing employee needs to be modified
WHEN	Calling PATCH method of the API
BUT	Invalid companyID
THEN	Data is not updated; 422 response is returned
Example Error Message	“Unknown {0}.”

PATCH_006 - Unknown personId

Element	Details
Scenario ID	PATCH_006
Scenario Name	Unknown personId
HTTP Code	404
GIVEN	Data from an existing employee needs to be modified
WHEN	Calling PATCH method of the API
BUT	personId does not exist
THEN	Data is not updated; 404 response is returned
Example Error Message	“Employee with ID {0} was not found within the company {1}.”

PATCH_007 - Update an employment without mandatory parameters

Element	Details
Scenario ID	PATCH_007
Scenario Name	Update an employment AND request doesn’t have the mandatory parameters
HTTP Code	400
GIVEN	Employment data from an existing employee needs to be modified
WHEN	Calling PATCH method of the API with addOrReplaceById operation
BUT	positionId OR startDate OR endDate is not present on the request
THEN	Data is not updated; 400 response is returned
Example Error Message	“The {0}-property of the patch-element must be given….”

PATCH_008 - Delete an employment without mandatory parameters

Element	Details
Scenario ID	PATCH_008
Scenario Name	Delete an employment AND request doesn’t have the mandatory parameters
HTTP Code	400
GIVEN	Employment data from an existing employee needs to be deleted
WHEN	Calling PATCH method of the API with removeById operation
BUT	positionId OR startDate OR endDate is not present on the request
THEN	Data is not updated; 400 response is returned
Example Error Message	“The {0}-property of the patch-element must be given….”

PATCH_009 - Changing first name when part of name definition

Element	Details
Scenario ID	PATCH_009
Scenario Name	Changing the first name of an employee AND the first name is part of the name definition (System parameters)
HTTP Code	200
GIVEN	Data from an existing employee needs to be modified
WHEN	Calling PATCH method of the API
BUT	firstName field is part of the active System parameter “HS_NAME” value
THEN	200 response is returned together with the information of the employee and name property is automatically updated according to the System parameter “HS_NAME” value
Example Error Message	RESPONSE: Employee information is retrieved

PATCH_010 - Delete an employment that already existed

Element	Details
Scenario ID	PATCH_010
Scenario Name	Delete an employment that already existed
HTTP Code	200
GIVEN	Employment data from an existing employee needs to be deleted
WHEN	Calling PATCH method of the API
BUT	The given positionId does not exist for the employment
THEN	200 response is returned
Example Error Message	N/A

Sample Request

{
    "companyId": "SD1",
    "dateFrom": "2000-01-09T00:00:00.000",
    "dateTo": "2099-01-31T00:00:00.000",
    "nameInformation": {
        "aliasName": "JD",
        "firstName": "John",
        "surname": "Doe"
    },
    "paymentInformation": {
        "payMethod": "CH",
        "supplierGroupId": "1",
        "supplierId": "123"
    },
    "personId": "123",
    "personnelType": "E",
    "status": "N",
    "contactPoints": [
        {
            "address": {
                "countryCode": "GB",
                "streetAddress": "The Matrix"
            },
            "contactPointType": "1"
        }
    ],
    "relatedValues": [
        {
            "status": "N",
            "relationId": "C1",
            "relatedValue": "111",
            "dateFrom": "2000-01-09T00:00:00.000",
            "dateTo": "2099-12-31T00:00:00.000"
        }
    ]
}

Additional Parameters

The following parameters help retrieve or update basic information about an employee:

Parameter	Value	Description	Data Type	Default Value
childStrategy	optional	Used for patching Employments and their relations. Within a specified Date Range, you must decide which Child Entities to update and whether to create new Entities if required. Possible values: `"AddOrUpdate"`, `"Add"`, `"UpdateValidAsOfStartDate"`	string	AddOrUpdate
childEndAtEndDate	optional	Used for patching Employments and their relations. Specify if you wish to populate the End Date for a specific `personId` or its relations.	boolean	true
includeFlexiFields	optional	Specify if you wish to include or exclude retrieval of information from flexi-fields related to a specific `personId`.	boolean	true
includeRelatedValues	optional	Specify if you wish to include or exclude retrieval of related values for a specific `personId`.	boolean	true

Validation Rules for PATCH Method (validate)

Same scenarios as the single employee patch

Sample Request

{
    DELETE employees/123
}

Validation Rules for DELETE Method

DEL_001 - User is not authorised

Element	Details
Scenario ID	DEL_001
Scenario Name	User is not authorised
HTTP Code	403
GIVEN	Employee needs to be ‘Terminated’
WHEN	Calling DELETE method of the API
BUT	User is not authorised
THEN	API is not reached; 403 response is returned
Example Error Message or Response	“User is not authorised.”

DEL_002 - Missing required parameters

Element	Details
Scenario ID	DEL_002
Scenario Name	Missing required parameters
HTTP Code	404
GIVEN	Employee needs to be ‘Terminated’
WHEN	Calling DELETE method of the API
BUT	Required parameter is missing
THEN	API is not reached; 404 response is returned
Example Error Message or Response	“No HTTP resource was found matching {0}”

DEL_003 - Employee does not exist

Element	Details
Scenario ID	DEL_003
Scenario Name	Employee does not exist
HTTP Code	404
GIVEN	Employee needs to be ‘Terminated’
WHEN	Calling DELETE method of the API
BUT	personId does not exist
THEN	No deletion; 404 response is returned
Example Error Message or Response	“Employee with ID {0} was not found within the company {1}.”

DEL_004 - Employee exists

Element	Details
Scenario ID	DEL_004
Scenario Name	Employee exists
HTTP Code	200
GIVEN	Employee needs to be ‘Terminated’
WHEN	Calling DELETE method of the API
BUT
THEN	Employee is ‘Terminated’; 200 response is returned
Example Error Message or Response	Empty message

Best Practices

If you plan to create several employees, use the batch endpoint to help identify possible errors in all employees.
Respect hard limits:
- POST: Maximum 200 employees
Use Swagger UI for testing and schema validation before production calls.
Handle error codes gracefully; implement retry/backoff according to global rate limits.
Always check for deprecation alerts on this endpoint version.
Validate employees before sending DELETE requests to avoid unintentional data loss.

ERPx

ERPx

U4 ERPx

Employees

The Employee API in Unit4 ERPx manages employee-related data - creation, retrieval, updates, and termination (soft-delete) of employee records. It is designed for integration with mobile and other external applications, supporting microservice-based development, testing, and maintenance.

Supported Methods

Swagger / Schema

Version v1

Method Details

Sample Request

Validation Rules for POST Method

Sample Request

Validation Rules for POST Method (batch)

Sample Request

Validation Rules for POST Method (validate)

Sample Request

Additional Parameters

Validation Rules for GET Method

Sample Request

Additional Parameters

Limits & Notes

Validation Rules for PATCH Method Details

Sample Request

Additional Parameters

Validation Rules for PATCH Method (validate)

Sample Request

Validation Rules for DELETE Method

Best Practices

Action APIs

Query APIs (Read-Only)

U4 ERPx

Employees

The Employee API in Unit4 ERPx manages employee-related data - creation, retrieval, updates, and termination (soft-delete) of employee records. It is designed for integration with mobile and other external applications, supporting microservice-based development, testing, and maintenance.

Supported Methods

Swagger / Schema

Version v1

Method Details

Sample Request

Validation Rules for POST Method

Sample Request

Validation Rules for POST Method (batch)

Sample Request

Validation Rules for POST Method (validate)

Sample Request

Additional Parameters

Validation Rules for GET Method

Sample Request

Additional Parameters

Limits & Notes

Validation Rules for PATCH Method Details

Sample Request

Additional Parameters

Validation Rules for PATCH Method (validate)

Sample Request

Validation Rules for DELETE Method

Best Practices

Related endpoints

Action APIs

Employee personal contacts

Employee balance setups

Employee balances

Employee balances (connected employee)

Employee competence

Query APIs (Read-Only)

Next of kins

Employee competence

Employee connection to user