> ## Documentation Index
> Fetch the complete documentation index at: https://code.dcycle.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Step 1 - Set Up Your Company Structure
> Learn how to create and configure your organizational hierarchy for carbon footprint consolidation
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 Impact**
When 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.
```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
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']}")
```
```javascript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
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
```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
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']}")
```
```javascript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
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.
## 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
| 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` |
**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
```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
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:
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