Skip to main content

​
Custom Emission Groups

Custom Emission Groups are containers that organize related custom emission factors by category. They provide structure and context for your organization’s custom emission data.

​
Overview

​
What are Custom Emission Groups?

Custom Emission Groups act as folders or categories for organizing custom emission factors. Each group:
  • Contains multiple related custom emission factors
  • Has a specific category (purchases, wastes, or energy)
  • Defines the GHG type (fossil, biogenic, or mixed)
  • Belongs to a single organization

​
Hierarchy

Organization
└── Custom Emission Group (category: purchases)
    ├── Custom Emission Factor 1
    ├── Custom Emission Factor 2
    └── Custom Emission Factor 3

​
Categories

Custom Emission Groups are organized by three categories:

​
Purchases (purchases)

Groups for supplier-specific product emission factors. Example: “Supplier ABC Materials 2024”
  • Recycled aluminum sheets
  • Steel beams
  • Plastic components

​
Wastes (wastes)

Groups for custom waste treatment emission factors. Example: “Local Waste Facility Factors”
  • Incineration with energy recovery
  • Recycling processes
  • Landfill disposal

​
Energy (energy)

Groups for renewable energy contracts and custom energy factors. Example: “Wind Farm PPA 2024-2034”
  • 100% renewable wind energy
  • Solar PPA contracts
  • On-site generation

​
GHG Types

Each group specifies the GHG origin type:
TypeValueDescriptionExample
Fossil1Fossil fuel-derived emissionsConventional energy, petroleum products
Biogenic2Biological origin emissionsBiomass, biogas, biofuels
Mixed3Combination of fossil and biogenicMixed waste streams, hybrid processes

​
Workflow

1

Create Custom Emission Group

Define a group to organize your custom factors
POST /api/v1/custom_emission_groups
2

Add Custom Emission Factors

Add individual factors to the group
POST /api/v1/custom_emission_factors/{group_id}
3

Use in Operations

Reference factors when creating purchases, wastes, or energy records
{
  "custom_emission_factor_id": "factor-uuid",
  ...
}
4

Manage and Update

Update group metadata or factors as needed
PATCH /api/v1/custom_emission_groups/{id}
PATCH /api/v1/custom_emission_factors/{id}

​
Data Structure

​
Custom Emission Group

{
  "id": "group-uuid",
  "name": "Supplier ABC Products 2024",
  "description": "Custom emission factors from Supplier ABC with EPD verification",
  "category": "purchases",
  "ghg_type": 1,
  "organization_id": "org-uuid"
}

​
Key Fields

​
name
string
required
Descriptive name for the groupExample: "Supplier XYZ Materials 2024"
​
description
string
Detailed description of the group’s purposeExample: "EPD-verified emission factors for all materials from Supplier XYZ, valid for 2024"
​
category
string
required
Category typeValues: "purchases", "wastes", or "energy"
​
ghg_type
integer
required
GHG origin typeValues: 1 (fossil), 2 (biogenic), or 3 (mixed)

​
API Endpoints

Create Group

Create new emission group

List Groups

View all groups

Get Group

Retrieve group details

Update Group

Modify group metadata

Delete Group

Remove group

Get Units

List available units

List by Category

Filter groups by category

Organization Data

Get all organization groups

​
Best Practices

​
1. Organize by Source

Create groups based on data source: 
# Supplier-specific group
{
    "name": "Supplier ABC - 2024 EPD Data",
    "description": "All materials from Supplier ABC with third-party verified EPDs",
    "category": "purchases",
    "ghg_type": 1
}

# Facility-specific group
{
    "name": "Local Waste Facility - 2024",
    "description": "Custom waste treatment factors for our regional waste facility",
    "category": "wastes",
    "ghg_type": 3
}

​
2. Use Clear Naming Conventions

Include year, source, and scope in names: 
✅ Good names:
- "Supplier XYZ Materials 2024"
- "Wind Farm PPA 2024-2034"
- "Local Recycling Center Q1-Q2 2024"

❌ Unclear names:
- "Custom Factors"
- "Group 1"
- "Materials"

​
3. Document Everything

Use the description field extensively: 
{
    "name": "Renewable Energy PPA Portfolio",
    "description": """
        Combined renewable energy factors from multiple PPAs:
        - Wind Farm A (60% allocation, 100MW capacity)
        - Solar Farm B (40% allocation, 50MW capacity)
        Contract period: 2024-01-01 to 2034-12-31
        Third-party verification: Bureau Veritas, Report #2024-001
        Contact: [email protected]
    """,
    "category": "energy",
    "ghg_type": 2
}

​
4. One Group per Category per Source

Don’t mix categories or sources: 
# ✅ Good: One category, one source
{
    "name": "Supplier ABC Purchases 2024",
    "category": "purchases",
    "ghg_type": 1
}

# ❌ Bad: Mixing multiple sources or categories
# Create separate groups instead

​
Common Use Cases

​
Supplier Product Portfolio

Organize all products from a single supplier: 
{
  "name": "GreenTech Materials 2024",
  "description": "EPD-verified factors for all GreenTech products, updated quarterly",
  "category": "purchases",
  "ghg_type": 1
}
Then add factors:
  • Recycled aluminum sheets
  • Steel beams (low-carbon)
  • Composite materials
  • Packaging materials

​
Regional Waste Management

Group factors for a specific waste facility: 
{
  "name": "Regional Waste Facility - 2024",
  "description": "Custom factors for local waste treatment facility with energy recovery",
  "category": "wastes",
  "ghg_type": 3
}
Factors:
  • Incineration with energy recovery
  • Composting (organic waste)
  • Recycling (paper, plastic, metal)
  • Landfill disposal

​
Renewable Energy Portfolio

Organize PPA contracts: 
{
  "name": "Renewable Energy Portfolio 2024-2034",
  "description": "10-year PPAs for wind and solar energy, 100% renewable allocation",
  "category": "energy",
  "ghg_type": 2
}
Factors:
  • Wind farm PPA (60% allocation)
  • Solar farm PPA (40% allocation)
  • On-site solar panels

​
Validation Requirements

​
Required Fields

  • ✅ Name (name)
  • ✅ Category (category) - must be purchases, wastes, or energy
  • ✅ GHG type (ghg_type) - must be 1, 2, or 3
  • 📝 Description (description) - provide context and documentation

​
Automatic Checks

  • ⚠️ Category must be valid (purchases, wastes, or energy)
  • ⚠️ GHG type must be 1, 2, or 3
  • ⚠️ Name must be unique within organization (recommended)

Custom Emission Factors

Add factors to groups

Purchases

Use custom factors in purchases

Wastes

Apply to waste management

Units

Available measurement units