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

# Create Department

> Admin-only endpoint to create a new department.

Admin-only endpoint to create a new department.

## Request

### Headers

| Name          | Type   | Required | Description      |
| ------------- | ------ | -------- | ---------------- |
| Authorization | string | Yes      | Bearer token     |
| Content-Type  | string | Yes      | application/json |

### Request Body

```json theme={null}
{
  "name": "Quality Assurance",
  "description": "Ensures product quality and testing standards",
  "parentId": "64b7f2b3e4b0a5d3f9c54321"
}
```

### Request Body Schema

| Field       | Type   | Required | Description                                |
| ----------- | ------ | -------- | ------------------------------------------ |
| name        | string | Yes      | Department name                            |
| description | string | No       | Department description                     |
| parentId    | string | No       | Parent department ID (for sub-departments) |

#### Field Details

* **name**: Must be unique within the organization
* **description**: Optional but recommended for clarity
* **parentId**: Optional - omit for root-level department

## Response

### 200 OK - Successfully created department

```json theme={null}
{
  "message": "Department created successfully",
  "data": {
    "department": {
      "_id": "64b7f7g8h9i0j1k2l3m4n5o",
      "name": "Quality Assurance",
      "description": "Ensures product quality and testing standards",
      "parentId": "64b7f2b3e4b0a5d3f9c54321",
      "createdAt": "2024-01-15T10:30:00.000Z",
      "updatedAt": "2024-01-15T10:30: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"
  }
}
```

### 500 Internal Server Error

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

## Examples

### Create a root-level department

```bash theme={null}
curl -X POST 'http://localhost:2000/department/new' \
  -H 'Authorization: Bearer your-jwt-token' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Marketing",
    "description": "Marketing and promotional activities"
  }'
```

### Create a sub-department

```bash theme={null}
curl -X POST 'http://localhost:2000/department/new' \
  -H 'Authorization: Bearer your-jwt-token' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Digital Marketing",
    "description": "Online marketing and social media",
    "parentId": "64b7f7g8h9i0j1k2l3m4n5o"
  }'
```

## Notes

* This is an admin-only endpoint - requires administrative privileges
* Department names must be unique across the entire organization
* Parent department ID must be a valid MongoDB ObjectId
* Creating a sub-department requires the parent to exist
* The created department is returned in the response
* Timestamps are automatically generated (createdAt, updatedAt)
* Department names are case-sensitive
* Consider the organizational structure before creating departments

## Best Practices

1. **Planning**: Map out your department hierarchy before creation
2. **Naming**: Use clear, descriptive names
3. **Descriptions**: Provide meaningful descriptions for clarity
4. **Hierarchy**: Keep hierarchy levels reasonable (recommended: max 5 levels)
5. **Review**: Review department structure periodically

## Common Use Cases

* Creating new functional departments (e.g., "Data Science")
* Adding regional offices as departments
* Setting up project-based departments
* Restructuring organizational units


## OpenAPI

````yaml POST /department/new
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/new:
    post:
      tags:
        - Departments
      summary: Create a new department
      description: Admin-only endpoint to create a new department.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewDepartment'
              type: object
      responses:
        '200':
          description: Successfully created department
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  data:
                    type: object
                    properties:
                      department:
                        $ref: '#/components/schemas/Department'
        '400':
          description: Validation error / bad request
        '401':
          description: Unauthorized (missing/invalid token or insufficient permissions)
        '500':
          description: Server error
      security:
        - bearerAuth: []
components:
  schemas:
    NewDepartment:
      type: object
      required:
        - name
        - description
        - code
        - location
      properties:
        name:
          type: string
          description: Department name
          example: Engineering
        description:
          type: string
          description: Department description
          example: Handles all software engineering operations
        code:
          type: string
          description: Department code
          example: ENG-001
        location:
          type: string
          description: Department location
          example: San Francisco HQ
        parentDepartment:
          type: string
          nullable: true
          description: Parent department info
          example: 68c87b38e0c86b191d1b3c5b
    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

````