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

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

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

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: "sustainability_team@company.com"

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

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

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

Custom Emission Factors List Custom Emission Factors

​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