> ## Documentation Index
> Fetch the complete documentation index at: https://compass.docs.sunnyscoach.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Update Department

> Admin-only endpoint to update department details.

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

```json theme={null}
{
  "name": "Customer Success",
  "description": "Dedicated to ensuring customer satisfaction and retention",
  "parentId": "64b7f2b3e4b0a5d3f9c54321"
}
```

### 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 `null` to make it a root-level department

## Response

### 200 OK - Successfully updated department

```json theme={null}
{
  "message": "Successfully updated Engineering department",
  "data": {
    "department": {
      "_id": "64b7f2b3e4b0a5d3f9c54321",
      "name": "Customer Success",
      "description": "Dedicated to ensuring customer satisfaction and retention",
      "parentId": "64b7f2b3e4b0a5d3f9c54321",
      "createdAt": "2024-01-15T10:30:00.000Z",
      "updatedAt": "2024-01-16T14:25:00.000Z"
    }
  }
}
```

### 400 Bad Request

```json theme={null}
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Department name already exists"
  }
}
```

### 401 Unauthorized

```json theme={null}
{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Missing or invalid token or insufficient permissions"
  }
}
```

### 404 Not Found

```json theme={null}
{
  "error": {
    "code": "DEPARTMENT_NOT_FOUND",
    "message": "Department not found"
  }
}
```

### 500 Internal Server Error

```json theme={null}
{
  "error": {
    "code": "SERVER_ERROR",
    "message": "Internal server error"
  }
}
```

## Examples

### Update department name and description

```bash theme={null}
curl -X PUT 'http://localhost:2000/department/update/64b7f2b3e4b0a5d3f9c54321' \
  -H 'Authorization: Bearer your-jwt-token' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Customer Success",
    "description": "Dedicated to ensuring customer satisfaction and retention"
  }'
```

### Move department to new parent

```bash theme={null}
curl -X PUT 'http://localhost:2000/department/update/64b7f3c4e4b0a5d3f9c98765' \
  -H 'Authorization: Bearer your-jwt-token' \
  -H 'Content-Type: application/json' \
  -d '{
    "parentId": "64b7f7g8h9i0j1k2l3m4n5o"
  }'
```

### Make department root-level

```bash theme={null}
curl -X PUT 'http://localhost:2000/department/update/64b7f3c4e4b0a5d3f9c98765' \
  -H 'Authorization: Bearer your-jwt-token' \
  -H 'Content-Type: application/json' \
  -d '{
    "parentId": null
  }'
```

## 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


## OpenAPI

````yaml PUT /department/update/{departmentId}
openapi: 3.0.3
info:
  title: COMPASS API
  version: 1.0.0
  description: OpenAPI specification for the Compass backend routes.
servers:
  - url: http://localhost:2000
    description: Local development server
security: []
tags:
  - name: Auth
    description: >-
      Authentication and session management endpoints (OAuth and session
      validation)
  - name: Users
    description: Operations for managing user records
  - name: Departments
    description: Operations for managing departments
  - name: Email Meter
    description: APIs to get Email Meter Stats
  - name: HubSpot Tickets
    description: Feedback APIs
  - name: Permissions
    description: Permissions APIs
  - name: Transcription
    description: Transcription APIs
paths:
  /department/update/{departmentId}:
    put:
      tags:
        - Departments
      summary: Update an existing department
      description: Admin-only endpoint to update department details.
      parameters:
        - in: path
          name: departmentId
          required: true
          schema:
            type: string
            description: Department ID to update
            example: 64ef3c29f9a1c27e1b2c3a4d
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateDepartment'
      responses:
        '200':
          description: Successfully updated department
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Successfully updated Engineering department
                  data:
                    type: object
                    properties:
                      department:
                        $ref: '#/components/schemas/Department'
        '400':
          description: Validation error / bad request
        '401':
          description: Unauthorized (missing/invalid token or insufficient permissions)
        '404':
          description: Department not found
        '500':
          description: Server error
      security:
        - bearerAuth: []
components:
  schemas:
    UpdateDepartment:
      type: object
      properties:
        name:
          type: string
          description: Department name (leave empty string `""` if unchanged)
          example: Engineering
        description:
          type: string
          description: Department description (leave empty string `""` if unchanged)
          example: Handles all software engineering operations
        code:
          type: string
          description: Department code (leave empty string `""` if unchanged)
          example: ENG-001
        location:
          type: string
          description: Department location (leave empty string `""` if unchanged)
          example: San Francisco HQ
        parentDepartment:
          type: string
          nullable: true
          description: >
            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
    Department:
      type: object
      properties:
        _id:
          type: string
          example: 64ef3c29f9a1c27e1b2c3a4d
        name:
          type: string
          example: Engineering
        parentDepartment:
          type: object
          description: Parent department info (if applicable)
          example:
            _id: 64ef3c29f9a1c27e1b2c3aaa
            name: Technology
            description: Some description for this department
            code: TECH
        manager:
          $ref: '#/components/schemas/MatchSuggestionUser'
          type: object
          description: Manager info attached to department
        description:
          type: string
          example: Handles all software engineering operations
    MatchSuggestionUser:
      type: object
      properties:
        _id:
          type: string
          example: 64ef3c29f9a1c27e1b2c3a4d
        emails:
          type: array
          items:
            type: string
          example:
            - user@example.com
        personalInformation:
          type: object
          properties:
            firstName:
              type: string
              example: John
            lastName:
              type: string
              example: Doe
            name:
              type: string
              example: John Doe
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

````