Create Department

Creates a new department within a business customer's team structure. Departments allow business customers to organize authorized users (subProfiles) into logical groups for streamlined management and access control. Once created, authorized users can be assigned to the department.

Endpoint

POST /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 a business customer needs to organize their authorized users into departments (e.g., Finance, Operations, HR). Departments provide a way to group subProfiles and manage access levels collectively. This is relevant for businesses with multiple teams requiring differentiated access to banking features.

Request Body

The request body accepts one of two schemas:

Create Department Request (for new departments):

Update Department Request (to update an existing department via this endpoint):

{
  "name": "Finance",
  "description": "Handles all financial operations and reporting"
}

Response

200 OK

{
  "id": 42,
  "name": "Finance",
  "description": "Handles all financial operations and reporting",
  "creator": {
    "id": 7,
    "name": "Jane Smith"
  },
  "authorizedUserCount": 0
}

Error Codes

Common Mistakes

• Omitting the required name field — the request will fail with a 400 error.
• Exceeding the name character limit of 128 or description limit of 2048 characters.
• Using a personal customer token — departments are only available for business customers.
• Sending an expired Bearer token; tokens expire after 10 minutes and must be refreshed via POST /api/auth/refresh.

Related Endpoints

• GET /api/teams/departments — Retrieve a list of all departments for the business customer
• PUT /api/teams/departments/{departmentId} — Update an existing department
• DELETE /api/teams/departments/{departmentId} — Delete a department
• POST /api/teams/subprofiles — Create an authorized user (subProfile) to assign to a department

Example

curl -X POST https://api.banking.netevia.dev/api/teams/departments \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Finance",
    "description": "Handles all financial operations and reporting"
  }'