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

# Create Custom Emission Group

> Create a new custom emission group to organize emission factors

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

Create a new Custom Emission Group to organize related custom emission factors. This is the first step before adding individual emission factors.

<Note>
  After creating a group, you can add custom emission factors to it using the [Create Custom Emission Factor](/api-docs/custom-emission-factors/create) endpoint.
</Note>

## Request

### Headers

<ParamField header="x-api-key" type="string" required>
  Your API key for authentication

  **Example:** `sk_live_1234567890abcdef`
</ParamField>

<ParamField header="x-organization-id" type="string" required>
  Your organization UUID

  **Example:** `ff4adcc7-8172-45fe-9cf1-e90a6de53aa9`
</ParamField>

<ParamField header="x-user-id" type="string" required>
  Your user UUID

  **Example:** `a1b2c3d4-e5f6-7890-abcd-ef1234567890`
</ParamField>

### Body Parameters

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

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

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

  **Example:** `"EPD-verified emission factors for all materials from Supplier ABC"`
</ParamField>

<ParamField body="category" type="string" required>
  Category type for this group

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

<ParamField body="ghg_type" type="integer" required>
  Greenhouse gas origin type

  **Values:**

  * `1` - Fossil fuel-derived emissions
  * `2` - Biogenic emissions
  * `3` - Mixed (fossil + biogenic)
</ParamField>

## Response

Returns the created custom emission group with generated ID.

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

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  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
    }'
  ```

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

  ```javascript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  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));
  ```
</CodeGroup>

## Use Cases

### Supplier-Specific Group

Create a group for all products from a specific supplier:

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

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

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

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

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

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

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

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

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

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

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

## Related Endpoints

<CardGroup cols={2}>
  <Card title="Add Factors" icon="plus" href="/api-docs/custom-emission-factors/create">
    Add factors to this group
  </Card>

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

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

  <Card title="Overview" icon="book" href="/api-docs/custom-emission-groups/overview">
    Learn about groups
  </Card>
</CardGroup>


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