Skip to main content
POST
Create a new department
Admin-only endpoint to create a new department.

Request

Headers

Request Body

Request Body Schema

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

  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

Authorizations

Authorization
string
header
required

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

Body

application/json
name
string
required

Department name

Example:

"Engineering"

description
string
required

Department description

Example:

"Handles all software engineering operations"

code
string
required

Department code

Example:

"ENG-001"

location
string
required

Department location

Example:

"San Francisco HQ"

parentDepartment
string | null

Parent department info

Example:

"68c87b38e0c86b191d1b3c5b"

Response

Successfully created department

message
string
data
object