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

# Create Custom Emission Group

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>