> ## Documentation Index > Fetch the complete documentation index at: https://developer.findity.com/llms.txt > Use this file to discover all available pages before exploring further. # Update department > Updates a department. This is a partial update: only the properties present in the body are changed. Setting `parentId` moves the department, together with its sub-departments, under another department; null or an empty `parentId` moves it back to top level under the organization's root department. The organization's root department can be renamed and given a `vatType`, but not moved. Returns 403 when the organization does not exist or the authenticated user is not an administrator of it. Returns 404 when the department does not exist or belongs to a different organization, or when `parentId` is cleared and the organization has no valid root department configured. ## OpenAPI ````yaml /openapi/findity-admin-api.json put /organizations/{organizationId}/departments/{departmentId} openapi: 3.1.0 info: title: Findity Admin API description: Findity Admin API version: 1.0.0 servers: - url: https://stage-api.findity.com/api/v1/admin - url: https://api.findity.com/api/v1/admin security: - bearerAuth: [] paths: /organizations/{organizationId}/departments/{departmentId}: put: tags: - Departments summary: Update department description: > Updates a department. This is a partial update: only the properties present in the body are changed. Setting `parentId` moves the department, together with its sub-departments, under another department; null or an empty `parentId` moves it back to top level under the organization's root department. The organization's root department can be renamed and given a `vatType`, but not moved. Returns 403 when the organization does not exist or the authenticated user is not an administrator of it. Returns 404 when the department does not exist or belongs to a different organization, or when `parentId` is cleared and the organization has no valid root department configured. operationId: adminUpdateDepartment parameters: - name: organizationId in: path required: true description: > String. The organization's internal ID (32-character hex string) or its `externalSourceId`. When the value matches the format of an internal ID, the internal ID takes precedence. schema: type: string example: 11adfe2a080040e3892ffb89c21ec44e - name: departmentId in: path required: true description: > String. The ID of the department to update, as returned in the `id` field of the response. Lookup by `externalSourceId` is not supported for departments, unlike `organizationId`. schema: type: string example: 9360d03ad7294220868d67f42a2a144d requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AdminApiDepartmentPutRequest' example: name: Marketing & Communications parentId: b41d20cf417a4c41a273588bac7c1ffc responses: '200': description: OK — returns the updated department content: application/json: schema: $ref: '#/components/schemas/AdminApiDepartment' example: id: 9360d03ad7294220868d67f42a2a144d externalSourceId: SAP-4711 name: Marketing & Communications parentId: b41d20cf417a4c41a273588bac7c1ffc vatType: USE_CATEGORY customDimensionPresetValues: - id: a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4 dimensionDefinitionId: VAT25 presetListValueId: VAT25 presetListValueText: 25% presetStringValue: null level: 2 '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/400Error' examples: Invalid JSON body: value: result: error code: INVALID_JSON_BODY description: Could not parse JSON content. No known properties: value: result: error code: NO_KNOWN_JSON_PROPERTIES description: No known, or only read-only properties received Name cleared: value: result: error code: INVALID_JSON_PROPERTY_VALUE description: name is required Invalid vatType: value: result: error code: INVALID_JSON_PROPERTY_VALUE description: 'Invalid vatType: STANDARD' Name too long: value: result: error code: FIELD_EXCEEDS_MAX_LENGTH description: name exceeds maximum length of 255 characters. Parent department not found: value: result: error code: INVALID_PARENT_ID description: Parent department not found. Parent is the department itself or a descendant: value: result: error code: DEPARTMENT_PARENT_CYCLE description: >- Cannot set parent to this department or one of its own descendants. Moving the root department: value: result: error code: CANNOT_MOVE_ROOT_DEPARTMENT description: >- Cannot change the parent of the organization's root department. '403': description: Forbidden — organization not found or access denied content: application/json: schema: $ref: '#/components/schemas/403Error' examples: Organization not found or access denied: value: result: error description: Organization not found or access denied '404': description: >- Not found — department does not exist, or `parentId` cleared and the organization has no valid root department content: application/json: schema: $ref: '#/components/schemas/404Error' examples: Department not found: value: result: error code: DEPARTMENT_NOT_FOUND description: Department not found No valid root department: value: result: error code: DEPARTMENT_NOT_FOUND description: Department not found components: schemas: AdminApiDepartmentPutRequest: type: object description: > Partial update: only the properties present in the body are changed, the rest are left unchanged. Any other property, such as `id`, `level` or `customDimensionPresetValues` from a GET response, is ignored, so a department returned by GET can be modified and sent back as is. All properties are optional. required: [] properties: name: type: string description: > Optional. String, maximum 255 characters. Display name of the department. When present, it must be non-empty and not whitespace-only. Leading and trailing whitespace is trimmed. maxLength: 255 externalSourceId: type: - string - 'null' description: > Optional. String or null, maximum 255 characters. External source identifier, for example the department's ID in an integrated system. Leading and trailing whitespace is trimmed. Null or an empty value clears it. maxLength: 255 parentId: type: - string - 'null' description: > Optional. String or null. The `id` of the department to move this one under. It must be a department in the same organization, and not this department or one of its descendants. The department's sub-departments move with it, and `vatType` is left unchanged by a move. Null or an empty value moves the department back to top level, directly under the organization's root department. The organization's root department cannot be moved: a non-empty value on it is rejected, while null or an empty value is ignored. vatType: type: - string - 'null' description: > Optional. String or null, one of `USE_CATEGORY`, `NON_DEDUCTABLE_VAT` or `DEDUCTABLE_VAT`. VAT deduction handling for this department, case-sensitive. Applies to this department only: it is not inherited from the parent or passed on to sub-departments. Null or an empty value resets it to `USE_CATEGORY`. enum: - USE_CATEGORY - NON_DEDUCTABLE_VAT - DEDUCTABLE_VAT - null AdminApiDepartment: type: object required: - id - externalSourceId - name - parentId - vatType - customDimensionPresetValues - level properties: id: type: string description: Unique identifier of the department. externalSourceId: type: - string - 'null' description: >- External source identifier of the department, if set by an integration. Null when not set. name: type: string description: Display name of the department. parentId: type: - string - 'null' description: > The `id` of the parent department. Null only for the organization's own root unit (level 0). Every other department, including a top-level one directly under the root, has this set to its parent's id. vatType: type: string description: >- VAT deduction handling for this department. Defaults to `USE_CATEGORY` when not explicitly set. enum: - USE_CATEGORY - NON_DEDUCTABLE_VAT - DEDUCTABLE_VAT customDimensionPresetValues: type: array description: > Preset custom dimension values configured for this department, in the order they were created. The order is stable, so identical requests return the values in the same order. Excludes values belonging to deleted dimension definitions. items: $ref: '#/components/schemas/AdminApiCustomDimensionPresetValue' level: type: integer description: > Depth of the department within the organization's unit hierarchy. The organization's implicit root unit is level 0; a genuine top-level department is level 1. 400Error: type: object properties: result: type: string code: type: string description: type: string 403Error: type: object properties: result: type: string code: type: string description: type: string example: result: error description: Not allowed 404Error: type: object properties: result: type: string code: type: string description: type: string example: result: error code: ORGANIZATION_NOT_FOUND description: 'Failed to get organization for id: {orgId}' AdminApiCustomDimensionPresetValue: type: object required: - id - dimensionDefinitionId properties: id: type: string description: Unique identifier of the preset value. dimensionDefinitionId: type: string description: >- The ID of the custom dimension definition this preset value belongs to. presetListValueId: type: - string - 'null' description: >- The ID of the selected list value, when the dimension uses a list of values. Null when a free-text preset is used instead. presetListValueText: type: - string - 'null' description: >- Display text of the selected list value. Null when a free-text preset is used instead. presetStringValue: type: - string - 'null' description: >- Free-text preset value, when the dimension does not use a list of values. Null when a list value is used instead. securitySchemes: bearerAuth: type: http scheme: bearer ````