> ## 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.

# Custom Emission Groups

> Organize and manage custom emission factors into groups

<Warning>
  **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.
</Warning>

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:

| 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

<Steps>
  <Step title="Create Custom Emission Group">
    Define a group to organize your custom factors

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    POST /api/v1/custom_emission_groups
    ```
  </Step>

  <Step title="Add Custom Emission Factors">
    Add individual factors to the group

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    POST /api/v1/custom_emission_factors/{group_id}
    ```
  </Step>

  <Step title="Use in Operations">
    Reference factors when creating purchases, wastes, or energy records

    ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      "custom_emission_factor_id": "factor-uuid",
      ...
    }
    ```
  </Step>

  <Step title="Manage and Update">
    Update group metadata or factors as needed

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    PATCH /api/v1/custom_emission_groups/{id}
    PATCH /api/v1/custom_emission_factors/{id}
    ```
  </Step>
</Steps>

## Data Structure

### Custom Emission Group

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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

<ParamField body="name" type="string" required>
  Descriptive name for the group

  **Example:** `"Supplier XYZ Materials 2024"`
</ParamField>

<ParamField body="description" type="string">
  Detailed description of the group's purpose

  **Example:** `"EPD-verified emission factors for all materials from Supplier XYZ, valid for 2024"`
</ParamField>

<ParamField body="category" type="string" required>
  Category type

  **Values:** `"purchases"`, `"wastes"`, or `"energy"`
</ParamField>

<ParamField body="ghg_type" type="integer" required>
  GHG origin type

  **Values:** `1` (fossil), `2` (biogenic), or `3` (mixed)
</ParamField>

## API Endpoints

<CardGroup cols={2}>
  <Card title="Create Group" icon="folder-plus" href="/api-docs/custom-emission-groups/create">
    Create new emission group
  </Card>

  <Card title="List Groups" icon="list" href="/api-docs/custom-emission-groups/list">
    View all groups
  </Card>

  <Card title="Get Group" icon="magnifying-glass" href="/api-docs/custom-emission-groups/get">
    Retrieve group details
  </Card>

  <Card title="Update Group" icon="pen" href="/api-docs/custom-emission-groups/update">
    Modify group metadata
  </Card>

  <Card title="Delete Group" icon="trash" href="/api-docs/custom-emission-groups/delete">
    Remove group
  </Card>

  <Card title="Get Units" icon="ruler" href="/api-docs/custom-emission-groups/units">
    List available units
  </Card>

  <Card title="List by Category" icon="filter" href="/api-docs/custom-emission-groups/list-by-category">
    Filter groups by category
  </Card>

  <Card title="Organization Data" icon="building" href="/api-docs/custom-emission-groups/organization-data">
    Get all organization groups
  </Card>
</CardGroup>

## Best Practices

### 1. Organize by Source

Create groups based on data source:

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
# 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:

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
    "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:

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
# ✅ 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:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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)

## Related Documentation

<CardGroup cols={2}>
  <Card title="Custom Emission Factors" icon="chart-line" href="/api-docs/custom-emission-factors/overview">
    Add factors to groups
  </Card>

  <Card title="Purchases" icon="shopping-cart" href="/api-docs/purchases/list">
    Use custom factors in purchases
  </Card>

  <Card title="Wastes" icon="trash" href="/api-docs/wastes/codes">
    Apply to waste management
  </Card>

  <Card title="Units" icon="ruler" href="/api-reference/legacy/units/list">
    Available measurement units
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.