Skip to main content
Setting up your company’s organizational structure correctly is essential for accurate carbon footprint calculations. Dcycle’s Company Diagram feature allows you to create and manage complex corporate structures with parent-child relationships between organizations.

​
Understanding the Company Diagram

The Company Diagram is a visual canvas where you can map your entire corporate structure. It enables you to:
  • Visualize organizational hierarchy: See how your holding company, subsidiaries, and investees relate to each other
  • Manage parent-child relationships: Define which organizations own or control other organizations
  • Configure data consolidation: Control how emissions data flows up from child organizations to parent organizations
  • Set ownership percentages: Define the share of emissions to attribute based on equity stake or operational control
                    ┌─────────────────┐
                    │  Holding Corp   │ ← Matrix Organization (Parent)
                    │   (100% share)  │
                    └────────┬────────┘
                             │
            ┌────────────────┼────────────────┐
            │                │                │
   ┌────────┴────────┐ ┌─────┴─────┐ ┌────────┴────────┐
   │  Subsidiary A   │ │ Subsidiary│ │   Investee Co   │
   │ (100% - Scope   │ │     B     │ │ (25% - Scope    │
   │    1, 2, 3)     │ │   (75%)   │ │    1, 2 only)   │
   └─────────────────┘ └───────────┘ └─────────────────┘
Data Consolidation ImpactWhen you define a parent-child relationship, the parent organization’s carbon footprint will include emissions from child organizations based on:
  • Share percentage: The ownership or control stake (e.g., 75% ownership = 75% of child’s emissions)
  • Investment scopes: Which emission scopes to consolidate (Scope 1+2 or Scope 1+2+3)
This follows GHG Protocol consolidation approaches: equity share or operational/financial control.

​
Step 1.1: Create the Matrix Organization

The matrix organization is your top-level parent company (holding). This is the entity that will consolidate emissions from all subsidiaries and investees. 
import requests
import os

headers = {
    "Authorization": f"Bearer {os.getenv('DCYCLE_API_KEY')}",
    "Content-Type": "application/json"
}

# Create the holding/parent organization
organization_data = {
    "company_name": "Holding Corporation",
    "country": "ES",
    "sector": "Holdings",
    "vat": "A12345678",
    "employee_count_signup": 50,
    "is_group_fund": False  # Set to True for investment funds
}

response = requests.post(
    "https://api.dcycle.io/api/v1/organizations",
    headers=headers,
    json=organization_data
)

parent_org = response.json()
parent_org_id = parent_org['id']
print(f"✅ Matrix organization created: {parent_org_id}")
print(f"   Name: {parent_org['company_name']}")

​
Step 1.2: Create a Child Organization via the Link/Parent Flow

For most corporate carbon footprint use cases, the recommended way to add investees is through the link/parent flow. In a single API call, the parent organization:
  • Creates the child organization
  • Creates the matrix relation between parent and child
  • Configures Share %, Scopes and Tag
  • Marks the relation as accepted, so it is immediately used in consolidation
  • Mirrors the structure in the Company Diagram and Investees sections in the app
import requests
import os

headers = {
    "Authorization": f"Bearer {os.getenv('DCYCLE_API_KEY')}",
    "Content-Type": "application/json",
    "x-organization-id": os.getenv("DCYCLE_PARENT_ORG_ID"),  # Parent organization (matrix)
}

body = {
    "company_name": "Subsidiary A",
    "country": "ES",
    "sector": "Manufacturing",
    "employee_count_signup": 200,
    "vat": "B87654321",
    "user_id": os.getenv("DCYCLE_CHILD_ADMIN_USER_ID"),  # Admin user for the child org
    "share": 0.75,                  # 75% ownership
    "investment_scopes": [1, 2, 3], # Consolidate Scope 1, 2 and 3
    "tag": "subsidiary",
}

response = requests.post(
    "https://api.dcycle.io/api/v1/matrices/link/parent",
    headers=headers,
    json=body,
)

child_link = response.json()
print(f"✅ Child organization created: {child_link['company_name']}")
print(f"   Child ID: {child_link['id']}")
print(f"   Parent ID: {child_link['parent_id']}")
print(f"   Status: {child_link['status']}")
The share, investment_scopes, tag and status fields you see in the Investees section are stored in this matrix relationship. The next section explains how each of these fields affects consolidation.

​
Configuring Investees: Share %, Scopes, Tag and Status

When you call the matrices/link/parent endpoint (or update an existing link), you configure the matrix relationship that controls how emissions are consolidated from child to parent organizations.

​
Configuration Options

FieldDescriptionValues
Share %Ownership or control percentage0.01 to 1.0 (e.g., 0.75 = 75%)
ScopesWhich emission scopes to consolidate[1, 2] or [1, 2, 3]
TagLabel for categorizationAny string (e.g., “subsidiary”, “joint-venture”)
StatusRelationship statuspending, accepted, rejected
What it means: The percentage of the child organization’s emissions attributed to the parent.Examples:
  • 1.0 (100%): Fully consolidated subsidiary
  • 0.75 (75%): 75% ownership stake
  • 0.25 (25%): Minority investment
GHG Protocol approach: Use equity share (based on ownership %) or operational/financial control (100% if you have control, 0% if not).
What it means: Which scopes of the child’s emissions to include in consolidation.Options:
  • [1, 2]: Consolidate only Scope 1 and Scope 2 emissions
  • [1, 2, 3]: Consolidate Scope 1, 2, and 3 emissions (full value chain)
When to use each:
  • Use [1, 2] for financial investments where you don’t influence supply chain decisions
  • Use [1, 2, 3] for subsidiaries where you have operational control over the full value chain
What it means: A label to categorize the relationship for reporting and filtering.Common tags:
  • subsidiary - Fully owned subsidiary
  • joint-venture - Shared ownership/control
  • associate - Significant influence but not control
  • investment - Financial investment only
What it means: The approval status of the parent-child relationship.Values:
  • pending: Relationship awaiting confirmation
  • accepted: Active, confirmed relationship
  • rejected: Relationship was declined
Only accepted relationships are included in emissions consolidation.

​
Update Share and Scopes via API

import requests
import os

headers = {
    "Authorization": f"Bearer {os.getenv('DCYCLE_API_KEY')}",
    "Content-Type": "application/json",
    "x-organization-id": os.getenv("DCYCLE_PARENT_ORG_ID"),
}

update_body = {
    "child_org_id": child_link["id"],
    "parent_org_id": child_link["parent_id"],
    "share": 0.6,              # Adjust ownership to 60%
    "investment_scopes": [1, 2],  # Consolidate only Scope 1 and 2
    "status": "accepted",
    "tag": "joint-venture",
}

response = requests.patch(
    "https://api.dcycle.io/api/v1/matrices",
    headers=headers,
    json=update_body,
)

updated_matrix = response.json()
print(f"✅ Updated share: {updated_matrix['share']}")
print(f"   Scopes: {updated_matrix['investment_scopes']}")
print(f"   Status: {updated_matrix['status']}")
Status Must Be “Accepted”Only relationships with status: "accepted" will have their emissions consolidated into the parent organization’s carbon footprint. Pending or rejected relationships are excluded from calculations.
Using the Dcycle App?Managing investees is much easier through our web interface:
  1. Navigate to Company → Investees
  2. Click Add organization to start the link/parent flow
  3. Set Share %, Scopes, Tag, and Status
  4. Review the structure visually in the Company Diagram canvas