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	`/api/v1/employees/{employeeId}`
Base URL	`[https://smartway.pro](https://smartway.pro)`
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.
`manager`	boolean	no	Update the department manager role. Only JSON-boolean values `true` or `false` are allowed; `true` keeps the employee active, while `false` removes only the department manager role unless `active` is also sent as `false`.

curl example

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

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": true,
  "manager": true
}
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": true,
  "manager": true
}

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.
`manager`	boolean	Department manager role flag. `true` means the employee has this role.

Business logic

The API determines companyId from the Bearer token, not from request parameters.

The API determines 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 user account on the authorisation server and enables access to the personal account.

If active changes from true to false, the server deletes the linked user account on the authorisation server 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.

manager = true adds the department manager role and guarantees active account access; if active = false is sent at the same time, manager access takes priority and the employee remains an active account user.

manager = false removes only the department manager role unless active is also sent as false; account access remains active.

If active = false and manager = false are sent together, the server revokes account access and deletes the linked user account on the authorisation server.

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 user account on the authorisation server.
`active` changes from `true` to `false`	The server deletes the linked user account on the authorisation server.
`active` and `email` are changed at the same time	The account already linked to this employee is synchronised.
`manager` is sent as a string or number	The API returns `400 Bad Request` because `manager` must be JSON-boolean.
`manager=true` and `active=false`	Manager access takes priority; the employee remains an active account user.
`manager=false` without `active=false`	Only the department manager role is removed; account access remains active.

Errors

Error responses

HTTP status	When it occurs
`400 Bad Request`	Empty PATCH body or invalid values, including empty `name` / `surname`.
`400 Bad Request`	`manager` is not a JSON-boolean value `true` or `false`.
`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 on the authorisation server.
`500 Internal Server Error`	Unexpected API error.
`503 Service Unavailable`	Internal server integration failure.

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.

Assign or remove the department manager role through manager.

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 flag	`active` also controls synchronisation of the linked user account on the authorisation server.
Sending `manager` as the string `"true"` or `"false"`	Send `true` or `false` as a JSON boolean.
Sending `idCompany` or `hrEmail`	Do not send these values; the API determines 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 user account on the authorisation server 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.

What does manager = true do?

The server adds the department manager role and guarantees active account access, even if active = false is sent at the same time.

What does manager = false do?

The server removes only the department manager role unless active is also sent as false.