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

> Create a new custom emission factor within a group

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

Add a new custom emission factor to an existing Custom Emission Group. This endpoint allows you to define organization-specific emission factors with detailed GHG breakdowns.

<Note>
  You must first create a Custom Emission Group before adding factors to it. See [Custom Emission Groups](/api-reference/legacy/custom-emission-groups/create).
</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>

### Path Parameters

<ParamField path="id" type="string" required>
  UUID of the Custom Emission Group to add this factor to

  **Example:** `"group-uuid-here"`
</ParamField>

### Body Parameters

<ParamField body="ef_name" type="string" required>
  Descriptive name for the emission factor

  **Example:** `"Recycled Aluminum - Supplier ABC"`
</ParamField>

<ParamField body="unit_id" type="string" required>
  UUID of the measurement unit (from `/api/v1/units`)

  **Example:** `"kg-unit-uuid"`
</ParamField>

<ParamField body="factor_uploaded_by" type="string" required>
  Reference to person/team who uploaded this factor

  **Example:** `"sustainability_team@company.com"`
</ParamField>

<ParamField body="tag" type="string" required>
  Complexity level of the factor

  **Values:** `"simple"` or `"advanced"`
</ParamField>

<ParamField body="emission_factor_values" type="array" required>
  Array of emission values by gas type

  Each object must contain:

  * `gas_type` (string): `"CO2"`, `"CH4"`, `"N2O"`, `"HFC"`, `"PFC"`, `"SF6"`, or `"NF3"`
  * `value` (float): Emission value (kg gas per unit)

  **Minimum:** At least CO2 must be provided
</ParamField>

<ParamField body="uncertainty_grade" type="float">
  Confidence level of the factor (0-100%)

  **Example:** `15.5` (lower is more certain)
</ParamField>

<ParamField body="factor_start_date" type="date">
  Validity start date (YYYY-MM-DD)

  **Example:** `"2024-01-01"`
</ParamField>

<ParamField body="factor_end_date" type="date">
  Validity end date (YYYY-MM-DD)

  **Example:** `"2024-12-31"`
</ParamField>

<ParamField body="additional_docs" type="string">
  Documentation reference or notes

  **Example:** `"EPD No. ABC-2024-001, Third-party verified"`
</ParamField>

<ParamField body="renewable_percentage" type="float">
  For energy factors: percentage of renewable content (0-100)

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

<ParamField body="hazardous" type="boolean">
  For waste factors: whether waste is hazardous

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

<ParamField body="recycled" type="boolean">
  For waste/material factors: whether material is recycled

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

<ParamField body="low_code" type="string">
  For waste factors: LER/LOW waste code

  Retrieve available options from [`GET /api/v1/wastes/low_codes`](/api-reference/legacy/wastes/codes) — `waste_region` is required; pass `GLO`

  **Example:** `"15 01 01"`
</ParamField>

<ParamField body="rd_code" type="string">
  For waste factors: RD disposal method code

  Retrieve available options from [`GET /api/v1/wastes/rd_ler_list`](/api-reference/legacy/wastes/codes)

  **Example:** `"R3"`
</ParamField>

## Response

Returns the created custom emission factor object with generated ID.

