Skip to main content

Organizations API

The Organizations API allows you to retrieve your organization’s hierarchical structure. For holding companies with subsidiaries, this provides a complete tree view of all child organizations and their relationships.
New API: This endpoint is part of the new API architecture with improved design and maintainability.

Key Features

  • Organization Tree: View the complete hierarchical structure from the top-level holding down to all subsidiaries and child organizations
  • Automatic Root Detection: Always returns the full tree from the root organization, regardless of which organization the API key belongs to
  • Clean & Simple: Minimal response with just the essential fields (id, name, children)

Authentication

All endpoints require authentication using either:
  • API Key: Include in x-api-key header
  • JWT Token: Include in Authorization header as Bearer {JWT_TOKEN}

Headers

All requests must include:
x-api-key
string
required
Your API key for authenticationExample: sk_live_1234567890abcdef
x-organization-id
string
required
Your organization UUIDExample: a8315ef3-dd50-43f8-b7ce-d839e68d51fa

Available Endpoints

Organization Tree

View the complete organizational hierarchy

Data Model

Organization Tree Node

Each node in the tree represents an organization:
{
  "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",
          "children": []
        }
      ]
    },
    {
      "id": "e3d4c82b-1a8c-429c-aaea-1f82b6bd7fe4",
      "name": "Acme Services",
      "children": []
    }
  ]
}

Node Attributes

FieldTypeDescription
idUUIDUnique identifier for the organization
namestringOrganization name
childrenarrayList of child organization nodes (same structure, recursive)

Use Cases

View Holding Structure

Retrieve the full organization tree for a holding company:
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"Holding: {tree['name']}")
for subsidiary in tree["children"]:
    print(f"  - {subsidiary['name']} ({len(subsidiary['children'])} children)")

Find Specific Subsidiaries

Navigate the tree to find specific child organizations:
def find_org(node, name_contains):
    """Recursively search the tree for an organization by name."""
    results = []
    if name_contains.lower() in node["name"].lower():
        results.append(node)
    for child in node.get("children", []):
        results.extend(find_org(child, name_contains))
    return results

tree = response.json()
matches = find_org(tree, "construction")
for org in matches:
    print(f"Found: {org['name']} ({org['id']})")

Error Handling

Common HTTP Status Codes

StatusMeaningSolution
200Success-
401UnauthorizedVerify API key
404Not FoundCheck organization UUID
500Server ErrorContact support if persists

Error Response Format

{
  "detail": "Error description",
  "code": "ERROR_CODE"
}

Authentication Guide

Learn how to authenticate API requests

Vehicles API

Manage vehicles within organizations

Employees API

Manage employee commuting data

Invoices API

Manage invoices for organizations

Rate Limiting

API requests are subject to rate limiting. Include rate limit information from response headers:
  • X-RateLimit-Limit: Maximum requests per minute
  • X-RateLimit-Remaining: Requests remaining
  • X-RateLimit-Reset: Unix timestamp when limit resets