Skip to main content

​
Wastes API

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 either:
  • API Key: Include in x-api-key header
  • JWT Token: Include in Authorization header as Bearer {JWT_TOKEN}

​
Headers

All requests must include:
​
x-organization-id
string
required
Your organization UUIDExample: a8315ef3-dd50-43f8-b7ce-d839e68d51fa
​
x-api-key
string
required
Your API key for authenticationExample: sk_live_1234567890abcdef

​
Available Endpoints

List Wastes

Retrieve all waste records with filtering and pagination

Create Waste

Add a new waste record to a facility

Update Waste

Modify waste record details

​
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
  • total_km_to_waste_center (float, optional): Distance to waste center in km

​
Emission Configuration

  • waste_efs_id (UUID, optional): UUID of the waste emission factor (LER/RD code combination)
  • unit_id (UUID, optional): UUID of the quantity unit (defaults to kg)
  • custom_emission_factor_id (UUID, optional): UUID of a custom emission factor

​
Read-Only Fields

  • co2e (float): Calculated CO2 equivalent emissions in kg CO2e
  • co2e_biomass (float): Biogenic CO2 emissions in kg CO2e
  • status (string): Current processing status

​
Workflow

​
Creating a Waste Record

  1. Identify the facility: Get the facility UUID from the Facilities API
  2. Find the emission factor (optional): Use waste LER/RD codes to find the appropriate waste_efs_id
  3. Create the waste record with quantity, dates, and emission factor
  4. CO2e is calculated automatically after creation

​
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

StatusMeaningSolution
200Success-
201Created-
400Bad RequestCheck request parameters and format
401UnauthorizedVerify API key or JWT token
403ForbiddenFacility doesn’t belong to your organization
404Not FoundCheck resource ID
422Validation ErrorReview error details in response

Facilities API

Manage facilities where waste is generated

Scope 3 Category 5

Guide for waste-related emissions (GHG Protocol)