GET /api/v1/context/incentives — Program Incentives

The incentives context endpoint exposes program-level rebate, tax credit, and financing incentive records for HVAC, solar, roofing, plumbing, and electrical trades. Records are sourced from official program portals, utility websites, and government databases. Each record carries a quote_safe flag indicating whether the program data is deterministic enough for customer-facing quote presentation. Use the status filter to restrict results to active programs, and the equipment_id parameter to automatically infer the relevant measure from a matched HVAC product. Endpoint

GET https://homeservicedata.org/api/v1/context/incentives

Query Parameters

string

default:"hvac"

Trade vertical to filter by. One of: hvac, solar, roofing, plumbing, electrical.

string

Two-letter state code (e.g., CA, TX). Case-insensitive.

string

Utility provider name or slug to filter programs offered by that utility.

string

Measure key used to filter programs applicable to a specific installation type (e.g., heat_pump_central, central_ac). Overrides the measure inferred from equipment_id.

string

HSD equipment record ID. When provided, the API resolves the associated measure_key and uses it to filter relevant programs automatically.

string

Filter by program status. One of: active, planned, paused, waitlist, expired, superseded, state_dependent, limited, unknown.

string

Filter by income qualification tier. One of: low_income, moderate_income, market_rate, unknown.

boolean

When true, returns only records cleared for customer-facing quote use.

boolean

default:"false"

When true, includes programs with status: expired that would otherwise be excluded.

integer

default:"100"

Maximum number of records to return. Capped at 500.

Supplying equipment_id causes the API to look up the equipment record and infer the measure_key. If the equipment ID is not found a 404 is returned. Explicitly passing measure always takes precedence over the inferred value.

Response Fields

array

Array of incentive program objects.

Show Record fields

string

Unique record identifier.

string

Normalized slug key for the program (e.g., ca-sgip-heat-pump).

string

Human-readable program name.

string

Name of the administering organization (utility, government body, etc.).

string

Type of authority: federal, state, utility, local, nonprofit, or unknown.

string

Incentive category: rebate, tax_credit, loan, grant, pace, on_bill_financing, or other.

string

Trade this program applies to.

string | null

Plain-language description of the program benefits.

string

Current program status.

string | null

ISO 8601 date when the program became active.

string | null

ISO 8601 date when the program expires, if known.

string | null

ISO 8601 timestamp of the most recent data verification.

string | null

URL to the authoritative program page.

boolean

Whether this record is safe for use in customer-facing quotes.

string | null

Confidence tier: high, medium, or low.

object

Summary metadata about the query result.

Show Coverage fields

string

Trade filter applied.

string | null

State filter applied.

string | null

Utility filter applied.

string | null

Measure key used (explicit or inferred).

object | null

Resolved equipment context if equipment_id was provided.

integer

Number of records in the response.

boolean

Whether results were restricted to quote-safe records.

boolean

Whether expired programs were included.

string

Description of the trust model applied to this dataset.

Filter by status=active and quote_safe=true to get the smallest, highest-confidence set suitable for presenting rebate estimates directly to homeowners.

Example Request

curl -G https://homeservicedata.org/api/v1/context/incentives \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode "trade=hvac" \
  --data-urlencode "state=CA" \
  --data-urlencode "status=active" \
  --data-urlencode "quote_safe=true" \
  --data-urlencode "limit=5"

Example Response

{
  "success": true,
  "data": {
    "records": [
      {
        "id": "inc_01hzka1bc2de3fg4hi5jk6lmno",
        "program_key": "ca-utility-heat-pump-rebate",
        "program_name": "Home Energy Efficiency Rebate — Heat Pump",
        "authority": "Southern California Edison",
        "authority_type": "utility",
        "program_type": "rebate",
        "trade_category": "hvac",
        "summary": "Up to $1,000 rebate for qualifying ducted heat pump installations replacing a gas furnace.",
        "status": "active",
        "effective_date": "2024-01-01",
        "expires_at": "2024-12-31",
        "last_verified_at": "2024-10-20T14:00:00Z",
        "source_url": "https://www.sce.com/residential/rebates/heat-pump",
        "quote_safe": true,
        "confidence": "high"
      }
    ],
    "coverage": {
      "trade": "hvac",
      "state": "CA",
      "utility": null,
      "measure": null,
      "equipment_context": null,
      "records_returned": 1,
      "quote_safe_only": true,
      "includes_expired": false,
      "trust_basis": "Official sources first; uncertain state-dependent, waitlist, missing amount, or non-deterministic records return with quote_safe=false."
    }
  }
}

Overview

Search & Catalog

Finance

Equipment & Hardware

Context Datasets

Composite

Sync

GET /api/v1/context/incentives — Program Incentives

Query Parameters

Response Fields

Example Request

Example Response

​Query Parameters

​Response Fields

​Example Request

​Example Response

Query Parameters

Response Fields

Example Request

Example Response