Skip to main content
POST
https://api.dcycle.io
/
api
/
v1
/
custom_emission_factors
/
{id}
Create Custom Emission Factor
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));

​
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.
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 authenticationExample: sk_live_1234567890abcdef
​
x-organization-id
string
required
Your organization UUIDExample: ff4adcc7-8172-45fe-9cf1-e90a6de53aa9
​
x-user-id
string
required
Your user UUIDExample: a1b2c3d4-e5f6-7890-abcd-ef1234567890

​
Path Parameters

​
id
string
required
UUID of the Custom Emission Group to add this factor toExample: "group-uuid-here"

​
Body Parameters

​
ef_name
string
required
Descriptive name for the emission factorExample: "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 factorExample: "[email protected]"
​
tag
string
required
Complexity level of the factorValues: "simple" or "advanced"
​
emission_factor_values
array
required
Array of emission values by gas typeEach 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 notesExample: "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 hazardousExample: false
​
recycled
boolean
For waste/material factors: whether material is recycledExample: true
​
low_code
string
For waste factors: LER/LOW waste codeExample: "15 01 01"
​
rd_code
string
For waste factors: RD disposal method codeExample: "R3"

​
Response

Returns the created custom emission factor object with generated ID.

​
Example

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": "[email protected]",
    "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": "[email protected]",
  "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

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

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

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

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

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