openapi: 3.0.3
info:
  title: 1ClickImpact Environmental Impact API
  description: >
    REST API for programmatic environmental impact — plant trees, remove ocean plastic,
    capture carbon, and make charitable donations. Integrate sustainability into any
    product in minutes.
  version: 1.0.0
  contact:
    name: 1ClickImpact Support
    url: https://1clickimpact.com/contact
  license:
    name: Proprietary
    url: https://1clickimpact.com/terms

servers:
  - url: https://api.1clickimpact.com
    description: Production
  - url: https://sandbox.1clickimpact.com
    description: Sandbox (free testing — no real-world impact)

security:
  - ApiKeyAuth: []

components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: API key obtained from your 1ClickImpact dashboard.

  schemas:
    CustomerFields:
      type: object
      properties:
        customer_email:
          type: string
          format: email
          description: Plant/clean/offset on behalf of this customer. Enables per-customer tracking.
        customer_name:
          type: string
          description: Display name for the customer.
        notify:
          type: boolean
          default: true
          description: Send an email notification to the customer.

    ImpactBreakdown:
      type: object
      properties:
        tree_planted:
          type: integer
          description: Total trees planted.
        waste_removed:
          type: number
          description: Total ocean waste removed in lbs.
        carbon_captured:
          type: number
          description: Total carbon captured in lbs.
        money_donated:
          type: integer
          description: Total money donated in cents.

    ImpactRecord:
      type: object
      properties:
        user_id:
          type: string
        type:
          type: string
          enum: [tree_planted, waste_removed, carbon_captured, money_donated]
        amount:
          type: number
        time_utc:
          type: string
          format: date-time

    Error:
      type: object
      properties:
        error:
          type: string
        message:
          type: string

