Create Waste

Create a new waste record for a facility

POST /v1/wastes

Create Waste

JavaScript

const options = {
  method: 'POST',
  headers: {
    'x-api-key': '<x-api-key>',
    'x-organization-id': '<x-organization-id>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    facility_id: '<string>',
    identification_name: '<string>',
    start_date: '<string>',
    end_date: '<string>',
    base_quantity: 123,
    description: '<string>',
    destination: '<string>',
    total_km_to_waste_center: 123,
    unit_id: '<string>',
    waste_ler_code_id: '<string>',
    waste_rd_code_id: '<string>',
    custom_emission_factor_id: '<string>',
    custom_ef_record_id: '<string>'
  })
};

fetch('https://api.dcycle.io/v1/wastes', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

200

{
  "id": "<string>",
  "identification_name": "<string>",
  "description": "<string>",
  "start_date": "<string>",
  "end_date": "<string>",
  "base_quantity": 123,
  "quantity": 123,
  "percentage": 123,
  "destination": "<string>",
  "total_km_to_waste_center": 123,
  "status": "<string>",
  "error_messages": {},
  "co2e": 123,
  "co2e_biomass": 123,
  "enabled": {},
  "file_id": {},
  "file_name": {},
  "file_url": {},
  "created_at": {},
  "updated_at": {}
}

← Wastes API

Deprecated. Use POST /v2/wastes: one or many wastes per request, idempotent, calculated asynchronously, with webhooks. This endpoint keeps working; its responses carry Deprecation and Link: </v2/wastes>; rel="successor-version" headers. A removal date (Sunset) will be announced in the changelog with notice.

Create a new waste disposal record linked to a specific facility. The waste record will be processed for CO2e emissions calculation based on the emission factor and quantity provided.

CO2e Calculation: After creation, emissions are automatically calculated using the specified emission factor or custom emission factor. The co2e field will be updated asynchronously.

waste_efs_id removed. The legacy catalog-based emission factor selector is no longer accepted — sending it in the request body has no effect. Every waste is created through the conversion-factors pipeline: pass waste_ler_code_id (required) and optionally waste_rd_code_id for a standard emission factor, or custom_ef_record_id for a custom 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: a8315ef3-dd50-43f8-b7ce-d839e68d51fa

Body Parameters

facility_id · uuid · required

UUID of the facility this waste belongs to

Retrieve available options from GET /v1/facilities

Example: "660e8400-e29b-41d4-a716-446655440000"

identification_name · string · required

Waste identification name or invoice number

Example: "RSU-2024-001"

start_date · date · required

Start date of the waste period (ISO 8601 format), a year from 1970 to next year

Example: "2024-01-01"

end_date · date · required

End date of the waste period (ISO 8601 format), a year from 1970 to next year, on or after start_date

Example: "2024-03-31"

base_quantity · number · required

Waste quantity in the specified unit. Must be greater than 0.

Example: 1500.0

description · string

Description of the waste

Example: "Municipal solid waste from office building"

destination · string

Waste destination or treatment facility name

Example: "Waste treatment plant Madrid"

total_km_to_waste_center · number

Distance to waste treatment center in kilometers

Example: 25.0

unit_id · uuid

UUID of the quantity unit. Defaults to kilograms if not specified.

Example: "61743a63-ff70-459c-9567-5eee8f7dfd5c"

waste_ler_code_id · uuid · required

UUID of the LER (European List of Waste) code. The pipeline resolves the emission factor from waste_matches keyed on (LER, R/D, source).

Retrieve available options from GET /v1/wastes/ler-codes

Example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"

waste_rd_code_id · uuid

Optional (roughly a third of records name no treatment). UUID of the R/D (recovery/disposal) operation code.

Retrieve available options from GET /v1/wastes/rd-codes — pass ler_code_id to restrict to codes valid for the chosen LER

Example: "b2c3d4e5-f6a7-8901-bcde-fa2345678901"

custom_emission_factor_id · uuid

Deprecated, no longer functional. Even if sent, it is never persisted — use custom_ef_record_id for a custom emission factor.

Example: "880e8400-e29b-41d4-a716-446655440000"

custom_ef_record_id · uuid

UUID of a custom emission-factor record. Transient input — it is not stored on the waste row, but persisted as a client_choice calculation config keyed on the waste, which the calculation pipeline consumes.

Mutually exclusive with custom_emission_factor_id.

Example: "c3d4e5f6-a7b8-9012-cdef-ab3456789012"

Response

id · string

Unique identifier (UUID) for the waste record

identification_name · string

Waste identification name

description · string

Description of the waste

start_date · date

Start date of the waste period

end_date · date

End date of the waste period

base_quantity · number

Original waste quantity

quantity · number

Adjusted quantity after applying percentage allocation

percentage · number

Allocation percentage (0–1)

destination · string

Waste destination or treatment facility

total_km_to_waste_center · number

Distance to waste treatment center in km

status · string

Current status: uploaded, active, loading, or error

error_messages · array[string] | null

Error details when status is error

co2e · number

CO2 equivalent emissions in kg CO2e (calculated asynchronously)

co2e_biomass · number

Biogenic CO2 emissions in kg CO2e

enabled · boolean | null

Whether the waste record is enabled for emission calculations

file_id · string | null

UUID of the linked file (if created via bulk import)

file_name · string | null

Name of the linked import file

file_url · string | null

Download URL for the linked file

created_at · datetime

Timestamp when the record was created

updated_at · datetime | null

Timestamp when the record was last updated

Example

cURL

curl -X POST "https://api.dcycle.io/v1/wastes" \
  -H "x-api-key: ${DCYCLE_API_KEY}" \
  -H "x-organization-id: ${DCYCLE_ORG_ID}" \
  -H "Content-Type: application/json" \
  -d '{
    "facility_id": "660e8400-e29b-41d4-a716-446655440000",
    "identification_name": "RSU-2024-001",
    "start_date": "2024-01-01",
    "end_date": "2024-03-31",
    "base_quantity": 1500.0,
    "description": "Municipal solid waste",
    "destination": "Waste treatment plant Madrid",
    "total_km_to_waste_center": 25.0,
    "waste_ler_code_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "waste_rd_code_id": "b2c3d4e5-f6a7-8901-bcde-fa2345678901"
  }'

