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));import requests
url = "https://api.dcycle.io/api/v1/custom_emission_factors/{id}"
payload = {
"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>"
}
headers = {
"x-api-key": "<x-api-key>",
"x-organization-id": "<x-organization-id>",
"x-user-id": "<x-user-id>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)curl --request POST \
--url https://api.dcycle.io/api/v1/custom_emission_factors/{id} \
--header 'Content-Type: application/json' \
--header 'x-api-key: <x-api-key>' \
--header 'x-organization-id: <x-organization-id>' \
--header 'x-user-id: <x-user-id>' \
--data '
{
"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>"
}
'Create Custom Emission Factor
Create a new custom emission factor within a group
POST
/
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));import requests
url = "https://api.dcycle.io/api/v1/custom_emission_factors/{id}"
payload = {
"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>"
}
headers = {
"x-api-key": "<x-api-key>",
"x-organization-id": "<x-organization-id>",
"x-user-id": "<x-user-id>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)curl --request POST \
--url https://api.dcycle.io/api/v1/custom_emission_factors/{id} \
--header 'Content-Type: application/json' \
--header 'x-api-key: <x-api-key>' \
--header 'x-organization-id: <x-organization-id>' \
--header 'x-user-id: <x-user-id>' \
--data '
{
"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>"
}
'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
string
required
Your API key for authenticationExample:
sk_live_1234567890abcdefstring
required
Your organization UUIDExample:
ff4adcc7-8172-45fe-9cf1-e90a6de53aa9string
required
Your user UUIDExample:
a1b2c3d4-e5f6-7890-abcd-ef1234567890Path Parameters
string
required
UUID of the Custom Emission Group to add this factor toExample:
"group-uuid-here"Body Parameters
string
required
Descriptive name for the emission factorExample:
"Recycled Aluminum - Supplier ABC"string
required
UUID of the measurement unit (from
/api/v1/units)Example: "kg-unit-uuid"string
required
Reference to person/team who uploaded this factorExample:
"sustainability_team@company.com"string
required
Complexity level of the factorValues:
"simple" or "advanced"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)
float
Confidence level of the factor (0-100%)Example:
15.5 (lower is more certain)date
Validity start date (YYYY-MM-DD)Example:
"2024-01-01"date
Validity end date (YYYY-MM-DD)Example:
"2024-12-31"string
Documentation reference or notesExample:
"EPD No. ABC-2024-001, Third-party verified"float
For energy factors: percentage of renewable content (0-100)Example:
100.0boolean
For waste factors: whether waste is hazardousExample:
falseboolean
For waste/material factors: whether material is recycledExample:
truestring
For waste factors: LER/LOW waste codeExample:
"15 01 01"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": "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
}'
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']}")
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));
Successful Response
{
"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{
"detail": "Custom emission group not found",
"code": "NOT_FOUND"
}
/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"
}
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"
}
"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"
}
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
Was this page helpful?