Delete a department
Department Management
Delete Department
Admin-only endpoint to delete a department by its ID. Returns the deleted department’s basic details if successful.
DELETE
Delete a department
Admin-only endpoint to delete a department by its ID. Returns the deleted department’s basic details if successful.
Request
Headers
| Name | Type | Required | Description |
|---|---|---|---|
| Authorization | string | Yes | Bearer token |
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| departmentId | string | Yes | Department ID to delete |
Response
200 OK - Successfully deleted department
400 Bad Request
401 Unauthorized
500 Internal Server Error
Example
Notes
- This is an admin-only endpoint - requires administrative privileges
- Department ID must be a valid MongoDB ObjectId
- Deletion is permanent - cannot be undone
- Department must be empty (no assigned users) to be deleted
- All sub-departments must be deleted first
- The response includes the deleted department’s details
deletedAttimestamp is added to track when deletion occurred
Prerequisites for Deletion
Before deleting a department, ensure:- No Active Users: All users must be reassigned to other departments
- No Sub-departments: All child departments must be deleted first
- No Dependencies: No active workflows depend on this department
Deletion Workflow
- Check Users: Verify no users are assigned to the department
- Handle Sub-departments: Delete or move all child departments
- Reassign Users: Move any remaining users to other departments
- Delete Department: Call this endpoint to remove the department
Error Scenarios
Department has users
Department has sub-departments
Impact Analysis
Before Deletion
- Check user assignments
- Verify sub-department status
- Review dependent systems
After Deletion
- Department is permanently removed
- Historical data may reference deleted department
- Users cannot be assigned to deleted department
Best Practices
- Backup Data: Export department data before deletion
- User Communication: Notify affected users of changes
- Gradual Process: Use deprecation before deletion when possible
- Audit Trail: Document deletion reasons and approvals
- Testing: Test deletion process in non-production environment
Safety Considerations
- Irreversible Action: Confirm before proceeding
- Data Integrity: Ensure no broken references
- User Impact: Minimize disruption to users
- Compliance: Follow organizational deletion policies
Alternative Approaches
Instead of deletion, consider:- Archiving: Mark department as inactive
- Renaming: Repurpose for new use
- Merging: Combine with another department
Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Path Parameters
Unique identifier of the department to delete