Skip to main content
PUT
Update an existing department
Admin-only endpoint to update department details.

Request

Headers

Path Parameters

Request Body

Request Body Schema

Field Details

  • name: Must be unique if changed
  • description: Update the department description
  • parentId: Can be changed to reorganize hierarchy
  • parentId: Use null to 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 updatedAt timestamp 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

  1. Plan Changes: Consider impact on hierarchy before updating
  2. Communicate: Notify users of department name changes
  3. Test: Test hierarchy changes in non-production first
  4. Backup: Document current structure before major changes
  5. Review: Regularly review department structure for optimization

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

departmentId
string
required

Department ID to update

Example:

"64ef3c29f9a1c27e1b2c3a4d"

Body

application/json
name
string

Department name (leave empty string "" if unchanged)

Example:

"Engineering"

description
string

Department description (leave empty string "" if unchanged)

Example:

"Handles all software engineering operations"

code
string

Department code (leave empty string "" if unchanged)

Example:

"ENG-001"

location
string

Department location (leave empty string "" if unchanged)

Example:

"San Francisco HQ"

parentDepartment
string | null

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.

Example:

"64ef3c29f9a1c27e1b2c3aaa"

Response

Successfully updated department

message
string
Example:

"Successfully updated Engineering department"

data
object