Update Custom Emission Factor

Update an existing custom emission factor

PATCH /api/v1/custom_emission_factors/{id}

Update Custom Emission Factor

JavaScript

const options = {
  method: 'PATCH',
  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({
    factor_uploaded_by: '<string>',
    ef_name: '<string>',
    emission_factor_values: [{}],
    additional_docs: '<string>',
    low_code: '<string>',
    rd_code: '<string>',
    hazardous: true,
    recycled: true
  })
};

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.

Update specific fields of an existing custom emission factor. Only the fields provided in the request will be updated.

You cannot update the following fields: tag, uncertainty_grade, factor_start_date, factor_end_date, or unit_id. To change these, delete the factor and create a new one.

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 Factor to update

Example: "factor-uuid-here"

Body Parameters

All fields are optional - only include the fields you want to update.

factor_uploaded_by · string · required

Reference to person/team responsible for this update

Example: "[e-mail]"

ef_name · string

Updated descriptive name for the emission factor

Example: "Recycled Aluminum - Supplier ABC (Q2 2024)"

emission_factor_values · array

Updated emission values by gas type. Must match the factor’s tag:

• Simple tag: Single co2e value
• Advanced tag: All three values (CO2, CH4, N2O)

Example:

[
  {"gas_type": "CO2", "value": 2.25},
  {"gas_type": "CH4", "value": 0.009},
  {"gas_type": "N2O", "value": 0.0025}
]

additional_docs · string

Updated documentation reference or notes

Example: "EPD No. ABC-2024-002, Updated Q2 2024"

low_code · string

For waste factors: Updated 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: Updated RD disposal method code

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

Example: "R3"

hazardous · boolean

For waste factors: Updated hazardous status

Example: false

recycled · boolean

For waste/material factors: Updated recycled status

Example: true

Response

Returns the complete updated custom emission factor object.

Example

cURL

curl -X PATCH "https://api.dcycle.io/api/v1/custom_emission_factors/factor-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 '{
    "factor_uploaded_by": "[e-mail]",
    "ef_name": "Recycled Aluminum - Supplier ABC (Updated Q2 2024)",
    "emission_factor_values": [
      {"gas_type": "CO2", "value": 2.25},
      {"gas_type": "CH4", "value": 0.009},
      {"gas_type": "N2O", "value": 0.0025}
    ],
    "additional_docs": "EPD No. ABC-2024-002, Updated with Q2 2024 data"
  }'

Use Cases

Update Emission Values

When supplier provides updated EPD data:

# Get current factor first
current_factor = requests.get(
    f"https://api.dcycle.io/api/v1/custom_emission_factors/{factor_id}",
    headers=headers
).json()

# Update only the emission values
response = requests.patch(
    f"https://api.dcycle.io/api/v1/custom_emission_factors/{factor_id}",
    headers=headers,
    json={
        "factor_uploaded_by": "[e-mail]",
        "emission_factor_values": [
            {"gas_type": "CO2", "value": 2.05},  # Improved process
            {"gas_type": "CH4", "value": 0.007},
            {"gas_type": "N2O", "value": 0.002}
        ],
        "additional_docs": f"{current_factor['additional_docs']} - Updated 2024-06-15"
    }
)

print(f"✅ Emission values updated")

Update Documentation Reference

Add audit trail information:

const factor = await axios.get(
  `https://api.dcycle.io/api/v1/custom_emission_factors/${factorId}`,
  { headers }
).then(res => res.data);

await axios.patch(
  `https://api.dcycle.io/api/v1/custom_emission_factors/${factorId}`,
  {
    factor_uploaded_by: '[e-mail]',
    additional_docs: `${factor.additional_docs} | Third-party verified by SGS on 2024-06-20`
  },
  { headers }
);

Update Waste Codes

Correct waste classification codes:

requests.patch(
    f"https://api.dcycle.io/api/v1/custom_emission_factors/{waste_factor_id}",
    headers=headers,
    json={
        "factor_uploaded_by": "[e-mail]",
        "low_code": "15 01 02",  # Corrected code
        "rd_code": "R4",
        "hazardous": False
    }
)

Common Errors

404 Not Found

Cause: Custom emission factor not found

{
  "detail": "Custom emission factor not found",
  "code": "NOT_FOUND"
}

Solution: Verify the factor ID exists.

422 Validation Error - Invalid Tag/Values Mismatch

Cause: The custom emission factor data custom emission factor values specified is invalid.

{
  "detail": "The custom emission factor data custom emission factor values specified is invalid.",
  "code": "VALIDATION_ERROR"
}

Solution: Ensure emission values match the factor’s tag:

• Simple tag requires: [{"gas_type": "co2e", "value": X}]
• Advanced tag requires: [{"gas_type": "CO2", ...}, {"gas_type": "CH4", ...}, {"gas_type": "N2O", ...}]

422 Validation Error - Negative Values

Cause: The custom emission factor value(s) specified is(are) invalid.

{
  "detail": "The custom emission factor value(s) specified is(are) invalid.",
  "code": "VALIDATION_ERROR"
}

Solution: Emission values must be non-negative (≥ 0).

Best Practices

1. Always Include Audit Trail

Document who made the change and why:

update_data = {
    "factor_uploaded_by": "[e-mail]",
    "additional_docs": f"{current_docs} | Updated 2024-06-15 by Jane Doe - New supplier data"
}

2. Validate Before Updating

Fetch current factor first to understand its structure:

# Get current factor
current = requests.get(f"https://api.dcycle.io/api/v1/custom_emission_factors/{factor_id}", headers=headers).json()

# Only update if tag is 'advanced'
if current['tag'] == 'advanced':
    # Safe to update with 3-gas values
    requests.patch(url, headers=headers, json=update_data)

3. Update Related Documentation

Keep additional_docs field up to date:

update_data = {
    "factor_uploaded_by": user_email,
    "emission_factor_values": new_values,
    "additional_docs": "EPD No. ABC-2024-002, Supersedes ABC-2024-001, Updated Q2 2024"
}

4. Cannot Update Immutable Fields

If you need to change tag, uncertainty_grade, unit_id, or validity dates:

1. Delete the existing factor
2. Create a new one with correct values

# Instead of trying to update unit_id (not allowed)
# Delete and recreate
requests.delete(f"https://api.dcycle.io/api/v1/custom_emission_factors/{factor_id}", headers=headers)
requests.post(f"https://api.dcycle.io/api/v1/custom_emission_factors/{group_id}", headers=headers, json=new_factor_data)

Related Endpoints

Get Factor

View current values

Delete Factor

Remove factor

Create Factor

Add new factor

Overview

Learn about custom factors