Skip to main content
POST
/
api
/
v1
/
custom_emission_groups
Create Custom Emission Group
const options = {
  method: 'POST',
  headers: {
    'x-api-key': '<x-api-key>',
    'x-organization-id': '<x-organization-id>',
    'x-user-id': '<x-user-id>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({name: '<string>', description: '<string>', category: '<string>', ghg_type: 123})
};

fetch('https://api.dcycle.io/api/v1/custom_emission_groups', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

​
Create Custom Emission Group

Create a new Custom Emission Group to organize related custom emission factors. This is the first step before adding individual emission factors.
After creating a group, you can add custom emission factors to it using the Create Custom Emission Factor endpoint.

​
Request

​
Headers

​
x-api-key
string
required
Your API key for authenticationExample: sk_live_1234567890abcdef
​
x-organization-id
string
required
Your organization UUIDExample: ff4adcc7-8172-45fe-9cf1-e90a6de53aa9
​
x-user-id
string
required
Your user UUIDExample: a1b2c3d4-e5f6-7890-abcd-ef1234567890

​
Body Parameters

​
name
string
required
Descriptive name for the groupExample: "Supplier ABC Materials 2024"
​
description
string
Detailed description of the group’s purpose and scopeExample: "EPD-verified emission factors for all materials from Supplier ABC"
​
category
string
required
Category type for this groupValues: "purchases", "wastes", or "energy"
​
ghg_type
integer
required
Greenhouse gas origin typeValues:
  • 1 - Fossil fuel-derived emissions
  • 2 - Biogenic emissions
  • 3 - Mixed (fossil + biogenic)

​
Response

Returns the created custom emission group with generated ID. 
{
  "id": "group-uuid",
  "name": "Supplier ABC Materials 2024",
  "description": "EPD-verified emission factors for all materials from Supplier ABC",
  "category": "purchases",
  "ghg_type": 1
}

​
Example

curl -X POST "https://api.dcycle.io/api/v1/custom_emission_groups" \
  -H "Authorization: Bearer ${DCYCLE_API_KEY}" \
  -H "x-organization-id: ${DCYCLE_ORG_ID}" \
  -H "x-user-id: ${DCYCLE_USER_ID}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Supplier ABC Materials 2024",
    "description": "EPD-verified emission factors for all materials from Supplier ABC",
    "category": "purchases",
    "ghg_type": 1
  }'

​
Use Cases

​
Supplier-Specific Group

Create a group for all products from a specific supplier: 
supplier_group = {
    "name": "GreenTech Materials Q1 2024",
    "description": "EPD-verified factors for GreenTech products. Contact: procurement@company.com",
    "category": "purchases",
    "ghg_type": 1  # Fossil
}

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

group_id = response.json()['id']
print(f"Created group: {group_id}")

# Now add individual product factors to this group
# POST /api/v1/custom_emission_factors/{group_id}

​
Waste Facility Group

Create a group for custom waste treatment factors: 
waste_group = {
    "name": "Regional Waste Facility 2024",
    "description": "Custom factors for local waste treatment with energy recovery. Facility ID: WF-2024-001",
    "category": "wastes",
    "ghg_type": 3  # Mixed (fossil + biogenic)
}

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

​
Renewable Energy PPA Group

Create a group for Power Purchase Agreement factors: 
const ppaGroup = {
  name: 'Wind Farm PPA 2024-2034',
  description: '10-year wind energy PPA, 100% renewable. Contract #PPA-WIND-2024-001',
  category: 'energy',
  ghg_type: 2  // Biogenic
};

const group = await axios.post(
  'https://api.dcycle.io/api/v1/custom_emission_groups',
  ppaGroup,
  { headers }
).then(res => res.data);

console.log(`PPA group created: ${group.id}`);

​
Complete Workflow

Create group, then add factors: 
import requests
import os

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

# Step 1: Create group
group_response = requests.post(
    "https://api.dcycle.io/api/v1/custom_emission_groups",
    headers=headers,
    json={
        "name": "Supplier ABC Materials 2024",
        "description": "EPD-verified materials",
        "category": "purchases",
        "ghg_type": 1
    }
)

group_id = group_response.json()['id']
print(f"✅ Created group: {group_id}")

# Step 2: Add emission factors to the group
factor_data = {
    "ef_name": "Recycled Aluminum - Supplier ABC",
    "unit_id": "kg-unit-uuid",
    "factor_uploaded_by": "procurement@company.com",
    "tag": "advanced",
    "emission_factor_values": [
        {"gas_type": "CO2", "value": 2.15},
        {"gas_type": "CH4", "value": 0.008},
        {"gas_type": "N2O", "value": 0.002}
    ],
    "recycled": True
}

factor_response = requests.post(
    f"https://api.dcycle.io/api/v1/custom_emission_factors/{group_id}",
    headers=headers,
    json=factor_data
)

print(f"✅ Added factor: {factor_response.json()['id']}")

​
Common Errors

​
422 Validation Error - Invalid Category

{
  "detail": "The custom emission group category is invalid.",
  "code": "VALIDATION_ERROR"
}
Solution: Use "purchases", "wastes", or "energy" for the category field.

​
422 Validation Error - Invalid GHG Type

{
  "detail": "Value error for ghg_type",
  "code": "VALIDATION_ERROR"
}
Solution: Use 1 (fossil), 2 (biogenic), or 3 (mixed) for ghg_type.

​
400 Bad Request - Duplicate Name

{
  "detail": "A custom emission group with this name already exists",
  "code": "DUPLICATE"
}
Solution: Use a unique name, or append year/version to existing name.

​
Best Practices

​
1. Use Descriptive Names

Include source, year, and scope: 
# ✅ Good names
"Supplier XYZ Materials 2024"
"Wind Farm PPA 2024-2034"
"Regional Waste Facility Q1-Q4 2024"

# ❌ Unclear names
"Custom Factors"
"Group 1"
"Materials"

​
2. Document Thoroughly

Use the description field to capture important details: 
{
    "name": "GreenTech Supplier - 2024",
    "description": """
        EPD-verified emission factors from GreenTech Industries.
        - Verification: Bureau Veritas Report #2024-001
        - Valid: 2024-01-01 to 2024-12-31
        - Contact: procurement@company.com
        - Supplier ID: SUPP-GT-2024
    """,
    "category": "purchases",
    "ghg_type": 1
}

​
3. Choose Correct GHG Type

Select based on the emission source: 
# Fossil (1): Conventional energy, petroleum products
{"category": "purchases", "ghg_type": 1}

# Biogenic (2): Biomass, biogas, renewable energy
{"category": "energy", "ghg_type": 2}

# Mixed (3): Waste streams with both fossil and biogenic content
{"category": "wastes", "ghg_type": 3}

​
4. One Category per Group

Don’t mix categories - create separate groups: 
# ✅ Good: Separate groups
purchases_group = {"name": "Supplier ABC Purchases", "category": "purchases", "ghg_type": 1}
waste_group = {"name": "Supplier ABC Waste", "category": "wastes", "ghg_type": 3}

# ❌ Bad: Don't try to use one group for multiple categories

Add Factors

Add factors to this group

List Groups

View all groups

Update Group

Modify group metadata

Overview

Learn about groups