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

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"
}

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