# 1ClickImpact API - Full Reference

Last verified 2026-08-16. Maintained by 1ClickImpact, Inc. - canonical source for API behavior.

Base URL (Production): https://api.1clickimpact.com
Base URL (Sandbox):    https://sandbox.1clickimpact.com
Auth Header: x-api-key: YOUR_API_KEY

Related AI / LLM index files:
- Main site: https://1clickimpact.com/llms.txt and https://1clickimpact.com/llms-full.txt
- Shopify app help: https://help.1clickimpact.com/llms.txt
- This API reference (short): https://docs.1clickimpact.com/llms.txt

---

## WhoAmI
GET /v1/whoami
Description: Verify your API key and retrieve your account details.
Headers: x-api-key: YOUR_API_KEY

Response example:
{
  "user_id": "U123",
  "email": "my-email@email.com"
}

---

## Plant Trees
POST /v1/plant_tree
Description: Plant trees for your organization or on behalf of a customer. Each unit = 1 tree.
Headers: Content-Type: application/json, x-api-key: YOUR_API_KEY

Request body:
{
  "amount": 5,
  "customer_email": "optional@email.com",
  "customer_name": "Optional Name",
  "category": "food",
  "notify": true,
  "metadata": { "order_id": "ORD-456", "source": "shopify" }
}
- amount (required): number of trees to plant (1-10,000,000)
- customer_email (optional): plants on behalf of a customer; triggers customer tracking
- customer_name (optional): display name for the customer; customer_email must be present
- category (optional): only supported value is "food" - plants food-bearing trees providing nutrition/income for local communities and grants access to exclusive live planting sessions. If omitted, standard reforestation trees are planted.
- notify (optional): send email notification to customer (default: true). Always disabled in sandbox.
- metadata (optional): object of key-value pairs for storing additional information about the impact. Keys: strings up to 40 chars. Values: strings up to 500 chars. Max 20 pairs. Reserved keys (`gift`, `widgetID`) cannot be used.

Response example:
{
  "user_id": "U123",
  "tree_planted": 5,
  "time_utc": "2024-09-16T20:34:04.429Z"
}

---

## Clean Ocean
POST /v1/clean_ocean
Description: Remove ocean plastic waste. Amount is in lbs.
Headers: Content-Type: application/json, x-api-key: YOUR_API_KEY

Request body:
{
  "amount": 5,
  "customer_email": "optional@email.com",
  "customer_name": "Optional Name",
  "notify": true,
  "metadata": { "cleanup_site": "Pacific Coast", "event": "World Ocean Day 2024" }
}
- amount (required): lbs of waste to remove (1-10,000,000)
- customer_email (optional): removes on behalf of a customer
- customer_name (optional): customer_email must be present
- notify (optional): email notification to customer (default: true). Always disabled in sandbox.
- metadata (optional): object of key-value pairs for storing additional information about the impact. Keys: strings up to 40 chars. Values: strings up to 500 chars. Max 20 pairs. Reserved keys (`gift`, `widgetID`) cannot be used.

Response example:
{
  "user_id": "U123",
  "waste_removed": 5,
  "time_utc": "2024-09-16T20:34:04.429Z"
}

---

## Capture Carbon
POST /v1/capture_carbon
Description: Capture/offset CO2 emissions. Amount is in lbs.
Headers: Content-Type: application/json, x-api-key: YOUR_API_KEY

Request body:
{
  "amount": 5,
  "customer_email": "optional@email.com",
  "customer_name": "Optional Name",
  "notify": true,
  "metadata": { "facility": "Portland Plant", "batch": "B-2024-09" }
}
- amount (required): lbs of CO2 to capture (1-10,000,000)
- customer_email (optional): captures on behalf of a customer
- customer_name (optional): customer_email must be present
- notify (optional): email notification to customer (default: true). Always disabled in sandbox.
- metadata (optional): object of key-value pairs for storing additional information about the impact. Keys: strings up to 40 chars. Values: strings up to 500 chars. Max 20 pairs. Reserved keys (`gift`, `widgetID`) cannot be used.

Response example:
{
  "user_id": "U123",
  "carbon_captured": 5,
  "time_utc": "2024-09-16T20:34:04.429Z"
}

