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>"
}
'

POST

api

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_1234567890abcdef

string

required

Your organization UUIDExample: ff4adcc7-8172-45fe-9cf1-e90a6de53aa9

string

required

Your user UUIDExample: a1b2c3d4-e5f6-7890-abcd-ef1234567890

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

Minimum: At least CO2 must be provided

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

boolean

For waste factors: whether waste is hazardousExample: false

boolean

For waste/material factors: whether material is recycledExample: true

string

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

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

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

Custom Emission Factors List Custom Emission Factors

Introduction

Logistics

Facilities

Vehicles

Purchases

Wastes

Reference Data

Custom Emission Factors

Custom Emission Groups

Create Custom Emission Factor

Create Custom Emission Factor

Request

Headers

Path Parameters

Body Parameters

Response

Example

Successful Response

Common Errors

400 Bad Request - Invalid Group ID

422 Validation Error - Missing CO2

422 Validation Error - Invalid Tag

422 Validation Error - Invalid Uncertainty

Best Practices

1. Include All Relevant GHGs

2. Document Your Sources

3. Set Realistic Validity Periods

4. Be Honest About Uncertainty

List Factors

Update Factor

Create Group

Overview

​Create Custom Emission Factor

​Request

​Headers

​Path Parameters

​Body Parameters

​Response

​Example

​Successful Response

​Common Errors

​400 Bad Request - Invalid Group ID

​422 Validation Error - Missing CO2

​422 Validation Error - Invalid Tag

​422 Validation Error - Invalid Uncertainty

​Best Practices

​1. Include All Relevant GHGs

​2. Document Your Sources

​3. Set Realistic Validity Periods

​4. Be Honest About Uncertainty

​Related Endpoints

List Factors

Update Factor

Create Group

Overview

Create Custom Emission Factor

Request

Headers

Path Parameters

Body Parameters

Response

Example

Successful Response

Common Errors

400 Bad Request - Invalid Group ID

422 Validation Error - Missing CO2

422 Validation Error - Invalid Tag

422 Validation Error - Invalid Uncertainty

Best Practices

1. Include All Relevant GHGs

2. Document Your Sources

3. Set Realistic Validity Periods

4. Be Honest About Uncertainty

Related Endpoints