GET /api/v1/quote-context — Bundled Quote Context

The /api/v1/quote-context endpoint is the primary entry point for building home-service quotes. Rather than stitching together five or six separate API calls, you send one GET request and receive finance options, equipment records, incentive eligibility, climate context, labor adders, permit requirements, and utility territory resolution in a single response. Every response also includes a coverage object that summarizes how many quote-safe records were returned and surfaces any data gaps or unresolved requirements so your quoting tool can decide whether it has enough information to present a price.

Request

GET https://homeservicedata.org/api/v1/quote-context

Authentication

All requests must include your API key in the x-api-key header. This endpoint requires a production access tier.

Query Parameters

Trade & Geography

string

default:"solar"

The home-service vertical to scope the response. Defaults to solar when omitted.Allowed values: solar, hvac, roofing, plumbing, electrical.

string

Two-letter U.S. state code (e.g. GA, CA, TX). Used to filter finance products, incentives, permits, and climate records to the given state. Must be exactly two uppercase letters; otherwise a 400 is returned.

string

County name (e.g. Fulton, Los Angeles). The County suffix is stripped automatically before matching. Used alongside state for climate, permit, and finance-eligibility filtering.

string

Five-digit FIPS code for the county (e.g. 13121). Alternative to county when you have a FIPS code available. Used for climate context lookups.

string

City name. Used to filter permit records when state or county is also provided.

string

Full postal address (street, city, state, ZIP). Maximum 300 characters. When provided, the API resolves utility territory for the address and includes the result in context.utility_territory_resolution. The raw address is never stored — only the resolution result is retained. Triggering utility territory resolution consumes from a separate rate-limit budget; see the note below.

Finance Filters

string

Filter finance products to a specific lender by slug (e.g. goodleap, mosaic). The value is slugified before matching.

string

Filter finance products by payment type (e.g. loan, lease, ppa).

integer

Filter finance products by loan term in months. Must be a valid integer.

integer

default:"25"

Maximum number of finance records to return. Minimum 1, maximum 100.

Equipment Filters

string

Filter the equipment catalog to a specific category.Allowed values: module, inverter, roofing, hvac, product.

string

Filter equipment records by manufacturer name.

string

Filter equipment records by SKU.

string

HVAC equipment ID. When provided, the API fetches equipment-specific incentive context and uses the equipment’s measure_key to scope incentive and finance-eligibility lookups (unless measure is also explicitly supplied).

integer

default:"25"

Maximum number of equipment records to return. Minimum 1, maximum 100.

Context Filters

string

Utility name for incentive lookup (e.g. Georgia Power). Used to scope incentive records to a specific utility provider.

string

Measure key for incentive and finance-eligibility filtering (e.g. air_source_heat_pump, rooftop_solar). When omitted and equipment_id is provided, the measure is inferred from the equipment record. For trade=hvac with no equipment_id, defaults to air_source_heat_pump.

integer

default:"10"

Maximum number of records to return per context category (climate, incentives, labor adders, permits, finance eligibility). Minimum 1, maximum 50. Also caps utility territory matches at 10.

The address field is used only for utility territory resolution during the current request. It is never persisted, logged, or associated with your API key. The inputs.address_redacted field in the response is a boolean that confirms whether an address was supplied — the address itself is not echoed back.

Always inspect the coverage.warnings[] array in every response. Warnings indicate data gaps such as no finance rows matching the requested trade, missing climate context due to absent geography inputs, or a utility territory resolution that did not reach quote-safe status. A 200 status with an empty finance array and warnings present means the response is incomplete for quoting purposes.

For trade=hvac, always include at least state and county (or county_fips) to receive climate context records. Without geography, the climate array will be empty and a warning will be added to coverage.warnings.

Response

object

Top-level data envelope containing the full quote context bundle.

Show data

string

The trade that was used to scope this response (e.g. hvac, solar).

object

Echo of all resolved inputs used to construct this response.

Show inputs

string | null

Normalized two-letter state code, or null if not provided.

string | null

County name as supplied.

string | null

County FIPS code as supplied.

string | null

City as supplied.

string | null

Utility name as supplied.

string | null

Resolved measure key — either the explicit measure param, the equipment’s measure key, or the trade default.

boolean

true if an address was provided, false otherwise. The address itself is never returned.

string | null

Financier slug filter as supplied.

string | null

Payment type filter as supplied.

integer | null

Term filter in months as supplied.

string | null

Normalized equipment category filter.

string | null

Manufacturer filter as supplied.

string | null

SKU filter as supplied.

string | null

HVAC equipment ID as supplied.

object

Summary of records returned and data quality signals.

Show coverage

integer

Number of finance records returned.

integer

Number of equipment records returned (capped by equipment_limit).

integer

Total equipment records matching the filters, before the limit is applied.

object

Per-category count of context records returned.

Show context_records

integer

Climate context records returned.

integer

Incentive records returned.

integer

Labor adder records returned.

integer

Permit context records returned.

integer

Finance eligibility context records returned.

integer

1 if utility territory was resolved, 0 otherwise.

object

Per-category breakdown of quote-safe vs. non-quote-safe records.

Show quote_safe_summary

object

{ total, quote_safe, not_quote_safe } for finance records.

object

{ total, quote_safe, not_quote_safe } for equipment records.

