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

# Create Custom Emission Factor

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

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

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

  **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-docs/custom-emission-factors/list">
    View all factors in a group
  </Card>

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

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

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