Update employee

PATCH /v1/users/:id

Updates fields of an existing employee. Pass only the fields being changed. Requires Bitrix24 account administrator rights on the Bitrix24 side — without them the call is rejected.

Request fields (body)

Full field list — Employee fields. User (UF_*) fields are accepted.

Profile photo

personalPhoto is the one employee field that reads and writes differently: on READ it comes back as the photo URL, on WRITE it takes the file itself — an array of exactly two non-empty strings: the file name and its base64 content.

{ "personalPhoto": ["avatar.png", "iVBORw0KGgoAAAANSUhEUg..."] }

The shape works on PATCH /v1/users/:id and POST /v1/users. The response is the ordinary update response; to confirm the photo actually changed, re-read the employee and compare the URL: Bitrix24 stores files by content, so uploading the same image again leaves the URL as it was.

What is refused, and why it matters:

• the nested {"personalPhoto": {"fileData": [...]}} — refused with 400 INVALID_PARAMS. Bitrix24 answers it with success and CLEARS the avatar, so letting it through would trade one silent failure for another;
• a value Bitrix24 cannot read as file content on UPDATE — an empty string {"personalPhoto": ""}, a whitespace-only string, the literal "false", the booleans true and false, the number 0, a string with fewer than two base64-alphabet characters ("0", "!!!", "==="), an inline pair whose content is one of those (["avatar.png", "="]), and any other structure whose second value is missing, null or unreadable — the nested {"fileData": [...]}, an empty array, a one-element array, an explicit null or a structure in the content element. The portal takes each of them as a command to remove the photo, so all of them are refused as INVALID_PARAMS before the Bitrix24 call on the single PATCH and both batch surfaces. To keep the current photo, omit the field. The single PATCH returns 400 INVALID_PARAMS; batch routes keep their own error envelopes described under Request and data;
• batch routes (POST /v1/users/batch, POST /v1/batch) refuse the photo: a batch sub-call travels as a query string — the base64 is encoded twice — and batch routes stay on the global body cap while single-route writes are raised to 40 MiB. Past the sub-call length limit the value would be truncated, and a truncated write still answers success. Send the photo as a single call;
• unusable content or extension (.svg, .php, corrupted base64) is refused by the portal itself — 422 with an "invalid file type" message, and the photo stays untouched.

The new refusal applies only to UPDATE. On POST /v1/users, an empty string does not get the new refusal: a newly created employee has no previous photo to lose. The single POST /v1/users and PATCH /v1/users/:id routes still accept the inline pair. The POST /v1/users/invite wrapper validates the same pair separately and retains its own PERSONAL_PHOTO_INVALID code for an invalid photo.

Writing this field removes the photo on no surface, and null is not a way to do it either: the single PATCH and the per-entity batch accept it and simply ignore it, while the global POST /v1/batch refuses it with INVALID_PARAMS, because its encoder would turn null into the same remove-the-photo command. One separate command removes the photo — DELETE /v1/users/:id/personal-photo, and it is irreversible.

Examples

curl — personal key

curl -X PATCH "https://vibecode.bitrix24.com/v1/users/29" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "workPosition": "Senior manager",
    "departmentId": [1, 47]
  }'

curl — OAuth application

curl -X PATCH "https://vibecode.bitrix24.com/v1/users/29" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "workPosition": "Senior manager",
    "departmentId": [1, 47]
  }'

JavaScript — personal key

const res = await fetch('https://vibecode.bitrix24.com/v1/users/29', {
  method: 'PATCH',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    workPosition: 'Senior manager',
    departmentId: [1, 47],
  }),
})

const { success, data } = await res.json()

JavaScript — OAuth application

const res = await fetch('https://vibecode.bitrix24.com/v1/users/29', {
  method: 'PATCH',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    workPosition: 'Senior manager',
    departmentId: [1, 47],
  }),
})

const { success, data } = await res.json()

Response fields

Response example

{
  "success": true,
  "data": {
    "id": 29,
    "name": "John",
    "lastName": "Brown",
    "email": "john.brown@example.com",
    "active": true,
    "workPosition": "Senior manager",
    "departmentId": [1, 47],
    "userType": "employee"
  }
}

Error response example

403 — update rejected by Bitrix24:

{
  "success": false,
  "error": {
    "code": "UPDATE_FAILED",
    "message": "Bitrix24 rejected user.update (result: false)",
    "hint": "Bitrix24 returns false when the calling user lacks portal admin rights, when a read-only field was touched (isOnline, lastLogin, dateRegister, isAdmin), or when the target user ID does not exist. Verify the webhook/OAuth identity is a portal admin."
  }
}

Errors

Full list of common API errors — Errors.

Known specifics

Changing email. If the new email is already taken by another employee in the Bitrix24 account, Bitrix24 returns BITRIX_ERROR: wrong_email. Before PATCH — check via GET /v1/users?filter[EMAIL]=new@example.com.

See also

• Get employee
• Employee fields
• Deactivate employee
• Batch
• Limits and optimization