# 1ClickImpact API — Full Reference

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

---

## 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
}
- 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.

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
}
- 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.

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 CO₂ 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
}
- amount (required): lbs of CO₂ 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.

Response example:
{
  "user_id": "U123",
  "carbon_captured": 5,
  "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). Contact 1ClickImpact to configure a specific cause; defaults to tree planting.
Headers: Content-Type: application/json, x-api-key: YOUR_API_KEY

Request body:
{
  "amount": 500,
  "customer_email": "optional@email.com",
  "customer_name": "Optional Name",
  "notify": true
}
- amount (required): smallest USD units (e.g. 10 = $0.10, 100 = $1.00, 500 = $5.00). Range 1–1,000,000,000.
- 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.
- If no cause is configured on your account, donations go to tree planting by default. Contact 1ClickImpact to set up a custom cause.

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

---

## 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,
  "money_donated": 25000,
  "user_impact": {
    "tree_planted": 60,
    "waste_removed": 30,
    "carbon_captured": 45,
    "money_donated": 15000
  },
  "customer_impact": {
    "tree_planted": 40,
    "waste_removed": 20,
    "carbon_captured": 30,
    "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,
      "money_donated": 0
    },
    {
      "date": "2025-01-21",
      "tree_planted": 0,
      "waste_removed": 10,
      "carbon_captured": 0,
      "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" | "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
    },
    {
      "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).

---

## 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" | "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
    }
  ],
  "cursor": "eyJjcmVhdGVkT24i..."
}

---

## 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 / money_donated: impact amounts
  - category: "food" when food-bearing trees were planted
  - 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)
  - 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)
  - 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)

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_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"
}

---

## 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.