Custom Emission Factor Databases - Dcycle Platform Docs

Dcycle calculates emissions with the factors of public databases (DEFRA, OCCC, ecoinvent, …). When you have a better factor of your own, for example one measured at your plant or provided by your waste manager, you can load it as a custom emission factor record and point your data at it.

Beta. The custom emission factors API is in beta: the contract may still change before general availability. Handle unknown fields in responses gracefully.

How it is organized

Custom factors live in three levels, the same way public databases do:

Database            e.g. "Acme measured factors"          (owned by your organization)
└── Version         e.g. "2024 measured", reference year 2024
    └── Record      e.g. "Mixed packaging – Ecoveza plant": 0.21 kg CO2e per kg

Level	What it is	Key fields
Database	A collection of factors owned by your organization. You can share it with your subsidiaries.	`name` (unique), `display_name`, `child_access`
Version	A release of the database, typically one per reference year. In the API its id is called `source_id`.	`version`, `reference_year`
Record	One emission factor: what it measures, in which unit, and its value per gas. Its `id` is what your data references (e.g. `custom_ef_record_id` on a waste).	`name`, `unit_id`, `tag`, `activity_categories`, `factors`

Records: units, gases and tags

A record’s unit_id is the unit of the activity (kilograms of waste, kWh, litres…). Each factor gives the emissions for one of those units, per gas:

`gas_type`	Unit of `value`
`co2e`	kg CO2e per unit of activity
`co2`	kg CO2 per unit of activity
`ch4`	g CH4 per unit of activity
`n2o`	g N2O per unit of activity

The record’s tag says which gases it carries:

`tag`	Factors required	Use it when
`simple`	exactly one `co2e`	You only know the total CO2e.
`advanced`	exactly one `co2`, one `ch4` and one `n2o`	You know each gas; Dcycle converts them to CO2e with your organization’s GWP values.
`full`	exactly one each of `co2e`, `co2`, `ch4` and `n2o`	You know the total and the breakdown.

A factor can be limited in time with start_date and end_date; by default it applies from 1970-01-01 onwards.

Activity categories

activity_categories says which kind of data may use the record. A record is only offered, and only accepted, for the categories it lists. For wastes, include wastes. Other values include stationary, electricity, transport, purchases, water, travels and hotel_stays. An unknown value is rejected with CUSTOM_RECORD_INVALID_CATEGORIES.

Using a record in your data

Pass the record’s id where the data asks for a custom factor. For wastes, that is custom_ef_record_id in POST /v2/wastes:

{
  "records": [
    {
      "facility_id": "660e8400-e29b-41d4-a716-446655440000",
      "identification_name": "ALB-2026-09-0001",
      "start_date": "2026-09-01",
      "end_date": "2026-09-30",
      "base_quantity": 1250.5,
      "unit_id": "61743a63-ff70-459c-9567-5eee8f7dfd5c",
      "custom_ef_record_id": "c3d4e5f6-a7b8-9012-cdef-ab3456789012"
    }
  ]
}

The record must be enabled, list the right activity category, and be visible to the organization that owns the data: its own databases, the databases its group shares with it, and those of its subsidiaries.

From zero to a usable factor

Create a database

POST /v1/emission-factors/custom-databases → keep its id.

Create a version

POST /v1/emission-factors/custom-databases/{database_id}/versions → keep its id (the source_id).

Create a record

POST /v1/emission-factors/custom-databases/{database_id}/versions/{source_id}/records → its id is the record id your data references.

BASE=https://api.dcycle.io/v1/emission-factors/custom-databases
H=(-H "x-api-key: ${DCYCLE_API_KEY}" -H "x-organization-id: ${DCYCLE_ORG_ID}" -H "Content-Type: application/json")

DATABASE_ID=$(curl -s -X POST "$BASE" "${H[@]}" \
  -d '{"name": "acme-measured-factors", "display_name": "Acme measured factors"}' | jq -r .id)

SOURCE_ID=$(curl -s -X POST "$BASE/$DATABASE_ID/versions" "${H[@]}" \
  -d '{"version": "2024 measured", "reference_year": 2024}' | jq -r .id)

curl -s -X POST "$BASE/$DATABASE_ID/versions/$SOURCE_ID/records" "${H[@]}" \
  -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"}]
  }' | jq -r .id

Authentication

Every endpoint takes the same headers as the rest of the API: x-api-key and x-organization-id. Only the organization that owns a database can change it, its versions and its records (otherwise 403 CUSTOM_DATABASE_NOT_OWNER); organizations it is shared with can read and use its records.

Endpoints

List Databases

Databases visible to your organization

Create Database

A new database owned by your organization

List Versions

Versions of a database

Create Version

A new version of a database

List Records

Records of a version, with search and paging

Get Record

One record by id

Create Record

A new emission factor

Update Record

Change a record

Delete Record

Remove a record

​How it is organized

​Records: units, gases and tags

​Activity categories

​Using a record in your data

​From zero to a usable factor

​Authentication

​Endpoints

List Databases

Create Database

List Versions

Create Version

List Records

Get Record

Create Record

Update Record

Delete Record

How it is organized

Records: units, gases and tags

Activity categories

Using a record in your data

From zero to a usable factor

Authentication

Endpoints