## Example

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl -X POST "https://api.dcycle.io/api/v1/custom_emission_factors/group-uuid" \
    -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 '{
      "ef_name": "Recycled Aluminum - Supplier ABC",
      "unit_id": "kg-unit-uuid",
      "factor_uploaded_by": "sustainability@company.com",
      "tag": "advanced",
      "uncertainty_grade": 15,
      "factor_start_date": "2024-01-01",
      "factor_end_date": "2024-12-31",
      "additional_docs": "EPD No. ABC-2024-001",
      "emission_factor_values": [
        {
          "gas_type": "CO2",
          "value": 2.15
        },
        {
          "gas_type": "CH4",
          "value": 0.008
        },
        {
          "gas_type": "N2O",
          "value": 0.002
        }
      ],
      "recycled": true
    }'
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import requests
  import os

  api_key = os.getenv("DCYCLE_API_KEY")
  org_id = os.getenv("DCYCLE_ORG_ID")
  user_id = os.getenv("DCYCLE_USER_ID")

  headers = {
      "Authorization": f"Bearer {api_key}",
      "x-organization-id": org_id,
      "x-user-id": user_id,
      "Content-Type": "application/json"
  }

  group_id = "group-uuid"

  factor_data = {
      "ef_name": "Recycled Aluminum - Supplier ABC",
      "unit_id": "kg-unit-uuid",
      "factor_uploaded_by": "sustainability@company.com",
      "tag": "advanced",
      "uncertainty_grade": 15,
      "factor_start_date": "2024-01-01",
      "factor_end_date": "2024-12-31",
      "additional_docs": "EPD No. ABC-2024-001",
      "emission_factor_values": [
          {"gas_type": "CO2", "value": 2.15},
          {"gas_type": "CH4", "value": 0.008},
          {"gas_type": "N2O", "value": 0.002}
      ],
      "recycled": True
  }

  response = requests.post(
      f"https://api.dcycle.io/api/v1/custom_emission_factors/{group_id}",
      headers=headers,
      json=factor_data
  )

  factor = response.json()
  print(f"✅ Custom emission factor created: {factor['id']}")
  ```

  ```javascript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const axios = require('axios');

  const apiKey = process.env.DCYCLE_API_KEY;
  const orgId = process.env.DCYCLE_ORG_ID;
  const userId = process.env.DCYCLE_USER_ID;

  const headers = {
    'Authorization': `Bearer ${apiKey}`,
    'x-organization-id': orgId,
    'x-user-id': userId,
    'Content-Type': 'application/json'
  };

  const groupId = 'group-uuid';

  const factorData = {
    ef_name: 'Recycled Aluminum - Supplier ABC',
    unit_id: 'kg-unit-uuid',
    factor_uploaded_by: 'sustainability@company.com',
    tag: 'advanced',
    uncertainty_grade: 15,
    factor_start_date: '2024-01-01',
    factor_end_date: '2024-12-31',
    additional_docs: 'EPD No. ABC-2024-001',
    emission_factor_values: [
      { gas_type: 'CO2', value: 2.15 },
      { gas_type: 'CH4', value: 0.008 },
      { gas_type: 'N2O', value: 0.002 }
    ],
    recycled: true
  };

  axios.post(
    `https://api.dcycle.io/api/v1/custom_emission_factors/${groupId}`,
    factorData,
    { headers }
  )
  .then(response => {
    const factor = response.data;
    console.log(`✅ Custom emission factor created: ${factor.id}`);
  })
  .catch(error => console.error(error));
  ```
</CodeGroup>

### Successful Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "factor-uuid",
  "factor_id": "factor-uuid",
  "ef_name": "Recycled Aluminum - Supplier ABC",
  "unit_id": "kg-unit-uuid",
  "factor_uploaded_by": "sustainability@company.com",
  "tag": "advanced",
  "uncertainty_grade": 15.0,
  "factor_start_date": "2024-01-01",
  "factor_end_date": "2024-12-31",
  "additional_docs": "EPD No. ABC-2024-001",
  "emission_factor_values": [
    {
      "gas_type": "CO2",
      "value": 2.15
    },
    {
      "gas_type": "CH4",
      "value": 0.008
    },
    {
      "gas_type": "N2O",
      "value": 0.002
    }
  ],
  "recycled": true,
  "renewable_percentage": null,
  "hazardous": null,
  "low_code": null,
  "rd_code": null
}
```

## Common Errors

### 400 Bad Request - Invalid Group ID

**Cause:** Custom emission group not found

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "detail": "Custom emission group not found",
  "code": "NOT_FOUND"
}
```

**Solution:** Verify the group ID exists using `/api/v1/custom_emission_groups`.

### 422 Validation Error - Missing CO2

**Cause:** At least CO2 emission value must be provided

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "detail": "At least CO2 emission value must be provided",
  "code": "VALIDATION_ERROR"
}
```

**Solution:** Include at least one emission value for CO2.

### 422 Validation Error - Invalid Tag

**Cause:** The custom emission factor data tag specified is invalid

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "detail": "The custom emission factor data tag specified is invalid",
  "code": "VALIDATION_ERROR"
}
```

**Solution:** Use `"simple"` or `"advanced"` for the tag field.

### 422 Validation Error - Invalid Uncertainty

**Cause:** The custom emission factor data uncertainty\_grade specified is invalid

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "detail": "The custom emission factor data uncertainty_grade specified is invalid",
  "code": "VALIDATION_ERROR"
}
```

**Solution:** Uncertainty grade must be between 0 and 100.

## Best Practices

### 1. Include All Relevant GHGs

Don't just provide CO2 - include CH4 and N2O when available:

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
emission_factor_values = [
    {"gas_type": "CO2", "value": 2.15},
    {"gas_type": "CH4", "value": 0.008},  # Important for waste/agriculture
    {"gas_type": "N2O", "value": 0.002}   # High GWP (265x CO2)
]
```

### 2. Document Your Sources

Always include documentation references:

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
additional_docs = "EPD No. ABC-2024-001, Third-party verified by Bureau Veritas, dated 2024-01-15"
```

### 3. Set Realistic Validity Periods

Update factors annually or when supplier data changes:

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
factor_start_date = "2024-01-01"
factor_end_date = "2024-12-31"  # Review next year
```

### 4. Be Honest About Uncertainty

Track confidence levels to prioritize data improvement:

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
# High confidence - supplier EPD
uncertainty_grade = 15

# Medium confidence - industry average
uncertainty_grade = 35

# Low confidence - estimate
uncertainty_grade = 65
```

## Related Endpoints

<CardGroup cols={2}>
  <Card title="List Factors" icon="list" href="/api-reference/legacy/custom-emission-factors/list">
    View all factors in a group
  </Card>

  <Card title="Update Factor" icon="pen" href="/api-reference/legacy/custom-emission-factors/update">
    Modify existing factor
  </Card>

  <Card title="Create Group" icon="folder-plus" href="/api-reference/legacy/custom-emission-groups/create">
    Create a new emission group first
  </Card>

  <Card title="Overview" icon="book" href="/api-reference/legacy/custom-emission-factors/overview">
    Learn about custom factors
  </Card>
</CardGroup>


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