> ## Documentation Index
> Fetch the complete documentation index at: https://code.dcycle.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom Emission Factor Databases

> Bring your own emission factors: databases, versions and records your calculations can use

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.

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

## 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`](/api-reference/wastes/create-v2):

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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

<Steps>
  <Step title="Create a database">
    [`POST /v1/emission-factors/custom-databases`](/api-reference/custom-emission-factors/create-database) → keep its `id`.
  </Step>

  <Step title="Create a version">
    [`POST /v1/emission-factors/custom-databases/{database_id}/versions`](/api-reference/custom-emission-factors/create-version) → keep its `id` (the `source_id`).
  </Step>

  <Step title="Create a record">
    [`POST /v1/emission-factors/custom-databases/{database_id}/versions/{source_id}/records`](/api-reference/custom-emission-factors/create-record) → its `id` is the record id your data references.
  </Step>
</Steps>

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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

<CardGroup cols={2}>
  <Card title="List Databases" icon="list" href="/api-reference/custom-emission-factors/list-databases">
    Databases visible to your organization
  </Card>

  <Card title="Create Database" icon="plus" href="/api-reference/custom-emission-factors/create-database">
    A new database owned by your organization
  </Card>

  <Card title="List Versions" icon="list" href="/api-reference/custom-emission-factors/list-versions">
    Versions of a database
  </Card>

  <Card title="Create Version" icon="plus" href="/api-reference/custom-emission-factors/create-version">
    A new version of a database
  </Card>

  <Card title="List Records" icon="list" href="/api-reference/custom-emission-factors/list-records">
    Records of a version, with search and paging
  </Card>

  <Card title="Get Record" icon="magnifying-glass" href="/api-reference/custom-emission-factors/get-record">
    One record by id
  </Card>

  <Card title="Create Record" icon="plus" href="/api-reference/custom-emission-factors/create-record">
    A new emission factor
  </Card>

  <Card title="Update Record" icon="pencil" href="/api-reference/custom-emission-factors/update-record">
    Change a record
  </Card>

  <Card title="Delete Record" icon="trash" href="/api-reference/custom-emission-factors/delete-record">
    Remove a record
  </Card>
</CardGroup>