DOCSEARCHbyAlgolia
Submit Docs

1ClickImpact API Reference

website·Indexed 33 days ago

https://docs.1clickimpact.com

Technical specifications for the 1ClickImpact API, including authentication via x-api-key and endpoints for environmental actions such as Plant Trees, Clean Ocean, Capture Carbon, and Restore Coral. Includes utility features like Website Carbon and AI Energy, as well as methods for managing user impact records and cancellations.

Tokens
3K
Snippets
20
Records
26
Agent score
13%

What's inside 1ClickImpact

  2. Estimate and offset AI model energy usage

    The AI Energy Calculator is a free tool to estimate electricity, water, and carbon footprints for 45+ AI models across providers like OpenAI, Anthropic, Google, and others. Users can input model, workload, region, and monthly volume to see energy (Wh), water (mL), and CO2 (gCO2e) impacts. The resulting carbon footprint can be offset via a single API call to the /v1/capture_carbon endpoint.

  3. Implement 1ClickImpact Webhooks

    Webhooks allow you to receive real-time, HMAC-signed impact events (e.g., impact.initiated, impact.completed, impact.cancelled) instead of polling the track endpoint.

    Key Implementation Details:

    • Deduplication: Use the id field in the payload envelope for deduplication; do not use X-1CI-Delivery-Id as it changes on retries.
    • Verification: Verify the X-1CI-Signature header using the signing secret (whsec_...) from the dashboard. Compute HMAC_SHA256(secret, t + "." + rawRequestBody) and compare it to the v1 value using a constant-time check.
    • Response: Return a 2xx status code quickly to acknowledge receipt. 429 and 5xx responses will trigger retries with backoff.
    // Example Webhook Payload Envelope
{
  "id": "<tracking_id>#<type>#<occurred_at>",
  "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",
    "occurred_at": "2026-03-19T15:22:14.753Z",
    "track": { ...full track response... }
  }
}

  4. Handle pagination for 1ClickImpact API records

    The API uses cursor-based pagination for the /v1/records, /v1/customer_records, and /v1/customers endpoints.

    • Page Size: Default is 10; maximum is 1000 using the limit query parameter.
    • Navigation: If a cursor field is present in the response, pass that value as the cursor query parameter in the subsequent request to retrieve the next page.
    • Termination: When the cursor field is absent from the response, the last page has been reached.
    • Filtering: You can further restrict results using start_date and end_date parameters in YYYY-MM-DD format.

  5. Retrieve daily impact time-series data

    Use GET /v1/impact/daily to retrieve daily impact data for dashboards and trend analysis. You can optionally filter the results using start_date and end_date in YYYY-MM-DD format.
    curl -X GET "https://api.1clickimpact.com/v1/impact/daily?start_date=2025-01-01&end_date=2025-03-01" \
     -H "x-api-key: YOUR_API_KEY"

  6. Cancel and reverse an impact record

    Cancel a previously created impact (e.g., for order refunds). This reverses usage billing and removes the impact from aggregate totals. This operation is idempotent.

    Constraints:

    • Impacts already processed (donation received by non-profit) cannot be cancelled via API.
    • Requires the original user_id and time_utc timestamp from the record.
    POST /v1/cancel_impact
{
  "user_id": "U1234",
  "time_utc": "2025-03-12T15:22:14.753Z",
  "reason": "order refunded"
}

  8. Browse verified environmental projects

    Use GET /v1/projects to list verified environmental projects. You can filter by project type (trees, ocean, or carbon) and specify a locale (e.g., en, de, es, fr, nl) to receive translated content.
    curl -X GET "https://api.1clickimpact.com/v1/projects?type=trees&locale=en" \
  -H "x-api-key: YOUR_API_KEY"

  9. Retrieve AI energy calculation options

    Use GET /v1/ai_energy/options to fetch the full catalog of supported model_ids, providers, hardware, regions, workloads, and regimes. This endpoint should be cached and refreshed only when the data_version changes.
    curl -X GET "https://api.1clickimpact.com/v1/ai_energy/options" \
     -H "x-api-key: YOUR_API_KEY"

  10. Get aggregated lifetime impact totals

    The GET /v1/impact endpoint returns the total lifetime impact across all categories (trees, waste, carbon, coral, money). It provides a breakdown between user_impact (direct) and customer_impact (generated on behalf of customers).
    curl -X GET "https://api.1clickimpact.com/v1/impact" \
     -H "x-api-key: YOUR_API_KEY"

  11. Fetch detailed impact history records

    The GET /v1/records endpoint allows retrieval of the organization's full impact history. It supports pagination via limit and cursor, and filtering by specific impact types using the filter_by query parameter (which can be repeated for multiple types).
    curl -X GET "https://api.1clickimpact.com/v1/records?filter_by=carbon_captured&filter_by=waste_removed&limit=50" \
     -H "x-api-key: YOUR_API_KEY"

  12. Restore coral reefs via API

    Fund coral reef restoration by outplanting coral fragments. The amount is the number of fragments.

    Client-side calculations:

    • Reef structures: amount / 15 (approx. 15 fragments per structure).
    • Reef area: amount * 144 cm² or amount * 22.32 in².
    POST /v1/restore_coral
{
  "amount": 20,
  "customer_email": "optional@email.com",
  "customer_name": "Optional Name",
  "notify": true,
  "metadata": { "reef_site": "Great Barrier Reef" }
}