Create a new department
Department Management
Create Department
Admin-only endpoint to create a new department.
POST
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
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
400 Bad Request
401 Unauthorized
500 Internal Server Error
Examples
Create a root-level department
Create a sub-department
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
- Planning: Map out your department hierarchy before creation
- Naming: Use clear, descriptive names
- Descriptions: Provide meaningful descriptions for clarity
- Hierarchy: Keep hierarchy levels reasonable (recommended: max 5 levels)
- 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
Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Body
application/json
Department name
Example:
"Engineering"
Department description
Example:
"Handles all software engineering operations"
Department code
Example:
"ENG-001"
Department location
Example:
"San Francisco HQ"
Parent department info
Example:
"68c87b38e0c86b191d1b3c5b"