Wastes API

Manage waste records and calculate CO2e emissions from waste disposal

The Wastes API allows you to create, retrieve, update, and delete waste records within your organization’s facilities. Each waste record tracks disposal activities and enables automatic CO2e emissions calculations based on waste type, quantity, and disposal method.

New API: This endpoint is part of the new API architecture with improved design and maintainability.

Key Features

• Waste Tracking: Create and manage waste disposal records per facility
• Emission Factors: Link waste records to standard emission factors (LER/RD codes) or custom emission factors
• CO2e Calculation: Automatic emissions calculation based on waste type and quantity
• Flexible Units: Support for different quantity units with automatic conversion
• Pagination Support: Efficiently retrieve large lists of waste records

Authentication

All endpoints require authentication using an API key included in the x-api-key header.

Headers

All requests must include:

x-organization-id · string · required

Your organization UUID

Example: a8315ef3-dd50-43f8-b7ce-d839e68d51fa

x-api-key · string · required

Your API key for authentication

Example: sk_live_1234567890abcdef

Available Endpoints

List Wastes

Retrieve all waste records with filtering and pagination

Create Wastes (v2, beta)

Create one or up to 5,000 wastes in one request, with asynchronous calculation

Delete Wastes (v2, beta)

Delete up to 5,000 wastes by id, asynchronously

Update Waste

Modify waste record details

Create Waste (deprecated)

Superseded by Create Wastes (v2)

LER Codes

Look up waste_ler_code_id

R/D Codes

Look up waste_rd_code_id

waste_efs_id removed. The old single id for a LER + R/D pair is no longer accepted on create or update, and it has no effect if sent: send the LER code (waste_ler_code_id) and the treatment (waste_rd_code_id) separately. GET /v1/waste-efs stays read-only for existing records.

How Dcycle finds the emission factor: from the LER code (plus the R/D code when you send it), from the description when you have no codes, or from your own factor in custom_ef_record_id. A record needs at least one of the three. See How the emissions are calculated.

Waste Attributes

Core Information

• identification_name (string, required): Waste identification name or invoice number
• description (string, optional): Description of the waste
• start_date (date, required): Start date of the waste period
• end_date (date, required): End date of the waste period
• base_quantity (float, required): Waste quantity in the specified unit
• facility_id (UUID, required): UUID of the facility this waste belongs to

Disposal Details

• destination (string, optional): Waste destination or treatment facility
• provider_name (string, optional): Business name of the waste manager
• transporter_name (string, optional): Business name of the carrier, when it is not the waste manager
• total_km_to_waste_center (float, optional): Distance to waste center in km

Emission Configuration

• waste_ler_code_id (UUID): id of the LER code, from GET /v1/wastes/ler-codes. Required unless you send a description or a custom_ef_record_id
• waste_rd_code_id (UUID, optional): id of the R/D treatment code, from GET /v1/wastes/rd-codes
• unit_id (UUID): id of the quantity unit, from GET /v2/units. POST /v2/wastes requires kilograms (61743a63-ff70-459c-9567-5eee8f7dfd5c, the unit GET /v2/units?type=wastes lists), or the unit of the custom_ef_record_id record; there is no default
• custom_emission_factor_id (UUID, optional): Deprecated, no longer functional
• custom_ef_record_id (UUID, optional): id of one of your custom emission factor records

Read-Only Fields

• co2e (float): Calculated CO2 equivalent emissions in kg CO2e
• co2e_biomass (float): Biogenic CO2 emissions in kg CO2e
• status (string): Where the waste is in its calculation; the values are listed in Get Waste

Workflow

Creating wastes

1. Find the ids of the facility, the unit, the LER code and the R/D code: see Find the ids you send
2. Validate the batch with POST /v2/wastes?dry_run=true: every check runs and nothing is written
3. Send it with POST /v2/wastes: one or up to 5,000 records, stored at once, answered with an ingest job
4. Follow the calculation with GET /v2/ingest-jobs/{job_id}, or receive the ingest_job.finished webhook when it ends
5. Check the failures in the job’s items and read each waste with Get Waste

Response Format

Waste Object

{
  "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",
  "total_km_to_waste_center": 25.0,
  "status": "active",
  "co2e": 450.75,
  "co2e_biomass": 12.3,
  "enabled": true,
  "created_at": "2024-11-24T10:30:00Z",
  "updated_at": "2024-11-24T10:30:00Z"
}

Error Handling

Common HTTP Status Codes

Status	Meaning	Solution
200	Success	-
201	Created	-
202	Accepted: the records are stored and an ingest job calculates them (v2)	Follow the job in the Location header
400	Bad Request	Check request parameters and format
401	Unauthorized	Verify API key or JWT token
403	Forbidden	Facility doesn’t belong to your organization
404	Not Found	Check resource ID
422	Validation Error	Review error details in response
429	Too Many Requests	Wait Retry-After seconds; see Rate limits

The v2 endpoints (/v2/wastes) answer errors as problem details: branch on code, and read the list of problems in errors.

Related Documentation

Facilities API

Manage facilities where waste is generated

Scope 3 Category 5

Guide for waste-related emissions (GHG Protocol)