Skip to main content
POST
Create Historical Emission
← Historical Emissions Create a new manual emission entry. The scope is automatically derived from the category. The entry is included in your organization’s total emissions.

Request

Headers

string
required
Your API key for authenticationExample: sk_live_1234567890abcdef
string
required
Your organization UUIDExample: a8315ef3-dd50-43f8-b7ce-d839e68d51fa

Body Parameters

string
UUID of the company the entry belongs to: your organization (the default) or a company of its group you can write to. Any other id returns 403 Forbidden. Writing into another company requires a user (not a bare API key) who is a non-Viewer member of your organization.Example: "b7e2c1d4-1f2a-4c3b-9d8e-5a6b7c8d9e0f"
string
required
Start date of the emission period (ISO 8601)Example: "2022-01-01"
string
required
End date of the emission period. Must be greater than or equal to start_date.Example: "2022-12-31"
string
required
Emission category. Determines the GHG scope automatically.Scope 1: process, recharge, stationary, transport, waste_water_treatment_population, waste_water_treatment_sludge, waste_water_treatment_waterScope 2: electricityScope 3: purchases, travels, wastes, capex, employees_in_itinere, employees_in_labore, electricity_generation, electricity_transmission_and_distribution, stationary_generation, transport_generation, transport_distribution_upstream, transport_distribution_downstream, sold_products_waste, upstream_leased, downstream_leased, use_of_product_combustion, use_of_product_electricity, use_of_product_water, waste_water_treatment_discharge, water
number
required
Total CO2e emissions in kilograms. Must be greater than 0.Example: 45200.5
string
Free text description of the emission entryExample: "2022 electricity consumption from utility bills"
string
UUID of an uploaded evidence file to attach. It must be a file of your organization (or of a subsidiary you can write to); any other id returns 404 Not Found.
string
URL of the evidence file
string
Name of the evidence file (max 255 characters)

Response

Returns the created historical emission object with HTTP 201.
string
Historical emission UUID
string
Organization UUID
date
Start date of the emission period (ISO 8601)
date
End date of the emission period (ISO 8601)
integer
GHG scope automatically derived from category (1, 2, or 3)
string
Emission category (e.g. electricity, transport, purchases)
number
Total CO2e emissions in kilograms
string | null
Free text description of the emission entry
string
GHG gas type (e.g. co2e)
integer
GHG type: 0 = fossil, 1 = biomass
boolean
Whether this emission entry is enabled and included in totals
string | null
UUID of the attached evidence file
string | null
URL of the attached evidence file
string | null
Name of the attached evidence file
string | null
How the entry was created: manual (the app’s form or this API), bulk_file (a spreadsheet import in the app; source_file_id is that spreadsheet) or estimation (an employee commuting estimation). Null on entries created before 2026-10-23.
string | null
UUID of the spreadsheet a bulk_file entry was imported from. Apart from file_id, which is only the evidence attached to the entry. Null on every other entry.
datetime
Creation timestamp (ISO 8601)
string | null
Last update timestamp (ISO 8601)

Example

Successful Response

Common Errors

401 Unauthorized

Cause: Missing or invalid API key

403 Forbidden

Cause: The authenticated user is not a member of the organization
Cause: organization_id is outside your group’s companies you can write to, or the caller may not write into another company

404 Not Found

Cause: file_id is not a file that can document an entry of that company (it does not exist, is deleted, belongs to another organization, or is private to another company of your group)

422 Validation Error

Cause: end_date is before start_date
Cause: total_co2e is not positive
Aggregate figures recorded here are spread into total_impacts, the same table the activity-based calculations write to.

List

View all historical emissions

Update

Modify an existing entry