Organization Tree

const options = {
  method: 'GET',
  headers: {'x-api-key': '<x-api-key>', 'x-organization-id': '<x-organization-id>'}
};

fetch('https://api.dcycle.io/v2/organizations/tree', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.dcycle.io/v2/organizations/tree"

headers = {
    "x-api-key": "<x-api-key>",
    "x-organization-id": "<x-organization-id>"
}

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

print(response.text)

{
  "id": "<string>",
  "name": "<string>",
  "children": {
    "id": "<string>",
    "name": "<string>",
    "children": {}
  }
}

GET

organizations

tree

Organization Tree

const options = {
  method: 'GET',
  headers: {'x-api-key': '<x-api-key>', 'x-organization-id': '<x-organization-id>'}
};

fetch('https://api.dcycle.io/v2/organizations/tree', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.dcycle.io/v2/organizations/tree"

headers = {
    "x-api-key": "<x-api-key>",
    "x-organization-id": "<x-organization-id>"
}

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

print(response.text)

{
  "id": "<string>",
  "name": "<string>",
  "children": {
    "id": "<string>",
    "name": "<string>",
    "children": {}
  }
}

Organization Tree

Retrieve the complete hierarchical structure of your organization, starting from the top-level parent (holding) down to all subsidiaries and child organizations. The tree always starts from the root organization, regardless of which organization is specified in the x-organization-id header. This means you can use the API key from any organization in the tree and always get the full hierarchy.

Request

Headers

string

required

Your API key for authenticationExample: sk_live_1234567890abcdef

string

required

Your organization UUID. Can be any organization in the tree - the response always starts from the root.Example: dce3ff33-9fcc-4521-910f-7972d81fb70c

Response

string

Organization UUID (root/holding organization)

string

Organization name

array[object]

Child organizations (recursive structure - each child has the same shape)

Show Organization Node

string

Organization UUID

string

Organization name

array[object]

Nested child organizations (same recursive structure)

Example

curl -X GET "https://api.dcycle.io/v2/organizations/tree" \
  -H "x-api-key: ${DCYCLE_API_KEY}" \
  -H "x-organization-id: ${DCYCLE_ORG_ID}"

import requests
import os

api_key = os.getenv("DCYCLE_API_KEY")
org_id = os.getenv("DCYCLE_ORG_ID")

headers = {
    "x-api-key": api_key,
    "x-organization-id": org_id
}

response = requests.get(
    "https://api.dcycle.io/v2/organizations/tree",
    headers=headers
)

tree = response.json()
print(f"Root: {tree['name']} ({tree['id']})")
for child in tree["children"]:
    print(f"  - {child['name']} ({child['id']})")
    for grandchild in child.get("children", []):
        print(f"      - {grandchild['name']}")

const axios = require('axios');

const apiKey = process.env.DCYCLE_API_KEY;
const orgId = process.env.DCYCLE_ORG_ID;

const headers = {
  'x-api-key': apiKey,
  'x-organization-id': orgId
};

axios.get(
  'https://api.dcycle.io/v2/organizations/tree',
  { headers }
)
.then(response => {
  const tree = response.data;
  console.log(`Root: ${tree.name} (${tree.id})`);
  tree.children.forEach(child => {
    console.log(`  - ${child.name} (${child.id})`);
    child.children.forEach(grandchild => {
      console.log(`      - ${grandchild.name}`);
    });
  });
})
.catch(error => console.error(error));

Successful Response

{
  "id": "dce3ff33-9fcc-4521-910f-7972d81fb70c",
  "name": "Acme Holdings",
  "children": [
    {
      "id": "d9e08b1a-bd28-4950-a730-3c300a2ff91e",
      "name": "Acme Construction",
      "children": [
        {
          "id": "22dcadf6-2da8-4077-a555-7da22c3c5eae",
          "name": "Project Alpha - Office Building",
          "children": []
        },
        {
          "id": "dbcd29bd-b55d-4007-a16e-25924597580e",
          "name": "Project Beta - Highway Extension",
          "children": []
        }
      ]
    },
    {
      "id": "e3d4c82b-1a8c-429c-aaea-1f82b6bd7fe4",
      "name": "Acme Restoration",
      "children": [
        {
          "id": "d3cc0278-f383-4912-8fb6-a6b127ed30e3",
          "name": "Historic Building Renovation",
          "children": []
        }
      ]
    },
    {
      "id": "132c18ba-6e5c-4cbc-a5e1-fb71b75e9012",
      "name": "Acme Industrial",
      "children": []
    },
    {
      "id": "eaa14ae8-73c2-4a42-9731-296fca49b7c4",
      "name": "Acme Integrated Services",
      "children": []
    }
  ]
}

Common Errors

401 Unauthorized

Cause: Missing or invalid API key

{
  "detail": "Invalid API key",
  "code": "INVALID_API_KEY"
}

Solution: Verify your API key is valid and active. Get a new one from Settings > API.

404 Not Found

Cause: Organization not found

{
  "code": "ORGANIZATION_NOT_FOUND",
  "detail": "Organization with id=UUID('...') not found"
}

Solution: Verify that the x-organization-id header contains a valid organization UUID.

Use Cases

List All Subsidiaries (Flat)

Flatten the tree to get a simple list of all organizations:

def flatten_tree(node, depth=0):
    """Recursively flatten the organization tree."""
    orgs = [{"id": node["id"], "name": node["name"], "depth": depth}]
    for child in node.get("children", []):
        orgs.extend(flatten_tree(child, depth + 1))
    return orgs

response = requests.get(
    "https://api.dcycle.io/v2/organizations/tree",
    headers=headers
)

all_orgs = flatten_tree(response.json())
for org in all_orgs:
    indent = "  " * org["depth"]
    print(f"{indent}{org['name']} ({org['id']})")

Count Organizations by Level

Analyze the depth of the organizational structure:

from collections import Counter

def count_by_level(node, level=0, counter=None):
    """Count organizations at each level of the tree."""
    if counter is None:
        counter = Counter()
    counter[level] += 1
    for child in node.get("children", []):
        count_by_level(child, level + 1, counter)
    return counter

tree = response.json()
levels = count_by_level(tree)
for level, count in sorted(levels.items()):
    label = "Holding" if level == 0 else f"Level {level}"
    print(f"{label}: {count} organizations")

Export Organization IDs

Extract all organization IDs for use with other API endpoints:

def get_all_org_ids(node):
    """Extract all organization IDs from the tree."""
    ids = [node["id"]]
    for child in node.get("children", []):
        ids.extend(get_all_org_ids(child))
    return ids

tree = response.json()
org_ids = get_all_org_ids(tree)
print(f"Total organizations: {len(org_ids)}")

# Use IDs with other endpoints (e.g., get vehicles for each org)
for org_id in org_ids:
    vehicles = requests.get(
        "https://api.dcycle.io/v2/vehicles",
        headers={**headers, "x-organization-id": org_id}
    ).json()
    print(f"Org {org_id}: {vehicles['total']} vehicles")

Organizations Overview

Learn about the Organizations API

Authentication

Set up API authentication

​Organization Tree

​Request

​Headers

​Response

​Example

​Successful Response

​Common Errors

​401 Unauthorized

​404 Not Found

​Use Cases

​List All Subsidiaries (Flat)

​Count Organizations by Level

​Export Organization IDs

​Related Endpoints

Organizations Overview

Authentication

Organization Tree

Request

Headers

Response

Example

Successful Response

Common Errors

401 Unauthorized

404 Not Found

Use Cases

List All Subsidiaries (Flat)

Count Organizations by Level

Export Organization IDs

Related Endpoints