GET /api/v1/context/finance-eligibility — Eligibility Records

The /api/v1/context/finance-eligibility endpoint returns eligible-product records from the finance_eligibility dataset. Each record describes which specific product types and measures a lender or PACE program makes available in a given state, county, or scope — including whether a permit is required, what the maximum term is, and the availability status. Records are granular by design: a single program may produce multiple rows, one per criteria_scope (e.g. hillsborough_county, sarasota_county, all_other_counties).

Eligibility records sourced from contractor-uploaded PDFs carry quote_safe: false until an official public source or admin review approves them. Use the quote_safe filter or always inspect the field on each record before building proposal logic from it.

Endpoint

GET https://homeservicedata.org/api/v1/context/finance-eligibility

Request

Headers

string

required

Your API key. Obtain or rotate keys in your dashboard.

Query Parameters

string

Filter by trade category (case-insensitive). Accepted values: solar, hvac, roofing, plumbing, electrical. Returns 400 for unrecognized values.

string

Two-letter state code (e.g. GA, FL). Filters on state_code (exact match, case-insensitive). Returns 400 for values that are not a two-letter code.

string

Slugified measure key to filter on (e.g. solar_panels, heat_pump). Matched against measure_key using exact slug equality.

string

Financier slug or name. Slugified and matched against financier_slug (exact).

string

Filter by program type. Accepted values: pace, loan, lease, home_improvement_loan, rebate, unknown.

string

County name used to resolve criteria_scope. Records with criteria_scope matching the county key are returned, along with all_other_counties records for non-specifically-scoped counties. See criteria_scope below.

string

Substring match against product_label (case-insensitive). Useful for narrowing to a specific product name within a program.

boolean

Pass true to return only verified eligibility records; false for unverified context only. Omit to return all.

integer

Maximum number of records to return. Defaults to 100; hard cap is 500.

Understanding `criteria_scope`

criteria_scope encodes the geographic resolution of each eligibility rule. A single program often publishes different product availability or term limits by county, so a program with statewide coverage in Florida might have three records:

`criteria_scope`	Meaning
`hillsborough_county`	Rule applies specifically to Hillsborough County
`sarasota_county`	Rule applies specifically to Sarasota County
`all_other_counties`	Rule applies to every other county in the state

When you pass the county query parameter, the API resolves the county name to a scope key and returns matching records. Unrecognized county names are resolved to all_other_counties. If no county is passed, records for all scopes are returned.

Response

A successful response returns data.records (the eligibility rows), data.coverage (filter summary), and a usage block.

Response Fields

array

Array of finance eligibility records, ordered by trade_category, product_label, and criteria_scope ascending.

Show FinanceEligibilityRecord fields

string

Stable UUID for this eligibility record.

string | null

ID of the source document this record was extracted from.

string

Display name of the lender or PACE administrator.

string

URL-safe lender identifier. Pass this value in the financier query parameter.

string

Full name of the finance program (e.g. PACE Florida, GoodLeap HVAC Loan).

string

Program category: pace, loan, lease, home_improvement_loan, rebate, or unknown.

string

Trade this eligibility record applies to: solar, hvac, roofing, plumbing, or electrical.

string | null

Slugified measure identifier this record applies to (e.g. solar_panels, battery_storage, heat_pump). null if the record applies to all measures within the trade.

string | null

Product type sub-classification within the program (e.g. pace, loan).

string | null

Human-readable label for the product as written in the source document.

string | null

Geographic scope of this eligibility rule. One of: a county slug (e.g. hillsborough_county), all_other_counties, or null for statewide/unconstrained rules. See Understanding criteria_scope.

string | null

Two-letter state code where this eligibility rule applies.

string | null

Raw county name from the source document, if county-specific. null for statewide records.

object | null

Structured criteria extracted from the source (e.g. property type, ownership requirements, income limits).

boolean | null

Whether a permit is required to use this financing product for the measure. null if not stated in the source.

number | null

Maximum financing term in years for this product/measure combination.

string | null

Current availability of this product in the scoped area: e.g. available, suspended, limited.

boolean

true if this record has passed verification review. Always inspect this field before building proposal logic.

string | null

Data confidence tier: high, medium, or low.

string | null

ISO 8601 date when this eligibility rule became effective.

string | null

ISO 8601 datetime after which this eligibility record expires.

