Skip to main content
Build and maintain the department structure of an organization through the Findity Admin API. This guide walks through setting up the departments of an organization from your own system: making sure the organization has a root department, creating departments under it, reading the structure back, and then renaming, moving and deleting departments as your organization chart changes. It comes after Organizations and before Users, which places each user in a department.

Overview

A department is a unit in the organization’s hierarchy: Marketing, Development, or Payments under Development. Every department sits under one parent, so the structure is a tree. At the top is the root department, which stands for the organization itself. A department’s lifecycle is:
  1. Make sure the organization has a root department. Every other department hangs under it.
  2. Create departments, parents before children.
  3. Change them as your organization chart changes: rename a department, change its VAT handling, move it (with everything below it) under another department.
  4. Delete the departments that no longer exist.
Four things shape every call in this guide:
  • A department is addressed by its Findity id, always. Unlike an organization, it can’t be addressed by its externalSourceId in a path or as parentId. Read the id from the response when you create the department, or from the department tree.
  • PUT is a partial update: it changes only the properties you send.
  • externalSourceId, when you set it, is unique within the organization.
  • Deleting a department deletes everything below it, and its users are left without a department.

Prerequisites

  1. Complete Authentication and obtain an admin-scoped access token. The authenticated user must be an administrator of the organization.
  2. Have the organization’s id or externalSourceId ready. See Organizations. The organization needs an externalSourceId for the call in Step 1 that creates the root department.
  3. The organization needs a root department. The department endpoints can’t create it, and an organization created with POST /organizations doesn’t have one yet. Step 1 checks for it and, if it’s missing, creates it with one call to a different endpoint.

Key concepts

API endpoints

All endpoints use the Admin API base URL. Examples in this guide use the stage host — switch to the production host (api.findity.com) only when you’re ready to go live.
{organizationId} is the organization’s internal id or its externalSourceId. There is no list endpoint. The department tree is the list of all departments of an organization, and it is returned in one response without pagination.

Required headers

The call in Step 1 that creates the root department also needs the header X-Findity-ApiVersion: 3.

Step 1 — Make sure the organization has a root department

Check for the root department first: every other department endpoint depends on it, and Step 2 can’t create a department without it. GET /organizations/{organizationId}/departments/root
cURL
An organization that has a root department answers 200 with the department (see Get the root department): continue with Step 2. An organization without one answers 404: Example response (status 404 Not Found)
JSON
Create the root department with the call below, then continue with Step 2.
Legacy endpoint — creating the root department. The department endpoints can’t create the root department, so use this call once, and only when the check above returned 404. It is on a separate host and needs the X-Findity-ApiVersion: 3 header.PUT /organizations/externalid/{externalId}/organizationalunits/ on https://stage-expense.findity.com/api/admin. {externalId} is the organization’s externalSourceId.
cURL
Example response (status 200 OK)
JSON
  • Send organizationExternalSourceId (the organization’s own externalSourceId), name and externalSourceId. Without organizationExternalSourceId the call returns 200, but the department it creates isn’t the organization’s root and the department endpoints still return 404. Without externalSourceId the root’s externalSourceId is stored as the text null.
  • Don’t send subUnits. Create the departments below the root with Step 2.
  • Make the call again only if the check returned 404: on an organization that has a root department it answers 200 and returns the existing departments in subUnits.

Step 2 — Create departments

Create each department with a POST and keep the id from the response. Create a parent before its children: a child names its parent by parentId, and parentId takes the parent’s id. POST /organizations/{organizationId}/departments

Request body

Without an externalSourceId, every POST creates a new department, even when one with the same name already exists under the same parent. A repeated request then leaves you with duplicates that nothing in the API tells apart except their id. With an externalSourceId, the repeated request returns 400 DEPARTMENT_EXTERNAL_SOURCE_ID_ALREADY_EXISTS and creates nothing.
This creates the Marketing department directly under the root:
cURL
Example response (status 201 Created)
JSON
The response is the created department. Its parentId is the root’s id, because a department without parentId is created directly under the root. Create Development the same way, with its own vatType:
cURL
Example response (status 201 Created)
JSON
To create a department below another one, set parentId to the parent’s id. This creates Payments under Development, using the id from the response above:
cURL
Example response (status 201 Created)
JSON
Payments has the default vatType, not Development’s. The parent must be a department of the same organization: an unknown parentId, or one that belongs to another organization, returns 400 INVALID_PARENT_ID.

Step 3 — Read the structure back

Read the whole hierarchy with one call. Use it to check what was created, and at the start of every sync to learn which departments already exist. GET /organizations/{organizationId}/departments/tree
cURL
Example response (status 200 OK)
JSON
  • data always holds one element, the root, and meta.total and meta.count are always 1. Every other department is nested under its parent in children, and a department without sub-departments has an empty children array.
  • The endpoint takes no sort, max or offset and ignores them if you send them, because a partial tree would be an incomplete hierarchy.
  • Siblings come back sorted by name, ascending, and by id when the names are equal. The sort is case-sensitive and not locale-aware: uppercase letters come before lowercase, and accented letters after z.
  • A department that isn’t connected to the root isn’t in the tree, but you can still read it with Get a department.

