Update Department
Admin-only endpoint to update department details.
Request
Headers
| Name | Type | Required | Description |
|---|---|---|---|
| Authorization | string | Yes | Bearer token |
| Content-Type | string | Yes | application/json |
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| departmentId | string | Yes | Department ID to update |
Request Body
Request Body Schema
| Field | Type | Required | Description |
|---|---|---|---|
| name | string | No | New department name |
| description | string | No | New department description |
| parentId | string | No | New parent department ID |
Field Details
- name: Must be unique if changed
- description: Update the department description
- parentId: Can be changed to reorganize hierarchy
- parentId: Use
nullto make it a root-level department
Response
200 OK - Successfully updated department
400 Bad Request
401 Unauthorized
404 Not Found
500 Internal Server Error
Examples
Update department name and description
Move department to new parent
Make department root-level
Notes
- This is an admin-only endpoint - requires administrative privileges
- Department ID must be a valid MongoDB ObjectId
- Department names must remain unique after update
- Cannot set a department as its own parent (prevents circular references)
- Cannot set a child department as parent (prevents circular hierarchy)
- Moving a department also moves all its sub-departments
- The
updatedAttimestamp is automatically updated - Users assigned to the department are not affected by name changes
Hierarchy Considerations
- Moving Departments: All child departments move with the parent
- Circular Prevention: System prevents creating circular references
- Parent Validation: New parent must exist (unless setting to null)
- Depth Limits: Consider reasonable hierarchy depth limits
Impact on Users
- User department assignments remain valid
- Department-based permissions are preserved
- User profiles will show updated department names
- No disruption to user access or functionality
Best Practices
- Plan Changes: Consider impact on hierarchy before updating
- Communicate: Notify users of department name changes
- Test: Test hierarchy changes in non-production first
- Backup: Document current structure before major changes
- Review: Regularly review department structure for optimization
Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Path Parameters
Department ID to update
"64ef3c29f9a1c27e1b2c3a4d"
Body
Department name (leave empty string "" if unchanged)
"Engineering"
Department description (leave empty string "" if unchanged)
"Handles all software engineering operations"
Department code (leave empty string "" if unchanged)
"ENG-001"
Department location (leave empty string "" if unchanged)
"San Francisco HQ"
Parent department ID. - Must be a valid MongoDB ObjectId of an existing department. - Can be null if this department has no parent. - Leave empty if unchanged.
"64ef3c29f9a1c27e1b2c3aaa"