Update email and fields (hr:write; changing the email needs identity:admin)
PATCH /api/hr/v1/employees/{id}
Module: HR · operationId: updateEmployee · Tag: Employees · Auth: access token (Authorization: Bearer <accessToken>)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id |
path | string (uuid) | yes |
Request body
application/json (required)
version(integer, required): Version of the employee the change is based oncustomFields(object): Keys to change;nullclears a valueemail(string (email)): New e-mail address (needs identity:admin)
Example:
{
"customFields": {
"cost_center": null,
"phone": "+49 941 123450-27",
"position": "Service Desk Agentin (2nd Level)"
},
"version": 6
}
Responses
- 200 Saved (
application/json) - 400 Error (
application/json) - 409 Error (
application/json)
Fields of the 200 answer:
addressId(string, read-only): Person address of the employee in masterdata (roles customer and supplier), kept by HRaddressUnmatched(boolean, read-only): The masterdata address was deleted by the operator's microtech address import and the employee is not matched to a new one yet (addressId is empty; HR does not create one by itself). Omitted when false.createdAt(string (date-time)): When the employee was createdcreatedBy(string): Who created the employee (e-mail of the caller)customFields(object): Values of the tenant-defined fields by field key; restricted fields only with hr:writedisplayName(string): Name built from the tenant's display fields (falls back to the e-mail)email(string): E-mail address; the sign-in identitygroupIds(array of string): Ids of the groups the employee belongs toid(string): Id of the employeeinvitationSent(boolean): Only on create: whether the invitation mail was sentlastLoginAt(string (date-time)): Last sign-inroleIds(array of string): Ids of the directly assigned rolesstatus(string): disabled employees cannot sign in (one ofactive,disabled)tenantColor(string): Only on getMe: the active tenant's colour (a portal tenant colour name such as blue), for the identity stripe of the app; omitted when masterdata does not answerupdatedAt(string (date-time)): When the employee was last changedupdatedBy(string): Who last changed the employee (e-mail of the caller)version(integer): Version for optimistic locking: send the version you read with a change (stale: 409 version_conflict)
Example 200 answer:
{
"addressId": "7e9a1c3e-5b7d-4f9a-8c1e-3b5d7f9a1c20",
"addressUnmatched": false,
"createdAt": "2023-10-12T09:14:00Z",
"createdBy": "clara.becker@muster-it.example",
"customFields": {
"department": "service",
"employment_type": "vollzeit",
"entry_date": "2023-11-02",
"first_name": "Sophie",
"last_name": "Huber",
"personnel_number": "1017",
"phone": "+49 941 123450-17",
"position": "Service Desk Agentin"
},
"displayName": "Sophie Huber",
"email": "sophie.huber@muster-it.example",
"groupIds": [
"21a3c5e7-9b1d-4d3f-8a5c-7e9b1d3f5a91"
],
"id": "e5a1c3d7-2b4f-4c6e-8a0b-1d3f5b7c9e02",
"lastLoginAt": "2026-11-19T07:28:41Z",
"roleIds": [
"13e5a7c9-1d3f-4a5c-9e7a-9b1d3f5a7c82"
],
"status": "active",
"updatedAt": "2026-09-01T08:02:00Z",
"updatedBy": "clara.becker@muster-it.example",
"version": 6
}
Example request
curl -X PATCH 'https://api.mbcom.cloud/api/hr/v1/employees/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
--data '{"customFields":{"cost_center":null,"phone":"+49 941 123450-27","position":"Service Desk Agentin (2nd Level)"},"version":6}'