Rename a Department

This endpoint allows an authorized user (typically an Owner or a Partner) to rename an existing department and optionally update its description. Departments are organizational entities used to group sub-users within a business, helping to define internal access boundaries and role groupings. Department names can reflect functional units as teams evolve and reorganize.

Endpoint

PUT /api/teams/departments

Authentication

Bearer token required. Obtain via:

POST https://api.banking.netevia.dev/api/auth/v2

Include in header: Authorization: Bearer {token}
Token lifetime: 10 minutes. Refresh via POST /api/auth/refresh.

When to use

Use this endpoint when reorganizing internal team structures and needing to update a department's name or description to reflect new functional groupings. For example, renaming "Support Team" to "Customer Success" or updating a department description to clarify its purpose. Departments are exclusively used for sub-user management and are not exposed to end customers.

Request Body

{
  "departmentId": 42,
  "name": "Customer Success",
  "description": "Handles post-sale customer support and onboarding for all business accounts."
}

Response

200 OK

{
  "id": 42,
  "name": "Customer Success",
  "description": "Handles post-sale customer support and onboarding for all business accounts.",
  "creator": {
    "id": 7,
    "name": "Jane Smith"
  },
  "authorizedUserCount": 5
}

Error Codes

Common Mistakes

• Omitting departmentId — this field is required to identify which department to rename; without it the request will be rejected with a 400 error.
• Providing a name that exceeds 128 characters — the schema enforces a maximum length of 128 characters for the department name.
• Sending a description that exceeds 2048 characters — the description field has a maximum length of 2048 characters.
• Calling this endpoint as a sub-user without Owner or Partner privileges — only Owners and Partners are authorized to rename departments.

Related Endpoints

• POST /api/teams/departments — Create a new department
• GET /api/teams/departments — List all departments for the business
• DELETE /api/teams/departments/{departmentId} — Delete a department

Example

curl -X PUT https://api.banking.netevia.dev/api/teams/departments \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "departmentId": 42,
    "name": "Customer Success",
    "description": "Handles post-sale customer support and onboarding for all business accounts."
  }'