Departments

Full CRUD on departments. Members, approvers and budget owners are nested user objects when you read and plain user ids when you write; every id must be an active member of the company.

A key sees every department of the company: the per-user narrowing the in-app endpoint applies is not mirrored here.

Operations

Reads need master-data:read, writes master-data:write.

• GET/api/v2/{companyId}/departments/: Paginated by name, with members, approvers and budget owners nested as user objects.
• POST/api/v2/{companyId}/departments/: name is required. Every user id must be an active member of the company, and legalEntity must belong to it.
• GET/api/v2/{companyId}/departments/{id}/: One department. Soft-deleted rows are returned here too.
• PUT/api/v2/{companyId}/departments/{id}/: Replaces the writable fields; a user list you omit is cleared.
• PATCH/api/v2/{companyId}/departments/{id}/: Changes only the fields you send. The response is the read shape either way, with users nested.
• DELETE/api/v2/{companyId}/departments/{id}/: Soft delete; the row stays retrievable by id.
• POST/api/v2/{companyId}/bulk-upsert/departments/: Bulk upsert, up to 50 rows, matched by id then name. Relations (members, approvers, budget owners, legal entity) must belong to this company. Shared rules under Bulk upserts in the Introduction.