curl -X PATCH "https://api.dcycle.io/v1/emission-factors/custom-databases/5f1c2e7a-3b4d-4e8f-9a01-2c3d4e5f6a7b/versions/7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d/records/c3d4e5f6-a7b8-9012-cdef-ab3456789012" \
-H "x-api-key: ${DCYCLE_API_KEY}" \
-H "x-organization-id: ${DCYCLE_ORG_ID}" \
-H "Content-Type: application/json" \
-d '{
"name": "Mixed packaging - Ecoveza plant (2024)"
}'
import os
import requests
response = requests.patch(
"https://api.dcycle.io/v1/emission-factors/custom-databases/5f1c2e7a-3b4d-4e8f-9a01-2c3d4e5f6a7b/versions/7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d/records/c3d4e5f6-a7b8-9012-cdef-ab3456789012",
headers={
"x-api-key": os.environ["DCYCLE_API_KEY"],
"x-organization-id": os.environ["DCYCLE_ORG_ID"],
},
json={
"name": "Mixed packaging - Ecoveza plant (2024)"
},
timeout=30,
)
response.raise_for_status()
print(response.json())
const axios = require('axios');
const response = await axios.patch('https://api.dcycle.io/v1/emission-factors/custom-databases/5f1c2e7a-3b4d-4e8f-9a01-2c3d4e5f6a7b/versions/7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d/records/c3d4e5f6-a7b8-9012-cdef-ab3456789012', {
"name": "Mixed packaging - Ecoveza plant (2024)"
}, {
headers: {
'x-api-key': process.env.DCYCLE_API_KEY,
'x-organization-id': process.env.DCYCLE_ORG_ID,
},
});
console.log(response.status, response.data);
{
"id": "c3d4e5f6-a7b8-9012-cdef-ab3456789012",
"name": "Mixed packaging - Ecoveza plant (2024)",
"unit_id": "61743a63-ff70-459c-9567-5eee8f7dfd5c",
"source_id": "7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d",
"tag": "simple",
"additional_docs": null,
"evidence": [],
"uncertainty_grade": "0",
"is_biogenic": false,
"renewable_percentage": null,
"enabled": true,
"activity_categories": [
"wastes"
],
"factors": [
{
"id": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b",
"source_id": "7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d",
"concept_id": "2f3e4d5c-6b7a-4899-8a0b-2c3d4e5f6a7b",
"from_unit_id": "61743a63-ff70-459c-9567-5eee8f7dfd5c",
"to_unit_id": "0b1c2d3e-4f5a-4b6c-8d7e-9f0a1b2c3d4e",
"formula": "x * 0.21",
"start_date": "1970-01-01",
"end_date": null,
"gas_type": "co2e"
}
]
}
Update Custom Record
Change a custom emission factor record
PATCH
/
v1
/
emission-factors
/
custom-databases
/
{database_id}
/
versions
/
{source_id}
/
records
/
{record_id}
curl -X PATCH "https://api.dcycle.io/v1/emission-factors/custom-databases/5f1c2e7a-3b4d-4e8f-9a01-2c3d4e5f6a7b/versions/7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d/records/c3d4e5f6-a7b8-9012-cdef-ab3456789012" \
-H "x-api-key: ${DCYCLE_API_KEY}" \
-H "x-organization-id: ${DCYCLE_ORG_ID}" \
-H "Content-Type: application/json" \
-d '{
"name": "Mixed packaging - Ecoveza plant (2024)"
}'
import os
import requests
response = requests.patch(
"https://api.dcycle.io/v1/emission-factors/custom-databases/5f1c2e7a-3b4d-4e8f-9a01-2c3d4e5f6a7b/versions/7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d/records/c3d4e5f6-a7b8-9012-cdef-ab3456789012",
headers={
"x-api-key": os.environ["DCYCLE_API_KEY"],
"x-organization-id": os.environ["DCYCLE_ORG_ID"],
},
json={
"name": "Mixed packaging - Ecoveza plant (2024)"
},
timeout=30,
)
response.raise_for_status()
print(response.json())
const axios = require('axios');
const response = await axios.patch('https://api.dcycle.io/v1/emission-factors/custom-databases/5f1c2e7a-3b4d-4e8f-9a01-2c3d4e5f6a7b/versions/7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d/records/c3d4e5f6-a7b8-9012-cdef-ab3456789012', {
"name": "Mixed packaging - Ecoveza plant (2024)"
}, {
headers: {
'x-api-key': process.env.DCYCLE_API_KEY,
'x-organization-id': process.env.DCYCLE_ORG_ID,
},
});
console.log(response.status, response.data);
{
"id": "c3d4e5f6-a7b8-9012-cdef-ab3456789012",
"name": "Mixed packaging - Ecoveza plant (2024)",
"unit_id": "61743a63-ff70-459c-9567-5eee8f7dfd5c",
"source_id": "7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d",
"tag": "simple",
"additional_docs": null,
"evidence": [],
"uncertainty_grade": "0",
"is_biogenic": false,
"renewable_percentage": null,
"enabled": true,
"activity_categories": [
"wastes"
],
"factors": [
{
"id": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b",
"source_id": "7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d",
"concept_id": "2f3e4d5c-6b7a-4899-8a0b-2c3d4e5f6a7b",
"from_unit_id": "61743a63-ff70-459c-9567-5eee8f7dfd5c",
"to_unit_id": "0b1c2d3e-4f5a-4b6c-8d7e-9f0a1b2c3d4e",
"formula": "x * 0.21",
"start_date": "1970-01-01",
"end_date": null,
"gas_type": "co2e"
}
]
}
← Custom Emission Factors
Send only the fields to change.
A malformed body (missing field, wrong type) answers the standard validation format:
factors, when sent, replaces all of the record’s factors.
Beta. Part of the custom emission factors API, currently in beta. The contract may still change before general
availability.
curl -X PATCH "https://api.dcycle.io/v1/emission-factors/custom-databases/5f1c2e7a-3b4d-4e8f-9a01-2c3d4e5f6a7b/versions/7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d/records/c3d4e5f6-a7b8-9012-cdef-ab3456789012" \
-H "x-api-key: ${DCYCLE_API_KEY}" \
-H "x-organization-id: ${DCYCLE_ORG_ID}" \
-H "Content-Type: application/json" \
-d '{
"name": "Mixed packaging - Ecoveza plant (2024)"
}'
import os
import requests
response = requests.patch(
"https://api.dcycle.io/v1/emission-factors/custom-databases/5f1c2e7a-3b4d-4e8f-9a01-2c3d4e5f6a7b/versions/7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d/records/c3d4e5f6-a7b8-9012-cdef-ab3456789012",
headers={
"x-api-key": os.environ["DCYCLE_API_KEY"],
"x-organization-id": os.environ["DCYCLE_ORG_ID"],
},
json={
"name": "Mixed packaging - Ecoveza plant (2024)"
},
timeout=30,
)
response.raise_for_status()
print(response.json())
const axios = require('axios');
const response = await axios.patch('https://api.dcycle.io/v1/emission-factors/custom-databases/5f1c2e7a-3b4d-4e8f-9a01-2c3d4e5f6a7b/versions/7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d/records/c3d4e5f6-a7b8-9012-cdef-ab3456789012', {
"name": "Mixed packaging - Ecoveza plant (2024)"
}, {
headers: {
'x-api-key': process.env.DCYCLE_API_KEY,
'x-organization-id': process.env.DCYCLE_ORG_ID,
},
});
console.log(response.status, response.data);
{
"id": "c3d4e5f6-a7b8-9012-cdef-ab3456789012",
"name": "Mixed packaging - Ecoveza plant (2024)",
"unit_id": "61743a63-ff70-459c-9567-5eee8f7dfd5c",
"source_id": "7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d",
"tag": "simple",
"additional_docs": null,
"evidence": [],
"uncertainty_grade": "0",
"is_biogenic": false,
"renewable_percentage": null,
"enabled": true,
"activity_categories": [
"wastes"
],
"factors": [
{
"id": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b",
"source_id": "7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d",
"concept_id": "2f3e4d5c-6b7a-4899-8a0b-2c3d4e5f6a7b",
"from_unit_id": "61743a63-ff70-459c-9567-5eee8f7dfd5c",
"to_unit_id": "0b1c2d3e-4f5a-4b6c-8d7e-9f0a1b2c3d4e",
"formula": "x * 0.21",
"start_date": "1970-01-01",
"end_date": null,
"gas_type": "co2e"
}
]
}
Request
Headers
string
required
Your API key for authenticationExample:
sk_live_1234567890abcdefstring
required
Your organization UUIDExample:
a8315ef3-dd50-43f8-b7ce-d839e68d51fastring
required
Must be
application/jsonuuid
required
The database id.Example:
5f1c2e7a-3b4d-4e8f-9a01-2c3d4e5f6a7buuid
required
The version id (
id of the version).Example: 7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0duuid
required
The record id.Example:
c3d4e5f6-a7b8-9012-cdef-ab3456789012Body Parameters
The fields of Create Record, all optional:name, unit_id, tag, activity_categories, factors, enabled, is_biogenic, renewable_percentage,
uncertainty_grade.
Changing
unit_id, tag or is_biogenic requires sending factors too (422 CUSTOM_RECORD_FACTORS_REQUIRED).
Once data uses the record, its factors and activity_categories can no longer be changed
(409 CUSTOM_RECORD_IN_USE): create a new record instead, or disable this one with "enabled": false.Response
The updated record:uuid
Record id: the value your data references (e.g.
custom_ef_record_id on a waste).string
Record name.
uuid
Unit of the activity the factor applies to.
uuid
Version the record belongs to.
string
Available values:
simple, advanced, full.array[string]
Categories that can use the record.
boolean
Only enabled records can be used by new data.
boolean
Whether the CO2 factor is reported as biogenic.
number | null
Renewable share (electricity only).
number
Uncertainty grade.
string | null
URL of the first evidence document, if any.
array[object]
Evidence documents:
file_id, file_name, file_url, size_kb.array[object]
One per gas.
Show factor fields
Show factor fields
uuid
Factor id.
string
co2e, co2, ch4 or n2o.string
The factor applied to the activity quantity
x, e.g. x * 0.21.uuid
The record’s
unit_id.uuid
Unit of the result: kg CO2e, kg CO2, g CH4 or g N2O.
date
First day the factor applies.
date | null
Last day it applies;
null means open-ended.uuid
Version of the record.
uuid
Internal concept id.
Common Errors
401 Unauthorized
Missing or invalid API key.403 Forbidden
LOGGED_USER_NOT_MEMBER: the API key’s user is not a member of the organization in x-organization-id.
404 Not Found
CUSTOM_DATABASE_NOT_FOUND or CUSTOM_VERSION_NOT_FOUND: the database or version does not exist or is not visible to
your organization.
403 CUSTOM_DATABASE_NOT_OWNER
Only the organization that owns the database can create or change its records.404 CUSTOM_RECORD_NOT_FOUND
The record does not exist in that version or is not visible.409 CUSTOM_RECORD_IN_USE
Data already uses the record, so its factors or activity categories cannot change.422 Unprocessable Entity
code | Cause |
|---|---|
CUSTOM_RECORD_INVALID_FACTORS | The factors do not match tag (e.g. a simple record without exactly one co2e). |
CUSTOM_RECORD_INVALID_CATEGORIES | An activity_categories value does not exist. |
CUSTOM_RECORD_BIOGENIC_CATEGORY | is_biogenic on a category other than stationary, process or transport. |
CUSTOM_RECORD_BIOGENIC_REQUIRES_CO2 | is_biogenic without a co2 factor. |
CUSTOM_RECORD_RENEWABLE_CATEGORY | renewable_percentage on a non-electricity category. |
{"detail": [{"loc": [...], "msg": "...", "type": "..."}]}.
Also CUSTOM_RECORD_FACTORS_REQUIRED: unit_id, tag or is_biogenic changed without new factors.
Related Endpoints
Get Record
One record by id
Delete Record
Remove a record
Was this page helpful?