---

## Restore Coral
POST /v1/restore_coral
Description: Fund coral reef restoration by outplanting coral fragments. Amount is the number of coral fragments. As a reference, ~15 fragments rebuild 1 reef structure, and each fragment restores ~144 cm² (22.32 in²) of reef. The API returns the raw coral_restored count; derive structures (÷ 15) or reef area (× 144 cm² / × 22.32 in²) client-side.
Headers: Content-Type: application/json, x-api-key: YOUR_API_KEY

Request body:
{
  "amount": 20,
  "customer_email": "optional@email.com",
  "customer_name": "Optional Name",
  "notify": true,
  "metadata": { "reef_site": "Great Barrier Reef" }
}
- amount (required): number of coral fragments to restore (1-10,000,000)
- customer_email (optional): restores on behalf of a customer
- customer_name (optional): customer_email must be present
- notify (optional): email notification to customer (default: true). Always disabled in sandbox.
- metadata (optional): object of key-value pairs for storing additional information about the impact. Keys: strings up to 40 chars. Values: strings up to 500 chars. Max 20 pairs. Reserved keys (`gift`, `widgetID`) cannot be used.

Response example:
{
  "user_id": "U123",
  "coral_restored": 20,
  "time_utc": "2024-09-16T20:34:04.429Z"
}

---

## Donate Money
POST /v1/donate_money
Description: Make a charitable donation. Amount is in the smallest currency unit (cents for USD). Supports optional `category` to tag donations with a specific cause.
Headers: Content-Type: application/json, x-api-key: YOUR_API_KEY

Request body:
{
  "amount": 500,
  "category": "hunger",
  "customer_email": "optional@email.com",
  "customer_name": "Optional Name",
  "notify": true,
  "metadata": { "charity": "PayPal Giving Fund", "campaign": "holiday-2024" }
}
- amount (required): smallest USD units (e.g. 10 = $0.10, 100 = $1.00, 500 = $5.00). Range 1-1,000,000,000.
- category (optional): donation cause category ID. The full cause label will appear in the /v1/track response as `donation_category`. Valid values:
  - "veterans" -> Veterans Support
  - "animals" -> Animal Welfare
  - "hunger" -> Hunger Relief
  - "education" -> Education
  - "climate" -> Climate Action
  - "water" -> Clean Water
  - "healthcare" -> Healthcare
  - "housing" -> Housing & Shelter
  - "youth" -> Youth Development
  - "disaster" -> Disaster Relief
- customer_email (optional): donates on behalf of a customer
- customer_name (optional): customer_email must be present
- notify (optional): email notification to customer (default: true). Always disabled in sandbox.
- metadata (optional): object of key-value pairs for storing additional information about the impact. Keys: strings up to 40 chars. Values: strings up to 500 chars. Max 20 pairs. Reserved keys (`gift`, `widgetID`) cannot be used.

Response example:
{
  "user_id": "U123",
  "money_donated": 500,
  "category": "hunger",
  "time_utc": "2024-09-16T20:34:04.429Z"
}

---

## Cancel Impact
POST /v1/cancel_impact
Description: Cancel and reverse a previously created impact. Designed for refund flows. Removes the impact from aggregate totals, reverses usage billing, and marks the impact as cancelled in the tracking system. The original record is preserved for audit purposes. Idempotent - calling multiple times returns the same result without double-reversing.
Headers: Content-Type: application/json, x-api-key: YOUR_API_KEY

Request body:
{
  "user_id": "U1234",
  "time_utc": "2025-03-12T15:22:14.753Z",
  "reason": "order refunded"
}
- user_id (required): the user ID associated with the impact to cancel (format U12345). From /v1/records or /v1/customer_records.
- time_utc (required): the UTC timestamp of the original impact (ISO 8601 format). From /v1/records or /v1/customer_records.
- reason (optional): reason for cancellation (max 200 characters).

Response example:
{
  "user_id": "U1234",
  "time_utc": "2025-03-12T15:22:14.753Z",
  "cancelled_on": "2025-04-30T10:15:32.000Z",
  "reason": "order refunded",
  "tree_planted": 10,
  "category": "food",
  "message": "impact cancelled successfully"
}