string

ISO 8601 datetime of the most recent source verification.

string | null

URL of the source document or page.

string[] | null

Requirement statements from the source that could not be parsed into structured fields.

string | null

Human-readable title of the source document.

string | null

Provenance category: e.g. official_lender_doc, contractor_upload, web_scrape.

object

Summary of filters applied to this request.

Show coverage fields

string

Applied trade filter, or "all".

string | null

Applied state filter (uppercased), or null.

string | null

Applied county filter, or null.

string | null

Applied financier filter, or null.

string

Applied program type filter, or "all".

string | null

Applied measure filter, or null.

string | null

Applied product substring filter, or null.

integer

Number of records in this response after all filters.

string

The dataset key that backed this response: finance_eligibility.

string

Explanation of quote_safe semantics for this endpoint.

Examples

curl -G https://homeservicedata.org/api/v1/context/finance-eligibility \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode "trade=hvac" \
  --data-urlencode "state=GA"

import requests

resp = requests.get(
    "https://homeservicedata.org/api/v1/context/finance-eligibility",
    headers={"x-api-key": "YOUR_API_KEY"},
    params={"trade": "hvac", "state": "GA"},
)
records = resp.json()["data"]["records"]

const res = await fetch(
  "https://homeservicedata.org/api/v1/context/finance-eligibility?trade=hvac&state=GA",
  { headers: { "x-api-key": "YOUR_API_KEY" } }
);
const { records } = (await res.json()).data;

Example Response

{
  "data": {
    "records": [
      {
        "id": "elig_001bbb",
        "source_document_id": "src_ga_pace_001",
        "financier_name": "Ygrene Energy Fund",
        "financier_slug": "ygrene_energy_fund",
        "program_name": "Ygrene PACE Georgia",
        "program_type": "pace",
        "trade_category": "hvac",
        "measure_key": "heat_pump",
        "product_type": "pace",
        "product_label": "Ygrene PACE — Heat Pump",
        "criteria_scope": "all_other_counties",
        "state_code": "GA",
        "county_name": null,
        "eligibility_criteria": {
          "property_type": ["residential", "commercial"],
          "ownership_required": true
        },
        "permit_required": true,
        "max_term_years": 25,
        "availability_status": "available",
        "quote_safe": true,
        "confidence": "high",
        "effective_date": "2023-06-01",
        "expires_at": null,
        "last_verified_at": "2024-10-05T14:00:00.000Z",
        "source_url": "https://ygrene.com/contractors/georgia",
        "unresolved_requirements": null,
        "source_title": "Ygrene Georgia Contractor Program Guide",
        "source_kind": "official_lender_doc"
      }
    ],
    "coverage": {
      "trade": "hvac",
      "state": "GA",
      "county": null,
      "financier": null,
      "program_type": "all",
      "measure": null,
      "product": null,
      "returned": 1,
      "source": "finance_eligibility",
      "quote_safe_rule": "Eligibility lists from contractor-uploaded PDFs are context until an official public/current source or admin approval marks them quote-safe."
    }
  },
  "usage": {
    "endpoint": "/api/v1/context/finance-eligibility",
    "status_code": 200,
    "duration_ms": 52
  }
}

Error Reference

Status	Cause
`400`	Invalid `trade`, `program_type`, `quote_safe`, or `state` parameter value.
`401`	Missing or invalid `x-api-key` header.
`403`	Your key does not have access to the `finance_eligibility` dataset.
`500`	Internal server error.

Combine state, trade, and measure to scope eligibility records to a single job type (e.g. HVAC heat pumps in Georgia). Then cross-reference financier_slug with /api/v1/context/finance-products to pull the matching program’s APR ranges and loan limits in one workflow.

Overview

Search & Catalog

Finance

Equipment & Hardware

Context Datasets

Composite

Sync

GET /api/v1/context/finance-eligibility — Eligibility Records

Endpoint

Request

Headers

Query Parameters

Understanding `criteria_scope`

Response

Response Fields

Examples

Example Response

Error Reference

​Endpoint

​Request

​Headers

​Query Parameters

​Understanding criteria_scope

​Response

​Response Fields

​Examples

​Example Response

​Error Reference

Endpoint

Request

Headers

Query Parameters

Understanding `criteria_scope`

Response

Response Fields

Examples

Example Response

Error Reference