For AI agents: markdown of this page — /docs-content-en/entities/users/delete.md documentation index — /llms.txt

Deactivate employee

DELETE /v1/users/:id

Deactivates an employee — revokes access to the Bitrix24 account but keeps the entire record and its relations. The call sets the activity field to active: false, and all data and action history remain in Bitrix24. To restore access, call PATCH /v1/users/:id { active: true }. Requires Bitrix24 account administrator rights.

Parameters

Parameter Type Required Description
Parameterid (path) Typenumber Requiredyes DescriptionEmployee ID. List: GET /v1/users

Examples

curl — personal key

Terminal 
curl -X DELETE "https://vibecode.bitrix24.com/v1/users/1331" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

Terminal 
curl -X DELETE "https://vibecode.bitrix24.com/v1/users/1331" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/users/1331', {
  method: 'DELETE',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})

const { success, data } = await res.json()
if (success && data.deactivated) {
  console.log(`Employee ${data.id} deactivated`)
}

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/users/1331', {
  method: 'DELETE',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

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

Response fields

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on successful deactivation
Fielddata.id Typenumber DescriptionID of the deactivated employee
Fielddata.active Typeboolean DescriptionAlways false after deactivation
Fielddata.deactivated Typeboolean DescriptionAlways true — explicitly marks the operation as a deactivation
Fielddata.user Typeobject DescriptionFull employee record after deactivation. If the re-read of the record fails, the field is absent, but the deactivation is still completed

Response example

JSON 
{
  "success": true,
  "data": {
    "id": 1331,
    "active": false,
    "deactivated": true,
    "user": {
      "id": 1331,
      "name": "John",
      "lastName": "Brown",
      "email": "john.brown@example.com",
      "active": false,
      "workPosition": "Manager",
      "departmentId": [1],
      "userType": "employee"
    }
  }
}

Error response example

403 — the key owner has no Bitrix24 account administrator rights:

JSON 
{
  "success": false,
  "error": {
    "code": "UPDATE_FAILED",
    "message": "Bitrix24 rejected user.update for deactivation (result: false)",
    "hint": "Bitrix24 returns false when the calling user lacks portal admin rights, or when the target user id does not exist. Verify the webhook/OAuth identity is a portal admin."
  }
}

Errors

HTTP Code Description
HTTP400 CodeINVALID_ID Description:id is not a positive integer
HTTP401 CodeTOKEN_MISSING DescriptionThe API key has no configured tokens
HTTP403 CodeSCOPE_DENIED DescriptionThe API key lacks the user scope
HTTP403 CodeUPDATE_FAILED DescriptionBitrix24 returned result: false: the key owner has no Bitrix24 account administrator rights, or no employee with this ID exists

Full list of common API errors — Errors.

Known specifics

Relations remain. After deactivation the employee is still listed as a deal owner, comment author, and chat participant. The email stays taken — you cannot reuse it when creating a new employee without first reactivating the existing one: PATCH /v1/users/:id { active: true }.

Re-reading the record after deactivation. Vibecode tries to fetch the current record after a successful deactivation and puts it into data.user. If the helper call fails, the field is absent, but the deactivation itself has already been performed and confirmed. A follow-up GET /v1/users/:id returns the record with active: false.

See also