Response fields:
  - user_id: the user ID associated with the cancelled impact
  - time_utc: the UTC timestamp of the original impact
  - cancelled_on: UTC time when the impact was cancelled
  - reason: cancellation reason if provided (optional)
  - tree_planted / waste_removed / carbon_captured / coral_restored / money_donated: original impact amounts that were reversed (only non-zero fields present)
  - category: category of the cancelled impact if one was set (optional)
  - message: "impact cancelled successfully" for new cancellations, "impact was already cancelled" for repeat calls

Notes:
  - Impacts that have already been processed (donation received by a non-profit) cannot be cancelled via the API. Contact 1ClickImpact for assistance.
  - You are not charged for cancelled impacts - usage billing is automatically reversed.
  - The /v1/track response for a cancelled impact will show `cancelled_on` and `cancellation_reason` fields.

---

## Website Carbon
GET /v1/carbon
Description: Calculate the carbon footprint of any website. Returns CO2 emissions per page view, carbon rating (A+ to F), green hosting status, and energy statistics using V4 of the Sustainable Web Design Model. Results are cached for 7 days.
Headers: x-api-key: YOUR_API_KEY
Query params:
  - url (required): website URL to analyze (e.g., "example.com" or "https://example.com/page"). Subdomains supported. Redirects followed automatically. Max 2048 characters.
  - recalculate (optional): "true" to bypass cache and force fresh analysis. Default: false.

Response example:
{
  "url": "example.com",
  "cleaner_than": 0.91,
  "rating": "A",
  "green_hosting": false,
  "statistics": {
    "transfer_size": 495573,
    "energy": 0.000139,
    "co2": {
      "grid": {
        "grams": 0.068
      },
      "renewable": {
        "grams": 0.057
      }
    }
  },
  "tested_on": "2026-04-21"
}

Response fields:
  - url: normalized URL analyzed (lowercase, no protocol, no trailing slash)
  - cleaner_than: 0.0-1.0 - fraction of websites this page is cleaner than (e.g., 0.91 = cleaner than 91%)
  - rating: carbon grade - A+ (<=0.040g), A (<=0.079g), B (<=0.145g), C (<=0.209g), D (<=0.278g), E (<=0.359g), F (>0.359g)
  - green_hosting: whether the host uses renewable energy (verified by Green Web Foundation)
  - statistics.transfer_size: total page weight in bytes
  - statistics.energy: kWh consumed per page view
  - statistics.co2.grid.grams: grams CO2 per view assuming standard grid energy (494 gCO2e/kWh)
  - statistics.co2.renewable.grams: grams CO2 per view assuming renewable energy for data center portion
  - tested_on: date analyzed (YYYY-MM-DD), cached for 7 days

Notes:
  - Sandbox keys (test_ prefix) return a mock response with sample data
  - First analysis of a URL may take up to 30 seconds; subsequent requests return cached results instantly
  - The API verifies the URL is reachable before analysis; unreachable sites return an error

---

## AI Energy
POST /v1/ai_energy/calculate
Description: Estimate the electricity (Wh), water (mL), and carbon (gCO2e) of running any AI model (GPT, Claude, Gemini, Llama, DeepSeek, Grok, Kimi, and more) at your usage. Returns p5/median/p95 uncertainty bands per query, per month, and per year, plus an energy breakdown, human-scale equivalents, resolved assumptions, and a confidence report. Models energy from the tokens up with a Monte-Carlo over uncertain coefficients. Covers 45+ models across 9 providers. Each call counts as 1 API call.
Headers: x-api-key: YOUR_API_KEY, Content-Type: application/json
Required body fields:
  - model_id (string): model to estimate, e.g. "claude-fable-5", "gpt-5.5", "gemini-3-pro". Use "generic-frontier" for a provider-agnostic frontier model. See GET /v1/ai_energy/options for the full list.
  - scale (object): monthly volume. { "mode": "queries" | "tokens" | "users", "queries_per_month": 1000000 }
