Create Custom Emission Factor

Create a new custom emission factor within a group

POST /api/v1/custom_emission_factors/{id}

Create Custom Emission Factor

JavaScript

const options = {
  method: 'POST',
  headers: {
    'x-api-key': '<x-api-key>',
    'x-organization-id': '<x-organization-id>',
    'x-user-id': '<x-user-id>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    ef_name: '<string>',
    unit_id: '<string>',
    factor_uploaded_by: '<string>',
    tag: '<string>',
    emission_factor_values: [{}],
    uncertainty_grade: 123,
    factor_start_date: '<string>',
    factor_end_date: '<string>',
    additional_docs: '<string>',
    renewable_percentage: 123,
    hazardous: true,
    recycled: true,
    low_code: '<string>',
    rd_code: '<string>'
  })
};

fetch('https://api.dcycle.io/api/v1/custom_emission_factors/{id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

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.

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.

You must first create a Custom Emission Group before adding factors to it. See Custom Emission Groups.

Request

Headers

x-api-key · string · required

Your API key for authentication

Example: sk_live_1234567890abcdef

x-organization-id · string · required

Your organization UUID

Example: ff4adcc7-8172-45fe-9cf1-e90a6de53aa9

x-user-id · string · required

Your user UUID

Example: a1b2c3d4-e5f6-7890-abcd-ef1234567890

Path Parameters

id · string · required

UUID of the Custom Emission Group to add this factor to

Example: "group-uuid-here"

Body Parameters

ef_name · string · required

Descriptive name for the emission factor

Example: "Recycled Aluminum - Supplier ABC"

unit_id · string · required

UUID of the measurement unit (from /api/v1/units)

Example: "kg-unit-uuid"

factor_uploaded_by · string · required

Reference to person/team who uploaded this factor

Example: "[e-mail]"

tag · string · required

Complexity level of the factor

Values: "simple" or "advanced"

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

uncertainty_grade · float

Confidence level of the factor (0-100%)

Example: 15.5 (lower is more certain)

factor_start_date · date

Validity start date (YYYY-MM-DD)

Example: "2024-01-01"

factor_end_date · date

Validity end date (YYYY-MM-DD)

Example: "2024-12-31"

additional_docs · string

Documentation reference or notes

Example: "EPD No. ABC-2024-001, Third-party verified"

renewable_percentage · float

For energy factors: percentage of renewable content (0-100)

Example: 100.0

hazardous · boolean

For waste factors: whether waste is hazardous

Example: false

recycled · boolean

For waste/material factors: whether material is recycled

Example: true

low_code · string

For waste factors: LER/LOW waste code

Retrieve available options from GET /api/v1/wastes/low_codes — waste_region is required; pass GLO

Example: "15 01 01"

rd_code · string

For waste factors: RD disposal method code

Retrieve available options from GET /api/v1/wastes/rd_ler_list

Example: "R3"

Response

Returns the created custom emission factor object with generated ID.

Example

cURL

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": "[e-mail]",
    "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
  }'

Successful Response

{
  "id": "factor-uuid",
  "factor_id": "factor-uuid",
  "ef_name": "Recycled Aluminum - Supplier ABC",
  "unit_id": "kg-unit-uuid",
  "factor_uploaded_by": "[e-mail]",
  "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

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

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

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

{
  "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:

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:

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:

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:

# High confidence - supplier EPD
uncertainty_grade = 15

# Medium confidence - industry average
uncertainty_grade = 35

# Low confidence - estimate
uncertainty_grade = 65

Related Endpoints

List Factors

View all factors in a group

Update Factor

Modify existing factor

Create Group

Create a new emission group first

Overview

Learn about custom factors