Skip to main content

Create Department

POST /clients/{client_id}/departments

Creates a new department within a client organization.

Path Parameters​

ParameterTypeDescription
client_idstring (uuid)Unique identifier for the client organization

Request Body​

FieldTypeRequiredDescription
namestringYesDepartment display name. Must be unique within the client.
descriptionstringNoOptional department description.

Response​

Returns the created Department object with status 201 Created.

Example Requests​

Create with name and description​

curl -X POST "https://api.example.com/v2/clients/aa7cf840-9ca9-46a3-9778-9015d6580d50/departments" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Engineering",
    "description": "Software development and infrastructure teams"
  }'

Create with name only​

curl -X POST "https://api.example.com/v2/clients/aa7cf840-9ca9-46a3-9778-9015d6580d50/departments" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sales"
  }'

Example Response​

{
  "id": "d1a2b3c4-e5f6-7890-abcd-ef1234567890",
  "name": "Engineering",
  "description": "Software development and infrastructure teams",
  "member_count": 0,
  "created_at": "2026-02-24T10:00:00.000Z",
  "updated_at": "2026-02-24T10:00:00.000Z"
}

member_count is 0 on a newly created department.

Error Responses​

StatusDescription
400Invalid request body (e.g. missing or empty name)
401Authentication required
403Insufficient permissions for this client
404Client not found
409A department with this name already exists in this client
500Server error

400 -- missing name​

{
  "error": {
    "code": "invalid_request",
    "message": "Department name is required",
    "details": {
      "field": "name"
    }
  }
}

409 -- name conflict​

{
  "error": {
    "code": "conflict",
    "message": "A department with this name already exists",
    "details": {
      "name": "Engineering"
    }
  }
}