> ## 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.

# Create Waste

> Create a new waste record for a facility

# Create Waste

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.

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

## Request

### Headers

<ParamField header="x-api-key" type="string" required>
  Your API key for authentication

  **Example:** `sk_live_1234567890abcdef`
</ParamField>

<ParamField header="x-organization-id" type="string" required>
  Your organization UUID

  **Example:** `a8315ef3-dd50-43f8-b7ce-d839e68d51fa`
</ParamField>

### Body Parameters

<ParamField body="facility_id" type="uuid" required>
  UUID of the facility this waste belongs to

  **Example:** `"660e8400-e29b-41d4-a716-446655440000"`
</ParamField>

<ParamField body="identification_name" type="string" required>
  Waste identification name or invoice number

  **Example:** `"RSU-2024-001"`
</ParamField>

<ParamField body="start_date" type="date" required>
  Start date of the waste period (ISO 8601 format)

  **Example:** `"2024-01-01"`
</ParamField>

<ParamField body="end_date" type="date" required>
  End date of the waste period (ISO 8601 format)

  **Example:** `"2024-03-31"`
</ParamField>

<ParamField body="base_quantity" type="number" required>
  Waste quantity in the specified unit. Must be greater than 0.

  **Example:** `1500.0`
</ParamField>

<ParamField body="description" type="string">
  Description of the waste

  **Example:** `"Municipal solid waste from office building"`
</ParamField>

<ParamField body="destination" type="string">
  Waste destination or treatment facility name

  **Example:** `"Waste treatment plant Madrid"`
</ParamField>

<ParamField body="total_km_to_waste_center" type="number">
  Distance to waste treatment center in kilometers

  **Example:** `25.0`
</ParamField>

<ParamField body="unit_id" type="uuid">
  UUID of the quantity unit. Defaults to kilograms if not specified.

  **Example:** `"61743a63-ff70-459c-9567-5eee8f7dfd5c"`
</ParamField>

<ParamField body="waste_efs_id" type="uuid">
  UUID of the waste emission factor (based on LER/RD code combination)

  **Example:** `"770e8400-e29b-41d4-a716-446655440000"`
</ParamField>

<ParamField body="custom_emission_factor_id" type="uuid">
  UUID of a custom emission factor. For organizations with custom emission data.

  **Example:** `"880e8400-e29b-41d4-a716-446655440000"`
</ParamField>

## Response

<ResponseField name="id" type="string">
  Unique identifier (UUID) for the waste record
</ResponseField>

<ResponseField name="identification_name" type="string">
  Waste identification name
</ResponseField>

<ResponseField name="description" type="string">
  Description of the waste
</ResponseField>

<ResponseField name="start_date" type="date">
  Start date of the waste period
</ResponseField>

<ResponseField name="end_date" type="date">
  End date of the waste period
</ResponseField>

<ResponseField name="base_quantity" type="number">
  Original waste quantity
</ResponseField>

<ResponseField name="quantity" type="number">
  Adjusted quantity after applying percentage allocation
</ResponseField>

<ResponseField name="percentage" type="number">
  Allocation percentage (0–1)
</ResponseField>

<ResponseField name="destination" type="string">
  Waste destination or treatment facility
</ResponseField>

<ResponseField name="total_km_to_waste_center" type="number">
  Distance to waste treatment center in km
</ResponseField>

<ResponseField name="status" type="string">
  Current status: `uploaded`, `active`, `loading`, or `error`
</ResponseField>

<ResponseField name="error_messages" type="array[string] | null">
  Error details when status is `error`
</ResponseField>

<ResponseField name="co2e" type="number">
  CO2 equivalent emissions in kg CO2e (calculated asynchronously)
</ResponseField>

<ResponseField name="co2e_biomass" type="number">
  Biogenic CO2 emissions in kg CO2e
</ResponseField>

<ResponseField name="enabled" type="boolean | null">
  Whether the waste record is enabled for emission calculations
</ResponseField>

<ResponseField name="file_id" type="string | null">
  UUID of the linked file (if created via bulk import)
</ResponseField>

<ResponseField name="file_name" type="string | null">
  Name of the linked import file
</ResponseField>

<ResponseField name="file_url" type="string | null">
  Download URL for the linked file
</ResponseField>

<ResponseField name="created_at" type="datetime">
  Timestamp when the record was created
</ResponseField>

<ResponseField name="updated_at" type="datetime | null">
  Timestamp when the record was last updated
</ResponseField>

## Example

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  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_efs_id": "770e8400-e29b-41d4-a716-446655440000"
    }'
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import requests
  import os

  api_key = os.getenv("DCYCLE_API_KEY")
  org_id = os.getenv("DCYCLE_ORG_ID")

  headers = {
      "x-api-key": api_key,
      "x-organization-id": org_id,
      "Content-Type": "application/json"
  }

  payload = {
      "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_efs_id": "770e8400-e29b-41d4-a716-446655440000"
  }

  response = requests.post(
      "https://api.dcycle.io/v1/wastes",
      headers=headers,
      json=payload
  )

  waste = response.json()
  print(f"Waste created: {waste['id']}")
  print(f"Status: {waste['status']}")
  ```

  ```javascript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const axios = require('axios');

  const apiKey = process.env.DCYCLE_API_KEY;
  const orgId = process.env.DCYCLE_ORG_ID;

  const headers = {
    'x-api-key': apiKey,
    'x-organization-id': orgId,
    'Content-Type': 'application/json'
  };

  const payload = {
    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_efs_id: "770e8400-e29b-41d4-a716-446655440000"
  };

  axios.post('https://api.dcycle.io/v1/wastes', payload, { headers })
    .then(response => {
      const waste = response.data;
      console.log(`Waste created: ${waste.id}`);
    })
    .catch(error => console.error(error));
  ```
</CodeGroup>

### Successful Response

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

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

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

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

<CardGroup cols={2}>
  <Card title="List Wastes" icon="list" href="/api-reference/wastes/list">
    Retrieve all waste records with filtering
  </Card>

  <Card title="Update Waste" icon="pencil" href="/api-reference/wastes/update">
    Modify an existing waste record
  </Card>

  <Card title="Facilities" icon="building" href="/api-reference/facilities/list">
    List facilities for your organization
  </Card>
</CardGroup>