List departments tree

Returns the organization’s full department hierarchy as a tree. data always holds a single element, the organization’s root department (level 0), and every department reachable from the root is nested under its parent through children. Departments not connected to the root (for example, with no parent) are not included, although they can still be retrieved with Get department. Siblings are sorted by name ascending (case-sensitive and not locale-aware, so uppercase letters sort before lowercase and accented letters after z), with id ascending as a tie-breaker. The whole tree is always returned in one response, so this endpoint does not take sort, max or offset, and ignores them if they are sent. Splitting the tree into pages would give the client an incomplete hierarchy, and since data always holds a single root there is nothing to page across. Sibling order is fixed as described above. meta.total and meta.count are therefore always 1. Returns 403 when the organization does not exist or the authenticated user is not an administrator of it. Returns 404 when the organization has no valid root department configured.

GET

organizations

{organizationId}

departments

tree

List departments tree

curl --request GET \
  --url https://stage-api.findity.com/api/v1/admin/organizations/{organizationId}/departments/tree \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://stage-api.findity.com/api/v1/admin/organizations/{organizationId}/departments/tree"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://stage-api.findity.com/api/v1/admin/organizations/{organizationId}/departments/tree', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://stage-api.findity.com/api/v1/admin/organizations/{organizationId}/departments/tree",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://stage-api.findity.com/api/v1/admin/organizations/{organizationId}/departments/tree"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://stage-api.findity.com/api/v1/admin/organizations/{organizationId}/departments/tree")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "meta": {
    "count": 1,
    "total": 1
  },
  "data": [
    {
      "id": "63b7a7802a644e8ca296c9796ffa7074",
      "externalSourceId": null,
      "name": "Acme AB",
      "parentId": null,
      "vatType": "USE_CATEGORY",
      "customDimensionPresetValues": [],
      "level": 0,
      "children": [
        {
          "id": "b41d20cf417a4c41a273588bac7c1ffc",
          "externalSourceId": "DEV-01",
          "name": "Development",
          "parentId": "63b7a7802a644e8ca296c9796ffa7074",
          "vatType": "USE_CATEGORY",
          "customDimensionPresetValues": [
            {
              "id": "4f1c2b7e9a8d4c3b8e6f5a4d3c2b1a09",
              "dimensionDefinitionId": "d2e3f4a5b6c74d8e9f0a1b2c3d4e5f60",
              "presetListValueId": "a1b2c3d4e5f64a7b8c9d0e1f2a3b4c5d",
              "presetListValueText": "Project Phoenix",
              "presetStringValue": null
            }
          ],
          "level": 1,
          "children": [
            {
              "id": "9360d03ad7294220868d67f42a2a144d",
              "externalSourceId": null,
              "name": "Payments",
              "parentId": "b41d20cf417a4c41a273588bac7c1ffc",
              "vatType": "DEDUCTABLE_VAT",
              "customDimensionPresetValues": [],
              "level": 2,
              "children": []
            }
          ]
        },
        {
          "id": "e7f8a9b0c1d24e3f8a9b0c1d2e3f4a5b",
          "externalSourceId": null,
          "name": "Sales",
          "parentId": "63b7a7802a644e8ca296c9796ffa7074",
          "vatType": "NON_DEDUCTABLE_VAT",
          "customDimensionPresetValues": [],
          "level": 1,
          "children": []
        }
      ]
    }
  ]
}

{
  "result": "error",
  "description": "Organization not found or access denied"
}

