API Documentation
ESG PULSE REST API v1
The ESG PULSE REST API allows you to programmatically push ESG data from your systems to our platform. Use this API to automate data collection from your ERP, IoT devices, utility providers, and other data sources.
Data Ingestion
Push emissions, water, waste, and energy data
Webhooks
Real-time notifications for data events
SDKs
Python, Node.js, and REST clients
Base URL
https://api.esgpulse.ai/v1Authentication
All API requests require authentication using an API key. Include your API key in theX-API-Keyheader with every request.
⚠️ Keep your API key secure. Never expose it in client-side code or public repositories.
Example Request
curl -X POST https://api.esgpulse.ai/v1/emissions \
-H "Content-Type: application/json" \
-H "X-API-Key: your_api_key_here" \
-d '{
"entries": [...]
}'Emissions API
/emissionsCreate new emission entries for Scope 1, 2, or 3 emissions.
Request Body
{
"entries": [
{
"scope": "scope1", // scope1, scope2, scope3
"category": "Stationary Combustion",
"source": "Natural Gas",
"activity_value": 1000,
"activity_unit": "m3",
"financial_year": "2024-25",
"facility_id": "uuid", // Optional
"notes": "Q1 consumption" // Optional
}
]
}Response (201 Created)
{
"success": true,
"data": {
"inserted": 1,
"entries": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"scope": "scope1",
"co2_equivalent": 1892.5, // Auto-calculated tCO2e
"verification_status": "pending_approval"
}
]
}
}/emissionsRetrieve emission entries with optional filters.
Query Parameters
| Parameter | Type | Description |
|---|---|---|
scope | string | Filter by scope (scope1, scope2, scope3) |
financial_year | string | Filter by financial year (e.g., 2024-25) |
facility_id | uuid | Filter by facility |
limit | integer | Max results to return (default: 100) |
Water API
/waterCreate water consumption and discharge entries.
Request Body
{
"entries": [
{
"source_type": "municipal", // municipal, groundwater, surface, rainwater, recycled
"consumption_kl": 500,
"discharge_kl": 350,
"wastewater_recycled_kl": 100,
"financial_year": "2024-25",
"facility_id": "uuid" // Optional
}
]
}Waste API
/wasteCreate waste generation and disposal entries.
Request Body
{
"entries": [
{
"waste_type": "hazardous", // hazardous, non_hazardous, e_waste, biomedical
"category": "Used Oil",
"quantity_kg": 250,
"disposal_method": "recycled", // landfill, recycled, incinerated, composted
"financial_year": "2024-25",
"facility_id": "uuid" // Optional
}
]
}Energy API
/energyCreate energy consumption entries.
Request Body
{
"entries": [
{
"energy_type": "electricity", // electricity, diesel, natural_gas, solar, wind
"consumption_kwh": 50000,
"is_renewable": false,
"financial_year": "2024-25",
"facility_id": "uuid" // Optional
}
]
}Webhooks
Configure webhooks to receive real-time notifications when data is created, updated, or when reports are generated.
Available Events
emission.createdemission.updatedemission.deletedwater.createdwaste.createdenergy.createdreport.generatedscore.calculatedalert.triggeredWebhook Payload Example
{
"event": "emission.created",
"timestamp": "2024-01-15T10:30:00Z",
"data": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"scope": "scope1",
"co2_equivalent": 1892.5,
"facility_id": "...",
"created_by": "api"
}
}SDKs & Libraries
Python SDK
pip install esgpulse
from esgpulse import Client
client = Client(api_key="your_key")
client.emissions.create({
"scope": "scope1",
"category": "Combustion",
"activity_value": 1000
})Node.js SDK
npm install @esgpulse/sdk
import { ESGPulse } from '@esgpulse/sdk';
const client = new ESGPulse('your_key');
await client.emissions.create({
scope: 'scope1',
category: 'Combustion',
activityValue: 1000
});