Successful Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "identification_name": "RSU-2024-001",
  "description": "Municipal solid waste",
  "start_date": "2024-01-01",
  "end_date": "2024-03-31",
  "base_quantity": 1500.0,
  "quantity": 1500.0,
  "percentage": 1.0,
  "destination": "Waste treatment plant Madrid",
  "total_km_to_waste_center": 25.0,
  "status": "uploaded",
  "error_messages": null,
  "co2e": 0.0,
  "co2e_biomass": 0.0,
  "enabled": true,
  "file_id": null,
  "file_name": null,
  "file_url": null,
  "created_at": "2024-11-24T10:30:00Z",
  "updated_at": "2024-11-24T10:30:00Z"
}

Common Errors

401 Unauthorized

Cause: Missing or invalid API key

{
  "detail": "Invalid API key",
  "code": "INVALID_API_KEY"
}

Solution: Verify your API key is valid and active.

403 Forbidden

Cause: Facility doesn’t belong to your organization

{
  "detail": "Facility doesn't belong to organization",
  "code": "FACILITY_NOT_BELONG_TO_ORGANIZATION"
}

Solution: Verify that the facility_id belongs to your organization. Use the Facilities API to list available facilities.

422 Validation Error

Cause: Missing required fields or invalid values

{
  "detail": [
    {
      "loc": ["body", "base_quantity"],
      "msg": "ensure this value is greater than 0",
      "type": "value_error.number.not_gt"
    }
  ]
}

Solution: Check that all required fields are provided and values are valid.

Related Endpoints

List Wastes

Retrieve all waste records with filtering

Update Waste

Modify an existing waste record

Facilities

List facilities for your organization