{
  "result": "error",
  "code": "DEPARTMENT_NOT_FOUND",
  "description": "Department not found"
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

organizationId

string

required

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.

Example:

"11adfe2a080040e3892ffb89c21ec44e"

Response

meta

object

required

Hide child attributes

meta.count

integer

required

Number of top-level entries in data. Always 1, since the tree has a single root.

meta.total

integer

required

Total number of top-level entries. Always 1, since the tree has a single root.

data

object[]

required

Always contains exactly one element: the organization's root department (level 0), with every department reachable from it nested under it through children. Departments not connected to the root are not included.

Hide child attributes

data.id

string

required

Unique identifier of the department.

data.externalSourceId

string | null

required

External source identifier of the department, if set by an integration. Null when not set.

data.name

string

required

Display name of the department.

data.parentId

string | null

required

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.

data.vatType

enum<string>

required

VAT deduction handling for this department. Defaults to USE_CATEGORY when not explicitly set.

Available options:

USE_CATEGORY,

NON_DEDUCTABLE_VAT,

DEDUCTABLE_VAT

data.customDimensionPresetValues

object[]

required

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.

Hide child attributes

data.customDimensionPresetValues.id

string

required

Unique identifier of the preset value.

data.customDimensionPresetValues.dimensionDefinitionId

string

required

The ID of the custom dimension definition this preset value belongs to.

data.customDimensionPresetValues.presetListValueId

string | null

The ID of the selected list value, when the dimension uses a list of values. Null when a free-text preset is used instead.

data.customDimensionPresetValues.presetListValueText

string | null

Display text of the selected list value. Null when a free-text preset is used instead.

data.customDimensionPresetValues.presetStringValue

string | null

Free-text preset value, when the dimension does not use a list of values. Null when a list value is used instead.

data.level

integer

required

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.

data.children

object[]

required

The departments directly under this one. Each element has the same shape as this object — every AdminApiDepartment field plus its own children — recursively, down to departments with no sub-departments, whose children is an empty array. Sorted by name ascending (case-sensitive and not locale-aware, so uppercase letters sort before lowercase and accented letters after z), with id ascending as a tie-breaker.

⌘I

List departments tree

curl --request GET \
  --url https://stage-api.findity.com/api/v1/admin/organizations/{organizationId}/departments/tree \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://stage-api.findity.com/api/v1/admin/organizations/{organizationId}/departments/tree"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://stage-api.findity.com/api/v1/admin/organizations/{organizationId}/departments/tree', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://stage-api.findity.com/api/v1/admin/organizations/{organizationId}/departments/tree",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://stage-api.findity.com/api/v1/admin/organizations/{organizationId}/departments/tree"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://stage-api.findity.com/api/v1/admin/organizations/{organizationId}/departments/tree")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "meta": {
    "count": 1,
    "total": 1
  },
  "data": [
    {
      "id": "63b7a7802a644e8ca296c9796ffa7074",
      "externalSourceId": null,
      "name": "Acme AB",
      "parentId": null,
      "vatType": "USE_CATEGORY",
      "customDimensionPresetValues": [],
      "level": 0,
      "children": [
        {
          "id": "b41d20cf417a4c41a273588bac7c1ffc",
          "externalSourceId": "DEV-01",
          "name": "Development",
          "parentId": "63b7a7802a644e8ca296c9796ffa7074",
          "vatType": "USE_CATEGORY",
          "customDimensionPresetValues": [
            {
              "id": "4f1c2b7e9a8d4c3b8e6f5a4d3c2b1a09",
              "dimensionDefinitionId": "d2e3f4a5b6c74d8e9f0a1b2c3d4e5f60",
              "presetListValueId": "a1b2c3d4e5f64a7b8c9d0e1f2a3b4c5d",
              "presetListValueText": "Project Phoenix",
              "presetStringValue": null
            }
          ],
          "level": 1,
          "children": [
            {
              "id": "9360d03ad7294220868d67f42a2a144d",
              "externalSourceId": null,
              "name": "Payments",
              "parentId": "b41d20cf417a4c41a273588bac7c1ffc",
              "vatType": "DEDUCTABLE_VAT",
              "customDimensionPresetValues": [],
              "level": 2,
              "children": []
            }
          ]
        },
        {
          "id": "e7f8a9b0c1d24e3f8a9b0c1d2e3f4a5b",
          "externalSourceId": null,
          "name": "Sales",
          "parentId": "63b7a7802a644e8ca296c9796ffa7074",
          "vatType": "NON_DEDUCTABLE_VAT",
          "customDimensionPresetValues": [],
          "level": 1,
          "children": []
        }
      ]
    }
  ]
}

{
  "result": "error",
  "description": "Organization not found or access denied"
}

{
  "result": "error",
  "code": "DEPARTMENT_NOT_FOUND",
  "description": "Department not found"
}

Authentication

Findity Expense API

Findity Admin API

Findity Admin API V0

Findity Connect API

List departments tree

Authorizations

Path Parameters

Response