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 endpoint maps to updating the activity field (active: false); all data and action history remain in Bitrix24. To restore access — PATCH /v1/users/:id { active: true }. Requires Bitrix24 account administrator rights.

Parameters

Parameter Type Req. Description
id (path) number yes Employee ID

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
success boolean Always true on successful deactivation
data.id number ID of the deactivated employee
data.active boolean Always false after deactivation
data.deactivated boolean Always true — an explicit marker of the operation semantics
data.user object Full employee record after deactivation (best-effort: if the re-read of the record did not succeed, the field may be absent — the deactivation is still done)

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
400 INVALID_ID :id is not a positive integer
401 TOKEN_MISSING The API key has no configured tokens
403 SCOPE_DENIED The API key lacks the user scope
403 UPDATE_FAILED Bitrix24 returned result: false. Most often — no Bitrix24 account administrator rights; less often — 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 }.

Best-effort re-read of the record. 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 is already done and confirmed. A repeated GET /v1/users/:id will load the record with active: false.

See also