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));

import requests

url = "https://api.dcycle.io/api/v1/custom_emission_groups"

payload = {
    "name": "<string>",
    "description": "<string>",
    "category": "<string>",
    "ghg_type": 123
}
headers = {
    "x-api-key": "<x-api-key>",
    "x-organization-id": "<x-organization-id>",
    "x-user-id": "<x-user-id>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

curl --request POST \
  --url https://api.dcycle.io/api/v1/custom_emission_groups \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <x-api-key>' \
  --header 'x-organization-id: <x-organization-id>' \
  --header 'x-user-id: <x-user-id>' \
  --data '
{
  "name": "<string>",
  "description": "<string>",
  "category": "<string>",
  "ghg_type": 123
}
'

POST

api

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));

import requests

url = "https://api.dcycle.io/api/v1/custom_emission_groups"

payload = {
    "name": "<string>",
    "description": "<string>",
    "category": "<string>",
    "ghg_type": 123
}
headers = {
    "x-api-key": "<x-api-key>",
    "x-organization-id": "<x-organization-id>",
    "x-user-id": "<x-user-id>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

curl --request POST \
  --url https://api.dcycle.io/api/v1/custom_emission_groups \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <x-api-key>' \
  --header 'x-organization-id: <x-organization-id>' \
  --header 'x-user-id: <x-user-id>' \
  --data '
{
  "name": "<string>",
  "description": "<string>",
  "category": "<string>",
  "ghg_type": 123
}
'

Legacy API. This page documents the previous version of the API. This particular operation has no documented equivalent in the current API yet, so this remains the documented way to do it. Prefer the current API for everything it already covers.

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

string

required

Your API key for authenticationExample: sk_live_1234567890abcdef

string

required

Your organization UUIDExample: ff4adcc7-8172-45fe-9cf1-e90a6de53aa9

string

required

Your user UUIDExample: a1b2c3d4-e5f6-7890-abcd-ef1234567890

Body Parameters

string

required

Descriptive name for the groupExample: "Supplier ABC Materials 2024"

string

Detailed description of the group’s purpose and scopeExample: "EPD-verified emission factors for all materials from Supplier ABC"

string

required

Category type for this groupValues: "purchases", "wastes", or "energy"

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

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

group_data = {
    "name": "Supplier ABC Materials 2024",
    "description": "EPD-verified emission factors for all materials from Supplier ABC",
    "category": "purchases",
    "ghg_type": 1
}

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

group = response.json()
print(f"✅ Group created: {group['id']}")
print(f"Name: {group['name']}")

const axios = require('axios');

const headers = {
  'Authorization': `Bearer ${process.env.DCYCLE_API_KEY}`,
  'x-organization-id': process.env.DCYCLE_ORG_ID,
  'x-user-id': process.env.DCYCLE_USER_ID,
  'Content-Type': 'application/json'
};

const groupData = {
  name: 'Supplier ABC Materials 2024',
  description: 'EPD-verified emission factors for all materials from Supplier ABC',
  category: 'purchases',
  ghg_type: 1
};

axios.post(
  'https://api.dcycle.io/api/v1/custom_emission_groups',
  groupData,
  { headers }
)
.then(response => {
  const group = response.data;
  console.log(`✅ Group created: ${group.id}`);
  console.log(`Name: ${group.name}`);
})
.catch(error => console.error(error));

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

Cause: The custom emission group category is invalid.

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

Cause: Value error for 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

Cause: A custom emission group with this name already exists

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

Introduction

Logistics

Facilities

Vehicles

Purchases

Wastes

Reference Data

Custom Emission Factors

Custom Emission Groups

Create Custom Emission Group

Request

Headers

Body Parameters

Response

Example

Use Cases

Supplier-Specific Group

Waste Facility Group

Renewable Energy PPA Group

Complete Workflow

Common Errors

422 Validation Error - Invalid Category

422 Validation Error - Invalid GHG Type

400 Bad Request - Duplicate Name

Best Practices

1. Use Descriptive Names

2. Document Thoroughly

3. Choose Correct GHG Type

4. One Category per Group

Add Factors

List Groups

Update Group

Overview

​Request

​Headers

​Body Parameters

​Response

​Example

​Use Cases

​Supplier-Specific Group

​Waste Facility Group

​Renewable Energy PPA Group

​Complete Workflow

​Common Errors

​422 Validation Error - Invalid Category

​422 Validation Error - Invalid GHG Type

​400 Bad Request - Duplicate Name

​Best Practices

​1. Use Descriptive Names

​2. Document Thoroughly

​3. Choose Correct GHG Type

​4. One Category per Group

​Related Endpoints

Add Factors

List Groups

Update Group

Overview

Request

Headers

Body Parameters

Response

Example

Use Cases

Supplier-Specific Group

Waste Facility Group

Renewable Energy PPA Group

Complete Workflow

Common Errors

422 Validation Error - Invalid Category

422 Validation Error - Invalid GHG Type

400 Bad Request - Duplicate Name

Best Practices

1. Use Descriptive Names

2. Document Thoroughly

3. Choose Correct GHG Type

4. One Category per Group

Related Endpoints