How do you partially update an employee via the API?

PATCH /v1/employees/{employeeId} updates only the fields sent in the request. The body must contain at least one field. Access requires the employees.write scope.

Endpoint

Parameter	Value
Method	PATCH
Path	/v1/employees/{employeeId}
Base URL	https://smartway.pro/api
Auth	Bearer token
Required scope	employees.write

Purpose

This endpoint is used to partially update an employee within the current tenant.

fullName is not part of the PATCH contract; to change the full name, use name and surname.

Prerequisites

The client must send a valid Bearer token.
The token must contain company context.
The token must contain the employees.write scope.
employeeId must belong to an employee within the current tenant.
The PATCH body must contain at least one field.
idCompany and hrEmail are not sent by the external client.

Request

Path parameters

Parameter	Type	Required	Description
employeeId	int64	yes	Employee ID.

Body parameters

Field	Type	Required	Description
email	string	no	Update email.
name	string	no	Update the employee's first name. If the field is provided, it must contain non-empty text.
surname	string	no	Update the employee's surname. If the field is provided, it must contain non-empty text.
gender	string	no	Update gender.
department	string	no	Update the primary department.
departments	string[]	no	Replace the full set of departments.
jobTitle	string	no	Update the primary job title.
jobTitles	string[]	no	Replace the full set of job titles.
phone	string	no	Update phone number.
active	boolean	no	Update the active flag.

curl example

Update full name fields, primary fields, arrays, and active

curl -X PATCH 'https://smartway.pro/api/v1/employees/4432' \
  -H 'Authorization: Bearer <access_token>' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  --data-binary @- <<'JSON'
{
  "name": "Updated Name",
  "surname": "Surname",
  "department": "Management",
  "departments": ["КЛ", "Logistics"],
  "jobTitle": "Senior Manager",
  "jobTitles": ["Coordinator", "Analyst"],
  "active": false
}
JSON

Response

Successful response: 200 OK. Returns the updated Employee.

{
  "employeeId": 4432,
  "candidateId": 10748,
  "email": "employee@example.com",
  "fullName": "Updated Name Surname",
  "name": "Updated Name",
  "surname": "Surname",
  "gender": "not_specified",
  "department": "Management",
  "departments": [
    "Management",
    "Logistics",
    "КЛ"
  ],
  "jobTitle": "Senior Manager",
  "jobTitles": [
    "Analyst",
    "Coordinator",
    "Senior Manager"
  ],
  "phone": "+380000000000",
  "active": false
}

Response fields

Employee

Field	Type	Description
employeeId	int64	Employee ID.
candidateId	int64	Linked candidate ID.
email	string	Employee email.
fullName	string	Full name generated by the server from name + surname.
name	string	First name.
surname	string	Surname.
gender	string	Gender.
department	string	Primary department.
departments	string[]	Set of departments.
jobTitle	string	Primary job title.
jobTitles	string[]	Set of job titles.
phone	string	Phone number.
active	boolean	Active flag.

Business logic

The BFF takes companyId from the Bearer token, not from request parameters.
The BFF takes hrEmail from the Bearer token. hrEmail equals the email of the user with the HRADMIN role who created or rotated the active company API key.
If the active API key is rotated by another HRADMIN, subsequent patch operations automatically start using that HRADMIN's hrEmail.
PATCH changes only the fields sent in the body.
fullName is not sent in the PATCH body. The server generates fullName from the current name + surname.
name and surname can be sent together or separately. If a field is sent, it must contain non-empty text.
Text fields support UTF-8.
If only departments or jobTitles is provided, the first array element becomes the primary value.
If both a single field and an array are provided, the single field remains primary.
departments and jobTitles arrays in the response are returned in sorted order.
If the new email already belongs to another employee, the API returns 409 Conflict.
If active changes from false to true, the server creates or re-synchronises the linked Keycloak user and enables access to the personal account.
If active changes from true to false, the server deletes the linked Keycloak user and revokes access to the personal account.
If PATCH changes active and email at the same time, the server synchronises the account already linked to this employee, not an arbitrary user by the new email.

Edge cases

Edge cases

Scenario	API behaviour
PATCH body is empty	The API returns 400 Bad Request.
name or surname is sent empty	The API returns 400 Bad Request.
fullName is sent in the PATCH body	The field is not part of the PATCH contract; use name and surname.
New email already belongs to another employee	The API returns 409 Conflict.
Only departments or jobTitles is provided	The first array element becomes the primary value.
A single field and an array are provided	The single field remains primary; the response array is returned sorted.
active changes from false to true	The server creates or synchronises the linked Keycloak user.
active changes from true to false	The server deletes the linked Keycloak user.
active and email are changed at the same time	The account already linked to this employee is synchronised.

Errors

Error responses

HTTP status	When it occurs
400 Bad Request	Empty PATCH body or invalid values, including empty name / surname.
401 Unauthorized	Bearer token is missing or invalid.
403 Forbidden	Insufficient permissions or token without company context.
404 Not Found	Employee was not found within the current tenant.
409 Conflict	New email is already used by another employee or cannot be safely used to synchronise access in Keycloak.
500 Internal Server Error	Unexpected BFF error.
503 Service Unavailable	Internal integration failure BFF -> back2.

Usage

Update an employee's contact details.
Change department or job title.
Enable personal account access with active = true.
Revoke personal account access with active = false.
Update email with conflict checking.

Common mistakes

Typical integration mistakes

Common mistake	Correct approach
Sending an empty PATCH body	Send at least one field to change.
Sending fullName	Send name and surname.
Sending empty name or surname	If the field is sent, it must contain non-empty text.
Expecting active to only change a database flag	active also controls synchronisation of the linked Keycloak user.
Sending idCompany or hrEmail	Do not send these values; the BFF takes them from the Bearer token.

FAQ

Can I send only one field in PATCH?

Yes. The body must contain at least one field.

Can I change fullName directly?

No. fullName is not part of the PATCH contract. Use name and surname.

What happens if the new email is already used?

The API returns 409 Conflict.

What happens when active = false?

The server deletes the linked Keycloak user and revokes access to the personal account.

What happens if active and email are changed at the same time?

The server synchronises the account already linked to this employee.

Appearance

Language