Optional body fields:
  - region_id (string): grid & water region, e.g. "us-average" (default), "fr", "in", "eu-average"
  - workload_id (string): task preset, e.g. "chat" (default), "rag", "code-agent", "reasoning"
  - regime_id (string): serving/batching regime, e.g. "production-saturated" (default), "balanced", "single-stream"
  - boundary_id (string): "accelerator" | "node" | "comprehensive" (default)
  - input_tokens / output_tokens (number): override the workload's median token counts (output length is the biggest driver)
  - cache_hit_rate (number 0-1): share of input tokens served from a prompt cache
  - reasoning (boolean): switch a hybrid model into extended-thinking mode (much higher energy)
  - input_modality (string): "text" (default) | "image" | "video"
  - include_embodied (boolean): include manufacturing emissions in co2e_total (default true)
  - samples (integer): Monte-Carlo sample count (default 4000)

Request example:
{
  "model_id": "claude-fable-5",
  "workload_id": "chat",
  "region_id": "us-average",
  "scale": { "mode": "queries", "queries_per_month": 1000000 }
}

Response example (abridged):
{
  "per_query": {
    "energy":     { "p5": 0.033, "p50": 0.262, "p95": 0.980, "mean": 0.350 },
    "water_total":{ "p5": 0.522, "p50": 1.037, "p95": 2.001, "mean": 1.113 },
    "co2e_total": { "p5": 0.070, "p50": 0.130, "p95": 0.241, "mean": 0.138 }
  },
  "per_month": { "energy": { "p50": 314.5 }, "co2e_total": { "p50": 129.7 } },
  "per_year":  { "energy": { "p50": 3775 },  "co2e_total": { "p50": 1556 } },
  "confidence": { "overall": "estimated", "uncertainty_factor": 3.84 },
  "units": { "per_query.energy": "Wh", "per_month.energy": "kWh", "per_query.co2e": "g", "per_month.co2e": "kg" },
  "data_version": "2026.08"
}

Response fields:
  - per_query / per_month / per_year: energy, water_total/onsite/offsite, and co2e_location_based/market_based/embodied/total. Each is a band with p5, p50 (median), p95, mean. Units: per_query = Wh / mL / g; per_month & per_year = kWh / L / kg.
  - breakdown: where energy goes in percent (accelerator, host, idle capacity, facility overhead, prefill, decode, cache savings)
  - equivalents: human-scale comparisons keyed by carbon, energy, water (e.g. tree-years, phone charges, showers)
  - assumptions: every resolved input echoed back (model, provider, hardware, region, tokens, PUE, grid & water intensities, queries_per_month, ...)
  - confidence.overall: "measured" | "derived" | "estimated"; uncertainty_factor is P95/P5 on monthly energy
  - warnings: scenario-specific caveats (array, possibly empty); sources: citations behind the coefficients used
  - units: map of each field path to its unit; data_version: coefficient dataset version (e.g. 2026.08)

GET /v1/ai_energy/options
Description: Returns the full catalog needed to build a calculate request or render a UI - all models, providers, hardware, regions, workloads, regimes, boundaries, and the current default ids. Read-only; requires an API key and counts as 1 API call. Cache the response and refresh when data_version changes.
Headers: x-api-key: YOUR_API_KEY
Response fields: data_version, schema_version, models[], models_by_provider{}, providers{}, hardware{}, regions[], workloads[], regimes[], boundaries[], generative_units[], defaults{}

Notes:
  - Only model_id and scale are required for calculate; every other field falls back to a documented default from /v1/ai_energy/options
  - Numbers are informed estimates, not meter readings - always read the P5-P95 range, not just the midpoint
  - Closed models (GPT, Claude, Gemini) publish no specs, so their figures are inferred from comparable open-weight models and flagged "estimated" with a wider band
  - To neutralize the footprint, pass the monthly co2e_total to POST /v1/capture_carbon (amount in lbs)
  - Methodology: https://1clickimpact.com/ai-energy-calculator/methodology ; FAQ: https://1clickimpact.com/ai-energy-calculator/faq

---

## Aggregated Impact
GET /v1/impact
Description: Returns total lifetime impact across all categories, including top-level totals and a breakdown between your direct impact (user_impact) and impact generated on behalf of customers (customer_impact).
Headers: x-api-key: YOUR_API_KEY

