HR REST API Documentation

SetUser

This document defines the working logic of the 'SetUser' endpoint, which was developed to manage the users in the Human Resources module in Synergy via the REST API.

Upsert Logic

The 'SetUser' function works with upsert ('insert' or 'update') logic:

If the relevant user does not exist in the system, a record is created ('INSERT').
If the relevant user is in the system, the existing record is updated ('UPDATE').

Data control is done through the unique code field specific to each object. For the user, this field is the 'username' information.

Endpoint Reference

SetUser — Create/Update Users

'''http POST User/SetUser

User creates or updates.

**Key field:** 'username'

### Request Body

The request body must be a JSON object containing user information under the 'hrObject' key.

'''json
{
  "hrObject": {
    "username": "jdoe",
    "password": "Acme123",
    "firstName": "John",
    "lastName": "Doe",
    "eMail": "john.doe@acme.com",
    "status": 1,
    "importStatus": 1,
    "defaultCulture": "en-EN",
    "departmentCode": "it-dept",
    "professionCode": "senior-dev",
    "employmentStart": "2024-12-01",
    "employmentEnd": "2026-12-31",
    "companyCodes": [
      "AcmeCorp",
      "AcmeInt"
    ],
    "sex": 1,
    "category": 1,
    "type": 1,
    "IdentificationNumber": "111231231",
    "RegistrationNumber": "222222",
    "phone": "0200 123 45 67",
    "mobilePhone": "0500 123 45 67",
    "birthDate": "1986-11-04",
    "properties": [
      {
        "code": "prop-text",
        "valueML": {
          "tr-TR": "TR Value",
          "en-US": "EN Value"
        }
      },
      {
        "code": "prop-list",
        "valueML": {
          "tr-TR": "1"
        }
      }
    ],
    "managers": [
      {
        "managerKeyDescription": "default",
        "managerUserCode": "admin"
      }
    ]
  }
}

Field Descriptions

Domain Name	Type	Mandatory	Description
'username'	'string'	Yes	Username. It is the key area of the Upsert process.
'password'	'string'	Yes	User password.
'firstName'	'string'	Yes	The user's name.
'lastName'	'string'	Yes	The user's last name.
'eMail'	'string'	Yes	The user's email address.
'status'	'integer'	No	User status. '1': Active, '0': Passive.
'importStatus'	'integer'	No	HR Transfer transfer status.
'defaultCulture'	'string'	No	Default language code. Example: 'en-TR', 'en-US'.
'departmentCode'	'string'	Yes	The department code defined in the system.
'professionCode'	'string'	Yes	The title code defined in the system.
'companyCodes'	'string[]'	No	The sequence of company codes to which the user is assigned.
'sex'	'int'	No	'0': Female, '1': Male, '2': Other, '3': Not specified.
'category'	'int'	No	'0': Blue Collar, '1': White Collar.
'type'	'int'	No	'0': Normal, '1': Custom.
'IdentificationNumber'	'string'	No	Citizenship number.
'RegistrationNumber'	'string'	No	Registration number.
'Phone'	'string'	No	Landline phone number.
'mobilePhone'	'string'	No	Mobile phone number.
'birthDate'	'date'	No	Date of birth. Example: '1986-01-13'.
'employmentStart'	'date'	No	Date of commencement of work. Example: '2020-01-13'.
'employmentEnd'	'date'	No	Date of termination of employment. Example: '2026-12-13'.
'managers'	'string[]'	No	Admin array based on the user's admin key.
'properties'	'string[]'	No	The array of features included in the user detail.

'properties' array

User-owned custom fields are defined through the 'properties' array. More than one property can be submitted.

Domain Name	Type	Mandatory	Description
'code'	'string'	Yes	The property code defined in the system.
'valueML'	'object'	Yes	An object consisting of language-value pairs. All property types are passed through this format. Example: '{ "en-US": "value", "en-US": "value" }'.

Property values must be passed with a language code-value pair over 'valueML', regardless of data type 'boolean', 'string', 'decimal' or 'date'.

This usage is a necessity arising from the method of storing property data in the database.

Mandatory Property Control

When creating a new user, the mandatory properties in the user detail are checked.

If the mandatory properties are not included in the 'properties' block in the 'SetUser' function, a warning message is returned as follows:

'''json { "success": false, "message": "Required properties missing: Prop1, Company, TestList" }

### Deleting Property Values

When the 'properties' block is sent as an empty array in the user edit process, it is considered a request for the user's property data to be deleted.

'''json
{
  "properties": []
}

> Note: If the user detail has mandatory properties, the value deletion is not performed. Mandatory properties that cannot be deleted are specified in the response message.

'''json { "success": false, "message": "Required properties cannot be cleared: Prop1, Company, TestList" }

---

## 'managers' Array

The 'managers' array is used to identify the user's administrators. Multiple admin keys are supported.

| Domain Name | Type | Mandatory | Description |
|---|---|---|---|
| 'managerKeyDescription' | 'string' | Yes | The name of the administrator key defined on the system. Example: 'default'. |
| 'managerUserCode' | 'string' | Yes | The registration number of the user to be assigned to the relevant administrator key. |

### Deleting Administrator Information

When the 'managers' block is sent as an empty array in the user edit process, this is considered a request to delete the administrator information defined on the user.

'''json
{
  "managers": []
}

Sample Responses

Successful Response — '200 OK'

When the process is completed successfully, the ID value of the user created or updated in the 'result' field is returned.

'''json { "result": 21768, "success": true }

### Error Response — Caught Validation Error

In cases such as a lack of forced fields or an invalid value, the error is caught by the upsert function and returned with a clear message.

'''json
{
  "success": false,
  "message": "username is required."
}

Error Response — System Exception (Internal Error)

Not all errors may be caught at the validation level. For unexpected system failures, a nested exception chain is returned.

'''json { "success": false, "message": "Error occurred in HumanResourcesAPI.Set...", "internalMessage": "Error occurred in BaseAPI.SendRequestWithUrl | ...", "exception": { "ClassName": "... ServiceAPIException", "Code": "SAPI_HRA__0001", "FootPrint": "77f76fd2a6b4fa6ac5008d6c41e87854", "InnerException": { "ClassName": "... ServiceAPIException", "Code": "SAPI_BASE_0001", "InnerException": { "...": "..." } } } }

---

## Notes

1. The 'UserName' field serves as the key for both the creation and update process. For this reason, it must be sent in the update process.
2. The 'companyCodes' field accepts multiple company codes as arrays.
3. The 'departmentCode' and 'professionCode' fields refer to codes that are predefined in the system.
4. Mandatory field checks are carried out sequentially. In the save process, all mandatory fields are checked at the same time and not returned as a list.
   - For example, if both the 'firstName' and 'lastName' fields are sent blank, the warning for the 'firstName' field is shown first in the response.
   - Only the mandatory properties in the 'properties' block are checked in batches, and the missing properties are returned as a list.

HR REST API Documentation

SetUser​

Upsert Logic​

Endpoint Reference​

SetUser — Create/Update Users​

Field Descriptions​

'properties' array​

Mandatory Property Control​

Sample Responses​

Successful Response — '200 OK'​

Error Response — System Exception (Internal Error)​