Step 4 — Update a department

Change a department with a PUT that holds only the properties you want to change. The rest of the department stays as it is. PUT /organizations/{organizationId}/departments/{departmentId}

Request body

All properties are optional. Properties other than the four below, such as id, level and customDimensionPresetValues, are ignored, so a department you read with GET can be changed and sent back as it is. This renames Marketing and changes its VAT handling. Its externalSourceId and its place in the hierarchy are left as they are:
cURL
Example response (status 200 OK)
JSON
The response is the updated department. Repeating the same PUT gives the same result, so it is safe to retry. A body with none of the four properties returns 400 NO_KNOWN_JSON_PROPERTIES. The root department can be renamed and given a vatType in the same way. Changing a department’s vatType doesn’t change its sub-departments’ vatType.

Step 5 — Move a department

Set parentId to the id of the new parent. The department moves together with all its sub-departments, and every level below it follows. Nothing else about the department changes, including its vatType. PUT /organizations/{organizationId}/departments/{departmentId} This moves Marketing and Communications under Development:
cURL
Example response (status 200 OK)
JSON
  • To move a department back to the top level, send "parentId": null (or an empty string). It then sits directly under the root.
  • A department can’t be moved under itself or under one of its own sub-departments: the call returns 400 DEPARTMENT_PARENT_CYCLE. To swap two departments that are nested, first move one of them to the top level, then place the other, then move the first.
  • An unknown parentId returns 400 INVALID_PARENT_ID.
  • The root department can’t be moved. A parentId with a value on the root returns 400 CANNOT_MOVE_ROOT_DEPARTMENT, and a null or empty parentId on the root is ignored.
  • Users stay in the department when it moves.

Step 6 — Delete a department

Delete a department that no longer exists in your organization chart. DELETE /organizations/{organizationId}/departments/{departmentId}
cURL
Example response (status 204 No Content) The response has no body.
Deleting is permanent and doesn’t stop at the department you name. It also deletes every sub-department below it. The approvers set on the deleted departments are deleted, and the users placed in any of them are left without a department (department is null), but they aren’t deleted. Move the users to other departments first. If the request fails, nothing is changed. The root department can’t be deleted (400 CANNOT_DELETE_ROOT_DEPARTMENT).
Repeating the request returns 404 DEPARTMENT_NOT_FOUND, because the department is gone.

Get a department

Read one department by its id. GET /organizations/{organizationId}/departments/{departmentId}
cURL
Example response (status 200 OK)
JSON
The departmentId is the department’s id. The externalSourceId isn’t accepted: it returns 404 DEPARTMENT_NOT_FOUND. The value root in the path always means the root department (see below), so a department can’t be read with an id of root.

Get the root department

Read the root department, which is the top of the tree and has level 0. GET /organizations/{organizationId}/departments/root
cURL
Example response (status 200 OK)
JSON
Use the root’s id when you need to place a department directly under it with an explicit parentId.

Place users in departments

A user belongs to one department. Set it on the user, with the department’s id or its externalSourceId, when you create or update the user: see Department assignment in the Users guide. Deleting a department clears the department of its users.

Common integration patterns

Sync the organization chart from your ERP. Keep the departments of an organization equal to the units in your ERP, matching on externalSourceId.
  1. Make sure the organization has a root department (Step 1). Do this once per organization.
  2. Call GET /organizations/{organizationId}/departments/tree, and build a map from externalSourceId to id of every department that has one.
  3. Walk your ERP’s units from the top, parents before children. For a unit that isn’t in the map, call POST /organizations/{organizationId}/departments with its externalSourceId and the parent’s id as parentId, and add the id from the response to the map. The externalSourceId makes a rerun of a half-finished sync safe: the units that were already created answer 400 DEPARTMENT_EXTERNAL_SOURCE_ID_ALREADY_EXISTS instead of being created again.
  4. For a unit that is in the map, compare name, vatType and parentId with the tree and send PUT /organizations/{organizationId}/departments/{departmentId} with only the properties that differ.
  5. For a department that has an externalSourceId from your system but is no longer in your ERP, move its users to another department, then call DELETE. Every user in the list of users (GET /organizations/{organizationId}/users) has a department with the department’s id: see Users. Delete the topmost removed department only: its sub-departments go with it.
The tree also holds departments that your integration didn’t create, such as the root department. Don’t delete a department only because it isn’t in your ERP: delete the ones that carry an externalSourceId from your system.

Error handling

Errors use a JSON envelope. Match on code: the description of some errors comes in the language of the authenticated user, and requestId identifies the request.
JSON

Next steps

Last modified on November 16, 2026