Response example:
{
  "user_id": "U123",
  "tree_planted": 100,
  "waste_removed": 50,
  "carbon_captured": 75,
  "coral_restored": 200,
  "money_donated": 25000,
  "user_impact": {
    "tree_planted": 60,
    "waste_removed": 30,
    "carbon_captured": 45,
    "coral_restored": 120,
    "money_donated": 15000
  },
  "customer_impact": {
    "tree_planted": 40,
    "waste_removed": 20,
    "carbon_captured": 30,
    "coral_restored": 80,
    "money_donated": 10000
  }
}

---

## Daily Impact
GET /v1/impact/daily
Description: Returns time-series daily impact data. Use for dashboards, reports, and trend analysis.
Headers: x-api-key: YOUR_API_KEY
Query params:
  - start_date (optional): date in YYYY-MM-DD format e.g. "2025-01-01"
  - end_date (optional): date in YYYY-MM-DD format e.g. "2025-03-01"

Response example:
{
  "user_id": "U123",
  "daily_impact": [
    {
      "date": "2025-01-15",
      "tree_planted": 5,
      "waste_removed": 0,
      "carbon_captured": 0,
      "coral_restored": 0,
      "money_donated": 0
    },
    {
      "date": "2025-01-21",
      "tree_planted": 0,
      "waste_removed": 10,
      "carbon_captured": 0,
      "coral_restored": 20,
      "money_donated": 500
    }
  ]
}

---

## Records
GET /v1/records
Description: Retrieve your organization's full impact history. Supports multiple filter_by values as repeated query params.
Headers: x-api-key: YOUR_API_KEY
Query params:
  - filter_by (optional): "tree_planted" | "waste_removed" | "carbon_captured" | "coral_restored" | "money_donated" (repeatable, e.g. ?filter_by=carbon_captured&filter_by=waste_removed)
  - start_date (optional): YYYY-MM-DD - return records after this date
  - end_date (optional): YYYY-MM-DD - return records up to this date
  - limit (optional): records per page, default 10, max 1000
  - cursor (optional): cursor value from previous response for pagination
  - sort_order (optional): "asc" (default) | "desc" - sorted by time_utc

Response example:
{
  "user_records": [
    {
      "user_id": "U123",
      "time_utc": "2024-09-16T20:34:04.429Z",
      "tree_planted": 10,
      "metadata": { "order_id": "ORD-456", "source": "shopify" }
    },
    {
      "user_id": "U123",
      "time_utc": "2024-09-17T13:24:04.429Z",
      "waste_removed": 15
    }
  ],
  "cursor": "fNJjcmV32dGVkTiOi..."
}
Note: cursor is only present when more records exist (not the last page). The `metadata` field is only present on records that were created with metadata.

---

## Customer Records
GET /v1/customer_records
Description: Retrieve per-customer impact history. Optionally filter by a specific customer. Each record contains a nested customer object.
Headers: x-api-key: YOUR_API_KEY
Query params:
  - customer_email (optional): filter to a specific customer
  - filter_by (optional): "tree_planted" | "waste_removed" | "carbon_captured" | "coral_restored" | "money_donated" (repeatable)
  - start_date (optional): YYYY-MM-DD
  - end_date (optional): YYYY-MM-DD
  - limit (optional): default 10, max 1000
  - cursor (optional): from previous response for pagination
  - sort_order (optional): "asc" (default) | "desc" - sorted by time_utc

Response example:
{
  "customer_records": [
    {
      "user_id": "U123",
      "customer": {
        "customer_id": "U1234",
        "customer_email": "sample-customer@email.com",
        "customer_name": "Sample Customer"
      },
      "time_utc": "2024-06-12T15:22:14.753Z",
      "tree_planted": 10,
      "metadata": { "order_id": "ORD-456", "source": "shopify" }
    }
  ],
  "cursor": "eyJjcmVhdGVkT24i..."
}
Note: the `metadata` field is only present on records that were created with metadata.

---

