Step 1 - Set Up Your Company Structure

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/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']}")

const axios = require('axios');

const headers = {
  'Authorization': `Bearer ${process.env.DCYCLE_API_KEY}`,
  'Content-Type': 'application/json'
};

// Create the holding/parent organization
const organizationData = {
  company_name: 'Holding Corporation',
  country: 'ES',
  sector: 'Holdings',
  vat: 'A12345678',
  employee_count_signup: 50,
  is_group_fund: false
};

const response = await axios.post(
  'https://api.dcycle.io/v1/organizations',
  organizationData,
  { headers }
);

const parentOrg = response.data;
const parentOrgId = parentOrg.id;
console.log(`✅ Matrix organization created: ${parentOrgId}`);
console.log(`   Name: ${parentOrg.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/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']}")

const axios = require('axios');

const headers = {
  Authorization: `Bearer ${process.env.DCYCLE_API_KEY}`,
  'Content-Type': 'application/json',
  'x-organization-id': process.env.DCYCLE_PARENT_ORG_ID, // Parent organization (matrix)
};

const body = {
  company_name: 'Subsidiary A',
  country: 'ES',
  sector: 'Manufacturing',
  employee_count_signup: 200,
  vat: 'B87654321',
  user_id: process.env.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',
};

const response = await axios.post(
  'https://api.dcycle.io/v1/matrices/link/parent',
  body,
  { headers },
);

const childLink = response.data;
console.log(`✅ Child organization created: ${childLink.company_name}`);
console.log(`   Child ID: ${childLink.id}`);
console.log(`   Parent ID: ${childLink.parent_id}`);
console.log(`   Status: ${childLink.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.

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

Field	Description	Values
Share %	Ownership or control percentage	0.01 to 1.0 (e.g., 0.75 = 75%)
Scopes	Which emission scopes to consolidate	`[1, 2]` or `[1, 2, 3]`
Tag	Label for categorization	Any string (e.g., “subsidiary”, “joint-venture”)
Status	Relationship status	`pending`, `accepted`, `rejected`

Investment Scopes

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

Tag

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

Status

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.

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/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:

Navigate to Company → Investees
Click Add organization to start the link/parent flow
Set Share %, Scopes, Tag, and Status
Review the structure visually in the Company Diagram canvas

Calculate Emissions

ISO 14064

GHG Protocol

GLEC v3.0 Framework

Use Case Tutorials

Life Cycle Assessment (LCA)

Own Workforce (Social Data)

ISO 14001 Management Systems

Advanced

Automation & AI

Step 1 - Set Up Your Company Structure

Understanding the Company Diagram

Step 1.1: Create the Matrix Organization

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

Configuration Options

​Understanding the Company Diagram

​Step 1.1: Create the Matrix Organization

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

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

​Configuration Options

​Update Share and Scopes via API

Understanding the Company Diagram

Step 1.1: Create the Matrix Organization

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

Configuring Investees: Share %, Scopes, Tag and Status

Configuration Options

Update Share and Scopes via API