#Delete a department

DELETE /v1/departments/:id

Deletes a department by ID. Deletion is not blocked by child departments or assigned employees: Bitrix24 deletes the department and automatically re-parents its direct child departments onto the deleted department's parent, reassigning their sort (their own subtrees move up together with them). To control the resulting structure, move the child departments and employees manually before deleting.

#Parameters

#Examples

#curl — personal key

curl -X DELETE "https://vibecode.bitrix24.com/v1/departments/189" \
  -H "X-Api-Key: YOUR_API_KEY"

#curl — OAuth application

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

#JavaScript — personal key

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

if (res.status === 204) {
  console.log('Department deleted')
}

#JavaScript — OAuth application

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

if (res.status === 204) {
  console.log('Deleted')
}

#Response

On successful deletion, HTTP status 204 No Content is returned with an empty body — success is confirmed by the status.

#Response example

HTTP/1.1 204 No Content

#Error response example

404 — department not found:

{
  "success": false,
  "error": {
    "code": "ENTITY_NOT_FOUND",
    "message": "Department not found"
  }
}

#Errors

Full list of common API errors — Errors.

#Known specifics

Deleting a department with children is not forbidden and silently rebuilds the tree. When you DELETE a department that has child departments, Bitrix24 deletes it (204) and re-parents the direct child departments onto the deleted department's parent, reassigning their sort; their own subtrees move up together with them. Assigned employees also do not prevent deletion. To control the resulting structure, before deleting move the child departments via PATCH /v1/departments/:id (a new parentId) and reassign employees via PATCH /v1/users/:id with a new departmentId (array of department IDs).

#See also

• List departments — view child departments before deletion
• Update a department — moving child departments
• Employees — reassigning employees
• Batch — bulk deletion