API Documentation

Welcome to the Env API. The API allows you to programmatically manage your sustainability data, track carbon emissions, and automate ESG compliance reporting.

ℹī¸
Base URL: All API requests should be made to https://api.env.com/v1

Authentication

The Env API uses Bearer token authentication. You can generate API keys from your Organization Settings.

curl -X GET https://api.env.com/v1/organizations \\
  -H "Authorization: Bearer your_api_key_here"
import requests

response = requests.get(
    "https://api.env.com/v1/organizations",
    headers={"Authorization": "Bearer your_api_key_here"}
)
const response = await fetch("https://api.env.com/v1/organizations", {
  headers: {
    "Authorization": "Bearer your_api_key_here"
  }
});

Get Carbon Footprint

Retrieves the current carbon footprint data for an organization, including scope 1, 2, and 3 emissions.

GET /v1/organizations/{org_id}/carbon-footprint

Returns aggregated emission data for the specified organization. Data is updated in near real-time as new measurements are ingested.

Parameters

Parameter Type Required Description
org_id string Required Unique identifier for the organization
period string Optional Time period: current_month, ytd, last_12_months
include_breakdown boolean Optional Include detailed scope breakdown (default: true)

Example Request

curl -X GET https://api.env.com/v1/organizations/org_123/carbon-footprint?period=ytd \\
  -H "Authorization: Bearer sk_live_abc123"

Response

{
  "id": "cf_98x7c6v5",
  "org_id": "org_123",
  "period": "ytd",
  "emissions": {
    "total": 1245.8,
    "unit": "tCO2e",
    "scope_1": 320.5,
    "scope_2": 480.2,
    "scope_3": 445.1
  },
  "targets": {
    "goal": 1100.0,
    "progress": 0.89,
    "on_track": true
  },
  "updated_at": "2025-01-15T10:30:00Z"
}

Create Emission Data

Submit emission measurements manually or from automated systems. This endpoint accepts batch data for efficiency.

POST /v1/emissions

Creates one or more emission records. Supports activities like electricity consumption, fuel usage, waste generation, and transportation.

Request Body

Field Type Required Description
activity_type string Required Type: electricity, natural_gas, vehicle_fuel, air_travel
amount number Required Quantity consumed
unit string Required Unit: kWh, kWh, liters, miles
date string Required ISO 8601 date when activity occurred
location object Optional Optional geolocation metadata

Example Request

curl -X POST https://api.env.com/v1/emissions \\
  -H "Authorization: Bearer sk_live_abc123" \\
  -H "Content-Type: application/json" \\
  -d '{
    "activity_type": "electricity",
    "amount": 4500.5,
    "unit": "kWh",
    "date": "2025-01-10",
    "location": {
      "facility": "HQ-Building-A",
      "grid_region": "US-WEST"
    }
  }'

Response (201 Created)

{
  "id": "em_7h8j9k0l",
  "status": "processed",
  "emissions_kg_co2e": 1823.4,
  "factor_source": "EPA 2024",
  "created_at": "2025-01-15T10:30:00Z"
}

Webhooks

Configure webhooks to receive real-time notifications when events occur in your Env account.

⚠ī¸
Security: All webhook payloads are signed using HMAC-SHA256. Verify the X-Env-Signature header before processing.

Events

Event Description
emission.created A new emission record was processed
footprint.updated Monthly carbon footprint calculation completed
target.milestone A sustainability target milestone was reached
compliance.alert Potential regulatory compliance issue detected

Errors

Env uses standard HTTP status codes to indicate success or failure of API requests.

Status Meaning Description
400 Bad Request Invalid request parameters
401 Unauthorized Missing or invalid API key
403 Forbidden API key lacks required permissions
404 Not Found Resource does not exist
429 Too Many Requests Rate limit exceeded
500 Server Error Internal server error

Rate Limits

To ensure API stability, Env enforces the following rate limits:

📊
  • Standard Plan: 100 requests per minute
  • Enterprise Plan: 1,000 requests per minute
  • Batch Endpoints: Up to 1,000 records per request