Manage a Department's Team

This endpoint allows authorized users (such as an Owner or a Partner) to manage the sub-users assigned to a department. You can add or remove sub-users from a specific department in a single request by providing their user IDs. Departments are internal organizational structures used exclusively for sub-user management and are not customer-facing.

Endpoint

POST /api/teams/departments/manage

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 you need to reorganize sub-users across departments — for example, onboarding new team members into a functional group such as Finance or Compliance, or offboarding users who have changed roles. It is designed for business accounts where departments help control access levels, permissions, and user groupings across multiple operational areas. Both add and remove operations can be performed in a single call, keeping department membership synchronized in real time.

Request Body

{
  "departmentId": 42,
  "addUserIds": [101, 102],
  "removeUserIds": [103]
}

Response

200 OK

{
  "id": 42,
  "name": "Risk Management",
  "description": "Handles risk assessment and compliance monitoring.",
  "creator": {
    "id": 7,
    "name": "Jane Smith"
  },
  "authorizedUserCount": 5
}

Error Codes

Common Mistakes

• Providing neither addUserIds nor removeUserIds — at least one must be present and non-empty to perform a meaningful update.
• Supplying a departmentId that does not exist or belongs to a different business account, resulting in a 404 error.
• Including a user ID in both addUserIds and removeUserIds in the same request, which produces conflicting instructions and may result in a 400 error.
• Using a token issued for a Personal customer account — departments and sub-user management are available for Business accounts only.

Related Endpoints

• POST /api/teams/departments — Create a new department within a business account
• GET /api/teams/departments — List all departments for the authenticated business
• DELETE /api/teams/departments/{departmentId} — Delete a department
• GET /api/teams/subprofiles — List sub-users (authorized users) available for department assignment

Example

curl -X POST https://api.banking.netevia.dev/api/teams/departments/manage \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "departmentId": 42,
    "addUserIds": [101, 102],
    "removeUserIds": [103]
  }'