paths:
  /v1/whoami:
    get:
      operationId: whoami
      summary: Verify API key and retrieve account details
      description: Confirms your API integration is working and returns your account information.
      tags: [Account]
      responses:
        '200':
          description: Account details
          content:
            application/json:
              schema:
                type: object
                properties:
                  user_id:
                    type: string
                    example: U123
                  email:
                    type: string
                    example: my-email@email.com
        '401':
          description: Unauthorized — missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /v1/plant_tree:
    post:
      operationId: plantTree
      summary: Plant trees
      description: >
        Plant trees for your organization or on behalf of a customer.
        Provide `customer_email` to attribute impact to a specific customer.
        Each unit = 1 tree.
      tags: [Impact Actions]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/CustomerFields'
                - type: object
                  required: [amount]
                  properties:
                    amount:
                      type: integer
                      minimum: 1
                      description: Number of trees to plant.
                      example: 5
                    category:
                      type: string
                      enum: [food]
                      description: >-
                        Type of tree planting project. Only supported value is "food" — plants food-bearing trees that
                        provide nutrition and income for local communities, and grants access to exclusive live planting sessions.
                        If omitted, standard reforestation trees are planted.
            example:
              amount: 5
              customer_email: customer@example.com
              customer_name: Jane Doe
              category: food
              notify: true
      responses:
        '200':
          description: Trees planted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  user_id:
                    type: string
                    example: U123
                  tree_planted:
                    type: integer
                    example: 5
                  time_utc:
                    type: string
                    format: date-time
                    example: '2024-09-16T20:34:04.429Z'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /v1/clean_ocean:
    post:
      operationId: cleanOcean
      summary: Remove ocean plastic waste
      description: >
        Remove plastic and waste from the ocean. Amount is in lbs.
        Provide `customer_email` to attribute impact to a specific customer.
      tags: [Impact Actions]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/CustomerFields'
                - type: object
                  required: [amount]
                  properties:
                    amount:
                      type: integer
                      minimum: 1
                      description: Amount of ocean waste to remove in lbs (1–10,000,000).
                      example: 5
            example:
              amount: 5
              customer_email: customer@example.com
              notify: true
      responses:
        '200':
          description: Ocean cleaned successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  user_id:
                    type: string
                    example: U123
                  waste_removed:
                    type: number
                    example: 5
                  time_utc:
                    type: string
                    format: date-time
                    example: '2024-09-16T20:34:04.429Z'

  /v1/capture_carbon:
    post:
      operationId: captureCarbon
      summary: Capture carbon / offset CO₂
      description: >
        Capture carbon and offset CO₂ emissions. Amount is in lbs.
        Provide `customer_email` to attribute impact to a specific customer.
      tags: [Impact Actions]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/CustomerFields'
                - type: object
                  required: [amount]
                  properties:
                    amount:
                      type: integer
                      minimum: 1
                      description: Amount of CO₂ to capture in lbs (1–10,000,000).
                      example: 5
            example:
              amount: 5
              customer_email: customer@example.com
              notify: true
      responses:
        '200':
          description: Carbon captured successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  user_id:
                    type: string
                    example: U123
                  carbon_captured:
                    type: number
                    example: 5
                  time_utc:
                    type: string
                    format: date-time
                    example: '2024-09-16T20:34:04.429Z'

  /v1/donate_money:
    post:
      operationId: donateMoney
      summary: Make a charitable donation
      description: >
        Donate money to a cause. Amount is in the smallest currency unit (cents for USD).
        Contact 1ClickImpact to configure a custom cause; defaults to tree planting.
        Provide `customer_email` to attribute impact to a specific customer.
      tags: [Impact Actions]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/CustomerFields'
                - type: object
                  required: [amount]
                  properties:
                    amount:
                      type: integer
                      minimum: 1
                      description: Amount to donate in cents (e.g. 500 = $5.00).
                      example: 500
            example:
              amount: 500
              customer_email: customer@example.com
              notify: true
      responses:
        '200':
          description: Donation made successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  user_id:
                    type: string
                    example: U123
                  money_donated:
                    type: integer
                    example: 500
                  time_utc:
                    type: string
                    format: date-time
                    example: '2024-09-16T20:34:04.429Z'

  /v1/impact:
    get:
      operationId: getAggregatedImpact
      summary: Retrieve aggregated lifetime impact
      description: >
        Returns total lifetime impact across all categories. Includes top-level totals (user + customer combined)
        and a breakdown between your direct impact (user_impact) and impact on behalf of customers (customer_impact).
      tags: [Impact Data]
      responses:
        '200':
          description: Aggregated impact totals
          content:
            application/json:
              schema:
                type: object
                properties:
                  user_id:
                    type: string
                    example: U123
                  tree_planted:
                    type: integer
                    description: Total trees planted (user + customer combined).
                  waste_removed:
                    type: integer
                    description: Total ocean waste removed in lbs (user + customer combined).
                  carbon_captured:
                    type: integer
                    description: Total carbon captured in lbs (user + customer combined).
                  money_donated:
                    type: integer
                    description: Total money donated in cents (user + customer combined).
                  user_impact:
                    $ref: '#/components/schemas/ImpactBreakdown'
                  customer_impact:
                    $ref: '#/components/schemas/ImpactBreakdown'

  /v1/impact/daily:
    get:
      operationId: getDailyImpact
      summary: Retrieve daily impact time-series
      description: >
        Returns a time-series of daily impact data. Use optional query parameters to
        filter by date range. Useful for dashboards, reports, and trend analysis.
      tags: [Impact Data]
      parameters:
        - name: start_date
          in: query
          description: Filter from this date (ISO 8601 format).
          schema:
            type: string
            format: date
            example: '2025-01-01'
        - name: end_date
          in: query
          description: Filter to this date (ISO 8601 format).
          schema:
            type: string
            format: date
            example: '2025-03-01'
      responses:
        '200':
          description: Daily impact time-series
          content:
            application/json:
              schema:
                type: object
                properties:
                  user_id:
                    type: string
                    example: U123
                  daily_impact:
                    type: array
                    items:
                      type: object
                      properties:
                        date:
                          type: string
                          format: date
                          example: '2025-01-15'
                        tree_planted:
                          type: integer
                        waste_removed:
                          type: integer
                        carbon_captured:
                          type: integer
                        money_donated:
                          type: integer

  /v1/records:
    get:
      operationId: getRecords
      summary: Retrieve your organization's impact records
      description: >
        Returns your full impact history. Filter by impact type using `filter_by` (repeatable).
        Uses cursor-based pagination — pass `cursor` from response into next request.
      tags: [Records]
      parameters:
        - name: filter_by
          in: query
          description: Filter by impact type. Repeatable (e.g. ?filter_by=carbon_captured&filter_by=waste_removed).
          schema:
            type: string
            enum: [tree_planted, waste_removed, carbon_captured, money_donated]
        - name: start_date
          in: query
          description: Return records after this date (YYYY-MM-DD).
          schema:
            type: string
            format: date
            example: '2024-01-01'
        - name: end_date
          in: query
          description: Return records up to this date (YYYY-MM-DD).
          schema:
            type: string
            format: date
            example: '2024-12-31'
        - name: limit
          in: query
          description: Number of records per page. Default 10, max 1000.
          schema:
            type: integer
            example: 10
        - name: cursor
          in: query
          description: Cursor from previous response for fetching the next page.
          schema:
            type: string
        - name: sort_order
          in: query
          description: Sort by time_utc. "asc" (default) or "desc".
          schema:
            type: string
            enum: [asc, desc]
      responses:
        '200':
          description: List of impact records
          content:
            application/json:
              schema:
                type: object
                properties:
                  user_records:
                    type: array
                    items:
                      $ref: '#/components/schemas/ImpactRecord'
                  cursor:
                    type: string
                    description: Present only when more pages exist. Pass as `cursor` param in next request.

  /v1/customer_records:
    get:
      operationId: getCustomerRecords
      summary: Retrieve customer impact records
      description: >
        Returns per-customer impact history. Each record contains a nested `customer` object
        with customer_id, customer_email, and customer_name. Uses cursor-based pagination.
      tags: [Records]
      parameters:
        - name: customer_email
          in: query
          description: Filter records for a specific customer.
          schema:
            type: string
            format: email
        - name: filter_by
          in: query
          description: Filter by impact type. Repeatable.
          schema:
            type: string
            enum: [tree_planted, waste_removed, carbon_captured, money_donated]
        - name: start_date
          in: query
          description: Return records after this date (YYYY-MM-DD).
          schema:
            type: string
            format: date
        - name: end_date
          in: query
          description: Return records up to this date (YYYY-MM-DD).
          schema:
            type: string
            format: date
        - name: limit
          in: query
          description: Default 10, max 1000.
          schema:
            type: integer
            example: 10
        - name: cursor
          in: query
          description: Cursor from previous response for next page.
          schema:
            type: string
        - name: sort_order
          in: query
          description: Sort by time_utc. "asc" (default) or "desc".
          schema:
            type: string
            enum: [asc, desc]
      responses:
        '200':
          description: List of customer impact records
          content:
            application/json:
              schema:
                type: object
                properties:
                  customer_records:
                    type: array
                    items:
                      type: object
                      properties:
                        user_id:
                          type: string
                        customer:
                          type: object
                          properties:
                            customer_id:
                              type: string
                            customer_email:
                              type: string
                            customer_name:
                              type: string
                        time_utc:
                          type: string
                          format: date-time
                        tree_planted:
                          type: integer
                        waste_removed:
                          type: integer
                        carbon_captured:
                          type: integer
                        money_donated:
                          type: integer
                  cursor:
                    type: string
                    description: Present only when more pages exist.

  /v1/customers:
    get:
      operationId: getCustomers
      summary: List all onboarded customers
      description: >
        Returns a list of all customers who have had impact created on their behalf.
        Customers are auto-onboarded when you create impact using their customer_email.
      tags: [Records]
      parameters:
        - name: customer_email
          in: query
          description: Retrieve or check a specific customer.
          schema:
            type: string
            format: email
        - name: limit
          in: query
          description: Default 10, max 1000.
          schema:
            type: integer
            example: 10
        - name: cursor
          in: query
          description: Cursor from previous response for next page.
          schema:
            type: string
        - name: sort_order
          in: query
          description: Sort by onboarded_on. "asc" (default) or "desc".
          schema:
            type: string
            enum: [asc, desc]
      responses:
        '200':
          description: List of customers
          content:
            application/json:
              schema:
                type: object
                properties:
                  customers:
                    type: array
                    items:
                      type: object
                      properties:
                        customer_id:
                          type: string
                          example: U1234
                        customer_email:
                          type: string
                        customer_name:
                          type: string
                        onboarded_on:
                          type: string
                          format: date-time
                  cursor:
                    type: string
                    description: Present only when more pages exist.

  /v1/track:
    get:
      operationId: trackImpact
      summary: Track real-time lifecycle of a specific impact event
      description: >
        Returns real-time tracking data for a specific impact event across the complete environmental impact lifecycle.
        `user_id` and `time_utc` can be obtained from the POST action response (plant_tree, clean_ocean,
        capture_carbon, donate_money) OR from /v1/records or /v1/customer_records.
      tags: [Tracking]
      parameters:
        - name: user_id
          in: query
          required: true
          description: From the POST action response or /v1/records / /v1/customer_records.
          schema:
            type: string
            example: U1234
        - name: time_utc
          in: query
          required: true
          description: ISO 8601 timestamp. From the POST action response or /v1/records / /v1/customer_records.
          schema:
            type: string
            format: date-time
            example: '2025-03-12T15:22:14.753Z'
      responses:
        '200':
          description: Impact tracking details
          content:
            application/json:
              schema:
                type: object
                properties:
                  tracking_id:
                    type: string
                    description: Unique identifier formatted as user_id-time_utc.
                    example: U1234-2025-03-12T15:22:14.753Z
                  impact_initiated:
                    type: string
                    format: date-time
                    description: UTC time when the impact process was initiated.
                  tree_planted:
                    type: integer
                  waste_removed:
                    type: integer
                  carbon_captured:
                    type: integer
                  money_donated:
                    type: integer
                  category:
                    type: string
                    description: "food" when food-bearing trees were planted.
                  donation_available:
                    type: string
                    format: date-time
                    description: UTC time when donation became available. Optional.
                  donation_sent:
                    type: string
                    format: date-time
                    description: UTC time when donation was transferred to nonprofit. Optional.
                  assigned_agent:
                    type: string
                    description: Name of nonprofit/agent assigned to execute the impact. Optional.
                    example: Planting On Demand
                  project_location:
                    type: string
                    description: Description of project location and implementing partners. Optional.
                    example: Rwenzori Mountains, Uganda with Dream International.
                  location_map:
                    type: string
                    description: Google Maps embed URL for visualizing project location. Optional.
                  impact_completed:
                    type: string
                    format: date-time
                    description: UTC time when the impact was completed. Optional.
                  donation_category:
                    type: string
                    description: What type of impact the donation funded (e.g. "planting food trees"). Only for donate_money. Optional.
                  certificate:
                    type: string
                    format: uri
                    description: Certificate URL. Only present in production. Optional.
                  impact_video:
                    type: string
                    format: uri
                    description: URL to video recording or live session. Optional.
                  live_session_date:
                    type: string
                    format: date-time
                    description: UTC timestamp for scheduled live session. Optional.
                  is_test_transaction:
                    type: boolean
                    description: True if this was a test transaction. Optional.
                  is_bonus_impact:
                    type: boolean
                    description: True if this was a bonus impact from a subscription plan. Optional.

tags:
  - name: Account
    description: Verify credentials and retrieve account details
  - name: Impact Actions
    description: Create environmental impact — trees, ocean, carbon, donations
  - name: Impact Data
    description: Retrieve aggregated and time-series impact totals
  - name: Records
    description: Access full impact history for your org and customers
  - name: Tracking
    description: Real-time lifecycle tracking for specific impact events