object

{ total, quote_safe, not_quote_safe } for climate records.

object

{ total, quote_safe, not_quote_safe } for incentive records.

object

{ total, quote_safe, not_quote_safe } for labor adder records.

object

{ total, quote_safe, not_quote_safe } for permit records.

object

{ total, quote_safe, not_quote_safe } for finance eligibility records.

object

{ total, quote_safe, not_quote_safe } for utility territory resolution.

string[]

Deduplicated list of unresolved requirement strings bubbled up from individual records across all context categories. Each item is prefixed with its source category (e.g. "climate: requires county_fips", "incentives: utility name required").

string[]

High-level warnings about the completeness of the response. Inspect this array before presenting a quote. Common values include notices about zero finance rows, missing geography for climate context, and non-quote-safe utility resolution.

array

Array of finance product records matching the trade and applied filters. Each object contains program details, dealer fees, payment options, and quote-safe status.

array

Array of equipment catalog records matching the trade and applied filters. Each object contains manufacturer, SKU, pricing, and quote-safe status.

object

All contextual data needed to enrich and validate a quote.

Show context

object | null

Resolved incentive context for the supplied equipment_id. null when equipment_id was not provided.

array

Climate context records for the specified geography. Populated for trade=hvac when state and county or county_fips are provided.

array

Incentive records matching the trade, state, utility, and measure.

array

Labor adder records for the specified trade.

array

Permit context records for the specified trade and geography.

array

Finance eligibility records matching the trade, state, county, financier, and measure.

object | null

Utility territory resolution result for the provided address. Contains resolved utility name, quote-safe status, and any unresolved requirements. null when address was not provided.

Examples

curl -G https://homeservicedata.org/api/v1/quote-context \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode "trade=hvac" \
  --data-urlencode "state=GA" \
  --data-urlencode "county=Fulton" \
  --data-urlencode "measure=air_source_heat_pump"

curl -G https://homeservicedata.org/api/v1/quote-context \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode "trade=hvac" \
  --data-urlencode "address=123 Peachtree St NE, Atlanta, GA 30309" \
  --data-urlencode "measure=air_source_heat_pump" \
  --data-urlencode "financier=goodleap"

curl -G https://homeservicedata.org/api/v1/quote-context \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode "trade=solar" \
  --data-urlencode "state=CA" \
  --data-urlencode "equipment_category=module" \
  --data-urlencode "manufacturer=Qcells" \
  --data-urlencode "finance_limit=10" \
  --data-urlencode "equipment_limit=50"

Response

{
  "data": {
    "trade": "hvac",
    "inputs": {
      "state": "GA",
      "county": "Fulton",
      "county_fips": null,
      "city": null,
      "utility": null,
      "measure": "air_source_heat_pump",
      "address_redacted": false,
      "financier": null,
      "payment_type": null,
      "term_months": null,
      "equipment_category": null,
      "manufacturer": null,
      "sku": null,
      "equipment_id": null
    },
    "coverage": {
      "finance_records": 18,
      "equipment_records": 25,
      "equipment_total_available": 142,
      "context_records": {
        "climate": 3,
        "incentives": 5,
        "labor_adders": 4,
        "permits": 2,
        "finance_eligibility": 6,
        "utility_territory": 0
      },
      "quote_safe_summary": {
        "finance": { "total": 18, "quote_safe": 16, "not_quote_safe": 2 },
        "equipment": { "total": 25, "quote_safe": 22, "not_quote_safe": 3 },
        "climate": { "total": 3, "quote_safe": 3, "not_quote_safe": 0 },
        "incentives": { "total": 5, "quote_safe": 4, "not_quote_safe": 1 },
        "labor_adders": { "total": 4, "quote_safe": 4, "not_quote_safe": 0 },
        "permits": { "total": 2, "quote_safe": 2, "not_quote_safe": 0 },
        "finance_eligibility": { "total": 6, "quote_safe": 6, "not_quote_safe": 0 },
        "utility_territory": { "total": 0, "quote_safe": 0, "not_quote_safe": 0 }
      },
      "unresolved_requirements": [],
      "warnings": []
    },
    "finance": [ /* finance product records */ ],
    "equipment": [ /* equipment catalog records */ ],
    "context": {
      "equipment_incentive_context": null,
      "climate": [ /* climate context records */ ],
      "incentives": [ /* incentive records */ ],
      "labor_adders": [ /* labor adder records */ ],
      "permits": [ /* permit records */ ],
      "finance_eligibility": [ /* eligibility records */ ],
      "utility_territory_resolution": null
    }
  },
  "error": null,
  "meta": { "request_id": "req_01J...", "api_version": "2026-06-30" }
}

Overview

Search & Catalog

Finance

Equipment & Hardware

Context Datasets

Composite

Sync

GET /api/v1/quote-context — Bundled Quote Context

Request

Authentication

Query Parameters

Trade & Geography

Finance Filters

Equipment Filters

Context Filters

Response

Examples

Response

​Request

​Authentication

​Query Parameters

​Trade & Geography

​Finance Filters

​Equipment Filters

​Context Filters

​Response

​Examples

​Response

Request

Authentication

Query Parameters

Trade & Geography

Finance Filters

Equipment Filters

Context Filters

Response

Examples

Response