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:- Make sure the organization has a root department. Every other department hangs under it.
- Create departments, parents before children.
- Change them as your organization chart changes: rename a department, change its VAT handling, move it (with everything below it) under another department.
- Delete the departments that no longer exist.
- A department is addressed by its Findity
id, always. Unlike an organization, it can’t be addressed by itsexternalSourceIdin a path or asparentId. Read theidfrom the response when you create the department, or from the department tree. PUTis 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
- Complete Authentication and obtain an admin-scoped access token. The authenticated user must be an administrator of the organization.
- Have the organization’s
idorexternalSourceIdready. See Organizations. The organization needs anexternalSourceIdfor the call in Step 1 that creates the root department. - The organization needs a root department. The department endpoints can’t create it, and an organization created with
POST /organizationsdoesn’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
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
Step 2 — Create departments
Create each department with aPOST 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
This creates the Marketing department directly under the root:
cURL
201 Created)
JSON
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
201 Created)
JSON
parentId to the parent’s id. This creates Payments under Development, using the id from the response above:
cURL
201 Created)
JSON
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
200 OK)
JSON
dataalways holds one element, the root, andmeta.totalandmeta.countare always1. Every other department is nested under its parent inchildren, and a department without sub-departments has an emptychildrenarray.- The endpoint takes no
sort,maxoroffsetand ignores them if you send them, because a partial tree would be an incomplete hierarchy. - Siblings come back sorted by
name, ascending, and byidwhen the names are equal. The sort is case-sensitive and not locale-aware: uppercase letters come before lowercase, and accented letters afterz. - 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 aPUT 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 asid, 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
200 OK)
JSON
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
SetparentId 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
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
parentIdreturns400 INVALID_PARENT_ID. - The root department can’t be moved. A
parentIdwith a value on the root returns400 CANNOT_MOVE_ROOT_DEPARTMENT, and anullor emptyparentIdon 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
204 No Content)
The response has no body.
Repeating the request returns 404 DEPARTMENT_NOT_FOUND, because the department is gone.
Get a department
Read one department by itsid.
GET /organizations/{organizationId}/departments/{departmentId}
cURL
200 OK)
JSON
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 haslevel 0.
GET /organizations/{organizationId}/departments/root
cURL
200 OK)
JSON
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’sid 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 onexternalSourceId.
- Make sure the organization has a root department (Step 1). Do this once per organization.
- Call
GET /organizations/{organizationId}/departments/tree, and build a map fromexternalSourceIdtoidof every department that has one. - Walk your ERP’s units from the top, parents before children. For a unit that isn’t in the map, call
POST /organizations/{organizationId}/departmentswith itsexternalSourceIdand the parent’sidasparentId, and add theidfrom the response to the map. TheexternalSourceIdmakes a rerun of a half-finished sync safe: the units that were already created answer400 DEPARTMENT_EXTERNAL_SOURCE_ID_ALREADY_EXISTSinstead of being created again. - For a unit that is in the map, compare
name,vatTypeandparentIdwith the tree and sendPUT /organizations/{organizationId}/departments/{departmentId}with only the properties that differ. - For a department that has an
externalSourceIdfrom your system but is no longer in your ERP, move its users to another department, then callDELETE. Every user in the list of users (GET /organizations/{organizationId}/users) has adepartmentwith the department’sid: see Users. Delete the topmost removed department only: its sub-departments go with it.
Error handling
Errors use a JSON envelope. Match oncode: the description of some errors comes in the language of the authenticated user, and requestId identifies the request.
JSON

