v1

latestOpenAPI 3.0.22026-07-141713124.8 KB

Incentives

Retrieve residential incentive programs

Returns upfront rebates and ongoing (DR/VPP) programs available to a residential customer at a given location, across all electrification-relevant technologies (solar, battery, EV, heat pump, water heater, insulation, appliance, etc.).

The response includes:

upfront[] — at-purchase rebates and tax credits, ordered by confidence + provider preference + max amount
ongoing[] — recurring/performance programs (demand response, VPP, time-of-use bonuses)
totals — estimated dollar values when system_cost and/or system_size_kw are provided
meta — debug info: which aggregators expanded the result, confidence floor used

Aggregator expansion: when the customer's utility belongs to one or more aggregators (Mass Save, TVA EnergyRight, Energize CT, etc.), programs administered by those aggregators are automatically included. Same routing applies to ongoing programs (aggregator_id, installer_service_eids scoping for installer-VPPs like Sunrun-SCE).

Confidence filtering: by default only HIGH records surface. Pass min_confidence: 'MEDIUM' (or lower) to opt in to less-certain records. Confidence reflects whether the record is authority-confirmed (HIGH) versus hint-only from third-party databases like DSIRE (MEDIUM). The VERIFIED tier was historically present but consolidated into HIGH in May 2026 — VERIFIED is still accepted as a valid min_confidence for backwards compatibility but produces the same set as HIGH.

post/incentives

Request body

statestring required

Two-letter US state code (required)

addressstring

Street address. Used together with city/state/zipcode to resolve the customer's electric utility (and therefore eligible utility-specific programs).

citystring

zipcodestring

5-digit zip code

wattkeystring

The unique identifier for the address.

utility_eidinteger

EIA utility ID. Short-circuits the address→utility resolver when known. TX TDSP customers should use the TDSP's DOE/EIA number (Oncor 44372, CenterPoint 8901, AEP TX Central 3278, AEP TX North 20404, TNMP 40051).

incentive_typesstring[]

Filter to specific tech categories. Defaults to all 16 valid types.

fuel_typesstring[]

Filter by equipment fuel type. Defaults to the electrification set (excludes gas). Pass gas explicitly to include gas-only equipment programs.

min_confidence'VERIFIED' | 'HIGH' | 'MEDIUM' | 'LOW' | 'SOURCE_ONLY'

Minimum confidence tier. Defaults to HIGH (returns only authority-confirmed records). Set to MEDIUM to include DSIRE/AFDC/EnergyStar hint-level data; lower tiers expose increasingly uncertain records.

system_costnumber

Total installed cost of the system. Used to estimate dollar values for pct_of_cost and tax_credit programs.

system_size_kwnumber

System size in kW. Used to estimate dollar values for per_unit programs with unit kW or W.

Example request

{
  "state": "MA",
  "address": "100 Main St",
  "city": "Boston",
  "zipcode": "02101",
  "wattkey": "MTAwIE1haW4gU3Q=abc123",
  "utility_eid": 11804,
  "incentive_types": [
    "heat_pump",
    "battery_storage",
    "solar"
  ],
  "system_cost": 20000,
  "system_size_kw": 10
}

Response

Successful response

statusstring

Example response

{
  "status": "ok",
  "utility": {
    "eid": 11804,
    "name": "National Grid"
  },
  "upfront": [
    {
      "product": "Heat Pump",
      "product_key": "heat_pump",
      "program_name": "Mass Save Whole-Home Heat Pump",
      "provider": "Mass Save",
      "aggregator_id": "mass_save",
      "status": "open",
      "timing": "at_purchase"
    }
  ],
  "ongoing": [
    {
      "confidence": "HIGH",
      "compensation": {
        "price_type": "fixed"
      }
    }
  ],
  "meta": {
    "aggregators_expanded": [
      "mass_save"
    ],
    "min_confidence": "HIGH"
  }
}