## Customers
GET /v1/customers
Description: List all customers who have had impact created on their behalf. Customers are auto-onboarded when you create impact using their customer_email.
Headers: x-api-key: YOUR_API_KEY
Query params:
  - customer_email (optional): retrieve or check a specific customer
  - limit (optional): default 10, max 1000
  - cursor (optional): from previous response for pagination
  - sort_order (optional): "asc" (default) | "desc" - sorted by onboarded_on

Response example:
{
  "customers": [
    {
      "customer_id": "U1234",
      "customer_email": "sample-customer@email.com",
      "customer_name": "Sample Customer",
      "onboarded_on": "2024-06-12T15:22:14.753Z"
    }
  ],
  "cursor": "fNJjcmV32dGVkTiOi..."
}

---

## Track
GET /v1/track
Description: Real-time lifecycle tracking for a specific impact event across the complete environmental impact lifecycle.
Headers: x-api-key: YOUR_API_KEY
Query params:
  - user_id (required): from the POST action response OR from /v1/records or /v1/customer_records
  - time_utc (required): from the POST action response OR from /v1/records or /v1/customer_records

Example: GET /v1/track?user_id=U1234&time_utc=2025-03-12T15:22:14.753Z

Response fields:
  - tracking_id: unique identifier formatted as user_id-time_utc
  - impact_initiated: UTC time when the impact process was initiated
  - tree_planted / waste_removed / carbon_captured / coral_restored / money_donated: impact amounts
  - category: impact category. "food" for food-bearing trees, or a donation cause ID (e.g., "hunger", "education", "veterans") for donations
  - donation_available: UTC time when donation became available (optional)
  - donation_sent: UTC time when donation was transferred to nonprofit (optional)
  - assigned_agent: name of nonprofit/agent assigned to execute the impact (optional)
  - project_location: description of the project location and implementing partners (optional)
  - location_map: Google Maps embed URL for visualizing the project location (optional)
  - impact_completed: UTC time when the impact was completed (optional)
  - project_id: slug identifier of the environmental project associated with this impact - use with GET /v1/projects/:project_id (optional)
  - donation_category: what type of impact the donation funded, e.g. "planting food trees" (optional, donate_money only)
  - certificate: certificate URL - only present in production (optional)
  - impact_video: URL to video recording or live session (optional)
  - live_session_date: UTC timestamp for scheduled live session (optional)
  - metadata: object of key-value pairs provided when the impact was created (optional)
  - is_test_transaction: true if this was a test transaction (optional)
  - is_bonus_impact: true if this was a bonus impact from a subscription plan (optional)
  - cancelled_on: UTC time when the impact was cancelled. Only present for cancelled impacts (optional)
  - cancellation_reason: reason provided for the cancellation. Only present for cancelled impacts that included a reason (optional)

Response example:
{
  "tracking_id": "U1234-2025-03-12T15:22:14.753Z",
  "impact_initiated": "2025-03-12T15:22:14.753Z",
  "tree_planted": 10,
  "category": "food",
  "donation_available": "2025-03-22T23:44:02.121Z",
  "donation_sent": "2025-03-26T20:11:17.707Z",
  "assigned_agent": "Planting On Demand",
  "project_id": "trees-uganda-di",
  "project_location": "Rwenzori Mountains, Uganda with Dream International.",
  "location_map": "https://www.google.com/maps/embed?...",
  "impact_completed": "2025-04-16T13:00:00.000Z",
  "certificate": "https://1clickimpact.com/certificate/U1234-2025-03-12T15:22:14.753Z",
  "impact_video": "https://meet.google.com/ynx-sgcq-dbd",
  "live_session_date": "2025-04-16T13:00:00.000Z",
  "metadata": { "order_id": "ORD-456", "source": "shopify" }
}

---

## Webhooks
Receive real-time, HMAC-signed impact events at your own endpoint instead of polling GET /v1/track. Available on the Basic and Pro plans. Manage subscriptions in the dashboard under Account -> Webhooks (up to 10 endpoints per account); choose which events each endpoint receives.
Docs: https://docs.1clickimpact.com/webhooks

Event types:
  - impact.initiated: the impact was created and its lifecycle started
  - impact.donation_available: funds became available to send to the project
  - impact.donation_sent: funds were transferred to the project partner
  - impact.completed: the impact was fully completed and verified
  - impact.cancelled: the impact was cancelled

