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

GHG Types

Each group specifies the GHG origin type:

Type	Value	Description	Example
Fossil	`1`	Fossil fuel-derived emissions	Conventional energy, petroleum products
Biogenic	`2`	Biological origin emissions	Biomass, biogas, biofuels
Mixed	`3`	Combination of fossil and biogenic	Mixed waste streams, hybrid processes

Workflow

Create Custom Emission Group

Define a group to organize your custom factors

POST /api/v1/custom_emission_groups

Add Custom Emission Factors

Add individual factors to the group

POST /api/v1/custom_emission_factors/{group_id}

Use in Operations

Reference factors when creating purchases, wastes, or energy records

{
  "custom_emission_factor_id": "factor-uuid",
  ...
}

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

string

required

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

string

Detailed description of the group’s purposeExample: "EPD-verified emission factors for all materials from Supplier XYZ, valid for 2024"

string

required

Category typeValues: "purchases", "wastes", or "energy"

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: energy_procurement@company.com
    """,
    "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

Optional but Recommended

📝 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

​Custom Emission Groups

​Overview

​What are Custom Emission Groups?

​Hierarchy

​Categories

​Purchases (purchases)

​Wastes (wastes)

​Energy (energy)

​GHG Types

​Workflow

​Data Structure

​Custom Emission Group

​Key Fields

​API Endpoints

Create Group

List Groups

Get Group

Update Group

Delete Group

Get Units

List by Category

Organization Data

​Best Practices

​1. Organize by Source

​2. Use Clear Naming Conventions

​3. Document Everything

​4. One Group per Category per Source

​Common Use Cases

​Supplier Product Portfolio

​Regional Waste Management

​Renewable Energy Portfolio

​Validation Requirements

​Required Fields

​Optional but Recommended

​Automatic Checks

​Related Documentation

Custom Emission Factors

Purchases

Wastes

Units

Custom Emission Groups

Overview

What are Custom Emission Groups?

Hierarchy

Categories

Purchases (`purchases`)

Wastes (`wastes`)

Energy (`energy`)

GHG Types

Workflow

Data Structure

Custom Emission Group

Key Fields

API Endpoints

Best Practices

1. Organize by Source

2. Use Clear Naming Conventions

3. Document Everything

4. One Group per Category per Source

Common Use Cases

Supplier Product Portfolio

Regional Waste Management

Renewable Energy Portfolio

Validation Requirements

Required Fields

Optional but Recommended

Automatic Checks

Related Documentation