curl -X POST "https://api.dcycle.io/v1/emission-factors/custom-databases/5f1c2e7a-3b4d-4e8f-9a01-2c3d4e5f6a7b/versions/7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d/records" \
-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",
"unit_id": "61743a63-ff70-459c-9567-5eee8f7dfd5c",
"tag": "simple",
"activity_categories": [
"wastes"
],
"factors": [
{
"gas_type": "co2e",
"value": "0.21"
}
]
}'
import os
import requests
response = requests.post(
"https://api.dcycle.io/v1/emission-factors/custom-databases/5f1c2e7a-3b4d-4e8f-9a01-2c3d4e5f6a7b/versions/7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d/records",
headers={
"x-api-key": os.environ["DCYCLE_API_KEY"],
"x-organization-id": os.environ["DCYCLE_ORG_ID"],
},
json={
"name": "Mixed packaging - Ecoveza plant",
"unit_id": "61743a63-ff70-459c-9567-5eee8f7dfd5c",
"tag": "simple",
"activity_categories": [
"wastes"
],
"factors": [
{
"gas_type": "co2e",
"value": "0.21"
}
]
},
timeout=30,
)
response.raise_for_status()
print(response.json())
const axios = require('axios');
const response = await axios.post('https://api.dcycle.io/v1/emission-factors/custom-databases/5f1c2e7a-3b4d-4e8f-9a01-2c3d4e5f6a7b/versions/7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d/records', {
"name": "Mixed packaging - Ecoveza plant",
"unit_id": "61743a63-ff70-459c-9567-5eee8f7dfd5c",
"tag": "simple",
"activity_categories": [
"wastes"
],
"factors": [
{
"gas_type": "co2e",
"value": "0.21"
}
]
}, {
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",
"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"
}
]
}
Create Custom Record
Create a custom emission factor record
POST
/
v1
/
emission-factors
/
custom-databases
/
{database_id}
/
versions
/
{source_id}
/
records
curl -X POST "https://api.dcycle.io/v1/emission-factors/custom-databases/5f1c2e7a-3b4d-4e8f-9a01-2c3d4e5f6a7b/versions/7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d/records" \
-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",
"unit_id": "61743a63-ff70-459c-9567-5eee8f7dfd5c",
"tag": "simple",
"activity_categories": [
"wastes"
],
"factors": [
{
"gas_type": "co2e",
"value": "0.21"
}
]
}'
import os
import requests
response = requests.post(
"https://api.dcycle.io/v1/emission-factors/custom-databases/5f1c2e7a-3b4d-4e8f-9a01-2c3d4e5f6a7b/versions/7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d/records",
headers={
"x-api-key": os.environ["DCYCLE_API_KEY"],
"x-organization-id": os.environ["DCYCLE_ORG_ID"],
},
json={
"name": "Mixed packaging - Ecoveza plant",
"unit_id": "61743a63-ff70-459c-9567-5eee8f7dfd5c",
"tag": "simple",
"activity_categories": [
"wastes"
],
"factors": [
{
"gas_type": "co2e",
"value": "0.21"
}
]
},
timeout=30,
)
response.raise_for_status()
print(response.json())
const axios = require('axios');
const response = await axios.post('https://api.dcycle.io/v1/emission-factors/custom-databases/5f1c2e7a-3b4d-4e8f-9a01-2c3d4e5f6a7b/versions/7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d/records', {
"name": "Mixed packaging - Ecoveza plant",
"unit_id": "61743a63-ff70-459c-9567-5eee8f7dfd5c",
"tag": "simple",
"activity_categories": [
"wastes"
],
"factors": [
{
"gas_type": "co2e",
"value": "0.21"
}
]
}, {
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",
"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
A record is one emission factor. Its
A malformed body (missing field, wrong type) answers the standard validation format:
id is what your data references, e.g. custom_ef_record_id in POST /v2/wastes.
Beta. Part of the custom emission factors API, currently in beta. The contract may still change before general
availability.
curl -X POST "https://api.dcycle.io/v1/emission-factors/custom-databases/5f1c2e7a-3b4d-4e8f-9a01-2c3d4e5f6a7b/versions/7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d/records" \
-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",
"unit_id": "61743a63-ff70-459c-9567-5eee8f7dfd5c",
"tag": "simple",
"activity_categories": [
"wastes"
],
"factors": [
{
"gas_type": "co2e",
"value": "0.21"
}
]
}'
import os
import requests
response = requests.post(
"https://api.dcycle.io/v1/emission-factors/custom-databases/5f1c2e7a-3b4d-4e8f-9a01-2c3d4e5f6a7b/versions/7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d/records",
headers={
"x-api-key": os.environ["DCYCLE_API_KEY"],
"x-organization-id": os.environ["DCYCLE_ORG_ID"],
},
json={
"name": "Mixed packaging - Ecoveza plant",
"unit_id": "61743a63-ff70-459c-9567-5eee8f7dfd5c",
"tag": "simple",
"activity_categories": [
"wastes"
],
"factors": [
{
"gas_type": "co2e",
"value": "0.21"
}
]
},
timeout=30,
)
response.raise_for_status()
print(response.json())
const axios = require('axios');
const response = await axios.post('https://api.dcycle.io/v1/emission-factors/custom-databases/5f1c2e7a-3b4d-4e8f-9a01-2c3d4e5f6a7b/versions/7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d/records', {
"name": "Mixed packaging - Ecoveza plant",
"unit_id": "61743a63-ff70-459c-9567-5eee8f7dfd5c",
"tag": "simple",
"activity_categories": [
"wastes"
],
"factors": [
{
"gas_type": "co2e",
"value": "0.21"
}
]
}, {
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",
"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-5e6f7a8b9c0dBody Parameters
string
required
Record name, 1 to 255 characters. Make it recognizable: it is what users pick from.Example:
"Mixed packaging - Ecoveza plant"uuid
required
Unit of the activity the factor applies to (e.g. kilogram for wastes). Must match the unit your data will be in.Example:
"61743a63-ff70-459c-9567-5eee8f7dfd5c"string
required
Which gases the record carries.Available values:
simple (one co2e factor), advanced (one co2, one ch4 and one n2o), full (one of
each: co2e, co2, ch4, n2o).array[string]
required
At least one category that may use the record, e.g.
["wastes"]. See
Activity categories.array[object]
required
The factor values, one per gas, matching
tag. Each gas may appear once.Show factor fields
Show factor fields
string
required
Available values:
co2e, co2, ch4, n2o.number
required
Emissions per unit of activity: kg for
co2e and co2, grams for ch4 and n2o. Send it as a string
("0.21") to keep decimals exact.date
default:"1970-01-01"
First day the factor applies.
date | null
Last day it applies; omit for open-ended. Must be on or after
start_date.boolean
default:"true"
Disabled records stay in the database but new data cannot use them.
boolean
default:"false"
Report the CO2 factor as biogenic. Requires a
co2 factor, and only the stationary, process and transport
categories.number | null
Renewable share between 0 and 1. Electricity categories only.
number
default:"0"
Uncertainty grade of the factor.
Response
The created record (201 Created):
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.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": "..."}]}.
Related Endpoints
Get Record
One record by id
Update Record
Change a record
Was this page helpful?