Delivery: HTTP POST (application/json) to your endpoint. Headers:
  - X-1CI-Event-Type: the event type (e.g. impact.donation_sent)
  - X-1CI-Delivery-Id: identifier for a single delivery attempt (changes on retries); use it for tracing/logging, not deduplication
  - X-1CI-Signature: t=<unix_seconds>,v1=<hex hmac>
  - User-Agent: 1ClickImpact-Webhooks/1

Payload envelope:
{
  "id": "<tracking_id>#<type>#<occurred_at>",   // stable across retries; deduplicate on this
  "type": "impact.donation_sent",
  "sent_at": "2026-03-19T15:27:14.753Z",
  "data": {
    "tracking_id": "U1234-2026-03-12T15:22:14.753Z",
    "user_id": "U1234",
    "org_id": "O5678",                            // omitted when not associated with an org
    "occurred_at": "2026-03-19T15:22:14.753Z",
    "track": { ...full GET /v1/track response (same snake_case fields)... }
  }
}

Signature verification:
  - X-1CI-Signature has two comma-separated fields: t (unix timestamp in seconds) and v1 (hex-encoded HMAC-SHA256).
  - Compute HMAC_SHA256(secret, t + "." + rawRequestBody), hex-encode it, and compare to v1 with a constant-time check.
  - secret is the per-endpoint signing secret (prefix whsec_) from the dashboard. Use the raw request body, not re-serialized JSON.

Retries and delivery:
  - Success = any 2xx response. Respond quickly and do slow work asynchronously.
  - 429 and 5xx responses (and network errors) are retried with backoff.
  - Other 4xx responses are treated as client misconfiguration and are not retried.
  - Every attempt (status code, attempt count, payload) is stored in the dashboard delivery history, where you can also send test events.

Best practices: verify the signature on every request; deduplicate on the event id (stable across retries; not X-1CI-Delivery-Id, which changes per attempt); return 2xx fast; prefer the event's data.track over calling /v1/track again.

---

## Projects
GET /v1/projects
Description: Browse all verified environmental impact projects available through 1ClickImpact. Filter by project type and request localized content.
Headers: x-api-key: YOUR_API_KEY
Query params:
  - type (optional): "trees" | "ocean" | "carbon" - filter by impact type
  - locale (optional): "en" | "de" | "es" | "fr" | "nl" - return translated content; falls back to English

Response example:
{
  "projects": [
    {
      "project_id": "trees-uganda-di",
      "name": "Dream International Uganda",
      "type": "trees",
      "location": "Uganda",
      "description": "Dream International is a community-led tree and forest restoration in the Rwenzori Mountain region for ecosystem services, biodiversity, and climate resilience.",
      "about": [
        "Dream International leads a community-driven tree and forest restoration initiative in the Rwenzori Mountain region of western Uganda - part of the globally important Albertine Rift biodiversity hotspot.",
        "Local communities are trained and employed as stewards of restored forest areas, receiving ongoing support in sustainable land management, agroforestry, and eco-enterprise development.",
        "By restoring tree cover in the Rwenzori highlands, the project directly protects headwaters that supply clean drinking water to thousands of downstream households."
      ],
      "country_code": "UG",
      "organization": "Planting on Demand",
      "sdgs": [
        { "id": "climate-action", "number": 13, "title": "Climate Action", "color": "#3F7E44", "link": "https://sdgs.un.org/goals/goal13" },
        { "id": "life-on-land", "number": 15, "title": "Life On Land", "color": "#56C02B", "link": "https://sdgs.un.org/goals/goal15" },
        { "id": "clean-water", "number": 6, "title": "Clean Water & Sanitation", "color": "#26BDE2", "link": "https://sdgs.un.org/goals/goal6" },
        { "id": "decent-work", "number": 8, "title": "Decent Work & Economic Growth", "color": "#A21942", "link": "https://sdgs.un.org/goals/goal8" },
        { "id": "no-poverty", "number": 1, "title": "No Poverty", "color": "#E5243B", "link": "https://sdgs.un.org/goals/goal1" },
        { "id": "partnerships", "number": 17, "title": "Partnerships For The Goals", "color": "#19486A", "link": "https://sdgs.un.org/goals/goal17" }
      ],
      "image_urls": [
        "https://images.s3.us-east-1.amazonaws.com/projects/trees-uganda-di/1.jpg",
        "https://images.s3.us-east-1.amazonaws.com/projects/trees-uganda-di/2.jpg",
        "https://images.s3.us-east-1.amazonaws.com/projects/trees-uganda-di/3.jpg",
        "https://images.s3.us-east-1.amazonaws.com/projects/trees-uganda-di/4.jpg",
        "https://images.s3.us-east-1.amazonaws.com/projects/trees-uganda-di/5.jpg"
      ],
      "latitude": -12.3733,
      "longitude": 27.2903,
      "available": true
    }
  ]
}

---

## Project (single)
GET /v1/projects/:project_id
Description: Retrieve full details for a single project by its ID. Use the project_id from the /v1/projects list or from a /v1/track response.
Headers: x-api-key: YOUR_API_KEY
Path params:
  - project_id (required): unique identifier of the project (e.g., "trees-uganda-di")
Query params:
  - locale (optional): "en" | "de" | "es" | "fr" | "nl" - return translated content; falls back to English

Response fields:
  - project_id: unique slug identifier for the project
  - name: display name of the project
  - type: "trees" | "ocean" | "carbon"
  - location: human-readable location string
  - description: one-sentence project summary
  - about: array of paragraph strings with deeper project detail
  - country_code: ISO 3166-1 alpha-2 country code (e.g., "UG")
  - organization: name of the non-profit or partner executing the project
  - sdgs: array of UN SDG objects - each with id, number, title, description, color, link, icon_url
  - image_urls: array of image URLs for use in project cards or detail pages
  - latitude: project latitude coordinate
  - longitude: project longitude coordinate
  - available: boolean - whether the project is currently accepting new impacts

---

## Free Tools

Website Carbon Calculator: https://1clickimpact.com/website-carbon
- Free browser tool to check any website's carbon footprint
- Enter a URL and get an instant A+ to F carbon rating
- Shows CO2 per page view, green hosting status, transfer size, energy stats
- Annual impact equivalents (trees, cups of tea, smartphone charges, EV km)
- Suggests Climate Action Badge configuration and offset amounts
- No sign-up required

How It Works: https://1clickimpact.com/website-carbon/how-it-works
- Full methodology breakdown using Sustainable Web Design Model V4
- Energy intensity table (operational + embodied across data centers, networks, devices)
- Rating system explanation (A+ through F thresholds)
- V3 vs V4 comparison (0.81 -> 0.30 kWh/GB, 63% reduction)
- 10 FAQs about the calculator
- Sources and references

AI Energy Calculator: https://1clickimpact.com/ai-energy-calculator
- Free browser tool to estimate the electricity, water, and carbon of any AI model
- 45+ models across 9 providers (OpenAI, Anthropic, Google, xAI, DeepSeek, Moonshot, Mistral, self-hosted)
- Honest P5-P95 uncertainty ranges per query, month, and year
- Pick a model, workload, region, and monthly volume; see energy (Wh), water (mL), CO2 (gCO2e)
- Offset the footprint in one API call via /v1/capture_carbon
- No sign-up required
- Methodology: https://1clickimpact.com/ai-energy-calculator/methodology
- FAQ: https://1clickimpact.com/ai-energy-calculator/faq

---

## Errors
Standard HTTP status codes are used. Common errors:
- 401 Unauthorized: missing or invalid x-api-key
- 400 Bad Request: missing required fields or invalid values
- 429 Too Many Requests: rate limit exceeded
- 500 Internal Server Error: contact support

## Pagination
Cursor-based. Default page size is 10; max is 1000 via `limit` param. When more pages exist, the response includes a `cursor` field. Pass this `cursor` value as the `cursor` query param in the next request. When `cursor` is absent in the response, you have reached the last page. Supported on /v1/records, /v1/customer_records, and /v1/customers.
Can also use `start_date` and `end_date` (YYYY-MM-DD) to filter the date range of records returned.